Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
📖About
Ninads audit questions confirmed 3 gaps: (a) 3 running droids (me-step-exec-01, me-orch-launch-01, forseti-risk-01) leave no run-audit rows; (b) the 283 audited scheduled/triggered droids produce runs but NEVER activities — the Activity Tracker only hears about pipeline/bypass/review events from 18 droids; (c) the activities table has NO cost columns — every activity is cost-less by schema and the tracker approximates by joining the cost ledger per agent-day. Bridge: (1) audit the 3 uncovered droids; (2) add cost_usd + tokens columns to agent_activities and let log_activity carry them; bypass close stamps its activity with the initiatives ledger cost; (3) run_audit_end logs an activity for SIGNIFICANT runs only (failed, or nonzero cost) — deliberately NOT all 155k weekly ticks, which would drown the tracker in heartbeat noise.
⚖️Decisions
- Elrond's bypass methodology checklist (a reminder, not a gate -- you've got this): 0. File it requested_mode='bypass' (planner-vs-bypass is a deliberate choice). bypass_start REFUSES a non-bypass initiative (CAROL-INI-1846), and the dispatcher only skips the bypass lane when the mode says bypass -- a 'planner' mistag lets Merlin's pipeline grab the placeholder step and block your finished work. 1. Filed as planned status -- let the bypass claim/activate it; never file active. 2. Open the bypass (bypass_start) with your droid id + the remediation answer (remediates_initiative_id=NNN, or remediates_nothing=True). 3. Work the blocks for your work-type: template -> design -> code -> test -> review. Do the real work; record decisions on the initiative as you make them. 4. Reality is recorded for you at close -- code (files changed), each decision, and the twin-review verdict become real activities tied to this initiative and show in the Activity Tracker like a planner run (CAROL-INI-1840). No dummy rows. 5. Keep the initiative status moving; it parks in 'reviewing' and is tagged uat-pending for you at close (CAROL-INI-1836), so the stuck-watchdog leaves it alone until UAT. 6. Close runs the gates (design/architecture compliance + caller-audit). If a gate flags something pre-existing or unrelated to your change, waive it with a clear written rationale -- audit, don't skip. 7. Bypass skips the planner's auto-orchestration, NOT the standards. Same template checklist, same review, same observability as a planner run. (elrond)
- [status-router] planned -> executing | event=bypass_executing | bypass transition (or-bx-01)
- AUDIT ANSWER (Ninads question): run audit is genuinely near-total — 283/286 running droids leave run rows; the 3 flagged misses were false alarms (Forsetis risk scanner is monthly-scheduled WITH the audit wrapper; Merlins step executor and orchestrator launcher record runs through the pipelines own bookkeeping). REAL gaps were: runs never became activities, and activities had no cost columns. BRIDGED: (1) agent_activities gained cost_usd+tokens, log_activity carries them; (2) run_audit_end bridges SIGNIFICANT runs (failed or costful) to activities attributed to the droids owning agent — routine no-op ticks (150k/week) deliberately excluded to keep the tracker readable; (3) bypass close stamps its work activity with the initiatives ledger cost. Live-proven with real self-test runs; tests 4/4. (orion)
- [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
- HONESTY NOTE: the bypass-close cost stamp is shipped and unit-proven, but NOT yet live-observable — the closes code-changes activity never fires because changed-file detection is git-based and the VM repo HEAD is broken (bad object HEAD, carried open since Session 100). EVERY bypass close since then has silently lost its Step: code activity row. Criterion 3 set back to pending until git HEAD is repaired (that repair is the real blocker and should be next sessions priority). (orion)
- [status-router] reviewing -> blocked | event=operator_put | PUT /api/initiatives (operator)
- EXTENSION (Ninad, dedup-routed): surface the ledger — org profile Activities tab lists agent_activities (droid, type, status, cost) above the task list; every agents Dashboard gains an activities-per-day card with day cost + click-through; Activity Tracker rows display carried cost (display-only, rollups untouched). (orion)
- [status-router] blocked -> executing | event=bypass_executing | bypass transition (or-bx-01)
- Handover-watchdog: planner-pending nudge for phase 3 (auto-invoked Elrond planner). (elrond)
- Handover-watchdog: planner-pending nudge for phase 3 (auto-invoked Elrond planner). (elrond)
- EXT SHIPPED: org profiles now read the real ledger — new agent-activities + activities-trend endpoints (org app), Activities tab lists ledger entries with droid/type/status/cost above the task list, EVERY agents Dashboard gained an activities-per-day canvas chart (completed/failed, day cost, click lists the day) drawn in the apps hand-rolled style; Activity Tracker detail rows now prefer each activitys OWN recorded cost/tokens over the per-initiative smear. Org app restarted via break-glass (runs as OS user orion); tracker auto-relaunched by its watchdog on kill. GIT REPAIR (same session): HEAD pointed at a refactor branch whose objects were never written — deleted the dead loose ref, restored HEAD to master, rebuilt the corrupt index, purged stale reflog entries, regenerated one missing blob from the working tree; the Shipper immediately committed the 11-day backlog on its own schedule. This close is the live test of the bypass cost stamp. (orion)
- [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
- Also fixed in-flight: the ledger-cost helper was nested in the wrong scope (NameError at close); moved to module level. (orion)
- [status-router] reviewing -> executing | event=operator_put | Ninad: Activities-tab format is outstanding 2590 scope — reopening for an Orion bypass extension (task-card format + supervisor->Clara consolidation). (orion)
- Handover-watchdog: planner-pending nudge for phase 4 (auto-invoked Elrond planner). (elrond)
- Handover-watchdog: planner-pending nudge for phase 4 (auto-invoked Elrond planner). (elrond)
- [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
- [status-router] reviewing -> executing | event=operator_put | Ninad design ruling: activity type must be DERIVED from the executing droid registry process_type (scheduled/requested/autonomous), not caller-declared. Third extension of 2590. (orion)
- Handover-watchdog: planner-pending nudge for phase 5 (auto-invoked Elrond planner). (elrond)
- Handover-watchdog: planner-pending nudge for phase 5 (auto-invoked Elrond planner). (elrond)
- [status-router] executing -> reviewing | event=dispatcher_transition | dispatcher state change (ds-s1)
- [status-router] reviewing -> closed | event=operator_signoff | Auto-accepted (CAROL-INI-1859): Orion-initiated, >2 days in reviewing with no objection. (el-srac-01)
✅Success criteria
- Every running droid in the registry leaves run-audit rows — the 3 currently invisible ones (Merlins step executor and orchestrator launcher, Forsetis risk scanner) show fresh runs after their next trigger (must_have)
- When a droid run fails or spends money, it appears in the Activity Tracker as an activity with the droids name — routine no-op ticks stay out so the tracker remains readable (must_have)
- New activities carry their real cost: the activity written at a bypass close shows the initiatives actual ledger spend, visible in the Activity Tracker instead of a cost-less row (must_have)
- EXT2: An agent profile Activities tab shows each ledger activity as a readable card (droid name, human one-line note, status, cost, date) — no raw JSON visible, including for pre-existing rows (must_have)
- EXT2: A supervisor profile shows one consolidated line per direct reportee (their whole team counted: N tasks / N passed / N failed), and Clara sees one such line per supervisor — the designs 53/121 cascade (must_have)