feat: parse and preserve .ad target-v1 evidence (ADR 0012 migration step 3)

Recording now emits a `# agent-device:target-v1 {...}` comment immediately
before every click/press/longpress/fill action that resolves through the
tree (ref or selector), carrying the identity/ancestry/sibling/scrollRegion/
viewportOrder tuple from decision 3's record-time write algorithm plus a
record-time self-check (verified/unverifiable). The parser accepts known
fields in any order, NFC-normalizes, rejects malformed/oversized annotations
with INVALID_ARGS, binds an annotation only to the immediately-next action
line, and treats unknown future target-vN comments as ordinary comments.
writeReplayScript's read-then-rewrite (heal) path preserves v1 annotations
in canonical form. Nothing consumes the parsed evidence yet beyond
preservation — replay-time enforcement is a later migration step.

The identity tuple's own node/tree only ever lived on the internal
visualization/session-history payload (never the public response); it is
converted to the compact target-v1 evidence and stripped before anything is
persisted or returned.

Author: thymikee

src/commands/interaction/runtime/interactions.test.ts

@@ -127,7 +127,13 @@ test('runtime fill uses backend ref primitive without resolving snapshot geometr
   assert.deepEqual(calls, [{ ref: '@e1', text: 'hello', delayMs: 25 }]);
   assert.equal(result.kind, 'ref');
   assert.equal(result.point, undefined);
-  assert.equal(result.node, undefined);
+  // ADR 0012 decision 3: the native-ref preflight already looked this node up
+  // (for the offscreen/occlusion guards) and now reuses that lookup to carry
+  // `node`/`preActionNodes` for record-time target-binding evidence — at zero
+  // extra capture cost. These never reach the public response (stripped by
+  // `finalizeTouchInteraction`); this is the internal runtime result shape.
+  assert.equal(result.node?.ref, 'e1');
+  assert.ok(Array.isArray(result.preActionNodes));
   assert.deepEqual(result.target, { kind: 'ref', ref: '@e1' });
   assert.equal(result.text, 'hello');
   assert.deepEqual(result.backendResult, { ref: 'e1', text: 'hello' });

src/commands/interaction/runtime/resolution.ts

@@ -492,7 +492,12 @@ export async function preflightNativeRefInteraction(
   options: CommandContext,
   target: Extract<InteractionTarget, { kind: 'ref' }>,
   action: InteractionAction,
-): Promise<{ targetHittable?: boolean; hint?: string }> {
+): Promise<{
+  targetHittable?: boolean;
+  hint?: string;
+  node?: SnapshotNode;
+  preActionNodes?: SnapshotNode[];
+}> {
   const session = await runtime.sessions.get(options.session ?? 'default');
   const nodes = session?.snapshot?.nodes;
   if (!nodes || normalizeRef(target.ref) === null) return {};
@@ -502,7 +507,18 @@ export async function preflightNativeRefInteraction(
   if (!resolved) return {};
   assertInteractionNotBlocked(resolved.node, `Ref ${target.ref}`, action);
   assertVisibleRefTarget(resolved.node, nodes, target.ref, action);
-  return describeNonHittableTarget(resolved.node, action);
+  return {
+    ...describeNonHittableTarget(resolved.node, action),
+    // Reuses the lookup above (zero extra capture cost) so the native-ref
+    // fast path — `click @ref`/`fill @ref` with default options — can still
+    // record ADR 0012 decision-3 target-binding evidence from the stored
+    // session tree, not only from the full resolution path. Stripped back
+    // out of the response before it reaches any caller (see
+    // `interaction-touch-response.ts`/`finalizeTouchInteraction`); never
+    // exposed publicly.
+    node: resolved.node,
+    preActionNodes: nodes,
+  };
 }
 
 // isNodeVisibleOnScreen (not the effective-viewport form): items inside an

src/daemon/__tests__/session-store.test.ts

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { SessionStore } from '../session-store.ts';
 import type { SessionState } from '../types.ts';
 import { buildRequestFinishedEvent } from '../session-event-log.ts';
+import type { TargetAnnotationV1 } from '../../replay/target-identity.ts';
 
 type RecordActionEntry = Parameters<SessionStore['recordAction']>[1];
 
@@ -592,3 +593,56 @@ test('writeSessionLog preserves significant whitespace and empty string argument
     /--metro-host " host\\t" --launch-url "myapp:\/\/dev "/,
   ]);
 });
+
+// ---------------------------------------------------------------------------
+// ADR 0012 decision 3: recorded target-v1 evidence flows end to end through
+// `recordAction` → `SessionScriptWriter` into the `.ad` file, immediately
+// before the action it annotates.
+// ---------------------------------------------------------------------------
+
+const SAVE_TARGET_EVIDENCE: TargetAnnotationV1 = {
+  id: 'save',
+  role: 'button',
+  label: 'Save',
+  ancestry: [{ role: 'toolbar', label: 'Editor' }],
+  sibling: 0,
+  viewportOrder: 0,
+  verification: 'verified',
+};
+
+test('writeSessionLog emits the target-v1 annotation immediately before its action line', () => {
+  const fixture = makeFixture('agent-device-session-log-target-evidence-');
+  recordOpen(fixture.store, fixture.session);
+  fixture.store.recordAction(fixture.session, {
+    command: 'click',
+    positionals: ['@e12'],
+    flags: { platform: 'ios' },
+    result: {},
+    targetEvidence: SAVE_TARGET_EVIDENCE,
+  });
+  recordClose(fixture.store, fixture.session);
+
+  const script = writeScript(fixture);
+  const lines = script.trim().split('\n');
+  const clickLineIndex = lines.findIndex((line) => line.startsWith('click '));
+  assert.ok(clickLineIndex > 0);
+  assert.equal(
+    lines[clickLineIndex - 1],
+    '# agent-device:target-v1 {"id":"save","role":"button","label":"Save","ancestry":[{"role":"toolbar","label":"Editor"}],"sibling":0,"viewportOrder":0,"verification":"verified"}',
+  );
+});
+
+test('writeSessionLog never fabricates a target-v1 annotation for actions recorded without evidence', () => {
+  const fixture = makeFixture('agent-device-session-log-no-target-evidence-');
+  recordOpen(fixture.store, fixture.session);
+  fixture.store.recordAction(fixture.session, {
+    command: 'click',
+    positionals: ['@e12'],
+    flags: { platform: 'ios' },
+    result: {},
+  });
+  recordClose(fixture.store, fixture.session);
+
+  const script = writeScript(fixture);
+  assert.equal(/agent-device:target-v1/.test(script), false);
+});