feat(server): route native agents through shared Prism service

[lukemaj]

What: Route upstream delegation and thread launches through one Prism service, with scoped kits and persisted same-model recovery.
Why: The v2 port must retain Prism without duplicating upstream agent handlers or delivering a failed child result while recovery is pending.
So what: Review this single #169 PR into fork/v2; the planner will capture deferred UI evidence in the authorized integrated pass after the ports land.

Closes #169. Part of #166; advances the Objective by routing Drafters through visible native T3 threads. Based on merged #168/#181 at 6627c1afe97378cd0c2e4528dec20e8177acd133, including the landed #167 foundation, #170 people and #171 issue links. The diff contains only #169, with staged predecessor copies removed.

The shared resolver serves both delegate_task and t3_thread_launch. Explicit selections take precedence; optional role/lane inputs select ordered kit models and instructions. Selection checks capacity and availability before start and falls back on provider/model unavailability. Provider runtime guidance uses upstream tool names.

A fork-owned reactor persists original-run and deterministic command/message identities. Retryable machine failures receive one retry on the same provider, model and options. Reset waits reuse upstream usage-limit recovery. Finalization holds until recovery settles; actual dispatch composes the landed retirement admission and retry guard in the same SQLite commit. Stop releases the hold, while stale propagated Stop remains a receipt-only no-op.

The settings page preserves complete saved v1 kits at environment and project scopes. User decision D26 hides inert Retry/Escalation enable switches and removes skip-step claims: their model lists are used when the planner explicitly requests prismRole. Saved flags still decode, with no disabled-kit refusal. Automatic recovery remains independent. #169 owns Chromeria's autoResumeLimitedThreads=true default; Wight consumes it, and saved false overrides are preserved.

The existing prism-toolkit, prism-settings and tool-instructions feature IDs retain one primary owner per upstream path. Foundation, child-thread, people and issue-link ownership is preserved; overlaps use sharedFiles. No version bump, merge, installation, deployment or main push.

Proof and reuse binding on head 1e9d17a28f28e28f28df618c73a8a1b5a2a73859 against base 8fc40da4fd603f343f13d6e51676b6f1e091b555, all commands serial:

• Composed routing/settings/recovery/Stop/intake proof: 245 passed across 21 files, zero selected cases skipped. Real SQLite, receipts, EventSink and orchestration services exercise duplicate events, restart windows, exhausted retry, same selection/options, Stop/retirement, stale propagated Stop and reset eventual parent finalization.
• Full apps/server/src/serverSettings.test.ts run alone: 63 passed, including all seven saved roles, fields, lists, instructions and project overrides through an unrelated disk write, retained Wight assertions and true-default/false-override behavior.
• apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts run alone: 2 passed.
• Actual server package pnpm --filter t3 exec tsc --noEmit, contracts and web scoped typechecks: exit 0.
• Scoped lint: exit 0, with two unchanged foundation inline-schema warnings. Whole-stack fork-check.sh --base 12069eefd707f78eafc27812027c994eea0613cf: 17 feature owners, allowlist and inventory pass; git diff --check passes.

Full commands, failed checks and corrected results, dependency/rebase identities, fixed decisions and durable continuation are in the canonical #169 handoff. The earlier nonexistent server-package filter was a no-op and is not accepted proof; the actual t3 check passes. Missing settings in one MCP test layer and branded fixture values were corrected locally. An unchanged settings watcher timeout during an earlier combined run is retained in the record; its complete file passes alone without changing the watcher or skipping a case.

Independent exact-head review: success on current successor 1e9d17a28f28e28f28df618c73a8a1b5a2a73859, by lukemaj, GPT-6-Luna through Codex in T3 Code: exact-head findings. Source-only review; no author proof independently rerun. Prior a052 source review passed, but its CI Server1 exceeded the 10-minute job limit after MuseReplayMismatchError: legacy recorded runtime guidance lacked Prism text. The existing replay materializer now refreshes only Muse's first runtime block using current model/effort, preserving user inputs and exact structural matching. No timeout increase, skip, broad sanitization or waiver. Prior cd6 source review passed, but CI found unused exports, two restore fixtures still assuming default=false, and omitted cross-provider guidance. All red CI evidence remains in the failed run; no failure is accepted or waived. The successor makes only unused constants private/deletes unused v1 stream activity metadata, uses nondefault fixture values with unchanged assertions, restores truthful cross-provider guidance, and updates ownership/allowlist. #172 confirmed no consumer of the removed stream constant.

Current affected proof: scoped server/contracts Knip exit0; Prism/contracts/guidance 46 passed, full settings restore file alone 4 passed; actual server/contracts/web typechecks, scoped lint and inventory exit0. Routing/recovery/settings behavior is unchanged in this CI-only successor, so the composed245, full settings63 and MCP2 results above are reused from cd6 with the unchanged behavioral inputs. No local full suite or unnecessary repetition. Current fresh GitHub CI must be all green before merge. The approved documentation-only base advance to 8fc40da4fd603f343f13d6e51676b6f1e091b555 was mechanically rebased with no conflicts: all nine patches have identical range-diff, and only MISSION.md/docs/fork.md differ between the pre/post rebase trees. Every code, test and compiler input is unchanged; local proof is explicitly reused, and fork inventory/diff checks were renewed. No heavy tests were repeated.

Commands:

pnpm exec knip --workspace apps/server --workspace packages/contracts --exports --preprocessor ./scripts/knip-schemas.ts --no-config-hints
pnpm exec vp test run apps/server/src/prism packages/contracts/src/prism.test.ts apps/server/src/mcp/toolkits/orchestrator/tools.test.ts
pnpm --filter @t3tools/web exec vp test run src/components/settings/SettingsPanels.restore.test.tsx
pnpm --filter t3 exec tsc --noEmit
pnpm --filter @t3tools/contracts exec tsc --noEmit
pnpm --filter @t3tools/web exec tsc --noEmit
pnpm exec vp lint apps/server/src/mcp/toolkits/orchestrator/tools.ts apps/server/src/prism/recovery.testkit.ts apps/web/src/components/settings/SettingsPanels.restore.test.tsx packages/contracts/src/prism.ts

Root-approved D32 is excluded from this candidate. The user requires a separate small follow-up PR for immutable continuation source links and conclusive outcomes keyed by failed RunId, before #174 consumes that interface. See the decision and the consumer contract. This PR adds no scheduler logic or report registry.

Agent cost published with Agent Observer, publication and successor republication exit0. Coverage is incomplete: 41 sessions have unbound usage and one lacks usage records; estimated cost is unknown, not zero. No failed publication or cost waiver. Fresh successor GitHub CI is running and is not claimed green. Muse fix proof: real simple/muse failed before then passed; all five Muse fixture cases passed; runtime/materializer tests 10 passed; actual t3 compiler, scoped lint, inventory17 and diffcheck exit0. Author test fixture import/brand/manual-runtime errors were corrected and rerun; no failure accepted. Earlier local routing/settings/recovery proof is reused with unchanged production inputs.

UI evidence is explicitly deferred by the user: no browser or dev server was authorized. The planner owns one integrated settings/UI pass and before/after images after ports land. Focused logic and disk replay tests are complete. No full suite or live-provider verification is claimed; adapter-boundary lifecycle tests do not prove real provider execution. Recovery scan overhead has not been measured. Website/SEO impact: none, this changes the app and adds no public marketing page or URL.

Requirements and who asked: User/#169 and fixed #166 D4.1/D5′/D6′ require shared Prism, settings replay and coordinated one-retry/reset behavior; user also fixes D26, default ownership and deferred UI proof.
Deleted: Parallel spawn path, mid-run model switching, disabled-kit refusal, unknown-role passthrough, second transaction seam, duplicate primary ownership and failed-check waivers.
Bottleneck: Exact-head independent review and the single PR; the predecessor is merged and focused proof is complete.
Checked myself: Verified live predecessor merge/review and current Git identities, #169-only range-diff, ownership map, serial actual compiler/test outputs and real persisted receipts/settings behavior.

Implemented with GPT-6.1-Sol through Codex in T3 Code; independent reviewer routed through Prism to GPT-6-Luna through Codex.

Upstream edit inventory (user modularity rule)

Counts are candidate 1e9d17a28f28e28f28df618c73a8a1b5a2a73859 against live intended base 8fc40da4fd603f343f13d6e51676b6f1e091b555. Ownership classification checks file existence at upstream base 12069eefd707f78eafc27812027c994eea0613cf; new fork files are excluded. Test fixtures are listed separately from production hooks. All edited upstream paths are allowlisted with one primary owner, and overlaps are sharedFiles.

Production hooks and contract registration

Upstream-owned file	Added	Removed	Scope / justification
apps/server/src/mcp/OrchestratorMcpService.ts	+30	-6	Single Prism.resolve hook with input/validator arguments; callback reuses upstream resolveTargetRechecking rather than copying validation. Kit prefix and layer provisioning only.
apps/server/src/mcp/toolkits/orchestrator/tools.ts	+1	-1	Tool-description metadata sends native same/cross-provider work through shared Prism; upstream task lifecycle guidance retained.
apps/server/src/mcp/toolkits/project/handlers.ts	+21	-3	Single Prism.resolve hook and existing service contexts for reusable launch validation; kit prefix and invocation Effect provisioning. Routing logic stays in new PrismService.
apps/server/src/mcp/toolkits/project/tools.ts	+10	-1	Optional role/lane parameters and existing service dependencies declared for the handler hook.
apps/server/src/orchestration-v2/Orchestrator.ts	+4	-1	Context.Reference finalization hold plus fork retry commit-plan call, composed with existing retirement plans.
apps/server/src/orchestration-v2/runtimeLayer.ts	+20	-0	Layer registrations connect fork recovery coordinator/reference hooks/reactor to existing services. Recovery behavior stays in new fork files.
apps/server/src/provider/RuntimeInstructions.ts	+2	-1	One runtime guidance hook into new fork toolInstructions module.
apps/server/src/provider/T3OrchestrationInstructions.ts	+2	-2	Reconciles upstream delegation guidance with visible Prism routing; no duplicate provider logic.
apps/web/src/components/settings/SettingsSidebarNav.tsx	+2	-0	Registers Prism settings navigation.
apps/web/src/components/settings/settingsSearch.ts	+19	-0	Settings-search registration records for the new Prism route, no routing/settings behavior copied.
packages/contracts/src/index.ts	+1	-0	Exports the new fork Prism contracts module.
packages/contracts/src/orchestrationV2.ts	+3	-0	Optional internal retry-origin command fields for existing serialized dispatch.
packages/contracts/src/orchestratorMcp.ts	+3	-0	Optional lane/prismRole inputs on the upstream delegation schema.
packages/contracts/src/settings.ts	+6	-1	Registers typed scoped Prism settings and the user-owned autoResume default; persistence infrastructure unchanged.

Existing upstream tests

Upstream-owned file	Added	Removed	Scope / justification
apps/server/src/mcp/OrchestratorMcpService.activity.test.ts	+5	-4	Test dependency layer adjustment.
apps/server/src/mcp/OrchestratorMcpService.test.ts	+205	-114	Test: upstream delegation fixtures provide settings; configured kits and stale-provider re-probe regressions. Large reindent comes from parameterizing the existing explicit/configured validation case, preserving its assertions.
apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts	+3	-0	Test dependency layer adjustment.
apps/server/src/mcp/toolkits/core.test.ts	+4	-0	Test dependency layer adjustment.
apps/server/src/mcp/toolkits/project/handlers.test.ts	+251	-17	Test: shared service layers plus scoped kit/instruction, absent-adapter and stale-provider refresh/fallback cases at the real MCP handler boundary. Large fixtures fake only launch/provider boundaries.
apps/server/src/serverSettings.test.ts	+76	-29	Test: approved complete real v1 seven-role preservation fixture replaces the temporary opaque Prism sentinel; new default and saved false proof. Wight assertions preserved.
apps/web/src/components/settings/SettingsPanels.restore.test.tsx	+5	-2	Test: use a nondefault value for restore/cancel fixtures after the user-approved autoResume default became true. Assertions remain unchanged.

| apps/server/src/orchestration-v2/testkit/ReplayTranscriptNdjson.ts | +49 | -3 | Test-only helper: materialize current Muse runtime context in legacy exact outbound expectations. The larger hunk validates the typed turn/start shape and replaces only the first runtime block, preserving user/image input, IDs, effort and every other field; no replay matcher weakening. |

Generated registration

Upstream-owned file	Added	Removed	Scope / justification
apps/web/src/routeTree.gen.ts	+21	-0	Generated TanStack route registration for settings.prism; generated output mirrors the new fork route.

Fork-owned behavior lives in new Prism service/settings/recovery modules. The larger production hook hunks consist of call arguments and layer registrations, not copies or restructuring of upstream implementations. No consequential modularity redesign is needed.

[lukemaj]

Agent work on this PR

Estimated cost unknown · 0 responses · 42 sessions · 5.6 h wall time

Model	Responses	Tokens	Estimated cost

Flags: 3 human corrections · 68 large tool outputs · 50 repeated commands · 9 repeated failures · 65 repeated reads · 8 repeated skill loads · 41 sessions with usage bound to no task · 1 session without usage records

Details: snapshot, prices, coverage, counters

• Task toolboxmd/chromeria#169: outcome unknown (recorded acceptance only; a finished process never implies it).
• Proof: Port Prism as a service behind upstream delegation #169
• Snapshot 17acdbb16bbfed7d57cc71880b770ab45e6060a436731a0f025987f5698be762, records up to 2026-10-08 19:12 UTC.
• 42 sessions on claude, codex; AgentsMD 14.6.0.
• Not counted: 4,069 responses (at least $64.60) in sessions shared with other PRs that worked in no single PR's checkout.
• 3,083 responses in these sessions worked on other PRs and are counted there.
• Totals reconcile with the measured sessions: yes. Evidence complete: no.
• Prices: list-price estimate from T3 local rate table (path withheld) as of 2026-09-28, schedule 696aae45933d0a684a015d3f08cfb6f1aa2fef02e7d272b4689e3a692ea04fff. Unknown prices stay unknown, never zero.
  • T3 LiteLLM rate table when present; bundled schedule covers the rest.
• Native session usage or worker ownership is unavailable.
• Harness-reported cost: none reported.
• Usage totals are not billing. Subscription spending is separate and is never posted as spend.
• Crashed runs are counted separately: 0.

Token counters by model (native counter semantics; never added across semantics):

Selected rates (USD per million tokens). These rates value the report at the selected schedule date; they do not establish historical prices or subscription spending.

Model	Input tier	Input	Cache read	Cache write	Other output	Reasoning

Other output and reasoning are priced without double counting inclusive native output. Missing rates remain unknown.

_{Local measurement from native records; usage totals are not billing. Updated in place by agent-observer publish.}

[lukemaj]

What: Independent exact-head review of PR #183 found no supported blocking finding in the inspected source scope.
Why: The registered-adapter/unavailable-cache D5 gap is closed by refreshing provider eligibility and validating the requested advertised model before launch.
So what: This review clears the unchanged source candidate; D32 remains a separately approved follow-up.

Exact review

• PR: feat(server): route native agents through shared Prism service #183
• Base: 6627c1afe97378cd0c2e4528dec20e8177acd133 (fork/v2).
• Head: cd6ad61ade9041311738afc3de49961a292a15d4, unchanged from the reviewed candidate.
• Reviewed the three-file 99d0..cd6 correction and integrated Prism selection/launch paths. PR metadata was live-verified against the exact base and head.
• Reviewer: lukemaj, GPT-6-Luna, T3 Code through Codex. I did not author this port.
• No tests, typecheck, lint, or other proof was run by me. The author reports serial proof of 245 cases/21 files, 2 MCP cases, t3 typecheck exit 0, scoped lint exit 0, and fork check 17 owners passing; these remain author-reported results.

Verdict

No supported actionable blocker remains in this source-review scope.

The prior 99d0 trigger was a configured launch choice whose cached provider was unavailable with an empty catalog while a V2 adapter remained registered. validateLaunchSelection now checks adapter registration, reads the existing ProviderRegistry, refreshes once when provider eligibility fails, validates the requested slug or alias against the refreshed model catalog, and returns the canonical model slug (PrismService.ts). The launch handler supplies the existing provider and adapter registry contexts; it adds no infrastructure seam (handlers.ts).

For configured preferences, provider_unavailable and model_unavailable are caught as candidate rejection, allowing Prism to continue in order. The explicit-selection path validates directly and propagates failure without fallback (PrismService.ts). The new handler cases cover still-unavailable refresh, refreshed missing model, recovered first choice, explicit failure, and preservation of fallback effort/runtime mode (handlers.test.ts). This is D5 selection before dispatch; D6 remains the separate same-provider/model retry after a provider turn fails.

Earlier failed reviews remain on their original SHAs: 7142a479b58bcf0520b1c3fd06aaff4d8f1c6dba (Issue finding) and 99d0b3333d2e7438f3fb01c207f68f62d7277999 (Issue finding). D32 per-failure durable linkage remains excluded from this PR and belongs to the separately approved follow-up.

Requirements and who asked: User and #169 require ordered D5 pre-start fallback in delegate_task and t3_thread_launch, with explicit selection precedence; D6 remains same-provider/model retry after a provider turn fails.
Deleted: D32 changes and further recovery scope remain outside this PR.
Bottleneck: Exact-head independent source review was the remaining gate before PR publication; it is clear on this SHA.
Checked myself: Verified PR base/head and authenticated account, read the three-file correction, traced validation errors through configured fallback and explicit selection, and inspected the new cases. No proof process was run by this reviewer.

[lukemaj]

What: Independent exact-head review of PR #183 at a052dbe7597be24c5b3e3e1451506aad6ab25c82 found no supported blocking findings.
Why: The rebase changes only the approved Mission and fork-maintenance wording; all nine implementation patches are unchanged, and the refreshed upstream inventory matches the current diff.
So what: review/independent is success for this exact SHA; the fresh CI run remains pending and must finish green before merge.

Reviewed base 8fc40da4fd603f343f13d6e51676b6f1e091b555 and head a052dbe7597be24c5b3e3e1451506aad6ab25c82. The live PR body carries these same identities. The direct tree delta from the preceding reviewed head 0c790af41cc4a932a046a4bf3f21d43a865d2496 contains only MISSION.md and docs/fork.md; I inspected both wording changes. git range-diff reports = for all nine patches, so the previously inspected source and test inputs are unchanged.

The current PR body lists all 22 upstream-owned paths in separate production, existing-test, and generated sections. I compared its counts to the exact 8fc40da..a052dbe diff; the counts match, including tools.ts +1/-1 and SettingsPanels.restore.test.tsx +5/-2. The larger hunks have reasons, the restore fixture is in the Prism owner entry and upstream allowlist, and the feature map preserves single primary owners and shared overlaps.

The unchanged source review found no actionable defect: provider guidance covers same-provider and cross-provider work; the recovery test database is no longer exported without consumers; Prism constants remain used locally; the removed stream activity constant has no repository consumer; and restore/cancel fixtures invert the actual defaults while keeping assertions unchanged. D32 remains a separately approved follow-up and is not included.

No tests, typechecks, lint, browser, or dev server were run by the reviewer. Existing author proof was reused only where code and inputs were unchanged. At review time the fresh GitHub run had multiple jobs pending; CI is not claimed green. The prior 0c790af review status is error because that candidate was superseded by this rebase; earlier failed-candidate evidence was not waived.

Reviewer: lukemaj, Codex GPT-6-Luna in T3 Code.

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	4.9 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	20.8 KiB	—	29.3 KiB	✅
Codex	Live turn messages	—	1	—	8	✅
Claude	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	21.2 KiB	—	29.3 KiB	✅
Claude	Live turn messages	—	2	—	8	✅

Baseline: unavailable · PR result: 1e9d17a · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[lukemaj]

What: Independent source review of PR #183 at 1e9d17a28f28e28f28df618c73a8a1b5a2a73859 found no supported blocking findings.
Why: The four-file successor delta narrowly repairs stale Muse replay runtime context in test fixtures and updates its single-owner inventory entry.
So what: review/independent is success for this exact SHA; fresh CI must still finish green before merge.

Reviewed base 8fc40da4fd603f343f13d6e51676b6f1e091b555, head 1e9d17a28f28e28f28df618c73a8a1b5a2a73859, the complete a052dbe..1e9d17a delta, and the retained #169 source scope previously reviewed on a052dbe.

The Muse materializer changes only the leading input block of a turn/start expectation when it begins with <runtime_info>. It rebuilds that block from the selected model and frame reasoningEffort, preserving other input blocks and frame fields. The three oracle cases cover absent/present effort and a non-runtime first block. The current Muse fixtures use turn/start; no Muse session/prompt fixture reaches the generic prompt branch.

The existing replay matcher is unchanged and retains exact array length and recursive value matching. The materializer is test-only. The refreshed PR body lists 23 upstream-owned paths; the counts match the current diff, including this helper at +49/-3 with its hunk rationale. The feature map assigns the helper and oracle test to one owner, and the upstream edit allowlist includes the helper.

No production Prism behavior changed in this successor. D32 remains a separate follow-up. I ran no tests, typechecks, lint, browser, or dev server; author-reported proof was read without reruns. At review time several fresh CI test jobs were pending. The a052 CI cancellation and earlier red review evidence were left unchanged.

Reviewer: lukemaj, Codex GPT-6-Luna in T3 Code.