* refactor: split generic host mechanics into @agent-device/host-kit (#2082 W1)
The shared src/utils closure that blocked the platform-family moves lands
on declared owners: generic host mechanics form a new private
@agent-device/host-kit package between kernel and capture-kit, and
capture-kit keeps capture, snapshot, and recording behavior, depending on
host-kit for the mechanics it needs. tar-stream and yauzl move with the
archive code.
Every seam's exported subpaths are pinned in package-boundaries.test.ts,
the layering model ranks the new zone, R13's allow-list names it, and each
seam carries an exact eager-closure row. ADR-0019's substrate amendment
describes the layout.
Tests that mocked two of the moved modules separately became duplicate
same-seam vi.mock factories, where the second silently replaced the first;
those are merged, and the mocks that production code reaches past are
pinned at their injection points instead.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* refactor(host-kit): one narrow capability port per export
The four technical barrels (exec/fs/values/request) grouped by category
rather than by capability, so a consumer needing one mechanic evaluated
unrelated ones. Each export is now a single capability over the host
machine: command, process, diagnostics, retry, archive, file, request,
version. A port re-exports only what a consumer of that capability uses,
and every port carries its own eager-closure row.
Most of the old values barrel was never host mechanics. Pure record
readers, config-source values, result text, memoization, async scoping,
coordinate validation, and device-scope parsing touch no process, file, or
environment, so they join kernel's other primitives instead.
Closures fall accordingly: capture-kit's png-worker-client from 20 to 10,
png-resize from 28 to 18, session-teardown from 79 to 68, and the CLI from
386 to 380.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* chore: drop the migration inventories and trim the touched comments
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* docs: trim the touched host-kit and mutation-lane comments
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* docs: keep tool directives only in the touched files
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* docs: keep tool directives only across the touched tree
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* fix: point the Swift parity comment at the real TS twin and test
The W1 move rewrote this citation to packages/contracts/src/mobile-snapshot-semantics.ts,
which does not exist: the module went to capture-kit while isTapPointInsideViewport itself
went to packages/contracts/src/snapshot-visibility.ts. The TS test line was left pointing at
the pre-move path. Both now resolve.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
* fix: repoint comment citations at the homes this refactor moved them to
The W1 move left ~20 comment citations pointing at src/utils/*.ts and
src/request/*.ts paths that no longer exist. Each now names the capability
port that owns the symbol, which survives further file moves:
exec -> host-kit/command host-process, owner-identity -> host-kit/process
diagnostics -> host-kit/diagnostics atomic-file, process-lock -> host-kit/file
retry -> host-kit/retry request progress/cancel -> host-kit/request
version -> host-kit/version ttl-memo, source-value, parsing, device-isolation,
keyed-lock, success-text -> kernel subpaths
Comment-only; no closure, budget, or behavior change. ADR citations are left
as written, being dated records of the decision rather than live references.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH
---------
Co-authored-by: Claude <noreply@anthropic.com>
#1959 granularized the contracts entry surface but left the wide
platform/interaction façades in place as a compatibility surface for
~490 type-only importers. This mechanically moves every importer
(~350 files) onto the granular subpath each symbol actually lives on,
deletes the two façade files, and removes the fallow ignoreExports
entries and eager-closure-budget rows that existed only to cover them.
Eight previously-unexported source files needed new package.json
subpaths (clipboard, keyboard, network-traffic, platform-plugin,
platform-providers, runner-lease-context, screen-recording-runtime-host),
and ./interaction now points directly at src/interaction.ts instead of
the deleted barrel. .oxlintrc.json's no-restricted-imports rules for
the two façades are removed since there's no wide facade left to warn
against value-importing.
* test: daemon leak oracle around the real-subprocess daemon lanes (#1781 B1)
Adds test/integration/support/daemon-leak-oracle.ts and calls it at the end of
smoke-daemon-clean, smoke-daemon-http and daemon-replace-exit-flush. After
shutdown the oracle asserts that no daemon-owned process survives (ownership:
PPID descendant, PGID = daemon pid, AGENT_DEVICE_STATE_DIR env, state-dir
argv — never global counts) and that the isolated state dir holds only
classified artifacts (no *.tmp, no daemon.json/lock without a live daemon, no
open capture descriptor).
Red-proofs: pre-fix #1324 (a84caa818) leaves simctl recordVideo with ppid 1 /
pgid = dead daemon; pre-fix #1109 (be4bd092b) leaves the agent-browser daemon
plus its Chrome fleet. Both are clean on main.
Refs #1781#1431
* test: fail the daemon leak oracle on a surviving daemon and pin its rules
Review of #1859 found the oracle reported "clean" when the daemon itself
outlived shutdown: daemon pids were excluded from ownership, liveDaemonPids
never reached hasDaemonLeaks, and a live daemon even flipped daemon.json/lock
from stray to expected. stopProcessForTakeover is best-effort void, so only
smoke-daemon-clean independently asserted death.
- a live daemon pid at phase 'after-shutdown' is now itself a leak, and its
metadata files stay stray; a live daemon remains legitimate at 'after-close'
- split the pure ownership/residue rules into daemon-leak-model.ts and pin them
with daemon-leak-model.test.ts, using the real ps rows captured during the
#1109 and #1324 red-proofs (the lanes' daemons own no children, so the fixture
test is what guards those shapes in CI)
- exempt the managed tools/ install tree before the .tmp rule, so agent-browser's
own download temporaries are no longer a false LEAK
- report empty directories as residue (an unswept session scaffold leaves no file)
- reuse src/utils/host-process.ts (expandProcessTree, uniquePositivePids) and its
/bin/ps convention instead of re-deriving them
- assert in smoke-daemon-http on the success path, not in finally, so the settle
window cannot replace a primary assertion's diagnostic
Refs #1781#1431
* test: make the leak oracle's after-close phase name the session that closed
Re-review of #1859: `after-close` accepted every capture descriptor and legacy
marker, so the closed session's unfinalized handle was indistinguishable from
another session's legitimately live one — the phase could not fail, the same
shape as the surviving-daemon blocker, and it left half of B1's stated scope
undelivered.
- the observation carries the session directories closed at the checkpoint; a
capture handle must be finalized once its owning session is gone (every
session after shutdown, only the closed ones after close), while another
session's live handle stays expected and a legacy pid marker is never a
finish record
- the oracle accepts `closedSessions` and a `sessionsDir` override, normalizing
entries to the canonical `sessions/<name>/…` shape so an in-process harness
rooted directly at its own sessions dir is classified the same way
- add a real route regression: a provider-backed session with a live screen
recording is closed through the daemon route, and the oracle refuses a
descriptor left `lifecycle: "open"`. Reverting the close-route finalization
(session-close-lifecycle-teardown.ts, the #1325 fix) turns it red naming
sessions/default/screen-recording.resource.json; with the pre-fix model it
stays green, which is the P1 in one line
Refs #1781#1431
* test: require the closed-session identity at the leak oracle's owning interface
Re-review of #1859: `closedSessions` was optional and defaulted to empty, so any
caller — or the standalone CLI invoked with `--phase after-close` and no
`--closed-session` — silently restored the vacuous checkpoint that accepts every
unfinalized capture handle and reports clean.
- phase and the identity that phase needs are now one discriminated shape:
{ phase: 'after-close'; closedSessions: NonEmpty<string> } | { phase:
'after-shutdown' }, so the empty case is not expressible and 'after-shutdown'
is unchanged
- the CLI refuses the same invocation with a typed INVALID_ARGS error and a hint
naming what the missing identity would have cost, instead of degrading
- daemon-leak-oracle-cli.test.ts drives the real CLI: the unnamed after-close
invocation must fail without reporting, the named one finds the planted
unfinalized handle, and after-shutdown is unaffected. Reverting the guard makes
it print 'clean (after-close)' over that same handle and turns the test red
Refs #1781#1431
* test: split the leak oracle's unrecorded process arm out of the lane path
Maintainer asked whether the harness can be trimmed. The two arms differ in kind:
the daemon already records captures and state-dir artifacts, so those rules are
short and fire on every lane run; nothing records what a daemon spawned, so the
process arm reconstructs ownership from the OS four ways — and the three CLI
daemon lanes are device-free, so it only ever compared an empty set to an empty
set.
Move that arm to test/integration/support/daemon-owned-process-probe.ts, the
manual script that produced the #1109/#1324 evidence, and keep its rules pinned
by a fixture test (no lane can run the probe, so its fixtures are the only CI
guard on those shapes). The shipped oracle keeps every guarantee it had:
surviving daemon at after-shutdown, the closed-session finalization rule, the
state-dir allowlist, the CLI refusal, and the phase-discriminated types.
Lane-path harness 852 → 548 LOC (-36%); repo total roughly flat, because the
ownership reconstruction can be relocated but not deleted. That is the argument
for the follow-up: once the daemon records owned child pids the way it records
captures, the arm collapses to "read the record, assert they are dead" and moves
back into the oracle.
Re-proved after the move: #1324 against pre-fix a84caa818 on an iPhone 16
simulator still goes red through the probe (simctl recordVideo, ppid 1,
pgid = the dead daemon, 0-byte mp4), and clean once the orphan is reaped.
Refs #1781#1431
* test: guard the daemon-owned-process arm in CI on the live web lane
Re-review of ce9f0eeb: moving that arm to a manual probe left the two failures
B1 exists to prevent detectable only by hand, and a fixture test proves regexes
recognize synthetic rows, not that the shipped route reaps what it spawned.
Restore the arm to the shipped oracle (the three files return byte-identical to
3a5b9bef3) and give it a lane that can execute it: smoke-web-platform is the one
CI route whose daemon owns real children — the managed agent-browser daemon and
its Chrome fleet. After the normal smoke it reopens a session, stops the daemon
with that session still open (the #1109 shape: an ordinary close reaps the fleet,
so only an unclosed session can strand it), and requires that nothing owned
outlives the browser idle window.
Proven both ways locally: green in 59s, and red when the fleet is stranded
(browser idle window raised past the settle budget) with the oracle naming 15
owned processes — the #1109 signature, in a lane that runs on every PR.
Also: daemon-replace-exit-flush cleared `info` before the oracle ran, so a failed
stop would skip the `finally` retry and remove the state dir while the daemon was
still alive. Clear it only once the checkpoint passes.
Refs #1781#1431#1882
* docs: align daemon leak coverage rationale
* refactor(test): narrow daemon oracle to durable state leaks
* fix: stabilize replay nightly fixture boundaries
* test: stabilize exit flush integration coverage
* chore: drop the deleted exit-naive fixture from fallow's entry list (#1610 review P3)
* fix: flush stdout/stderr before every CLI process.exit() (#1596)
Node only flushes process.stdout/stderr synchronously to a file or TTY;
on a pipe (the normal condition for this CLI when driven as a
subprocess) a write queued right before process.exit() can be silently
dropped. handleRunCliFailure's --debug daemon-log-tail dump made this
reachable from the exact path that renders a SESSION_NOT_FOUND error
right after a daemon replace, matching field reports of the driving
process going silent immediately after "Replacing daemon ... unreachable"
plus the SESSION_NOT_FOUND error.
Add exitAfterFlush() and route every process.exit() in src/cli.ts and
src/bin.ts through it, so a piped caller always receives the full
structured error (with its "run open first" hint) before the process
terminates. Also bound the --debug log-tail dump to a byte cap instead
of an unbounded 200 lines.
Verified directly against the real CLI (piped subprocess, pre-fix vs
post-fix): a live daemon with a seeded >64KB log truncates its --debug
error output before the fix and delivers it in full after.
* fix: satisfy CI gates on #1596 (format, fallow, coverage)
- oxfmt formatting on the new integration test file.
- Register the two exit-flush regression fixtures (support/exit-naive.ts,
support/exit-after-flush.ts) as fallow entry points: they're run as real
subprocesses via a string path (runCmdSync), which fallow's static
dependency analysis can't follow, same as the existing
test/contention-retry-fixtures/* entries. exit-payload.ts becomes
reachable transitively through their static imports. Also switched the
integration test's local PAYLOAD_MARKER duplicate to import the one
fallow flagged as unused from exit-payload.ts.
- Added real unit coverage for the new exitAfterFlush code paths, since
node --test integration files aren't measured by the vitest coverage
gate: src/utils/__tests__/process-exit.test.ts exercises the
already-drained, backlogged-then-drains, and never-drains/timeout
branches directly against a fake stream; src/__tests__/cli-exit-paths.test.ts
drives runCli() for --version, bare help, no-command, and web to cover
their exitAfterFlush call sites, plus a --debug case with a >64KB seeded
daemon.log proving printDaemonLogTailOnError's new byte cap actually
trims the oldest lines.
Changed-line coverage gate now passes at 92.59% (was 59.26%); the two
remaining uncovered lines are the bottom-of-file `isDirectRun` catch
handler, which only runs when cli.ts is executed as the literal entry
script and is not reachable by importing it as a module in a test (the
same shape as bin.ts's already-excluded top-level fast paths).
Michał Pierzchała