docs: fix phantom specifiers, the duplicate ADR 0019, and the Node floor

[thymikee]

Summary

Closes #2520.

AGENTS.md routed request cancellation/progress and diagnostics to @agent-device/capture-kit
subpaths no package exports. Real homes: @agent-device/host-kit/request (40 importers) and
@agent-device/host-kit/diagnostics (106 importers, 0 for the capture-kit spelling). It also claimed
src/daemon/handlers/session.ts was over budget; that extraction already landed and the file is 242
lines, so the bullet is gone.

0019-end-state-hop-trace.md becomes ADR 0023: it is indexed in docs/adr/README.md and both
links to it (from ADR 0019 and ADR 0022) follow the rename.

I did not raise engines. The issue reads pnpm@11.17.0's >=22.13 as the runtime floor, but that
is a dev-tooling constraint: ci.yml runs scripts/check-package.ts on the installed tarball at
Node 22.12 precisely to verify "what a user on engines.node floor actually installs", and says so.
Raising engines to 22.13 would drop users CI proves work and make that job's stated purpose false.
So the floor stays 22.12 and the contributor requirement is what gets documented — CONTRIBUTING now
names 22.13 for the pinned pnpm, and README keeps 22.12. installation.md names the 22.12 floor and
the web backend's Node 24 hard fail (agent-browser-tool.ts:280), which it previously omitted.

agent-guidance-contract.test.ts now resolves every @agent-device/* specifier AGENTS.md names
against the owning package's exports, root included. That enforcement immediately caught a
second phantom in the same sentence: AGENTS.md listed @agent-device/contracts as an importable seam,
but the package publishes only subpath exports (./interaction, ./replay, ./snapshot, …) and no
. entry, so nothing can import it that way. Cross-layer contracts now route to
packages/contracts/src, which is how the rest of that section names a declaration site.

Validation

Docs and manifest only, so no runtime test applies. pnpm check:agent-guidance passes (5 tests) and
names both planted violations at a16821b661: restoring @agent-device/capture-kit/diagnostics in
AGENTS.md fails with "AGENTS.md names a subpath @agent-device/capture-kit does not export", and
deleting the . export from packages/selectors/package.json fails with "AGENTS.md imports a package
root @agent-device/selectors does not export". pnpm check:quick passed and pnpm check:affected --run at a16821b661 passed every selected check except mutation-model, which fails identically on
a clean origin/main tree in this worktree: its claim that
src/commands/interaction/runtime/gestures.test.ts reaches the scroll-edge-state kernel went stale
when the scroll path moved to src/daemon/scroll-runtime.ts. Pre-existing, advisory in CI (the
workflow triggers on scripts/mutation/** only) and unrelated to this diff — worth its own fix.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-13 08:16 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.50 MB	4.50 MB	-5.0 kB
Package (unpacked)	4.50 MB	4.50 MB	-5.0 kB
Package (download)	1.33 MB	1.32 MB	-1.8 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.7 ms	27.8 ms	+0.1 ms
CLI --help	76.7 ms	76.5 ms	-0.2 ms

[thymikee]

The documentation corrections and the runtime-versus-contributor Node floor are sound at 69d62bc. One gap remains in the requested export check: agent-guidance-contract.test.ts:91 skips root specifiers, so deleting the . export for @agent-device/selectors or @agent-device/contracts would still pass. Check the root export as well as subpaths, with a failing root-export case. Current checks pass and there are no conflicts; this is a gap in the new enforcement, not a runtime defect.

[thymikee]

Fixed at a16821b661. The root branch of the loop now asserts the package publishes . instead of continue-ing past it, so a bare specifier is checked like a subpath.

The check bites immediately: AGENTS.md listed @agent-device/contracts as an importable seam, and that package publishes only subpath exports (./interaction, ./replay, ./snapshot, …) with no . entry. It now routes to packages/contracts/src, matching how the rest of that section names declaration sites.

Both planted violations fail with typed messages:

• packages/selectors/package.json minus its . export → @agent-device/selectors: AGENTS.md imports a package root @agent-device/selectors does not export
• @agent-device/capture-kit/diagnostics restored in AGENTS.md → AGENTS.md names a subpath @agent-device/capture-kit does not export

pnpm check:agent-guidance 5/5 and pnpm check:quick pass at this head; check:affected is clean except the pre-existing mutation-model ownership claim, which fails the same way on a clean origin/main in this worktree.

[thymikee]

CI note for a16821b661: the first attempt of the iOS workflow failed its Smoke Tests job in RunnerTests+AlertObservationTests.swift:75 — testAlertCannotProveAnIdenticalReplacementAndDoesNotActivateIt compared First actions: 0; replacement actions: 0 against an expected one action, i.e. the alert exposed no buttons inside its deadline. Attempt 2 of the same run is green, and this diff touches no Apple source.

It is not unique to this branch. On main@973b74cc the same workflow failed the same file at line 72 (testAlertDismissDoesNotActivateAReplacementWithTheSameTitle, ALERT_DEADLINE_EXCEEDED), and on main@8e8eeb2c it failed Run fixture-backed iOS simulator E2E smoke at test/integration/ios-simulator-e2e/live-automation-scenario.ts:33. The alert-observation smoke family is red-or-flaky on main independently of this PR.

Current state at this head: 21 checks success/skipped, mergeable_state: clean.

[thymikee]

The root-export guard is fixed on a16821b, including the invalid contracts root reference. The reported planted-red cases exercise both root and subpath checks. No actionable findings remain; current checks pass and there are no conflicts. Ready for human review and merge.