refactor(contracts): make ExecResult host-command vocabulary, not root exec internals

[thymikee]

First step of the platform-seam work — the #1490 W3 / #1478 P6a prerequisite. Type-only, no behavior change.

Rewritten from the auto-generated description, which said this "eliminates circular dependency issues" for "platform packages" and exposes "public contracts API". None of those are accurate — see What this is not below.

The problem

ExecResult — { stdout, stderr, exitCode, stdoutBuffer? } — was declared beside the implementation in src/utils/exec.ts. 13 of the ~22 modules that name it live under src/platforms/, and every one of them wanted only the type: the shape of a finished host command, with no runtime behavior at all.

So platform modules imported root code to describe a value they already held. For a type that erases at compile time.

The change

ExecResult moves to @agent-device/contracts/platform, beside PlatformPlugin and the rest of the platform-family vocabulary.

The running stays in src/utils/exec.ts — process spawning, argument policy, timeouts, redaction are host policy the root composition owns, and #1490 keeps exec root-side deliberately. This splits the vocabulary from the policy rather than relocating the policy.

Per #1490's rules: no re-export shim at the old path. Every consumer names the contracts subpath, and exec.ts imports the type it implements against.

What this is not

• Not a circular-dependency fix. There was no cycle. check:layering reports zero value-import cycles before and after, and R4 would have rejected one. This was a layering/packaging blocker.
• Not public API. @agent-device/contracts is "private": true — an internal workspace package bundled into the single published artifact. Nothing is exposed to consumers.
• Not the exec seam. Stated explicitly so this is not mistaken for done: 45 platform modules still import utils/exec.ts for behavior — runCmd (98 references), requireExecSuccess (45), withCommandExecutorOverride (32), execFailureDetails (30), whichCmd (24), runCmdBackground (21), and a long tail. That is genuine capability coupling and needs the narrow injected-capability treatment W1c used for limrun, not a type move. It is the single biggest remaining blocker to platform packages, and it is the next slice, not this one.

Why it is worth landing on its own

It is the one part of the exec coupling that is pure cost with no design question attached: 13 modules paying a dependency for nothing. Separating it means the behavioral port that follows is reviewed on its own merits, with the noise already gone.

Validation

pnpm typecheck, lint, format:check, check:layering, check:production-exports, and VITEST_MAX_WORKERS=2 pnpm check:affected --run all green at dac1cf7.

Layering unmoved — R6 at 7, R9 at 47, R11 at 10 packages / 32 subpaths. check:production-exports is byte-identical to the main baseline (10 issues, 10 suppressed).

One number I have not fully attributed: the size report shows a reduction — JS raw −3.5 kB, gzip −1.3 kB, tarball −9.8 kB, unpacked −32 kB. A type-only move should be ≈0, so flagging rather than claiming a cause. The plausible mechanism is that modules which imported only type ExecResult from exec.ts now have no edge to it at all, so exec.js stops being pulled into chunks that never needed it — but I have not verified that, and I would rather say so than assert it. A reduction cannot regress behavior, and the packaged-CLI and bundle-size gates cover the artifact; happy to dig in if the number matters to review.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.99 MB	1.99 MB	-3.5 kB
JS gzip	644.0 kB	642.6 kB	-1.3 kB
npm tarball	780.7 kB	771.0 kB	-9.8 kB
npm unpacked	2.73 MB	2.70 MB	-32.0 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.6 ms	28.8 ms	+0.2 ms
CLI --help	66.7 ms	67.5 ms	+0.8 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/prepare-kind.js	-1.4 kB	-540 B
dist/src/registry.js	-999 B	-353 B
dist/src/internal/daemon.js	-283 B	-121 B
dist/src/screenshot-result.js	-74 B	-21 B
dist/src/runtime.js	-48 B	-19 B

[thymikee]

P1 — this reopens a deferred architecture path without its required trigger.

#1490 records W3 as “not now” and says it stops there. #1478 records P6 DEFER: P6a is not pursued, and P6b is deferred until a concrete platform/provider contribution or cleanup incident earns it.

This PR explicitly calls itself the first W3/P6a prerequisite, but names no new trigger, shrinks no R6/R9/layering measure, and leaves the 45 behavioral utils/exec.ts imports in place. That makes the type move speculative architecture churn, not an earned seam.

Please revert/close this, or first record and link a concrete trigger plus the narrowly scoped seam decision it earns. The mechanical type move is otherwise complete; it changes no runtime/device behavior, so live-device evidence is inapplicable.

[thymikee]

P1 accepted on the substance. You are right, and it contradicts my own analysis earlier in this session — I concluded platform packaging was "not now" and that the reviving condition is a forcing function rather than a tidiness argument, then framed this PR as a W3/P6a prerequisite anyway. No trigger, so the framing was wrong.

Your specific charge checks out against my own measurements: R6 stayed 7, R9 stayed 47, R11 stayed 10 packages / 32 subpaths. No gate-measurable improvement, and the 45 behavioral utils/exec.ts imports are untouched. Under a "not now" W3 the stated justification does not survive.

Two things before a decision, neither of them a defence of the framing:

1. One unverified fact that could matter. The size report shows a reduction — JS raw −3.5 kB, tarball −9.8 kB, unpacked −32 kB — on a change I described as type-only. I flagged it as unattributed rather than claiming a cause, and I am not claiming one now. If it is real and caused by type-only importers no longer pulling exec.js into chunks that never needed it, that is a present-tense artifact win independent of W3, and it would be an earned justification rather than a speculative one. If it turns out to be base-drift noise, it is nothing. I can verify it with a build diff if that is worth the round trip; otherwise treat it as unproven.

2. Ownership. This branch came out of a working session where the requester explicitly chose "deliberately prepare for platform packages" as the goal. That instruction and refactor: pnpm workspace — extract packages with enforced public APIs, spine-bottom-up #1490's recorded deferral are in genuine conflict, and the deferral is the repo's decision of record while the instruction is one session's. I am not going to resolve that by unilaterally closing your PR or by arguing the deferral away — I have taken it back to the requester for the call.

Either outcome is fine by me. If it closes, it closes; the diff is mechanical and costs nothing to redo once something actually earns the seam. If it stays open, it needs the trigger recorded and linked exactly as you say, and the description rewritten to stop claiming a prerequisite for work that is deferred.

Holding further pushes until that is settled.

---

Generated by Claude Code

[thymikee]

Closing per your P1 — the requester agrees.

No trigger exists, so the justification did not survive: R6 stayed 7, R9 stayed 47, R11 stayed 10 packages / 32 subpaths, and the 45 behavioral utils/exec.ts imports are untouched. Under a "not now" W3 this was speculative churn, and I framed it as a prerequisite for deferred work when I had concluded the opposite earlier the same session.

The diff is mechanical and costs nothing to redo when something actually earns the seam — a platform/provider contribution or a cleanup incident, per #1490 and #1478's own conditions. Recording what was learned so it is not re-derived:

• ExecResult is host vocabulary, not platform vocabulary. Consumers are 20 platforms / 8 daemon / 3 utils / 3 tests, so platforms are the loudest consumer, not the owner. If this is ever redone it belongs under a contracts/host subpath, not contracts/platform — which is not the @agent-device/host package refactor: pnpm workspace — extract packages with enforced public APIs, spine-bottom-up #1490 rejected, since that rejection was about absorbing exec/version policy, and the policy stays in src/utils/exec.ts either way.
• The real blocker is behavioral, not type-shaped. 45 platform modules import utils/exec.ts for runCmd (98 refs), requireExecSuccess (45), withCommandExecutorOverride (32), execFailureDetails (30), whichCmd (24), runCmdBackground (21) and a tail. That needs injected capabilities (the W1c limrun pattern), and it is the thing any future seam work should be measured against.
• One number left unverified: the size report showed −3.5 kB JS / −32 kB unpacked on a type-only change. I never attributed it and am not claiming it. If a future artifact-size investigation wants a lead, that is one.

Nothing further pushed to the branch.

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-07 15:57 UTC

[thymikee]

Correcting one line in my close comment: I said "nothing further pushed to the branch", and I have now pushed 49a59d1 to claude/platform-seam-exec-result so the work is not lost when this session's container is reclaimed.

This PR stays closed — the push does not reopen it and is not a request to reconsider. The commit is the contracts/host placement described in the close comment (ExecResult is host vocabulary, not platform vocabulary), kept only so it does not have to be re-derived if a future trigger earns the seam.

---

Generated by Claude Code