From 48847f480f08949dc434e718b2717a6e229aaf75 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Mon, 16 Nov 2026 01:01:49 -0700 Subject: [PATCH 1/2] docs(jarvis): ADR 0009 links the inbox 0012 by file; one rollover instruction; provenance and portfolio scope Docs-only mirror from the private connector repo: - ADR 0009's "(0012, 0014)" pointed at an ambiguous 0012; it now links the inbox-subscriptions ADR by file. - COORDINATORS.md gives one current rollover procedure instead of the pre-switch seed guarantee followed by an override. The seed and portfolio_status are described as pre-switch views that go with the fork. - ADR 0020: a work-state write still landing on this ledger after the cutover shows in portfolio_status until replayed; the seed is documented, not fixed. - ADR 0012: "changedByClient is null" applies to sidecar history only; approval rows kept on this ledger still get server-recorded senders. The stdio caller label now carries the T3 thread id. Co-Authored-By: Claude Opus 5.5 --- docs/jarvis/COORDINATORS.md | 10 +++++++--- docs/jarvis/decisions/0009-jarvis-inbox.md | 2 +- .../0012-ledger-fields-history-and-portfolio.md | 2 +- .../decisions/0020-ledger-of-record-is-the-sidecar.md | 4 ++-- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/jarvis/COORDINATORS.md b/docs/jarvis/COORDINATORS.md index e0f99e96b44f0..64d4133fcc190 100644 --- a/docs/jarvis/COORDINATORS.md +++ b/docs/jarvis/COORDINATORS.md @@ -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 in the sidecar, and its latest result, first. +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`, any row that carries an approval, because that work stays whole on T3's ledger (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 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. diff --git a/docs/jarvis/decisions/0009-jarvis-inbox.md b/docs/jarvis/decisions/0009-jarvis-inbox.md index 74fdd1bf83bb8..04234893331ec 100644 --- a/docs/jarvis/decisions/0009-jarvis-inbox.md +++ b/docs/jarvis/decisions/0009-jarvis-inbox.md @@ -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 diff --git a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md index ae238746fe40c..d54788e3296ef 100644 --- a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md +++ b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md @@ -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 sidecar entry. Treat sidecar `changedBy` as a hint, not verified attribution. Rows that stay on T3's ledger after the switch, the approval-bearing work in 0020, still get T3's server-recorded senders. ## Decision diff --git a/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md b/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md index c69ece36eea3e..b2ea23b9a5eab 100644 --- a/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md +++ b/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md @@ -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, until the reconciliation sweep (below) replays it. 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. 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 From faeb73a26517183bfa0f4d49830cc9a7033fb577 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Mon, 16 Nov 2026 01:04:55 -0700 Subject: [PATCH 2/2] docs(jarvis): approval-exception rows stay on T3 through rollover; imported provenance; persistent stragglers Mirrors the review repair in the private connector repo: - rollover updates work kept whole on this ledger here, never in the sidecar, and re-reads every owned row that carries or once carried an approval; - history imported from the fork keeps its server-recorded changedByClient; - a replayed straggler keeps showing in portfolio_status. Co-Authored-By: Claude Opus 5.5 --- docs/jarvis/COORDINATORS.md | 6 +++--- .../decisions/0012-ledger-fields-history-and-portfolio.md | 2 +- .../decisions/0020-ledger-of-record-is-the-sidecar.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/jarvis/COORDINATORS.md b/docs/jarvis/COORDINATORS.md index 64d4133fcc190..b350e80d9bb57 100644 --- a/docs/jarvis/COORDINATORS.md +++ b/docs/jarvis/COORDINATORS.md @@ -2,11 +2,11 @@ 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)). -1. Update the coordinator's rows in the sidecar, and its latest result, first. +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`, any row that carries an approval, because that work stays whole on T3's ledger (0020). Those two reads are its work list. +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. -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 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. +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. diff --git a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md index d54788e3296ef..f5e474219c305 100644 --- a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md +++ b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md @@ -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 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 sidecar entry. Treat sidecar `changedBy` as a hint, not verified attribution. Rows that stay on T3's ledger after the switch, the approval-bearing work in 0020, still get T3's server-recorded senders. +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 diff --git a/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md b/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md index b2ea23b9a5eab..f8144f3ea19bd 100644 --- a/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md +++ b/docs/jarvis/decisions/0020-ledger-of-record-is-the-sidecar.md @@ -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. A work-state write that still lands on T3's ledger after the cutover also shows there, until the reconciliation sweep (below) replays it. 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. The seed itself is not being fixed: it stays a documented pre-switch view until the fork retires (`../COORDINATORS.md`). +- **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