AGENTS.md routed request cancellation/progress and diagnostics to
`@agent-device/capture-kit` subpaths that no package exports; both live in
`@agent-device/host-kit/request` and `@agent-device/host-kit/diagnostics`. It also
named `@agent-device/contracts` as an importable seam although that package
publishes no root export, and claimed `src/daemon/handlers/session.ts` was over
budget after that extraction already landed at 242 lines.
Two ADRs carried number 0019. The hop trace has its own claims to make, so it now
numbers 0023, joins the index, and keeps the links from ADR 0019 and ADR 0022.
The Node floor split was undocumented: `engines.node` stays at 22.12 because CI
installs the published tarball on that floor, while contributors need 22.13 for the
pinned pnpm. CONTRIBUTING now says so, and installation.md names the 22.12 floor and
the web backend's Node 24 requirement.
Extend the agent-guidance contract to resolve every `@agent-device/*` specifier
AGENTS.md names against the owning package's `exports`, root included, so neither a
phantom subpath nor a phantom package root can route an agent to a module that does
not exist.
* docs(adr): record the #2278 coupling audit and re-trace entry-to-platform hops (ADR 0022)
* docs(adr): re-trace hop tables with spine side-calls excluded from hop counts
* docs(adr): renumber R74 references to R76 after the main merge
* docs(adr): rules-first restructure of 0012/0014/0016, drop completed migration logs
ADR 0012 alone was 42% of the ADR corpus by bytes; consulting it cost ~28k
tokens of mostly process history. Restructure per the new shape convention
(added to the ADR README): Status + a normative 'Rules at a glance' first so
a reader can stop after ~50 lines, rationale and refuted alternatives kept
below the fold, and completed migration plans/landing tables deleted — git
history is the archive.
- 0012: delete migration plan/progress; fix the Status section that still
claimed #1235 unimplemented against its own landing table; demote the
2026-07-10 evidence audit to the end (still cited by the decisions).
- 0014: same; the accepted Android blocking-dialog-recovery evidence gap and
its covering fixture tests move into Status so the waiver survives.
- 0016: verified implemented; rules summary added (nothing was history).
No rule's meaning changed; edits are reorganization plus stale-status fixes.
* docs(adr): propose ADR 0017 — unified request event journal
Apply ADR 0008's registry thesis to events. Inventory (2026-07-24) found four
parallel event vocabularies — ~155 stringly-typed diagnostics phases, the
session events.ndjson, the progress wire stream, and the replay timing trace
(one of its two writers unredacted) — with consumers coupled to emit sites by
string: agent-cost counts runner round-trips by matching two phase names.
Proposal: an EVENT_CATALOG in contracts making every kind a typed,
trait-carrying declaration; the diagnostics scope becomes the single journal
append point; every consumer becomes an explicitly registered sink; all
existing file/wire formats stay byte-compatible behind golden fixtures.
Explicitly rejects pub-sub and event sourcing. Status: Proposed — not indexed
in the ADR README until accepted.
* docs(adr): revise ADR 0017 per architecture review
Address all five review findings and adopt both requested judgments:
- P1 out-of-request events: finalizeRepairTeardown records a synthesized
close during idle-reap/daemon-shutdown with no live request; a
request-scoped-only journal would silently drop it. Added an explicit
session-scoped teardown scope model (fatal-scope precedent) and rejected
the ambient-fallback alternative.
- P1 redaction vs byte-compat: progress stays unredacted on its own channel;
the replay-trace unredacted->redacted change is now a declared, intentional
compatibility change with its own fixture update, not smuggled under a
byte-compat claim.
- P1 per-attempt trace routing: sinks with dynamic destinations read
scope-bound routing context (logPath-rebind precedent); drop-when-unbound
semantics; sink ordering/isolation/flush contract made normative.
- P2 progress typing: progress streaming removed from the journal entirely -
it is a transport-owned output port (ordering, disconnect-as-cancellation,
closed typed union); mirror emits noted as the future opt-in shape.
- P2 completeness check: orphan detection is now a static source scan in the
layering-lint style; runtime unit-suite observation explicitly rejected.
Also per review: catalog keys are internal identities; sinks map to legacy
wire discriminators, which are never automatically canonical. Migration plan
reduced to 4 steps.
* docs(adr): ADR 0017 — fork, never rebind, for per-attempt trace routing
Review found a blocking concurrency flaw in the revised routing design:
sharded test attempts run concurrently (Promise.allSettled in
runReplayTestShards) under one inherited AsyncLocalStorage request scope, so
mutable scope rebinding would let one attempt overwrite or clear another's
replay-timing destination after an await — cross-writing or dropping events.
Replace rebinding with a journal fork primitive: journal.fork(bindings, fn)
runs fn in a new ALS scope object sharing the parent's buffer/phaseCounts/
envelope/sinks but carrying frozen routing bindings. Each attempt wraps its
work (including nested replay dispatch) in a fork binding its own trace
path; the binding dies with the fork, so no clearing step exists to race.
Existing updateDiagnosticsScope rebinds stay confined to sequential request
setup, pre-fan-out. Validation gains a concurrent-shard regression proving
each replay-timing.ndjson contains only its own attempt's events.
* docs(adr): ADR 0017 — scope identity on the envelope for future exporter sinks
Reserve the one shape decision an OTel-style exporter would otherwise force
a retrofit for: every scope (request, teardown, fork) carries scopeId, forks
record parentScopeId, both ride the event envelope. Forks already form a
tree, so an exporter sink can emit parent-child spans from envelope fields
alone. Cross-process correlation stays requestId; a traceparent-style meta
field is additive under ADR 0006 and deferred. No exporter in this ADR.
* docs(adr): address re-review — renumber to 0018, full fork isolation, 0016 record-as
1. Renumber the proposal 0017 -> 0018: main now carries accepted ADR 0017
(parameterized recorded inputs, #1369); branch rebased onto it.
2. Fork contract strengthened: forks clone EVERY mutable scope field
(envelope, logPath, routing bindings) and own their event buffer; only
the sink list and the request-global phaseCounts tally are shared.
Verified in code: nested dispatch creates child execution scopes
(request-router.ts:257) whose updateDiagnosticsScope rebinds
session/logPath mid-flight, so a shared mutable envelope would
cross-route debug/session-log events between concurrent shards even with
frozen trace bindings. updateDiagnosticsScope now specified as mutating
only the innermost scope. The regression now covers all three routed
outputs (replay-timing, per-request diagnostics ndjson, events.ndjson).
3. 0016 rules summary updated for shipped #1348: sensitive fills use
fill --record-as <VAR> (ADR 0017); unparameterized fill/type stays
literal (body sections already updated by #1369's merge).
* docs(adr): ADR 0018 — name the usage sink as first consumer, privacy by construction
The motivating consumer is opt-in usage analytics over agent behavior:
command frequencies, typed failure codes, and outcome sequences that trip
agents (consecutive snapshots, screenshot-after-snapshot). Decision 4 pins
its discipline now, before any exporter exists: an allowlist-by-construction
UsageRecord schema whose every field draws from a registry-enumerated
vocabulary (command names, ADR 0010 error codes, flag names, durations,
hashed session + sequence number) — positionals, selectors, labels, fill
text, and error messages are unrepresentable by type, not redacted.
Anti-pattern detection is downstream analysis over the stream, never
emission-side logic; the sink itself is a follow-up after migration step 3.
Adds the matching invariant and a schema gate to validation.
* docs: ADR-0012 Decision 7 — agent-supervised re-record repair
Adds "heal-by-doing": when replay diverges on selector drift, the agent
performs the failed step's intent with ordinary interactive commands
against blessed refs, and the CLI emits the healed .ad from the session's
actual successful execution path (session.actions) instead of hand-edited
selector text. Folds in five normative protocol rules (R1-R5) from an
external design review (verdict: SOUND-WITH-FIXES) covering record-arming
timing, --from continuation semantics, mechanical repairHint routing, the
writer's bare-@ref fail-close, and the recorded-open requirement. Makes
explicit that this reintroduces an EXPLICIT, opt-in heal and is therefore
consistent with (not a reversal of) decision 1's retirement of --update's
SILENT auto-rewrite.
* docs: renumber to Decision 6 and make repairHint the mechanical primary router
- Rename 'Decision 7' -> 'Decision 6' (ADR has decisions 1-5; new one is the
6th, placed after 5. Mandatory validation; existing decisions unchanged).
- Reframe the two-sub-flows router: the CLI-computed repairHint (mechanical,
in-scope, ships with this decision per R3) is the PRIMARY router; the agent
follows the hint and uses screen.refs only as an ambiguity override, not as
the default router. Removes the agent-judgment-vs-R3 contradiction.
* docs: ADR-0012 Decision 6 — daemon-side repairHint (4 kinds) + repair-run boundary (R6)
Addresses two P1 review gaps:
- P1-A: state that repairHint is computed daemon-side at divergence time from
the recorded targetEvidence + the daemon's own full pre-action capture (only
the enum crosses the wire, so the flat/capped screen.refs never gate routing);
define repairHint for all four divergence kinds (selector-miss, identity-
mismatch, identity-unverifiable, action-failure) with the sparse-capture
fail-safe to manual.
- P1-B: add R6 — --save-script records a boundary watermark (session.actions.
length at invocation); the healed script serializes only the post-watermark
slice, so a reused session's earlier actions don't pollute it.
Clarifications: R4 fails loudly (non-zero exit, never swallowed); exact default
output path = <original-stem>.healed.ad sibling; arming sets recordSession AND
the watermark before step 1.
* docs: ADR-0012 — declare repairHint in the wire contract + make R3 total
Addresses three protocol blockers:
- Blocker 1: add repairHint to Decision 4's details.divergence field list and
spec it as a single bounded enum (record-and-heal|state-repair|caution|manual),
present on every divergence, carried at every level, surviving all four
projections (text/JSON/client/MCP).
- Blocker 2: make R3's mapping total — no recorded targetEvidence (reachable for
unannotated action-failure per #1223, or any kind on a legacy script) => manual,
generalizing the sparse-capture fail-safe.
- Blocker 3: correct capture-timing — target-binding kinds use their PRE-action
tree; action-failure uses its POST-response tree (adequate for the container
presence test); no new pre-action tree is stored for action-failure.
Validation extended for the projection-survival and no-evidence/post-response cases.
* docs: add ADR 0012 for interactive replay, resolution disclosure, and retiring --update healing
Records the decision to retire --update healing as a silent actor (repurposing
its candidate machinery as ranked suggestions), disclose selector
disambiguation in every interaction response, verify replay steps against
record-time identity evidence, and add an interactive replay --from loop with
a structured divergence report for all callers.
* docs(adr-0012): ground in live replay evidence; require step provenance for --from
Adds hands-on evidence from driving replay on the RN playground (silent
text-mode success, app-state divergence heal cannot fix, Maestro step-index
shift from runFlow flattening, per-format hint/code inconsistency, recordings
carrying zero observation steps), makes step provenance (source file + line,
including through Maestro runFlow inlining) a requirement of the divergence
report plus an optional replay --list-steps dry-run, and adds a one-line
text-mode success summary as decision 4d.
* docs: make interactive replay ADR implementable
* docs: tighten interactive replay contracts
* docs(adr-0012): demote geometry to disambiguation signal, fix matchCount, define matching algorithm
Reworks the target-v1 contract per review: identity is recorded id, else
role + normalized label, plus a leaf-anchored ancestry prefix (K=8, nearest
ancestors kept, root-side truncation only); absolute rects are demoted to
never-compared diagnostics with the ±8 tolerance removed rather than tuned;
duplicates disambiguate by recorded sibling order among the matching set,
then viewport-relative order within the recorded scroll region — never
absolute pixels; ties are identity-unverifiable divergences with candidates
listed. matchCount is redefined as the replay-time recorded-selector match
count (0..N, always present), with selector-miss (0) and identity-mismatch
(>=1, no identity candidate) as distinct classes in an explicit six-path
verification classification. Also inlines the quantitative benchmark numbers
(3.67->1.00 snapshots, 14.3 vs 23.3/26.7 commands, 38/38 in 539s) so the
evidence is durable without the external harness directory.
* docs(adr-0012): unify positional-signal candidate domains between record and replay
Fixes the P1 domain mismatch: sibling becomes a genuine same-parent child
index (parent already captured as ancestry[0], no new field; identical by
definition on both sides, non-isolating when the same index recurs under
different parents); viewportOrder gets one region-scoped domain — the
identity set partitioned by scroll region, ordinal within the recorded
partition on both sides, unavailable (never compared cross-region) when the
recorded region no longer exists; document order (pre-order index) is the
canonical total order making every ordering deterministic, including equal
rect centers. Residual ties stay identity-unverifiable with candidates
listed. Record-time write, replay verification, and mandatory validation
updated in lockstep; the six-path classification is unchanged.
* docs(adr-0012): conditional matchCount, dependency-ordered migration, writer invariant, suggestion ranking contract
* docs: refocus AGENTS.md on principles and gates; index ADRs; extend CONTEXT.md vocabulary
AGENTS.md: replace the routing/command-family prose maps (already
drifting from the code) with pointers to the self-describing,
parity-tested registries; add the two sections agents actually cannot
rediscover cheaply — Principles (one line per incident-backed lesson)
and Enforcement gates (the classify-don't-suppress index); extend the
module-size guidance from raw LOC caps to answer-one-question files,
1:1 test topology mirroring (removing the integration-aggregation
exemption that produced 3,400-line test files), sibling fixture
modules, claim collocation, and boundary-only barrels; record the
dev-loop staleness triple (dist/daemon/adopted-runner), the tsgo
typecheck, the Gatekeeper first-node-exec stall, the DEVICE_IN_USE
signature, and the contention-flake protocol; append the two gate
steps to the new-flag checklist.
CONTEXT.md: vocabulary for the ADR 0011 domain (dispatch path,
guarantee cell, owned waiver, parity table, coverage manifest,
delegation-on-error, ref generation pin) and an architecture paragraph
positioning ADR 0011 as ADR 0008's interaction-semantics counterpart.
docs/adr: flip 0011 to Accepted (implemented through Layer 3) and add
a read-this-when index that names the registries as the living source
of truth over ADR prose.
* docs: defer versioned-ref references to the implementing PR
Review sequencing note on #1097: these lines described #1096 behavior
not yet on main. They move to #1096's branch so docs land with the
implementation and the two PRs merge in any order.
Michał Pierzchała