refactor: daemon and contracts decoupling, wave 3 (registry package, type split, leaf moves)

[thymikee]

Purpose

Third decoupling wave for src/daemon and @agent-device/contracts, following #2316, #2317 and #2318. Measured on main at 27a97ee619 with a production-only import graph (1,629 files, 8,805 edges):

• src/daemon: 350 production files, 56.8k lines; 197 flat top-level files (30k lines). The value graph is acyclic and the daemon has zero edges into platform packages. It has 154 value edges into 67 root src/ files; the top hubs are command-catalog.ts (15 daemon files), core/command-descriptor/registry.ts (13), core/dispatch-resolve.ts (12), provider-device-runtime.ts (11).
• @agent-device/contracts: 190 modules, 18.2k lines, 118 subpaths. 106 modules export runtime code (13k lines). 146 modules are reachable from a platform/provider package; 44 are not; 19 are reachable from no package at all.

The command descriptor registry is the keystone: it is package-ready today (its only root dependency is core/parse-timeout.ts) and it is what forbids packaging the daemon client and the session event journal under R11.

Children (dependency order)

• A — refactor(core): move the command descriptor registry into its own workspace package #2336
• B — refactor(commands): move commands-side rendering out of src/daemon and retire the doctor progress flag #2337
• C — refactor(daemon): split src/daemon/types.ts into request types and session state #2338
• D — refactor(contracts): move single-owner modules out of @agent-device/contracts #2339 (blocked by A)
• E — refactor(daemon): move four pure leaves to their kits #2340
• F1 — refactor(daemon): extract the session event journal into a workspace package #2341 (blocked by A, C)
• F2 — refactor(daemon): relocate the daemon client out of src/daemon #2342 (blocked by A, B, C, E)

Rules for every child

• Move-dominated PRs with rename-only proof; pure moves carry their tests unchanged; gate edits land in a final chore(gates) commit.
• No compatibility re-exports at the old path (no-internal-package-reexports); every consumer switches to the owning specifier.
• New package subpaths point directly at moved source files so the eager-closure gate carries each baseline through rename detection; no APPROVED_OVER_CEILING row without a measurement.
• Ownership classification (which daemon module owns which platform-aware responsibility) stays in refactor(daemon): audit and retire residual semantic platform coupling #2278 and its children (refactor(daemon): own Apple runner session observation behind a semantic port #2332, refactor(daemon): normalize lifecycle participation of platform resource owners #2333, refactor(daemon): separate open-target planning from platform mechanics #2334). No child here classifies ownership.

Evaluated and not scheduled

• @agent-device/gestures (gesture-plan, android-touch-plan, apple-multitouch-support, gesture-admission; ~780 lines with a clean DAG below the contracts hubs): viable, deferred for new-package cost.
• Client-contracts audience split (client-* ×14 + facades/client.ts, 1.4k lines, all type-only consumers): buys ownership clarity, not coupling reduction.
• src/daemon/session-target-evidence.ts: needs capture-kit and ad-script; no package depends on both.
• HTTP artifact transfer cluster (15 top-level files, 1,984 lines, 0 root deps): a logical module, not a package; belongs with refactor(daemon): audit and retire residual semantic platform coupling #2278's ownership work.
• Maestro adapter fold into replay/: rejected, R9 engine-cycle prefix.

Completion

All children closed with their completion conditions met, and the two measurements above re-run and recorded here.

[thymikee]

Reconciliation and execution plan

Cross-checked all seven children against the umbrella checklist. The declared dependencies are mutually consistent — every Dependencies section agrees with the reverse edge stated by its blocker (A names D/F1/F2; C names F1/F2; E names F2's code-signature need; B and F2 agree on doctor-progress.ts). No contradictions to resolve, so the graph below is the umbrella's as written.

main ──┬── A #2336  registry package ──┬── D #2339  contracts single-owner moves
       │                               │
       ├── C #2338  types.ts split ────┴── F1 #2341  session event journal
       │
       ├── B #2337  commands-side rendering ──┐
       │                                      ├── F2 #2342  daemon client relocation
       └── E #2340  four leaf moves ──────────┘

Waves

Wave 1 — in flight, all based on main, developed in parallel:

	issue	branch
A	#2336	claude/2336-command-registry-package
B	#2337	claude/2337-commands-rendering-out-of-daemon
C	#2338	claude/2338-daemon-types-split
E	#2340	claude/2340-daemon-leaf-moves

Wave 2 — D stacks directly on A's branch. F1 stacks on an integration branch merging A and C, because it needs A's catalog/registry package and C's wire-only request shape.

Wave 3 — F2 stacks on an integration branch merging A, B, C and E.

Integration branches are cut by the coordinator once their inputs are pushed, so the dependent PRs review as their own diff rather than re-showing their bases.

Interlocks being watched

• C → F1. F1's completion condition (no path from a journal input type to SessionState or DeviceLease) is only satisfiable if C's wire-only shape actually lands. F1's fallback to @agent-device/kernel/contracts public request types is a fallback, not the plan.
• A → D. D must not move anything A's new package imports; A leaves contracts untouched, which keeps D's root-only set stable.
• B → F2. F2 assumes src/daemon/client/doctor-progress.ts is already deleted, not deprecated.
• E → F2. F2's remaining-seam inventory assumes code-signature*.ts has already left src/daemon.

The two graph measurements in the umbrella's Purpose section get re-run and recorded here once every child is closed.

---

Generated by Claude Code

[thymikee]

Wave 1 status and four corrections to this issue

All five wave-1/2 children are in flight. B (#2337) is merged as #2349.

	issue	PR	state
A	#2336	#2348	resolving a conflict with the new main
B	#2337	#2349	merged
C	#2338	#2346	rebased onto main, CI re-running
D	#2339	—	in progress, stacked on A's branch
E	#2340	#2347	clean against main, CI green so far

Four things this issue gets wrong or leaves underspecified. Each is verified against the tree, not inferred.

1. E is a prerequisite for A. This issue declares them independent.

walkDaemonCodeGraph in the daemon code-signature followed relative import specifiers only. On main that covers 619 of the daemon's modules — the rest of the daemon, reached by workspace specifier, is invisible to the signature a client compares a running daemon against. Any child of this umbrella that moves code into a workspace package therefore removes that code from the daemon's signature.

E hit this first (its four leaf moves took the walk to 611 and pushed the walker itself out of the graph it walks, which is the property code-signature-cache.ts's format guard rests on) and fixed it at the construction path in #2347: scoped specifiers resolve through the owning package's exports map, and the manifest is stamped so an exports retarget invalidates without either endpoint changing.

A moves 12 modules into a brand-new package and is exposed to exactly the same defect. So is F1, which creates another package. E must land before A, or A ships the same blind signature. Sequencing accordingly.

2. F1's dependency on C is not the one written here.

#2341 requires the journal package to import nothing under src/ (R11). C's wire-only shape, DaemonWireRequest, is declared at src/daemon/daemon-request-wire.ts — under src/ — so a workspace package may not import it. As exported it cannot be F1's input type.

It also is not needed. @agent-device/kernel/contracts already exports DaemonRequest and DaemonRequestMeta (packages/kernel/src/contracts.ts:100 and :73) carrying exactly the four fields the journal reads — command, flags, meta.requestId, meta.clientArtifactPaths — with no internal key and no path to SessionState or DeviceLease. C's module is itself built by narrowing that type.

So #2341's "or @agent-device/kernel/contracts public request/meta types" clause is the path that actually applies, not the fallback it reads as. C still satisfies #2338 as written. F1 stays sequenced behind C only for conflict avoidance — C's 408-file diff touches the session-event-*.ts files F1 relocates.

3. #2340's consumer list names two files that do not import the subject.

#2340 lists sparse-fallback-screenshot.ts and generic-runtime-execution.ts as screenshot-overlay consumers. On main neither imports it; the real consumers are src/daemon/screenshot-runtime.ts and src/daemon/android-snapshot-timeout-evidence.ts. E followed the code, correctly.

This matters beyond E: #2342 hand-lists its remaining seams the same way, and #2339 its consumer counts. Both are being told to verify every entry against the tree and report corrections, rather than treating the tables as authoritative.

4. The closing measurement needs one definition, chosen now.

This issue's Purpose states 154 daemon → root src/ value edges. A measured 150 → 114 with scripts/depgraph/build.ts (delta −36, exactly as predicted, ceiling met either way). The original figure was taken over a "production-only import graph (1,629 files, 8,805 edges)". Two definitions are in play and the Completion section promises this number gets re-run here. Pinning which filter counts — before the last child closes — avoids comparing two different measurements at the end.

---

Generated by Claude Code