🤖 refactor: Effect Phase 11 PR 4a — staged per-service core layers S1–S3 (History … AIService) + remainder projection

[ThomasK33]

Summary

Effect migration Phase 11, PR 4a of 6 (PR 4 ships as 4a + 4b, see below): the head of the core service graph — every service through AIService — now builds as staged per-service Layers (HistoryLive, ProviderLive, … AILive in di/layers/core.ts, composed S1 → S2a → S2b → S3 with Layer.provideMerge between stages and Layer.mergeAll only for verified siblings). The remainder of the former imperative body (MemoryConsolidationService … WorkspaceTurnManager plus all setter/listener wiring, order unchanged) survives as buildCoreTail, run by a transitional projection layer over the layer-built head. CoreLive replaces CoreProjectionLive in both roots (AppLive, CoreRootLive); MemoryMeta and WorkspaceMcpOverrides become explicit core-graph inputs (desktop: MemoryMetaLive/CrossCuttingLive; CLI: MemoryMetaLive + new WorkspaceMcpOverridesDefaultLive), so CoreServicesOptions.memoryMetaService/workspaceMcpOverridesService are gone. Service classes, constructors, facades and the wiring statements are untouched.

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

Implementation

• di/layers/core.ts — 13 adapter layers with today's argument lists (S1: History · InitStateManager · Provider · BackgroundProcessManager · ExtensionMetadata · Memory · TerminalAttentionStore · IdleDispatcher · TurnRequestBuilderBindings; S2a: SessionUsage · WorkspaceGoal; S2b: StreamManager; S3: AI), CoreInputTags, WorkspaceMcpOverridesDefaultLive, the transitional CoreTailProjectionLive (Layer.effectContext over buildCoreTail, exposing the six tail tags), and CoreLive = CoreTailProjectionLive ▹ S3. TurnRequestBuilderBindingsLive is Layer.sync (one mutable record per graph build, never shared across runtimes).
• coreServices.ts — buildCoreGraph → buildCoreTail(head: CoreGraphHead): CoreGraphTail: the head constructions are deleted (they are the layers now); the tail keeps every remaining statement verbatim. The two wiring lines that only need head services (the extension-metadata registration probe, bindings.memoryService) run first in the tail. CoreOptions moves here (next to CoreServicesOptions) so the layers module is the only importer across the seam (type-only the other way → no cycle).
• di/tags.ts — TerminalAttentionStoreTag (graph-internal collaborator of Task/TurnManager; CoreTags now includes it), CoreRootTags gains WorkspaceMcpOverrides.
• di/layers/app.ts / desktop.ts — CoreLive; CoreOptionsFromDesktopLive no longer smuggles memoryMetaService/workspaceMcpOverridesService through the options.
• Tests (coreServicesRoot.test.ts): the PR 3 identity harness is unchanged and green against CoreLive; new behavioral wiring assertions (bindings identity table + onWorkflowRunStatusChanged → emitWorkflowRunActivity; goal-continuation consumer registered — a second registration is refused; streamManager holds the MCP manager; registration probe installed and answering false for an unknown id), CLI-default inputs test, and the type-level missing-provider test (// @ts-expect-error on makeAppRuntime(CoreLive)). The 4b relocation of the tail into S4–S8 + CoreWiringLive will land under these tests unchanged.

PR 4 notes

Re-derived DAG (from the constructor argument lists in the former buildCoreGraph)

Inputs provided by the roots beneath CoreLive (CoreInputTags): Config, SessionLocator, ProvidersConfigStore, SecretsStore, FileLeaseManager, CoreOptions, MemoryMeta, WorkspaceMcpOverrides (the last two were opts.x ?? new X(...) defaults inside the body; they are always present, so they are inputs rather than optional options — desktop already built both in layers).

Service	Constructor dependencies (tags)	Stage
HistoryService	SessionLocator	S1
InitStateManager	Config	S1
ProviderService	Config, Options(policy), ProvidersConfigStore, FileLeaseManager	S1
BackgroundProcessManager	—	S1
ExtensionMetadataService	Options(path)	S1
MemoryService	Config, MemoryMeta	S1 (plan said S2a; MemoryMeta is an input, not a stage member)
TerminalAttentionStore	Config	S1
IdleDispatcher	—	S1 (constructed last today; its consumer registration stays in the wiring after Task/Workspace)
TurnRequestBuilderBindings {}	—	S1 (Layer.sync)
SessionUsageService	Config, History, Provider (lazy accessor)	S2a
WorkspaceGoalService	Config, History, ExtensionMetadata, Options, ProvidersConfigStore	S2a
StreamManager	History, SessionUsage, Provider (lazy accessor)	S2b (the plan's known split)
AIService	Config, History, InitState, Provider, BackgroundProcess, SessionUsage, WorkspaceMcpOverrides, Options, StreamManager, Bindings, ProvidersConfigStore, SecretsStore	S3
MemoryConsolidationService	Config, Memory, MemoryMeta, History, AI, Options, SessionUsage	S4 (4b)
MCPConfigService	Options, Config, AI (workspaceMetadataProvider)	S4 (4b)
MCPServerManager	MCPConfig, Config, Options, WorkspaceMcpOverrides	S5 (4b)
WorkspaceService	Config, History, AI, InitState, ExtensionMetadata, BackgroundProcess, SessionUsage, Options, StreamManager, SecretsStore, ProvidersConfigStore	deps end at S3 — 4b stages it S6 (after MCPServerManager) to keep today's construction order; its MCP manager / consolidation collaborators arrive via setters
TaskService	Config, History, AI, Workspace, InitState, SessionUsage, WorkspaceGoal, SecretsStore, TerminalAttention	S7 (4b)
WorkspaceTurnManager	Config, History, AI, Workspace, InitState, Task, TerminalAttention, StreamManager	S8 (4b)

Sibling claims in this PR (all checked against the argument lists above): S1's nine leaves depend only on inputs; S2a's two need only S1. Layer.mergeAll siblings build in declaration order in rc.112 (mergeAllEffect → forEach with concurrency: n, verified by a scratch probe) but nothing here relies on it. A throw inside a mergeAll sibling surfaces as the same synchronous raw throw from makeAppRuntime (scratch probe; the root test pins the equivalent for the projection).

4a/4b decision: split

The full peel (S1–S8 + CoreWiringLive, kept locally on a backup branch for 4b) measured +598/−408 product lines, well past the plan's ~600-line review-size guard even though most of it is 1:1 relocation of constructor calls and their rationale comments. This PR is 4a: S1–S3 as layers (+413/−186 product, +96 test) with the transitional CoreTailProjectionLive running the unchanged remainder (buildCoreTail). 4b (next, the only follow-up; PR 5 is not started) peels S4–S8 into layers, replaces buildCoreTail with CoreWiringLive, deletes the projection, and lands under the behavioral wiring tests added here.

I6 constructor side-effect audit

Moved into layers in this PR (13 + the 2 inputs):

Constructor (layer)	Side effects at construction	On declared args only?	Order-sensitive?
HistoryService (S1)	none	✓	no
InitStateManager (S1)	new EventStore(config, "init-status.json", …) (own store)	✓	no
ProviderService (S1)	emitter.setMaxListeners; providersConfigStore.watchProvidersFile(…)	✓ (store input)	no
BackgroundProcessManager (S1)	setMaxListeners on itself	✓	no
ExtensionMetadataService (S1)	none	✓	no — the registration probe (a setter) used to be installed immediately after construction and now runs as the first tail statement; none of the constructors built in between (WorkspaceGoalService, StreamManager, AIService) call extensionMetadata
MemoryService (S1, was after AIService)	super() only	✓	no
TerminalAttentionStore (S1, was before TaskService)	none	✓	no
IdleDispatcher (S1, was last)	asserts only	✓	no
SessionUsageService (S2a)	none (provider accessor is lazy)	✓	no
WorkspaceGoalService (S2a)	asserts/fields only	✓	no
StreamManager (S2b)	fields only	✓	no
AIService (S3)	providerService.onConfigChanged(…), streamManager.setEventSink(…), setMaxListeners, builds ProviderModelFactory/TurnRequestBuilder over its args	✓	yes, satisfied by staging (Provider S1, StreamManager S2b)
MemoryMetaService (input, MemoryMetaLive; CLI roots now layer-built instead of opts.memoryMetaService ?? new)	path join	✓	no
WorkspaceMcpOverridesService (input; CLI WorkspaceMcpOverridesDefaultLive)	assert	✓	no

Still constructed by buildCoreTail in this PR, positions relative to each other unchanged (audited now for 4b): MemoryConsolidationService (sidecar path only), MCPConfigService (asserts/fields), MCPServerManager (own unref'd setInterval), WorkspaceService (backgroundProcessManager.on ×5, aiService.on ×6, initStateManager.on, extensionMetadata.setTombstoneClearedListener, module-global setWorkflowArchiveAdmissionGuard, starts recoverBashMonitorStateAfterRestart() — all declared deps/self; none of its setter-provided collaborators), TaskService (aiService.on ×3 — registered after WorkspaceService's listeners, guaranteed because Task depends on Workspace; new AgentPeerMessageBroker(workspaceService), new GitPatchArtifactService(config)), WorkspaceTurnManager (new TaskHandleStore(config)).

Construction-order changes vs main, all inert by the table above: MemoryMeta/WorkspaceMcpOverrides/Memory/TerminalAttentionStore/IdleDispatcher are built before instead of after AIService; S1 siblings have no defined mutual order; the registration probe is installed after the S2–S3 constructors instead of before them. The wiring statement order inside the tail is unchanged.

Deviations from the plan

• MemoryMeta and WorkspaceMcpOverrides are core-graph inputs (CoreInputTags) rather than S1 members: the desktop already built both in layers (PR 1/PR 3), so making the core read the tags directly removes the CoreServicesOptions.memoryMetaService/workspaceMcpOverridesService pass-through (the two coreOptions.* identity asserts in serviceContainer.test.ts that pinned that pass-through are removed — the tag identity asserts next to them remain).
• CoreOptions type moved from di/layers/core.ts to coreServices.ts (next to CoreServicesOptions) so the seam has a single import direction.
• coreServicesRoot.test.ts: the throwing-body spy targets buildCoreTail (rename of buildCoreGraph); everything else in the PR 3 harness is unchanged.
• CoreTags includes TerminalAttentionStoreTag (not a CoreServices field); CoreLive's output is Exclude<CoreTags, MemoryMeta> because MemoryMeta is an input — the roots' merged context still carries every CoreTags entry (identity test).

Pre-review audits (plan §3)

1. Interruption posture — no new or moved fiber forks; layer bodies are synchronous constructors (rg 'fork' src/node/services/di/layers/ → none).
2. Uninterruptible teardown — unchanged (disposeAppRuntime/closeScopeBounded untouched).
3. No defect escapes — a layer body that throws surfaces as the synchronous throw from makeAppRuntime (constructor semantics), inside the callers' existing startup error paths; pinned for the projection (buildCoreTail spy) and for the desktop root (serviceContainer.test.ts), and probed for a nested mergeAll sibling (scratch).
4. Spy-seam check — no constructor signature changed (rg 'spyOn\(|new (History|InitState|Provider|…)' src tests: all direct constructions and private-method spies compile unchanged); the only test-visible renames are buildCoreGraph → buildCoreTail and the two removed option fields.
5. Sync-start — unchanged (no runner changes).
6. I6 — table above.
7. Zero-suspension (I3) — MemoryConsolidationService construction is unchanged text inside the tail; no lookup/await was inserted anywhere near its funnels.

Re-recorded gate numbers (R7/R8 post-staging data point)

Same methodology as PR 3: sibling git worktrees under /tmp (origin/main = 0b52386f1 vs this branch = cfedef9bc, pre-rebase; the rebase onto ffa2780f6 touched no shared code) with symlinked node_modules, interleaved runs, shared 96-core Coder host at load ≈ 140–150, CPU PSI some avg60 ≈ 29–35 %.

(a) Typecheck — the make typecheck command (concurrently over both tsgo projects), 6 interleaved pairs:

	origin/main	branch	Δ
wall median	11.00 s	10.99 s	−0.1 %
min / max	10.45 / 11.74 s	10.42 / 11.50 s

tsgo --extendedDiagnostics (deterministic compiler-work counts; wall check times were dominated by host noise — the main project measured 3.75 → 4.18 s in a first 4-run series and 5.69 → 5.54 s in a second 6-run series under rising load):

project	types	instantiations
renderer (tsconfig.json)	1 928 628 → 1 929 856 (+0.06 %)	7 775 777 → 7 779 016 (+0.04 %)
main (tsconfig.main.json)	1 047 163 → 1 048 459 (+0.12 %)	4 250 448 → 4 253 308 (+0.07 %)

(b) Startup — bun src/cli/index.ts server --no-auth with a fresh XUM_ROOT, XUM_LOG_LEVEL=debug, recorded under script -f, 10 interleaved pairs, SIGTERM ≈ 1 s after initialize completed:

metric	origin/main	branch	note
[startup] AppRuntime built ms (median, min–max)	12 (11–31)	18 (16–19)	+6 ms cold: 13 layers + 4 stage compositions built through the Layer machinery on first use instead of one coarse layer; in-process warm construction (new ServiceContainer 2nd–15th) is 0.9–1.5 → 1.6–2.7 ms median, +≈0.3 ms at the minimum
ServiceContainer.initialize completed { totalMs } (median, min–max)	97 (52–109)	99 (45–182)	within noise (unchanged code)
SIGTERM → exit wall (median, min–max), exit code	161 ms (149–197), 0 ×10	174 ms (150–204), 0 ×10	[shutdown] AppFiberScope closed → explicit steps → [shutdown] AppRuntime disposed in every transcript

Verdict: typecheck flat (R8), construction +≈6 ms cold / sub-millisecond warm against a ~100 ms initialize() and a splash measured in hundreds of ms (R7 — recorded, not a gate failure). 4b adds six more layers; re-measure there.

Lessons for 4b / PR 5

• The behavioral wiring tests in coreServicesRoot.test.ts are now the oracle for the tail relocation: 4b should move buildCoreTail into S4–S8 layers + CoreWiringLive with those tests unchanged, and swap the buildCoreTail spy in the throwing-body test for an equivalent nested-layer throw (e.g. spying createAgentPluginsMcpProvider inside MCPConfigLive).
• WorkspaceService's constructor needs nothing beyond S3; staging it after MCPServerManager (plan's S6) is a construction-order-parity choice, not a dependency — say so in the stage comment.
• Every S1–S3 layer is exported, so integration tests can swap a single service (Layer.provideMerge(Layer.succeed(History)(fake)) beneath CoreLive) — the plan's "per-service swap" leverage is available from this PR on.
• TurnRequestBuilderBindings must be Layer.sync, never Layer.succeed with a literal: the record is mutated by wiring, and a shared literal would leak across runtimes (tests build many).
• bun 1.2.15 Illegal instruction (exit 132) hit bun test src/node/services three times on this host in different files (BackupRepoCache wedge, workflows/WorkflowRunner.test.ts); each file passes on rerun here and on pristine main. Run the suite in chunks when it happens.

Validation

• make static-check green (typecheck both projects incl. the @ts-expect-error test, lint, fmt, docs).
• bun test src/node/services: every file green except the known environment baselines on this host, identical on pristine origin/main — taskGitPatchEngine ×2, WorkspaceTurnManager terminal recovery ×2, agent_skill_delete ×1, BackupRepoCache ×7 — plus one order-dependent flake (AttachmentService.generateCompletedReportsAttachment … newest first, passes alone on both trees). bun test src/cli 185/185. Named PR 4 gate (streamManager*, aiService, workspaceService*) 659/659. jest tests/ipc/{doubleRegister,savedQueries,windowTitle,acp.disconnectCleanup} 18/18.
• Dogfooding (headless Coder host, XUM_LOG_LEVEL=debug):
  • xum workflow echo run from the branch: [startup] AppRuntime built → ok from pr4a → [shutdown] AppFiberScope closed → BackgroundProcessManager.terminateAll() → [shutdown] AppRuntime disposed → exit 0 (the order workflow.test.ts pins).
  • xum server graceful quit: 10/10 branch runs exit 0 within 150–204 ms of SIGTERM with both [shutdown] runtime lines in place (table above).
  • Dev-server sandbox (make dev-server-sandbox --clean-projects): AppRuntime built {ms: 12}, initialize completed {totalMs: 239}; via agent-browser: added a scratch git 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-17-gcfedef9bc); no ManagedRuntime disposed/defect lines in the log; SIGTERM → exit in 344 ms with [shutdown] AppFiberScope closed {ms: 1} … [shutdown] AppRuntime disposed {ms: 3}.
  • Not exercised headless: the Electron before-quit path (same ServiceContainer.dispose(); tests/e2e in CI) and the oRPC memory pin/unpin round-trip (covered by effectBridge.test.ts + the identity tests).

Risks

• Low–medium. No service class, constructor, facade or wiring statement changed; the moved constructors are audited above and construction-order changes are limited to trivially inert constructors. The transitional projection keeps the tail exactly as on main. A throwing layer body still surfaces as the same synchronous constructor-style throw from new ServiceContainer(stores) / createCoreServices(opts) (tests).
• Startup: +≈6 ms cold construction (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: $21.59

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: ca7b1c7792

ℹ️ 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".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: ca7b1c7792

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.