Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/jarvis/COORDINATORS.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
# Continuing a coordinator

Use rollover when a long-running coordinator's provider context is crowded or stale and its remaining work is recorded in the ledger. Update its ledger rows and latest result first, then call `t3_thread_send` with its `threadId`, `coordinatorRollover: true`, `mode: "queue"`, and a short continuation request in `message`.
Use rollover when a long-running coordinator's provider context is crowded or stale and its remaining work is recorded in the ledger. The ledger of record is the `ledger` server, the sidecar ([0020](decisions/0020-ledger-of-record-is-the-sidecar.md)).

The thread keeps its history and identity. Its next turn uses a fresh provider session, seeded with up to 25 unfinished ledger rows whose `ownerThreadId` matches that thread and up to 4,000 encoded bytes of its latest assistant result, within an 8 KiB total seed budget. The seed includes titles, blockers and next actions; it carries no new approval. Re-read the ledger to recover longer fields or additional rows. Ordinary `freshContext: true` sends clear the provider context without adding a seed; normal sends keep their existing context. Rollover cannot steer or restart a running turn; queue it at a clean boundary.
1. Update the coordinator's rows, and its latest result, first. Rows in the sidecar are updated there. Work kept whole on T3's ledger, a row that carries or once carried a server-verified approval (0020), is updated on T3's ledger only; any sidecar row for its key is just a pointer to it.
2. Call `t3_thread_send` with its `threadId`, `coordinatorRollover: true`, `mode: "queue"`, and a short continuation request in `message`. Rollover cannot steer or restart a running turn; queue it at a clean boundary.
3. After the rollover, and before acting, the coordinator re-reads its own rows from the sidecar: it pages `ledger_query` for each of `open`, `blocked` and `waiting_on_human` (limit 100) until `nextCursor` is null, and keeps the rows whose `ownerThreadId` is its thread. It also re-reads, through T3's `ledger_query`, its unfinished rows there, and keeps every one that carries or once carried an approval (an approval in that row's T3 history), because that work stays whole on T3's ledger even after its approval is used or withdrawn (0020). Those two reads are its work list.

**Since 2026-11-14 ([0020](decisions/0020-ledger-of-record-is-the-sidecar.md)) the seed is stale.** It still comes from T3's frozen ledger, while the ledger of record is the `ledger` server (the sidecar). Before a rollover, update the rows in the sidecar. After it, the coordinator re-reads its own rows from the sidecar before acting: page `ledger_query` for each unfinished status until `nextCursor` is null, and filter by `ownerThreadId`. Only then does it set the seeded rows aside.
The thread keeps its history and identity. Its next turn uses a fresh provider session, seeded with up to 25 unfinished rows that the thread owns and up to 4,000 encoded bytes of its latest assistant result, within an 8 KiB total seed budget. T3 builds that seed from its own ledger, which has been frozen for work state since the switch, so the seeded rows are a pre-switch view. Only rows that carry or once carried an approval are current there. Treat the seed as a pointer, not as the work list, and set it aside once step 3 is done. It carries no new approval. `portfolio_status` reads the same frozen ledger, so it is a pre-switch view too; read an owner thread's run state with `t3_thread_read` instead. Neither view is being ported: both go when the fork retires.

Ordinary `freshContext: true` sends clear the provider context without adding a seed; normal sends keep their existing context.

Fetch the MCP resource `t3://jarvis/playbook` when starting or rolling over a coordinator. It serves the vocabulary and decisions in `docs/jarvis` from the running T3 build. `orchestrator_capabilities` returns its URI. A newly merged decision becomes available after that build is released and installed.

Expand Down
2 changes: 1 addition & 1 deletion docs/jarvis/decisions/0009-jarvis-inbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Accepted 2026-11-12. Acknowledge-only mode added 2026-11-13.

T3 agents send requests to Jarvis's T3 inbox thread. An event wakes Jarvis, which reads the request and answers in the requesting thread.

The inbox acknowledges each message with a run of its own; that run's result event is the wake signal (0012, 0014). Acknowledge-only mode lets the server write that acknowledgement instead of a model. The coordinator turns it on for the inbox after deploy, once it has verified that Jarvis still wakes.
The inbox acknowledges each message with a run of its own; that run's result event is the wake signal ([0012, inbox subscriptions and the heartbeat](0012-inbox-subscriptions-and-the-heartbeat.md); [0014](0014-event-routing-and-hub-watch.md)). Acknowledge-only mode lets the server write that acknowledgement instead of a model. The coordinator turns it on for the inbox after deploy, once it has verified that Jarvis still wakes.

## Acknowledge-only mode

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Ledger fields, history and portfolio

Accepted 2026-11-12. Since 2026-11-14 ([0020](0020-ledger-of-record-is-the-sidecar.md)) the ledger is the dot-t3code-mcp sidecar: wait reasons and history carry over, while run metadata and `portfolio_status` apply only to rows on T3's ledger: pre-switch rows, plus the post-switch work that needs a server-verified approval, which stays whole there. Sidecar rows are outside them. Sender provenance does not carry over: sidecar history records `changedBy` from a caller label (`X-Caller` or `DOT_T3CODE_MCP_CALLER`), which is not authenticated, and `changedByClient` is `null` for every post-switch entry. Treat post-switch `changedBy` as a hint, not verified attribution.
Accepted 2026-11-12. Since 2026-11-14 ([0020](0020-ledger-of-record-is-the-sidecar.md)) the ledger is the dot-t3code-mcp sidecar: wait reasons and history carry over, while run metadata and `portfolio_status` apply only to rows on T3's ledger: pre-switch rows, plus the post-switch work that needs a server-verified approval, which stays whole there. Sidecar rows are outside them. Sender provenance does not carry over to the sidecar: its history records `changedBy` from a caller label (`X-Caller`, or `DOT_T3CODE_MCP_CALLER` with the T3 thread id appended over stdio), which is not authenticated, and `changedByClient` is `null` for every entry the sidecar writes itself, which is all post-switch sidecar history. Treat that `changedBy` as a hint, not verified attribution. History imported from the fork at the switch keeps T3's server-recorded `changedByClient`, and so do rows that stay on T3's ledger after the switch, the approval-bearing work in 0020.

## Decision

Expand Down
4 changes: 2 additions & 2 deletions docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Accepted 2026-11-14. Amends [0003](0003-ledger-and-single-slack-writer.md), [001
- **Work that needs a server-verified approval stays whole on T3's ledger for now.** That means a money go-ahead under [0016](0016-no-human-in-the-loop.md), or a grant passed from T3 to Jarvis under [0004](0004-approval-authority.md). Such an item is not migrated: its work state and its approval live together on one T3 row, so [0015](0015-server-verified-approvals.md) applies exactly as written. T3 withdraws the approval itself when the row changes, finishes or is revoked, and an answer is used once. If a sidecar row exists for the same key, its nextAction points at the T3 row and its work state is not edited in both places. These rows are exempt from the freeze and from the reconciliation sweep. Any sidecar-native replacement needs Chris's decision first (tracked in the private connector repo).
- **Jarvis reaches the ledger by asking a T3 thread.** It does not call T3's ledger tools. Agents on a machine without the `ledger` server do the same.
- **There are no verified approvals in the sidecar.** It refuses `approval` on upsert and the `approved` filter on query. `approvalNote` is free text, including a Jarvis or agent relay, and never counts as approval. A task's authority comes from its intake dialog under [0016](0016-no-human-in-the-loop.md), linked on the row by thread and item id. Money still needs Chris's own fresh go-ahead every time, through the T3-ledger exception above.
- **Fork-only views are retired for sidecar rows.** T3 fills `lastRunId`, `lastRunStatus` and `lastRunAt` only on its own ledger, so they stay `null` in the sidecar. `portfolio_status` reads only T3's ledger, so it shows pre-switch rows plus the approval-bearing work that stays there (above). It is current for that exception and stale for everything else. Read an owner thread's run state with `t3_thread_read` instead. The completion supervisor already does.
- **Coordinator rollover seeds are stale.** `coordinatorRollover: true` still seeds the fresh session from T3's frozen ledger. After any rollover, the coordinator re-reads its rows from the sidecar before acting. `ledger_query` has no `ownerThreadId` filter, so it pages each of `open`, `blocked` and `waiting_on_human` (limit 100) until `nextCursor` is null, then filters by its `ownerThreadId`. It also re-reads, through T3's `ledger_query`, any seeded row that carries an approval (those stay on T3's ledger). Only after both reads does it set the seeded rows aside. Fixing the seed itself is tracked in the private connector repo.
- **Fork-only views are retired for sidecar rows.** T3 fills `lastRunId`, `lastRunStatus` and `lastRunAt` only on its own ledger, so they stay `null` in the sidecar. `portfolio_status` reads only T3's ledger, so it shows pre-switch rows plus the approval-bearing work that stays there (above). It is current for that exception and stale for everything else. A work-state write that still lands on T3's ledger after the cutover also shows there, and keeps showing after the reconciliation sweep (below) replays it into the sidecar, because the sweep leaves the T3 row as it is. Once the sidecar has the row, its T3 copy is stale. Read an owner thread's run state with `t3_thread_read` instead. The completion supervisor already does.
- **Coordinator rollover seeds are stale.** `coordinatorRollover: true` still seeds the fresh session from T3's frozen ledger. After any rollover, the coordinator re-reads its rows from the sidecar before acting. `ledger_query` has no `ownerThreadId` filter, so it pages each of `open`, `blocked` and `waiting_on_human` (limit 100) until `nextCursor` is null, then filters by its `ownerThreadId`. It also re-reads, through T3's `ledger_query`, its unfinished rows that carry or once carried an approval (those stay on T3's ledger, even after the approval is used or withdrawn). Only after both reads does it set the seeded rows aside. The seed itself is not being fixed: it stays a documented pre-switch view until the fork retires (`../COORDINATORS.md`).
- **Writes after the cutover are reconciled.** A work-state write that still lands on T3's ledger is replayed into the sidecar by a sweep, and its writer is told to switch. Rows that carry or once carried a server-verified approval are skipped, because they are the exception above.

## Alternatives
Expand Down
Loading