🤖 refactor: Effect Phase 11 PR 4b — staged core layers S4–S8 + CoreWiringLive (imperative core body removed)

[ThomasK33]

Summary

Effect migration Phase 11, PR 4b of 6 — the second half of PR 4 (4a: #4054). The remainder of the core service graph now builds as staged per-service Layers too: MemoryConsolidationLive · MCPConfigLive (S4) → MCPServerManagerLive (S5) → WorkspaceLive (S6) → TaskLive (S7) → WorkspaceTurnManagerLive (S8), and the former imperative body's setter/listener wiring is replayed, in its original order, by CoreWiringLive (Layer.effectDiscard over a synchronous body — no finalizers, no forks). CoreLive = CoreWiringLive ▹ S8; the transitional buildCoreTail / CoreTailProjectionLive from 4a are deleted, so coreServices.ts is now types only (CoreServicesOptions, CoreOptions, CoreServices). Service classes, constructors, facades and every wiring statement are unchanged; the 4a behavioral wiring tests and the PR 3 identity harness pass unchanged against the fully staged graph.

Stacked on PR 1 #4049, PR 2 #4050, PR 3 #4051, PR 4a #4054. Plan: <details> at the bottom.

Implementation

• di/layers/core.ts — six more adapter layers with today's argument lists; CoreWiringLive yields every collaborator it needs and then runs the former wiring lines verbatim: registration probe → bindings.memoryService → bindings.mcpServerManager / streamManager.setMCPServerManager / mcpServerManager.setSecretsResolver → the workspaceService.set* block + bindings.workspaceHeartbeatService/onWorkflowRunStatusChanged/workflowResultContinuationSender → workspaceGoalService.setOnActivityChange/setStreamInterrupter → taskService.setWorkspaceTurnManager / bindings.taskService/workspaceTurnManager / workspaceService.setAgentTaskIntegration → registerGoalContinuationConsumer(idleDispatcher, …). Stage comments record where staging is order-parity rather than dependency (WorkspaceLive at S6).
• coreServices.ts — buildCoreTail, CoreGraphHead, CoreGraphTail deleted; all imports type-only.
• coreServicesRoot.test.ts — the throwing-body test now spies createAgentPluginsMcpProvider inside MCPConfigLive (a nested S4 body) instead of buildCoreTail; the wiring test additionally pins the remaining edges (workspaceService's MCP manager / goal service / task integration / memory consolidation / MCP overrides collaborators, taskService's turn manager, and the goal service's activity fan-out and stream interrupter — each exercised through a spy). Red-checked: commenting out a single CoreWiringLive line (setAgentTaskIntegration) fails it. Every other test is unchanged.

PR 4 notes (4b)

DAG (re-derived in 4a, unchanged) and stage placement

Service	Constructor dependencies (tags)	Stage
MemoryConsolidationService	Config, Memory, MemoryMeta, History, AI, Options, SessionUsage	S4
MCPConfigService	Options, Config, AI (workspaceMetadataProvider)	S4 (true sibling of Consolidation: neither reads the other)
MCPServerManager	MCPConfig, Config, Options, WorkspaceMcpOverrides	S5
WorkspaceService	Config, History, AI, InitState, ExtensionMetadata, BackgroundProcess, SessionUsage, Options, StreamManager, SecretsStore, ProvidersConfigStore	S6 by order-parity, not dependency — its constructor needs nothing beyond S3; the MCP manager / consolidation collaborators arrive through CoreWiringLive setters. Staged after MCPServerManager to keep the former body's construction order (comment in code)
TaskService	Config, History, AI, Workspace, InitState, SessionUsage, WorkspaceGoal, SecretsStore, TerminalAttention	S7
WorkspaceTurnManager	Config, History, AI, Workspace, InitState, Task, TerminalAttention, StreamManager	S8
CoreWiringLive	Config, SecretsStore, Options, WorkspaceMcpOverrides + every core tag it wires	after S8 (Layer.effectDiscard)

I6 constructor side-effect audit (the six moved here; the 4a table covers the head)

Constructor (layer)	Side effects at construction	On declared args only?	Order-sensitive?
MemoryConsolidationService (S4)	sidecar path only	✓	no
MCPConfigService (S4)	asserts/fields	✓	no
MCPServerManager (S5)	own unref'd setInterval(cleanupIdleServers)	✓ (self)	no
WorkspaceService (S6)	backgroundProcessManager.on ×5, aiService.on ×6, initStateManager.on, extensionMetadata.setTombstoneClearedListener, module-global setWorkflowArchiveAdmissionGuard, starts recoverBashMonitorStateAfterRestart()	✓ — never touches its setter-provided collaborators (mcpServerManager, memoryConsolidationService, workspaceGoalService, agentTaskIntegration, …)	listener order on aiService/backgroundProcessManager vs TaskService — preserved, Task depends on Workspace
TaskService (S7)	aiService.on ×3, new AgentPeerMessageBroker(workspaceService), new GitPatchArtifactService(config)	✓	registered after WorkspaceService's listeners, guaranteed by staging
WorkspaceTurnManager (S8)	new TaskHandleStore(config)	✓	no

Wiring relocation vs main/4a: every wiring statement runs in CoreWiringLive after all constructors, in the original relative order. The constructors that used to run between wiring lines (WorkspaceService after W3–W5, TaskService/WorkspaceTurnManager after W6–W15, IdleDispatcher after W16–W19) read none of the wired state at construction (table above; TaskService's getWorkspaceTurnManager() call sits inside an event listener, recoverBashMonitorStateAfterRestart() suspends on I/O before anything could observe the setters, and the whole graph — construction plus wiring — completes inside one synchronous runSync build, exactly as the former body completed synchronously).

Deviations from the plan

• Stage placement keeps the plan's S4…S8 order even where the DAG would allow siblings (WorkspaceService at S6, see above) — construction-order parity over a shorter graph; recorded in the stage comment.
• CoreWiringLive is a Layer.effectDiscard over an Effect.gen body whose only yields are service tags (synchronous); it registers no finalizers and forks nothing (I5).
• Test change: the throwing-body spy target moved from buildCoreTail (deleted) to createAgentPluginsMcpProvider inside MCPConfigLive — a stronger probe, since the throw now originates in a nested S4 layer body.

Pre-review audits (plan §3)

1. Interruption posture — no new or moved fiber forks (CoreWiringLive body is synchronous; rg 'fork' src/node/services/di/layers/ → none).
2. Uninterruptible teardown — unchanged.
3. No defect escapes — a throw in a nested layer body (S4) surfaces as the synchronous throw from makeAppRuntime (pinned by the updated root test); the desktop root's equivalent is unchanged (serviceContainer.test.ts).
4. Spy-seam check — no constructor signature changed; the only test-visible change is the spy target above (buildCoreTail had one spy, in coreServicesRoot.test.ts).
5. Sync-start — unchanged.
6. I6 — table above.
7. Zero-suspension (I3) — MemoryConsolidationService is constructed by MemoryConsolidationLive with the same arguments; no lookup/await inserted near its funnels (its class is untouched).

Re-recorded gate numbers (R7/R8, fully staged graph)

Same methodology as 4a/PR 3 (sibling worktrees under one scratch dir, shared node_modules, interleaved; origin/main = c24d1db10 (4a merged) vs this branch at a4154cf19, rebased afterwards onto fb68404fc without touching shared code; host load ≈ 150–190, CPU PSI some avg60 ≈ 33–36 %).

(a) Typecheck — make typecheck's command, 5 interleaved pairs: main 11.10 s (10.49–11.86) vs branch 10.79 s (10.65–11.24) → −2.8 % (noise). tsgo --extendedDiagnostics (3 interleaved runs): renderer types 1 929 976 → 1 931 000 (+0.05 %), instantiations 7 779 050 → 7 780 247 (+0.02 %), check time medians 8.30 → 8.52 s; main project types 1 048 460 → 1 049 239 (+0.07 %), instantiations 4 253 308 → 4 254 490 (+0.03 %), check time 3.69 → 3.67 s. Cumulative over PR 3 → 4a → 4b the compiler-work counts moved < 0.2 %; R8 stays closed.

(b) Startup — xum server --no-auth, fresh XUM_ROOT, script -f, 10 interleaved pairs (order alternated), SIGTERM ≈ 1 s after initialize completed:

metric	origin/main (4a)	branch (4b)	note
[startup] AppRuntime built ms (median, min–max)	15 (14–26)	23 (17–74)	+≈8 ms cold on a heavily loaded host (three branch outliers ≥ 50 ms coincided with load spikes; the cluster is 17–25). In-process construction (new ServiceContainer, 3 processes × 15): cold 21.7/23.8/22.9 → 73.8/49.6/30.7 ms, warm median 1.34/1.63/2.01 → 2.63/1.71/1.51 ms, warm min 0.82–0.99 → 0.94–1.47 ms
ServiceContainer.initialize completed { totalMs }	89 (83–92)	85.5 (41–305)	within noise (unchanged code)
SIGTERM → exit wall, exit code	166 ms (127–187), 0 ×10	146 ms (144–166), 0 ×10	[shutdown] AppFiberScope closed → explicit steps → [shutdown] AppRuntime disposed in every transcript

Cumulative construction cost of the peel (PR 3 baseline 12 ms → 4a 18 → 4b 23 ms cold median; warm ≈ +0.5–1 ms): the Layer machinery's first-use cost for 19 layers + 8 stages + the wiring layer. Recorded against R7; startup remains dominated by initialize() and the renderer.

Lessons for PR 5 (DesktopLive group layers + DesktopWiringLive + thin ServiceContainer + StreamManager runner param)

• Group layers, not per-service, for the 45 desktop services (plan D1): the cold-construction cost above scales with layer count, so Layer.effectContext groups with today's construction order inside each are the right granularity there.
• DesktopWiringLive should follow CoreWiringLive's shape exactly: yield every collaborator first, then the former constructor's statements verbatim in order (serviceContainer.ts analytics aiService.on(...)/workspaceService.on(...) blocks, setGlobalCoderService/setSshPromptService, core.turnRequestBuilderBindings.analyticsService = …). Listener registration order on aiService matters between WorkspaceService/TaskService (core) and the desktop analytics listeners — desktop wiring runs after CoreLive, which preserves today's order.
• The ServiceContainer constructor still reads the core back with coreServicesFromContext and then constructs the desktop tail; when it thins to field assignment from Context.get, keep the two aiService-listener orders and the BackupService/BrowserBridgeTokenManager positions (PR 3 moved them after the core; harmless, audited).
• StreamManager's optional trailing runner param: WorkersLive gets EffectRunnerTag; StreamManagerLive (S2b) can pass yield* EffectRunnerTag only if EffectRunnerLive stays beneath CoreLive in both roots — it does (runtimeSeams at the base of AppLive and CoreRootLive).
• Test seams to keep: spyOn(appLayers, "AppLive") (TestClock injection and the throwing-layer test) and the coreServicesRoot.test.ts harness; both survived 4a/4b unchanged.
• Host flakes seen during PR 4 (none code-related; all reproduce on pristine main here): bun 1.2.15 Illegal instruction mid-suite, tools/workflow_run.test.ts wedge (3/3 on pristine main in isolation; it also cancelled 4a's first merge-group run — re-enqueue the same head), bashMonitorWakeReconciler/workspaceService bash-monitor-wake order flakes, AttachmentService … newest first, BackupRepoCache ×7, taskGitPatchEngine ×2, WorkspaceTurnManager terminal recovery ×2, agent_skill_delete.

Validation

• make static-check green (typecheck both projects incl. the @ts-expect-error test, lint, fmt, docs).
• bun test src/node/services (every file; the wedging backup/ and tools/workflow_run.test.ts run separately): 6 466 pass; the 8 failures are the environment baselines above, identical on pristine origin/main on this host. bun test src/cli + named PR 4 gate (streamManager*, aiService, workspaceService*) + coreServicesRoot/serviceContainer/di 883/883. jest tests/ipc/{doubleRegister,savedQueries,windowTitle,acp.disconnectCleanup} 18/18.
• Dogfooding (headless Coder host, XUM_LOG_LEVEL=debug): xum workflow echo run: AppRuntime built → ok from pr4b → AppFiberScope closed → terminateAll() → AppRuntime disposed → exit 0. xum server graceful quit 10/10 exit 0 (table). Dev-server sandbox: AppRuntime built {ms: 14}, initialize completed {totalMs: 382} (seeded config); via agent-browser added a scratch repo as a project, sent "Reply with exactly the single word: pong" → worktree workspace created, model replied pong (screenshot in the workspace chat shows v0.28.3-nightly.148-20-ga4154cf19), no ManagedRuntime disposed/defect lines; SIGTERM → exit in 173 ms with [shutdown] AppFiberScope closed {ms: 1} … [shutdown] AppRuntime disposed {ms: 1}. Not exercised headless: Electron before-quit (same ServiceContainer.dispose(); tests/e2e in CI) and the oRPC memory pin/unpin round-trip (effectBridge.test.ts + identity tests).

Risks

• Low–medium. The wiring relocation is the one behavioral surface: every statement is verbatim and in order, all constructors that used to run between wiring lines are audited as not observing them (I6 table), and the 4a behavioral wiring tests pass unchanged. A throwing layer body still surfaces as the synchronous constructor-style throw (tests, now from a nested S4 body).
• Startup: +≈8 ms cold construction on top of 4a (measured), no initialize() change.

---

📋 Implementation Plan

Effect migration — Wave 3 / Phase 11: ManagedRuntime + Layer dependency injection

0. Summary

Replace the two hand-written composition roots (createCoreServices + the ServiceContainer constructor) with an Effect Layer graph built once per process by a ManagedRuntime ("AppRuntime"), while keeping every service class, constructor signature, Promise facade, private method, and test seam compatible. The runtime becomes (a) the owner of the app-lifetime Scope, (b) the provider of "effect/context" for oRPC Effect-native handlers, and (c) the source of two runtime seams: an EffectRunner (context-bound, unsupervised runner that lets clock-driven workers run on a TestClock) and an AppFiberScope (a runtime-owned, supervised scope whose close is awaited by dispose() — the slot the streamManager engine core will occupy later).

Six stacked, independently mergeable PRs. Product PRs keep existing tests unchanged; only the final test-modernization PR edits tests. Net product LoC ≈ +420 (per-PR estimates below). Service classes are not rewritten — Layers are thin adapters around existing constructors; cycle-breaking setter wiring moves into explicit "wiring layers" that replay today's order.

Unlocks (not done here): streamManager ENGINE CORE conversion, TestClock for timing suites, app-lifetime scopes.

1. Verified current state (evidence)

• Roots. src/node/services/coreServices.ts:103-389 (createCoreServices: 25 constructions, 12 turnRequestBuilderBindings writes, ~14 setters) and src/node/services/serviceContainer.ts:161-575 (45 more constructions; aiService.on(...)/workspaceService.on(...) analytics wiring at 474-574; global registrations setGlobalCoderService/setSshPromptService at 469-471). new ServiceContainer(stores) is called by headlessEnvironment.ts:111, tests/ipc/setup.ts, src/cli/server.ts:132, src/node/acp/serverConnection.ts:155, src/desktop/main.ts:653; src/cli/run.ts:661 and src/cli/workflow.ts:376 call createCoreServices directly. ⇒ two graph roots (App vs Core), five process entry points, all constructing synchronously.
• Startup. ServiceContainer.initialize() (577-642) awaits six initialize()s (no try/catch; failure propagates to main.ts:1255-1265 "Startup Failed" dialog + quit; server.ts/ACP log and exit), then sync start()s idleCompaction/heartbeat/agentStatus, then two fire-and-forget sweeps. All constructors are synchronous; two have side effects on declared constructor dependencies only (AIService → streamManager.setEventSink, WorkspaceService → backgroundProcessManager.on/aiService.on).
• Teardown. dispose() (746-779) is explicit and hand-ordered (backgroundProcessManager.beginShutdown() MUST be first — it is a latch protecting persisted monitor records; bridges stop before sessions close; terminateAll late; timelineService.flush() last). shutdown() (718-732) is a second sequence fired concurrently by a second before-quit listener (main.ts:1321). main.ts:1296-1304 races dispose() against 5 s then app.quit(); cli/server.ts:227-268 has a 5 s process.exit(1) force timer; tests/ipc cleanup calls dispose() then shutdown(); headlessEnvironment.dispose never calls services.dispose().
• Existing Effect surface. 25 files import effect. Only Context.Service tag: MemoryMeta (src/node/orpc/effectContext.ts:21). handlerGen (@orpc/experimental-effect) runs Effect.runPromiseExit per request and Effect.provides opts.context["effect/context"]. streamBridge.ts runs streams on the global runtime. Scope-owning workers: heartbeatService.ts:134-243, idleCompactionService.ts:86-122 (Scope.makeUnsafe + Effect.runSync(Scope.close(..)), valid only because their fibers suspend solely on the clock), oauthFlowManager.ts:164, streamManager.ts:4767/4054 (already Effect.runFork(Scope.close(..)) — the async-close precedent). memoryConsolidationService.ts:667-703, 837-860: check-and-reserve funnels with zero suspensions before inFlight.set/harvestInFlight.set.
• effect@4.0.0-rc.112 API (verified in node_modules/effect/dist). Context.Service<Self, Shape>()("id") (module Context, not ServiceMap); Layer.{succeed,sync,effect,effectContext,effectDiscard,provide,provideMerge,mergeAll,build,buildWithScope} (no Layer.scoped; Layer.effect strips Scope from R); ManagedRuntime.make(layer) → { runSync, runSyncExit, runFork, runPromise, runPromiseExit, contextEffect, cachedContext, scope, dispose(), disposeEffect }; Effect.{runSyncWith,runForkWith,runPromiseWith,runPromiseExitWith}(context); Effect.context<R>(); Effect.serviceOption; Scope.{fork,forkUnsafe,close,provide}; TestClock from effect/testing (layer, adjust, setTime, withLive); Clock.Clock is a Context.Reference (defaulted; TestClock.layer() overrides it).
• ManagedRuntime internals the design relies on (ManagedRuntime.js): make creates scope = Scope.makeUnsafe("parallel") and layerScope = Scope.forkUnsafe(scope, "sequential"); the first runX forks a build fiber over Layer.buildWithMemoMap — a fully synchronous layer graph builds synchronously, so runtime.runSync(Effect.context()) succeeds and sets cachedContext; afterwards every runX is Effect.run…With(cachedContext) (no extra async boundary). Fibers started through runtime.runX are registered in scope (onFiberStart: Fiber.runIn(scope)). dispose() = Scope.close(scope) (interrupt registered fibers in parallel → layer finalizers sequentially in reverse), after which any runtime.runX dies with "ManagedRuntime disposed".
• Layer composition semantics. Layer.mergeAll(A, B) is not a dependency resolver: B's requirements are not satisfied by A's outputs; requirements bubble up. Dependencies are satisfied only via Layer.provide/provideMerge chains. Siblings in mergeAll may build concurrently.
• Test seams that pin signatures (Explore report): private-method spies (Config.saveConfig, WorkspaceService.retireKernelWorkflowRunReferences/startStartupRecovery/createSession/updateAgentStatus, MCPServerManager.startServers, AgentPluginInstallService.reconcileJournals, …); module-level export spies (agentStatusService.generateWorkspaceStatus, sshConnectionPool.verifyHostKeyAgainstPolicyEffect, …); direct construction in tests (Config 44 files, HistoryService 22, MemoryMetaService 11, WorkspaceService 7, IdleDispatcher 6, StreamManager 4, ServiceContainer 3); partial-mock casts (InitStateManager 193, AIService 158, TaskService 149, ORPCContext 62). effectBridge.test.ts:24-30 builds a partial ORPCContext via buildOrpcEffectContext + as unknown as ORPCContext.
• Timing probes (TestClock candidates): heartbeatService.test.ts 6 real sleeps, idleCompactionService.test.ts 2, retryManager.test.ts 3 setSystemTime, streamManager.test.ts 7 (partial-write debounce), streamBridge.test.ts 11 (heartbeat ticker), OAuth device-flow suites 14 (non-goal).

2. Target architecture

2.1 Building blocks (all under src/node/services/di/; the only directory allowed to import Layer/Context/ManagedRuntime/TestClock)

Module	Contents
tags.ts	One Context.Service tag per service class provided by the graph. Type-only imports of service classes ⇒ no runtime import cycles. Ids "xum/<Name>". Naming: class name minus trailing Service (MemoryMeta, Workspace, History); classes without that suffix or colliding with an exported name get a Tag suffix (ConfigTag, StreamManagerTag, IdleDispatcherTag). Exports the unions CoreTags and AppTags.
effectRunner.ts	interface EffectRunner { runSync<A,E>(e: Effect<A,E,never>): A; runSyncExit; runFork; runPromise; runPromiseExit } — a context-bound, unsupervised runner whose methods accept only effects with no service requirements (R = never; defaulted references like Clock do not appear in R). That makes "not a service locator" type-enforced: a fiber that needs services must take them as explicit constructor dependencies and, if it must be awaited on shutdown, fork into AppFiberScope. defaultEffectRunner = the global Effect.runX (today's exact behavior). effectRunnerFromContext(ctx) = Effect.run…With(ctx). EffectRunnerTag + EffectRunnerLive = Layer.effect(EffectRunnerTag, Effect.map(Effect.context<never>(), effectRunnerFromContext)), placed at the base of the graph so the captured context contains only refs (Clock, later Logger/Random) plus stores. Fibers forked through it are owned by the worker's own Scope (explicit start/stop), not by the ManagedRuntime; runtime.dispose() does not interrupt them. Services import only this file from di/.
appFiberScope.ts	AppFiberScopeTag: Scope.Closeable. AppFiberScopeLive = Layer.effect(AppFiberScopeTag, Effect.gen(function*(){ const parent = yield* Effect.scope; return yield* Scope.fork(parent, "parallel"); })) — a child of the runtime's layer scope. Fibers forked into it via Effect.forkIn(_, appFiberScope) are interrupted and awaited when the scope closes. This is the supervised seam for I/O-suspended fibers (engine core, later). ServiceContainer.dispose() closes it explicitly and early (§5) so interrupted fibers can still use their dependencies during finalization; runtime.dispose() later re-closes it idempotently as a backstop. No production occupant in Phase 11; the seam exists with tests.
appRuntime.ts	makeAppRuntime(layer): ManagedRuntime.make(layer) + eager synchronous build (runtime.runSync(Effect.context<R>()); assert(runtime.cachedContext !== undefined)); a layer body that suspends is a programming error and throws here — exactly where a throwing constructor throws today, so every entry point's existing catch/dialog/log path is preserved. disposeAppRuntime(runtime, timeoutMs) and closeScopeBounded(scope, timeoutMs) share one shape: Effect.uninterruptible teardown shell around Effect.interruptible(target.pipe(Effect.timeout(timeoutMs))) where target is runtime.disposeEffect resp. Scope.close(scope, Exit.void) (never a non-cancellable JS Promise wrapper); Effect.catchTag("TimeoutError", …) + Effect.catchDefect → log.warn; run via Effect.runPromise; never rejects; idempotent (Scope.close is idempotent; disposeEffect is guarded by a latch). Verify the exact rc Effect.timeout error type at implementation time (rc.112: fails with Cause.TimeoutError, _tag: "TimeoutError"). Module doc comment = the DI contract (§2.3, §5).
layers/stores.ts	StoresLive(stores: ConfigStores) = Layer.mergeAll of Layer.succeed for ConfigTag, SessionLocatorTag, ProvidersConfigStoreTag, SecretsStoreTag, FileLeaseManagerTag (true siblings — no inter-dependencies). StoresFromCoreOptionsLive reproduces the opts.x ?? new X(config.rootDir) defaults of coreServices.ts:106-112 for the CLI root.
layers/core.ts	CoreOptionsTag (today's CoreServicesOptions minus stores — carries the optional cross-cutting services exactly as today). PR 3: CoreProjectionLive = Layer.effectContext(...) wrapping the existing createCoreServices body and returning a Context<CoreTags> (coarse projection, zero behavior change). PR 4: peel into per-service Layer.effect(Tag, Effect.gen(...)) layers composed in explicit dependency stages (Layer.provideMerge between stages; Layer.mergeAll only for true siblings within a stage — every sibling claim below was checked against the constructor argument lists in coreServices.ts and must be re-checked in the PR): S1 History · InitState · Provider · BackgroundProcess · ExtensionMetadata · MemoryMeta · TerminalAttention · IdleDispatcher · WorkspaceMcpOverrides(default) · TurnRequestBuilderBindingsTag (Layer.succeed(_, {})) → S2a SessionUsage · Goal · Memory → S2b StreamManager (needs SessionUsage) → S3 AIService → S4 Consolidation · MCPConfig → S5 MCPServerManager → S6 Workspace → S7 Task → S8 TurnManager → CoreWiringLive (Layer.effectDiscard, Effect.sync only — no acquireRelease, replays coreServices.ts:137-166, 209-210, 258-270, 288-325, 349-352, 360-367 in order).
layers/desktop.ts	CrossCuttingLive (policy, telemetry, experiments, backup, sessionTiming, analytics, devTools, workspaceMcpOverrides, browserBridgeTokenManager), CoreOptionsFromDesktopLive (derives CoreOptionsTag from those tags + extensionMetadataPath), then group layers (Layer.effectContext returning a Context of several tags, constructed in today's order): BrowserLive, DesktopBridgeLive, OauthLive, WorkersLive (idleCompaction, heartbeat, agentStatus, timeline, refine), TerminalEditorLive, MiscDesktopLive; staged with provideMerge where one group needs another. DesktopWiringLive (Effect.sync only) = setters + aiService.on/workspaceService.on/memoryConsolidationService.on wiring + global registrations.
layers/app.ts	AppLive(stores) = DesktopLive ▹ CoreLive ▹ CoreOptionsFromDesktopLive ▹ CrossCuttingLive ▹ AppFiberScopeLive ▹ EffectRunnerLive ▹ StoresLive(stores) — read X ▹ Y as "X is provided with Y, and both stay exposed", i.e. X.pipe(Layer.provideMerge(Y)) (rc.112 signature: provideMerge(that: provider)(self: consumer); the right-hand operand is the dependency). Every ▹ keeps all tags visible in the final Context<AppTags>.
testEffectRunner.ts (test helper, sibling of testHistoryService.ts)	makeTestEffectRunner() → { runner, adjust(duration), setTime(ms), dispose } over one memoised ManagedRuntime.make(EffectRunnerLive.pipe(Layer.provideMerge(TestClock.layer()))) (the TestClock is the provider; the runner captures it), so the worker under test and TestClock.adjust share one TestClock.

2.2 Composition roots after Phase 11

flowchart TB
  Stores["StoresLive(stores)<br/>Config · SessionLocator · ProvidersConfigStore · SecretsStore · FileLeaseManager"]
  Runner["EffectRunnerLive (unsupervised, ref-bound)<br/>+ AppFiberScopeLive (supervised, closed on dispose)"]
  Cross["CrossCuttingLive (desktop only)<br/>Policy · Telemetry · Experiments · Analytics · SessionTiming · DevTools · WorkspaceMcpOverrides · Backup"]
  Opts["CoreOptionsTag<br/>desktop: derived from CrossCutting · CLI: Layer.succeed(opts)"]
  Core["CoreLive<br/>PR 3: coarse CoreProjectionLive → PR 4: stages S1…S8 + CoreWiringLive"]
  Desk["DesktopLive — group Layers<br/>Browser · DesktopBridge · OAuth · Workers · TerminalEditor · Misc → DesktopWiringLive"]
  RT["AppRuntime = ManagedRuntime.make(AppLive)<br/>eager sync build · Context<AppTags> = oRPC effect/context · dispose() last"]
  Stores --> Runner --> Cross --> Opts --> Core --> Desk --> RT
  CLI["CLI root (xum run / xum workflow)<br/>createCoreServices(opts) = makeAppRuntime(CoreLive ▹ StoresFromCoreOptionsLive ▹ AppFiberScopeLive ▹ EffectRunnerLive ▹ succeed(CoreOptionsTag, opts))"]
  Core -.same Layer definitions.-> CLI

Loading

ServiceContainer keeps its public fields and the synchronous new ServiceContainer(stores): the constructor calls makeAppRuntime(AppLive(stores)), stores this.serviceContext = runtime.runSync(Effect.context<AppTags>()), and assigns fields via Context.get(this.serviceContext, Tag). toORPCContext() returns the same plain fields plus "effect/context": this.serviceContext. initialize() is untouched. dispose() follows §5.

createCoreServices(opts) keeps its signature and return shape plus runtime and appFiberScope fields; cli/run.ts:1574-1580 and cli/workflow.ts:275-320 cleanup lists gain closeScopeBounded(appFiberScope) before session.dispose() and disposeAppRuntime(runtime) as the final step (PR 3).

Staged composition skeleton (PR 4 shape; direction matters):

// Each stage depends only on stages defined above it. `provideMerge` keeps both sides exposed.
const S1 = Layer.mergeAll(HistoryLive, InitStateLive, ProviderLive, /* … true siblings only */);
const S2a = Layer.mergeAll(SessionUsageLive, GoalLive, MemoryLive).pipe(Layer.provideMerge(S1));
const S2b = StreamManagerLive.pipe(Layer.provideMerge(S2a));          // StreamManager needs SessionUsage
const S3 = AIServiceLive.pipe(Layer.provideMerge(S2b));
// … S4 … S8 likewise …
export const CoreLive = CoreWiringLive.pipe(Layer.provideMerge(S8));  // wiring runs after every service exists

oRPC typing. OrpcEffectServices (in effectContext.ts) becomes AppTags, so ORPCContext["effect/context"]: Context<AppTags> is satisfied by the runtime context in production. buildOrpcEffectContext stays as the narrow test helper it already is (its only caller, effectBridge.test.ts:24-30, deliberately builds a partial context and casts it via unknown); no production caller remains after PR 1.

2.3 Invariants (the "DI contract"; enforced by tests and the appRuntime.ts doc comment)

#	Invariant	Constraint served
I1	Phase 11 compatibility contract, not permanent law: layer bodies are synchronous (Layer.succeed/Layer.sync/Layer.effect over sync effects; acquireRelease with a sync acquire is fine). makeAppRuntime asserts the eager build completed. Future async resource acquisition belongs in initialize()/startup effects or an explicit async factory root (ServiceContainer.create()), never silently inside a layer.	#2 sync-start, #5 startup parity
I2	Services never hold the ManagedRuntime. Workers hold an EffectRunner (default defaultEffectRunner); EffectRunner.runX ≡ Effect.run…With(ctx) — same sync-start semantics as Effect.runX, and still valid after runtime.dispose(), so late callbacks cannot hit "ManagedRuntime disposed". Supervision, when needed, is explicit via AppFiberScope.	#2, #3
I3	Per-call pipelines (Effect.runPromise(this.effects…) facades) and the memoryConsolidationService funnels are untouched. Audit item: no DI lookup, runner call, or await may be inserted before inFlight.set / harvestInFlight.set. Only lifecycle forks in workers move to this.runner.runX.	#1, #2
I4	Constructors, facades, private methods, module exports unchanged; new constructor parameters are optional, trailing, defaulting to defaultEffectRunner.	#1, #6
I5	Teardown order stays explicit in dispose()/shutdown(). Layer bodies and wiring layers register no finalizers in Phase 11 (Effect.sync only), so runtime.dispose() reorders nothing. The one supervised resource (AppFiberScope) is closed explicitly at a fixed position in dispose() (§5).	#3
I6	Wiring layers replay today's setter/listener order; a constructor may touch only its declared dependencies (built earlier by staging). Per-PR audit: grep each moved constructor for calls on setter-provided collaborators → forbidden. Dependency order is expressed only with provide/provideMerge stages; never rely on mergeAll sibling order.	#6
I7	No persisted-data changes; DI is in-process only.	#4
I8	Every process root builds from the same Layer definitions (CoreLive shared by App and CLI). Unit harnesses (createTestHistoryService, createTestToolConfig, createAgentSessionHarness, …) intentionally bypass Layers.	#7

2.4 Decisions and alternatives (product-LoC deltas)

D1 — Granularity: coarse core first (PR 3), per-service core stages behind a decision gate (PR 4), group layers for the desktop tail (PR 5)

Honest framing: the three unlocks (engine-core async scope, TestClock, app-lifetime scope) are delivered by AppRuntime + EffectRunner + AppFiberScope and do not require per-service layers. Per-service core layers are migration leverage: typed requirement sets for the engine-core work, per-service swap in integration tests, explicit dependency stages instead of implicit ordering.

• (A) Per-service everywhere (~70 layers): +900/−700. Desktop tail has hand-tuned teardown that must not become finalizers, so per-service there buys uniformity only. Rejected.
• (B) Recommended: PR 3 coarse CoreProjectionLive (+120/−10) delivers the shared root and runtime ownership; PR 4 peels the core into staged per-service layers (+330/−290) only if PR 3's typecheck/startup budgets hold (gate in §3); desktop tail as ~6 group layers (+170/−150). Tags for all services either way (~3 LoC each).
• (C) Coarse only: stop after PR 3 + desktop projection (~+200 total). Cheapest; the engine-core phase would then redo dependency declarations. Remains the fallback if PR 4's gate fails.

D2 — Async init stays an explicit `initialize()`; Layers construct only

Folding initialize() into layer construction would make the build asynchronous (breaks I1), change failure semantics (today: fail-fast → dialog/log), and move the six-step order into memoised builds. Deferred; a later phase can turn initialize() into runtime.runPromise(startupEffect) with per-step Effect.timeout.

D3 — Optional cross-cutting services stay optional via `CoreOptionsTag`, not `Effect.serviceOption`

Core layer bodies read opts.policyService etc. exactly as today, so CLI (absent) vs desktop (present) behavior is unchanged and no service gains a new undefined branch.

D4 — Two seams instead of one: `EffectRunner` (unsupervised, clock-bound) + `AppFiberScope` (supervised)

A single "runtime handle" conflates two needs. Workers need which clock (TestClock) and must keep sync stop(); the engine core needs who awaits me on shutdown. Explicit Clock injection per worker was rejected (a provideService(Clock.Clock, …) at every fork site, and it does not extend to other refs).

D5 — oRPC: `effect/context` = the runtime's `Context`; `handlerGen` unchanged

handlerGen already Effect.provides the context per request; providing ~70 entries instead of one is one Map merge per request. The existing echoAsync/echoEffect probes record the delta as a diagnostic in the PR body (no stable benchmark harness exists to make it a hard gate). effect/wrap not needed.

3. Phasing — six stacked PRs

Every PR: make static-check; gate suites below; existing tests unchanged (PR 6 is the only PR that edits tests, and only to replace real-timer probes). Before @codex review, run the house pre-review audits:

1. Interruption posture — list every new/moved fiber fork; state what interrupts it and when (unsupervised via EffectRunner + worker scope, or supervised via AppFiberScope).
2. Uninterruptible teardown — teardown effects are Effect.uninterruptible end-to-end; bounded waits inside use Effect.interruptible(Effect.timeout(...)) (house shape from 🤖 refactor: convert memoryConsolidationService and workspaceStatusGenerator internals to Effect; make in-flight run-lock reservation deterministic #4038).
3. No defect escapes — disposeAppRuntime/closeScopeBounded and every Promise facade fold defects; makeAppRuntime is the one place allowed to throw (constructor semantics).
4. Spy-seam check — rg 'spyOn\(' src/node/services/<touched>.test.ts tests/ per touched class; constructor arity and private-method Promise signatures unchanged (typecheck of tests proves it).
5. Sync-start check — a fork through EffectRunner runs to its first sleep before runFork returns (mirrors heartbeatService.ts:199-202).
6. Constructor side-effect audit (I6) for every constructor moved into a Layer in that PR.
7. Zero-suspension audit (I3) whenever memoryConsolidationService is in the diff.

PR 1 — Skeleton: AppRuntime + Stores/MemoryMeta layers + runtime-backed effect/context + dispose hook (+~150 LoC)

Scope

• di/tags.ts (ConfigTag, SessionLocatorTag, ProvidersConfigStoreTag, SecretsStoreTag, FileLeaseManagerTag, MemoryMeta moved from orpc/effectContext.ts, which re-exports it; AppTags union).
• di/layers/stores.ts (StoresLive), di/layers/core.ts with MemoryMetaLive = Layer.effect(MemoryMeta, Effect.map(ConfigTag, c => new MemoryMetaService(c.rootDir))), di/layers/app.ts (AppLive(stores) = MemoryMetaLive ▹ StoresLive).
• di/appRuntime.ts (makeAppRuntime, disposeAppRuntime); APP_RUNTIME_DISPOSE_TIMEOUT_MS in src/constants/.
• coreServices.ts: CoreServicesOptions.memoryMetaService? (precedent: workspaceMcpOverridesService?).
• serviceContainer.ts: build runtime first, pass Context.get(ctx, MemoryMeta) to createCoreServices, public readonly runtime, toORPCContext()["effect/context"] = this.serviceContext, dispose() appends disposeAppRuntime behind a disposed latch; new log.debug("[startup] AppRuntime built", { ms }).
• orpc/effectContext.ts: OrpcEffectServices = AppTags; buildOrpcEffectContext retyped/test-helper doc.
• headlessEnvironment.dispose calls await services.dispose() before removing the temp dir (the bench harness currently leaks the container; runtime ownership starts here).

Acceptance

• di/appRuntime.test.ts: (a) sync build sets cachedContext; (b) a layer with an async body makes makeAppRuntime throw synchronously (I1 enforced); (c) probe layers' finalizers run in reverse order on dispose; (d) dispose is idempotent and bounded (hung finalizer → warn, resolves at the timeout); (e) runtime.runFork after the eager build starts synchronously.
• serviceContainer.test.ts: Context.get(toORPCContext()["effect/context"], MemoryMeta) === services.memoryMetaService; dispose() closes the runtime; dispose(); shutdown() (tests/ipc order) is clean; a throwing layer surfaces as a synchronous throw from new ServiceContainer(stores) (same shape as today's constructor throw → existing entry-point catch paths).
• effectBridge.test.ts, memoryMeta*.test.ts unchanged and green; echo-probe overhead recorded in the PR body.
• Gate: bun test src/node/services/di src/node/services/serviceContainer.test.ts src/node/orpc src/node/services/memoryMeta* · make test-integration · make static-check.

Rollback: git revert; classes untouched.

PR 2 — Runtime seams: EffectRunner + AppFiberScope; TestClock on idleCompaction/heartbeat/retryManager (+~140 LoC)

Scope

• di/effectRunner.ts, di/appFiberScope.ts; AppLive gains AppFiberScopeLive ▹ EffectRunnerLive at the base; ServiceContainer exposes appFiberScope (used only by dispose() in Phase 11) and closes it per §5.
• IdleCompactionService, HeartbeatService, RetryManager: trailing optional runner: EffectRunner = defaultEffectRunner; every lifecycle Effect.runSync/runFork in start/stop/schedule/cancel becomes this.runner.runX. Deadline math (Date.now()/injected now) unchanged. ServiceContainer passes Context.get(ctx, EffectRunnerTag) to the two workers; RetryManager keeps the default until PR 5 (so streamManager.ts is untouched here).
• di/testEffectRunner.ts helper.

Acceptance

• New TestClock tests (existing real-timer tests untouched — they exercise the defaultEffectRunner path, which is production behavior wherever no runner is injected): heartbeat STARTUP_DELAY_MS → first tick after adjust, one tick per CHECK_INTERVAL_MS, no ticks after stop(); idleCompaction initial delay + cadence; retryManager fires exactly at delayMs, cancel() before adjust never fires.
• Pin runtime facts: runner.runSync(Scope.close(scope, Exit.void)) completes synchronously for a fiber suspended on a TestClock sleep; runFork through the runner reaches its first sleep synchronously; Effect.context<never>() inside EffectRunnerLive sees the upstream TestClock (else the helper provides Clock.Clock explicitly — same seam, one line).
• AppFiberScope contract tests: (i) an I/O-suspended fiber (interruptible Effect.async that never resolves, with a cancel path) forked with Effect.forkIn(_, appFiberScope) is interrupted and awaited by closeScopeBounded(appFiberScope) — and this happens before the explicit teardown steps in dispose() (assert ordering against a spy on desktopBridgeServer.stop); (ii) a fiber forked via EffectRunner is not interrupted by either close (documents the asymmetry); (iii) disposeAppRuntime afterwards idempotently re-closes the already-closed child scope (no error, no second finalizer run).
• If TestClock.adjust leaves continuations pending, the helper adds Effect.yieldNow/Fiber.await — decided by tests.
• Gate: heartbeatService.test.ts, idleCompactionService.test.ts, retryManager.test.ts, serviceContainer.test.ts, di/*, tests/ipc.

Rollback: revert restores defaults; no call site depends on the new params.

PR 3 — Shared core root: coarse CoreProjectionLive + createCoreServices facade + CLI runtime disposal (+120 / −10)

Scope

• Tags for the remaining 19 core services; CoreOptionsTag; StoresFromCoreOptionsLive.
• CoreProjectionLive = Layer.effectContext(Effect.gen(function*(){ const opts = yield* CoreOptionsTag; const stores = yield* …; const core = buildCoreGraph({ ...opts, ...stores }); return Context.make(History, core.historyService).pipe(Context.add(...)) })) where buildCoreGraph is today's createCoreServices body, unchanged, renamed.
• createCoreServices(opts) = makeAppRuntime(CoreProjectionLive ▹ StoresFromCoreOptionsLive ▹ AppFiberScopeLive ▹ EffectRunnerLive ▹ Layer.succeed(CoreOptionsTag, opts)), returns today's CoreServices object read from the context plus runtime and appFiberScope. cli/run.ts and cli/workflow.ts cleanup lists append closeScopeBounded(appFiberScope) before session.dispose() and disposeAppRuntime(runtime) after backgroundProcessManager.terminateAll().
• ServiceContainer stops calling createCoreServices; AppLive = CoreProjectionLive ▹ CoreOptionsFromDesktopLive ▹ CrossCuttingLive ▹ … (cross-cutting services move into CrossCuttingLive now because core options derive from them). Desktop constructions otherwise stay in the constructor.

Acceptance

• Identity test: every CoreServices field === Context.get(ctx, Tag); serviceContainer.test.ts unchanged and green.
• Decision gate for PR 4 recorded in the PR body: make typecheck wall time, [startup] AppRuntime built ms and initialize totals vs origin/main baseline from the sandbox (§7). Proceed to PR 4 only if typecheck regresses < 10 % and startup within noise; otherwise stop at (C).
• Gate: bun test src/node/services, src/cli/*.test.ts (run/workflow/server/cli), tests/ipc, make static-check.

Rollback: revert restores the imperative call; PR 1/2 unaffected.

PR 4 — Peel the core into staged per-service Layers + CoreWiringLive (+330 / −290 ⇒ net ≈ +40; split 4a/4b if > ~600 diff lines)

Scope

• Stages S1, S2a, S2b, S3…S8 (§2.1 + skeleton in §2.2) as Layer.effect adapters with today's argument lists; CoreWiringLive (Effect.sync only) replays the wiring lines in order; CoreLive = CoreWiringLive.pipe(Layer.provideMerge(S8)) replaces CoreProjectionLive; buildCoreGraph deleted.
• Before writing any stage: re-derive the DAG from the constructor argument lists (the plan's stage table was checked once; StreamManager → SessionUsage is the kind of edge that turns "siblings" into a stage split) and record it in the PR body.
• 4a (S1–S3: leaves through AIService) / 4b (S4–S8 + wiring) if needed — 4a alone is mergeable because the remaining services are built by a shrunken projection layer that reads S1–S3 from the context.

Acceptance

• Wiring assertions that are behavioral (a missing wiring line fails them): turnRequestBuilderBindings fully populated; goal continuation consumer registered on idleDispatcher; streamManager MCP manager set; registration probe installed on extensionMetadata.
• I6 audit table for all 19 constructors in the PR body; missing-provider = compile error (R must be never at makeAppRuntime) demonstrated by a type-level test (// @ts-expect-error).
• Gate: as PR 3 plus streamManager*.test.ts, aiService.test.ts, workspaceService*.test.ts.

Rollback: revert to PR 3's projection.

PR 5 — DesktopLive group layers + DesktopWiringLive; thin ServiceContainer; StreamManager runner param (+170 / −150 ⇒ net ≈ +20)

Scope

• Tags for the 45 desktop services; six group layers (Layer.effectContext, today's construction order inside each; provideMerge between groups that depend on each other); DesktopWiringLive (Effect.sync only) = serviceContainer.ts:209, 263-265, 271, 288-290, 334-340, 348, 365, 375, 381-382, 434, 438-471, 474-574 in order.
• ServiceContainer constructor = makeAppRuntime(AppLive(stores)) + field assignment from the context. toORPCContext() unchanged in shape.
• StreamManager: optional trailing runner: EffectRunner; schedulePartialWrite fork (streamManager.ts:1141) and RetryManager construction use it; Scope.close stays Effect.runFork (existing async-close precedent). WorkersLive receives EffectRunnerTag.

Acceptance

• All four existing serviceContainer.test.ts assertions unchanged; new identity test over toORPCContext() fields vs tags; dispose()/shutdown() call order asserted via spies on the public methods already spied today.
• I6 audit for the 45 constructors.
• Gate: tests/ipc + tests/ui (make test-integration), src/cli/server.test.ts, src/cli/cli.test.ts, streamManager*.test.ts, aiService.test.ts.

PR 6 — TestClock adoption sweep + shutdown hardening + contract docs (+~20 LoC product; tests edited)

Scope

• Replace real-sleep cadence probes with makeTestEffectRunner() in heartbeatService.test.ts, idleCompactionService.test.ts, retryManager.test.ts, and the partial-write debounce cases of streamManager.test.ts; keep one real-timer smoke test per worker (guards the defaultEffectRunner path).
• cli/server.ts: [shutdown] log lines per step incl. AppRuntime disposed {ms}; confirm the whole dispose() fits the existing 5 s force-exit budget.
• Finalize the contract doc comment in di/appRuntime.ts (I1–I8, §5).

Acceptance: converted suites have zero setTimeout-based cadence waits (grep in PR body), same assertions; make test-integration green; sandbox startup/shutdown evidence (§7).

4. TestClock story

• Mechanism. Effect.sleep, Schedule.fixed, Effect.timeout, Clock.currentTimeMillis read the Clock reference from the running fiber's context. Workers that fork through an EffectRunner built under TestClock.layer() run on the test clock; await testRunner.adjust("2 minutes") advances it. Date.now(), setTimeout, setInterval are unaffected — heartbeat deadline math via injected now, AgentStatusService's ref'd setInterval, and backgroundProcessManager stay on real timers/injected timestamps.
• Benefit now: heartbeatService.test.ts (6), idleCompactionService.test.ts (2), retryManager.test.ts (3 setSystemTime → adjust; Date.now-based retryAt may move to Clock.currentTimeMillis only if a test needs both clocks aligned), streamManager.test.ts debounce cases (7).
• Deferred: streamBridge.test.ts ticker (11) — needs a context/runner parameter on subscriptionIterable; OAuth device-flow polling and oauthFlowManager.test.ts (25) — non-goal.
• Stays real: child-process/PTY/WASM/fs-lock waits (backgroundProcessManager 72, quickjsRuntime 26, lock sleeps in workspaceService/taskService), end-to-end suites (tests/ipc, e2e).
• Pinned in PR 2, not assumed: adjust runs due sleeps and their synchronous continuations before resolving (or the helper yields until they do); Schedule.fixed anchoring under TestClock matches the wall-clock expectations in heartbeatService.ts:149-155; sync Scope.close of a TestClock-suspended fiber completes synchronously.

5. Shutdown protocol

1. Trigger points unchanged: main.ts before-quit (preventDefault → dispose() raced with 5 s → app.quit(); update-install path fire-and-forget), the second before-quit listener's shutdown() (unchanged, concurrent), cli/server.ts SIGINT/SIGTERM (5 s force exit), ACP close(), tests/ipc (dispose() then shutdown()), headless bench (dispose() from PR 1).
2. ServiceContainer.dispose() order:
   1. backgroundProcessManager.beginShutdown() — unchanged, first (latch protecting persisted monitor records).
   2. closeScopeBounded(appFiberScope, APP_FIBER_SCOPE_CLOSE_TIMEOUT_MS) — interrupts and awaits supervised fibers while every dependency they might touch during finalization is still alive. No occupants in Phase 11; the position is fixed now so the engine-core phase does not have to re-derive it.
   3. The existing explicit sequence verbatim (desktopBridgeServer.stop() … terminateAll() … timelineService.flush()).
   4. disposeAppRuntime(runtime, APP_RUNTIME_DISPOSE_TIMEOUT_MS) — closes the runtime scope (interrupts any fiber started via runtime.runX — none long-lived in Phase 11; runs layer finalizers — none in Phase 11 by I5). Hung → warn at the timeout; never rejects.
      Budget: 2 s + 2 s inner bounds inside the callers' 5 s outer budgets; the outer race in main.ts remains the last line of defense.
      Rule for future occupants: anything forked into AppFiberScope must tolerate interruption at any suspension point and must not depend on resources torn down in step 1; anything that needs a Layer finalizer must first prove reverse-construction order is compatible with steps 2–3 (I5).
3. Latches: disposed makes dispose() idempotent (two before-quit listeners, tests/ipc dispose+shutdown). shutdown() never touches the runtime or AppFiberScope.
4. Late callers: EffectRunner handles keep working after runtime dispose (I2), so a stray tick()/scheduleRetry() after quit cannot defect. The ManagedRuntime is referenced only by ServiceContainer and the createCoreServices return value.
5. Worker stop() stays synchronous (runner.runSync(Scope.close)) because their fibers suspend only on the clock. The engine core will fork into AppFiberScope (step 2.2 awaits it) — the reason both seams exist now.
6. Crash paths: unchanged — uncaughtException/SIGKILL run no finalizers. Finalizers are best-effort; durable state must remain crash-safe without them (AGENTS.md self-healing rule). Nothing in Phase 11 makes a finalizer the sole guardian of durable state.

6. Risk register

#	Risk	L/I	Mitigation
R1	A layer body suspends → runSync throws at startup	M/H	I1 assert + PR 1 test (b); doc comment; review checklist; entry-point catch paths verified in PR 1
R2	Construction-order side effects differ under staged builds	L/H	I6 audit per moved constructor; explicit provideMerge stages; wiring layers replay today's order; tests/ipc as behavioral gate
R3	Double teardown (shutdown() ∥ dispose(); dispose+shutdown in tests)	M/M	disposed latch; runtime/AppFiberScope closed only in dispose(); PR 1 test
R4	Late runtime.runX after dispose → defect	M/M	I2: services hold EffectRunner, never the ManagedRuntime
R5	TestClock semantics differ from assumptions	M/L	PR 2 pins them before any suite converts; per-suite fallback to real timers
R6	effect v4 RC churn (Context→ServiceMap, Layer renames)	M/M	All Layer/Context/ManagedRuntime/TestClock imports confined to di/; exact pin
R7	Startup latency regression (splash)	L/M	AppRuntime built ms + initialize totals vs baseline in sandbox; PR 3 gate
R8	Typecheck slowdown from large requirement unions	L/L	PR 3 gate records make typecheck wall time; fallback (C)
R9	Per-request Effect.provide of a ~70-entry Context	L/L	echo-probe diagnostic in PR 1/5 bodies
R10	Spy seams / direct-construction tests break	L/H	I4; optional trailing params; audit 4; typecheck of tests
R11	CLI roots forget to dispose runtime/scope	M/L	PR 3 wires both cleanups; src/cli/*.test.ts assert the cleanup steps exist
R12	Someone forks long-lived I/O work via EffectRunner expecting dispose to await it	M/M	Doc on EffectRunner ("unsupervised"); PR 2 asymmetry test; review audit 1

Rollback: PRs are stacked; revert in reverse order (6→1). Service classes are never modified except for optional trailing params, so any revert restores the previous composition root wholesale with no data or API implications.

7. Dogfooding (per PR; evidence attached to the PR body)

Environment (headless Coder host, no DISPLAY):

XUM_LOG_LEVEL=debug DEV_SERVER_SANDBOX_ARGS="--clean-projects" make dev-server-sandbox   # background bash task; prints URL + XUM_ROOT

• Startup correctness: <XUM_ROOT>/logs/*.log shows, in order: Loading services..., [startup] AppRuntime built {ms}, [startup] ServiceContainer.initialize starting, six step durations, [startup] ServiceContainer.initialize completed {totalMs, stepDurationsMs}. Paste baseline (origin/main) vs branch numbers.
• Startup-never-crash parity (once, locally, not committed): inject a throwing scratch layer → xum server exits non-zero with the existing logged error and no unhandled-rejection trace; for desktop, confirm by code path (loadServices() rejects → main.ts:1255 dialog) and via src/cli/server.test.ts/ACP tests.
• UI smoke (agent-browser): open <url> → snapshot -i → add a scratch git repo as a project → create a workspace → send one message → screenshot the loaded app and the response; attach_file both. Video: start agent-browser record before the flow and stop it with a hard timeout (timeout 30 agent-browser record stop); if stopping hangs (known), attach the truncated WebM plus the screenshots and say so.
• oRPC Effect path: pin/unpin a memory entry (rides handlerGen + runtime effect/context); screenshot before/after; grep logs for ManagedRuntime disposed/defect lines (expect none).
• Graceful quit: record the terminal with script -q /tmp/<workspace>-shutdown.log (or agent-tty if present), kill -TERM <pid> → expect [shutdown] lines, AppRuntime disposed {ms}, exit 0, no force-exit message; attach the typescript. Exercise the timeout branch once with a scratch hung finalizer → warn + timely exit.
• Electron (best effort): with Xvfb, make dev + agent-browser via CDP (electron skill): screenshot splash → main window, quit via menu, confirm exit < 5 s; otherwise state that the Electron path is covered by tests/e2e in CI and the shared dispose() path exercised by server.ts.

Gate suites per PR (plus make static-check always):

PR	Must pass
1	src/node/services/di/*, serviceContainer.test.ts, src/node/orpc/*, memoryMeta*, make test-integration
2	+ heartbeatService.test.ts, idleCompactionService.test.ts, retryManager.test.ts
3	+ bun test src/node/services, src/cli/*.test.ts; record PR 4 gate numbers
4	+ streamManager*.test.ts, aiService.test.ts, workspaceService*.test.ts
5	+ tests/ui via make test-integration, src/cli/server.test.ts, src/cli/cli.test.ts
6	converted suites + full make test-integration + sandbox startup/shutdown evidence

8. Non-goals (explicit)

• streamManager ENGINE CORE conversion (first AppFiberScope occupant; separate phase).
• Schema at persistence boundaries; OAuth refresh/device-flow workers; AgentStatusService setInterval → Effect.
• initialize() as a Layer/startup effect (D2); per-service optional tags (D3); streamBridge on the runtime; layer finalizers for existing dispose() steps.
• Any change to persisted data, IPC wire shapes, or oRPC handler bodies beyond the effect/context source.

9. Assumptions stated

• Effect.context<never>() inside EffectRunnerLive returns the enclosing build context including an upstream TestClock entry (PR 2 test; fallback: provide Clock.Clock explicitly in the helper).
• Scope.fork(parent) inside a Layer.effect body yields a child closed by the runtime's layer scope on dispose() (PR 2 AppFiberScope test).
• Layer bodies never need to observe sibling construction order; all ordering that matters is expressed as provide/provideMerge stages or wiring-layer statement order.
• EffectRunner's R = never constraint is sufficient for every lifecycle fork in the three Phase 11 workers and StreamManager.schedulePartialWrite (they only use Effect.sleep/Schedule/Effect.sync/Effect.tryPromise — no service tags). Verified by typecheck in PR 2/5.
• The desktop tail's teardown remains explicit unless a later RFC proves reverse-construction order compatible; this plan does not attempt it.

---

Generated with xum • Model: anthropic:claude-fable-5-1 • Thinking: xhigh • Cost: $40.69

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 0eacefc2da

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: ad6f85289b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".