From 6ea76f4e151bd3061785fc7351b5b4c568c58a75 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 4 Jul 2026 16:36:09 +0000
Subject: [PATCH] feat(m3.7): trace and replay (tron trace / tron replay)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Records automation commands into a .trontrace bundle and replays them (PRD §19).

  tron trace start [path]   tron trace stop   tron trace status
  tron replay <bundle>

- browser-core/automation/trace.ts: the bundle format — metadata.json,
  commands.jsonl (values redacted), snapshots/NNNN.json, errors.jsonl. Recording
  is cross-process via an active-trace pointer under the data dir.
- automate-cli: `trace` (start/stop/status) and `replay` commands; snapshot/
  click/fill now append to the active trace (a fresh snapshot per command).
  Form values are redacted by default (fill/type -> "[redacted]").
- replay re-runs clicks and non-redacted fills in order, skips redacted fills
  and snapshots, and stops at the first failing command with its seq.
- install.sh routes `tron trace` / `tron replay` to the automation runtime.

Tests (+10): the trace library (start/record/stop/read, redaction, errors) and
the CLI trace/replay flow (record between start/stop, redaction persisted,
status, replay clicks + skip redacted fills). Verified end-to-end via a WS CDP
stub: recorded snapshot/click/fill, finalized bundle with per-command snapshots,
replayed the click and skipped the redacted fill. Full workspace suite green.

Network/console summaries (§19) need a persistent listener and are a follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/public/install.sh                    |   6 +-
 docs/trace-replay.md                          |  53 ++++++++
 packages/browser-core/src/automate-cli.ts     |  96 ++++++++++++-
 .../browser-core/src/automate-trace.test.ts   | 104 ++++++++++++++
 packages/browser-core/src/automation/index.ts |   3 +
 .../browser-core/src/automation/trace.test.ts |  78 +++++++++++
 packages/browser-core/src/automation/trace.ts | 128 ++++++++++++++++++
 7 files changed, 464 insertions(+), 4 deletions(-)
 create mode 100644 docs/trace-replay.md
 create mode 100644 packages/browser-core/src/automate-trace.test.ts
 create mode 100644 packages/browser-core/src/automation/trace.test.ts
 create mode 100644 packages/browser-core/src/automation/trace.ts

diff --git a/apps/web/public/install.sh b/apps/web/public/install.sh
index e842fd1..95e4304 100755
--- a/apps/web/public/install.sh
+++ b/apps/web/public/install.sh
@@ -93,6 +93,8 @@ Usage:
   tron run <script>     Run a JS/TS script using @tronbrowser/sdk (--headless/--trace)
   tron analyze [goal]   Analyze/fill a form or page (--data, --execute, --json)
   tron mcp              Run a local MCP server over stdio (--headless)
+  tron trace start|stop Record commands into a .trontrace bundle
+  tron replay <bundle>  Replay a recorded trace against the session
   tron upgrade          Update to the latest release
   tron remove           Uninstall TronBrowser (keeps your profile data)
   tron version          Print the installed version
@@ -175,8 +177,8 @@ case "${1:-}" in
     SESSION="$(session_bin)"
     [ -x "$SESSION" ] || { echo "This TronBrowser build has no managed-session support (missing tron-session). Run: tron upgrade" >&2; exit 1; }
     exec "$SESSION" browser "$@" ;;
-  snapshot|click|fill|type|extract|screenshot|pdf)
-    # CDP automation on the managed session's current page (PRD M3.2/M3.3).
+  snapshot|click|fill|type|extract|screenshot|pdf|trace|replay)
+    # CDP automation on the managed session's current page (PRD M3.2/M3.3/M3.7).
     run_automation "$@" ;;
   analyze)
     # AI-assisted unknown-interface analysis / form fill (PRD M3.5). Runs via
diff --git a/docs/trace-replay.md b/docs/trace-replay.md
new file mode 100644
index 0000000..07a9094
--- /dev/null
+++ b/docs/trace-replay.md
@@ -0,0 +1,53 @@
+# Trace and replay (M3.7)
+
+Record the automation commands you run against a managed session into a
+`.trontrace` bundle, then inspect or replay them.
+
+```sh
+tron trace start ./run.trontrace   # begin recording (path optional)
+tron snapshot                      # …commands are recorded as you go
+tron click @e3
+tron fill @e4 "hi@example.com"
+tron trace status                  # show the active trace
+tron trace stop                    # finalize the bundle
+tron replay ./run.trontrace        # replay the recorded commands
+```
+
+`tron run --trace <dir>` also writes a (simpler) trace for SDK scripts — see
+[sdk-and-run.md](./sdk-and-run.md).
+
+## Bundle format
+
+A `.trontrace` bundle is a directory:
+
+```
+metadata.json          version, startedAt/stoppedAt, command count
+commands.jsonl         one record per command: { seq, t, name, args, snapshot?, error? }
+snapshots/NNNN.json    the page snapshot captured after each command
+errors.jsonl           errors keyed by command seq
+```
+
+While a trace is active, an "active trace" pointer under
+`~/.tronbrowser/automation/trace.json` tells each `tron` command (a separate
+process) where to append, and clears on `stop`.
+
+## Privacy
+
+**Form values are redacted by default.** A `tron fill @e4 "secret"` records the
+ref and `value: "[redacted]"` (with `valueRedacted: true`) — never the text.
+Cookies, tokens, and secrets are never written.
+
+## Replay
+
+`tron replay <bundle>` re-executes the recorded commands in order against the
+current session: clicks and non-redacted fills are replayed; redacted fills are
+**skipped** (the value isn't in the bundle), and snapshots aren't re-run.
+Replay stops at the first failing command (e.g. a stale ref) and reports the
+sequence number — good for reproducing deterministic navigation/click flows.
+
+## Scope
+
+- Requires Node ≥22 and a running managed session for recording/replay.
+- Network/console summaries (PRD §19) need a persistent session listener and are
+  a follow-up; the command/snapshot/error core is implemented here.
+- Trace library: `packages/browser-core/src/automation/trace.ts`.
diff --git a/packages/browser-core/src/automate-cli.ts b/packages/browser-core/src/automate-cli.ts
index e935a07..7081686 100644
--- a/packages/browser-core/src/automate-cli.ts
+++ b/packages/browser-core/src/automate-cli.ts
@@ -22,6 +22,14 @@ import { CdpClient, type CdpConnection } from './automation/cdp-client.js';
 import { cdpListUrl } from './automation/cdp.js';
 import { descriptorPath, parseDescriptor, resolveDataDir } from './automation/descriptor.js';
 import { printPdf, screenshotPng } from './automation/capture.js';
+import {
+  readActiveTrace,
+  readCommands,
+  recordCommand,
+  startTrace,
+  stopTrace,
+} from './automation/trace.js';
+import type { AgentSnapshot } from './automation/snapshot-script.js';
 import { extractExpression, parseFieldSpec, type FieldSpec } from './automation/extract-script.js';
 import {
   captureSnapshot,
@@ -107,6 +115,27 @@ async function attach(deps: CliDeps, dataDir = resolveDataDir(deps.env)): Promis
   return conn;
 }
 
+/** If a trace is active, append this command (+ a fresh snapshot) to it. */
+async function traceRecord(
+  env: NodeJS.ProcessEnv,
+  conn: CdpConnection,
+  name: string,
+  args: Record<string, unknown>,
+  snapshot?: AgentSnapshot,
+): Promise<void> {
+  const active = await readActiveTrace(resolveDataDir(env));
+  if (!active) return;
+  let snap = snapshot;
+  if (!snap) {
+    try {
+      snap = await captureSnapshot(conn);
+    } catch {
+      snap = undefined;
+    }
+  }
+  await recordCommand(active.dir, name, args, snap ? { snapshot: snap } : {});
+}
+
 /** Collect all `--field name=selector[@attr]` specs from an arg list. */
 function collectFields(args: string[]): FieldSpec[] {
   const specs: FieldSpec[] = [];
@@ -202,6 +231,7 @@ export async function run(argv: string[], overrides: Partial<CliDeps> = {}): Pro
           conn,
           rest.includes('--include-hidden') ? { includeHidden: true } : {},
         );
+        await traceRecord(deps.env, conn, 'snapshot', {}, snap);
         deps.out(rest.includes('--json') ? JSON.stringify(snap, null, 2) : formatSnapshotText(snap));
         return EXIT.ok;
       }
@@ -212,7 +242,9 @@ export async function run(argv: string[], overrides: Partial<CliDeps> = {}): Pro
           return EXIT.usage;
         }
         conn = await attach(deps);
-        deps.out(`clicked ${(await clickRef(conn, ref)).ref}`);
+        const clicked = await clickRef(conn, ref);
+        await traceRecord(deps.env, conn, 'click', { ref });
+        deps.out(`clicked ${clicked.ref}`);
         return EXIT.ok;
       }
       case 'fill': {
@@ -223,7 +255,9 @@ export async function run(argv: string[], overrides: Partial<CliDeps> = {}): Pro
           return EXIT.usage;
         }
         conn = await attach(deps);
-        deps.out(`filled ${(await fillRef(conn, ref, value)).ref}`);
+        const filled = await fillRef(conn, ref, value);
+        await traceRecord(deps.env, conn, 'fill', { ref, value });
+        deps.out(`filled ${filled.ref}`);
         return EXIT.ok;
       }
       case 'extract': {
@@ -284,6 +318,64 @@ export async function run(argv: string[], overrides: Partial<CliDeps> = {}): Pro
           await rm(dataDir, { recursive: true, force: true }).catch(() => {});
         }
       }
+      case 'trace': {
+        const dataDir = resolveDataDir(deps.env);
+        const sub = rest[0];
+        if (sub === 'start') {
+          const dir = rest[1] ?? join(process.cwd(), `session-${Date.now()}.trontrace`);
+          await startTrace(dataDir, dir);
+          deps.out(`tracing to ${dir}`);
+          return EXIT.ok;
+        }
+        if (sub === 'stop') {
+          const res = await stopTrace(dataDir);
+          if (!res) {
+            deps.err('no active trace');
+            return EXIT.usage;
+          }
+          deps.out(`stopped trace: ${res.dir} (${res.commands} command${res.commands === 1 ? '' : 's'})`);
+          return EXIT.ok;
+        }
+        if (sub === 'status') {
+          const active = await readActiveTrace(dataDir);
+          deps.out(active ? `tracing to ${active.dir}` : 'no active trace');
+          return EXIT.ok;
+        }
+        deps.err('usage: tron trace start [path] | stop | status');
+        return EXIT.usage;
+      }
+      case 'replay': {
+        const dir = rest.find((a) => !a.startsWith('--'));
+        if (!dir) {
+          deps.err('usage: tron replay <trace-dir>');
+          return EXIT.usage;
+        }
+        const commands = await readCommands(dir);
+        conn = await attach(deps);
+        let done = 0;
+        for (const c of commands) {
+          try {
+            if (c.name === 'click') {
+              await clickRef(conn, String(c.args.ref));
+            } else if (c.name === 'fill' || c.name === 'type') {
+              if (c.args.valueRedacted) {
+                deps.out(`skip ${c.name} ${String(c.args.ref)} (value redacted)`);
+                continue;
+              }
+              await fillRef(conn, String(c.args.ref), String(c.args.value));
+            } else {
+              continue; // snapshots and non-mutating records are not replayed
+            }
+            done += 1;
+            deps.out(`replayed ${c.name} ${String(c.args.ref ?? '')}`.trimEnd());
+          } catch (err) {
+            deps.err(`replay stopped at seq ${c.seq}: ${(err as Error).message}`);
+            return EXIT.failed;
+          }
+        }
+        deps.out(`replayed ${done} command${done === 1 ? '' : 's'}`);
+        return EXIT.ok;
+      }
       default:
         deps.err(`unknown automation command: ${command}`);
         return EXIT.usage;
diff --git a/packages/browser-core/src/automate-trace.test.ts b/packages/browser-core/src/automate-trace.test.ts
new file mode 100644
index 0000000..36aac8d
--- /dev/null
+++ b/packages/browser-core/src/automate-trace.test.ts
@@ -0,0 +1,104 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { EXIT, run, type CliDeps } from './automate-cli.js';
+import { readCommands } from './automation/trace.js';
+import type { CdpConnection } from './automation/cdp-client.js';
+
+// Fake conn: Runtime.evaluate returns {ok:true} — good enough for clickRef/fillRef
+// and for the trace's post-command snapshot capture (shape is not asserted here).
+function conn(hooks: { onEval?: (expr: string) => void } = {}): CdpConnection {
+  return {
+    send: (async (method: string, params?: { expression?: string }) => {
+      if (method === 'Runtime.evaluate') {
+        hooks.onEval?.(params?.expression ?? '');
+        return { result: { value: { ok: true, ref: '@e1' } } };
+      }
+      return {};
+    }) as CdpConnection['send'],
+    on: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+let dataDir: string;
+let bundle: string;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'cli-trace-'));
+  bundle = join(dataDir, 'run.trontrace');
+});
+afterEach(() => rmSync(dataDir, { recursive: true, force: true }));
+
+function harness(evalHook?: (expr: string) => void) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const deps: Partial<CliDeps> = {
+    env: { TRONBROWSER_DATA: dataDir },
+    loadDescriptor: async () => ({
+      version: 1, pid: 1, host: '127.0.0.1', port: 9222, profileDir: '/x',
+      profileName: 'agent', headless: false, ephemeral: false, createdAt: 't', activeTabId: 'p1',
+    }),
+    fetchTargets: async () => [{ id: 'p1', type: 'page', webSocketDebuggerUrl: 'ws://x/p1' }],
+    connect: async () => conn(evalHook ? { onEval: evalHook } : {}),
+    out: (t) => out.push(t),
+    err: (t) => err.push(t),
+  };
+  return { deps, out, err };
+}
+
+describe('tron trace / replay', () => {
+  it('records commands into a bundle between start and stop', async () => {
+    const h = harness();
+    expect(await run(['trace', 'start', bundle], h.deps)).toBe(EXIT.ok);
+    await run(['click', '@e1'], h.deps);
+    await run(['fill', '@e2', 'secret'], h.deps);
+    expect(await run(['trace', 'stop'], h.deps)).toBe(EXIT.ok);
+
+    const cmds = await readCommands(bundle);
+    expect(cmds.map((c) => c.name)).toEqual(['click', 'fill']);
+    expect(cmds[1].args.value).toBe('[redacted]'); // never persists the value
+  });
+
+  it('does not record when no trace is active', async () => {
+    const h = harness();
+    await run(['click', '@e1'], h.deps); // no trace started
+    // starting now yields an empty bundle
+    await run(['trace', 'start', bundle], h.deps);
+    expect(await readCommands(bundle)).toHaveLength(0);
+  });
+
+  it('reports trace status', async () => {
+    const h = harness();
+    await run(['trace', 'status'], h.deps);
+    await run(['trace', 'start', bundle], h.deps);
+    await run(['trace', 'status'], h.deps);
+    expect(h.out[0]).toBe('no active trace');
+    expect(h.out[h.out.length - 1]).toContain(bundle);
+  });
+
+  it('replays clicks and skips redacted fills', async () => {
+    // record a click + a fill
+    const rec = harness();
+    await run(['trace', 'start', bundle], rec.deps);
+    await run(['click', '@e1'], rec.deps);
+    await run(['fill', '@e2', 'secret'], rec.deps);
+    await run(['trace', 'stop'], rec.deps);
+
+    // replay against a fresh session, watching which expressions run
+    const exprs: string[] = [];
+    const play = harness((e) => exprs.push(e));
+    const code = await run(['replay', bundle], play.deps);
+    expect(code).toBe(EXIT.ok);
+    expect(play.out.join('\n')).toContain('replayed click @e1');
+    expect(play.out.join('\n')).toContain('skip fill @e2 (value redacted)');
+    // the click expression ran; the redacted fill did not
+    expect(exprs.some((e) => e.includes("data-tron-ref") && e.includes('click'))).toBe(true);
+  });
+
+  it('rejects an unknown trace subcommand', async () => {
+    const h = harness();
+    expect(await run(['trace', 'wat'], h.deps)).toBe(EXIT.usage);
+  });
+});
diff --git a/packages/browser-core/src/automation/index.ts b/packages/browser-core/src/automation/index.ts
index 594513b..5ad87c0 100644
--- a/packages/browser-core/src/automation/index.ts
+++ b/packages/browser-core/src/automation/index.ts
@@ -19,3 +19,6 @@ export * from './page.js';
 // Headless one-shot, extraction, and capture (PRD M3.3).
 export * from './extract-script.js';
 export * from './capture.js';
+
+// Trace bundle format (PRD M3.7).
+export * from './trace.js';
diff --git a/packages/browser-core/src/automation/trace.test.ts b/packages/browser-core/src/automation/trace.test.ts
new file mode 100644
index 0000000..7f7b11c
--- /dev/null
+++ b/packages/browser-core/src/automation/trace.test.ts
@@ -0,0 +1,78 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  readActiveTrace,
+  readCommands,
+  recordCommand,
+  redactArgs,
+  startTrace,
+  stopTrace,
+  tracePointerPath,
+} from './trace.js';
+import type { AgentSnapshot } from './snapshot-script.js';
+
+let dataDir: string;
+let bundle: string;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'trace-data-'));
+  bundle = join(dataDir, 'run.trontrace');
+});
+afterEach(() => rmSync(dataDir, { recursive: true, force: true }));
+
+const snap: AgentSnapshot = { url: 'https://x/', title: 'X', timestamp: 't', elements: [] };
+
+describe('redactArgs', () => {
+  it('redacts fill/type values but keeps the ref', () => {
+    expect(redactArgs('fill', { ref: '@e2', value: 'secret' })).toEqual({
+      ref: '@e2', value: '[redacted]', valueRedacted: true,
+    });
+    expect(redactArgs('click', { ref: '@e1' })).toEqual({ ref: '@e1' });
+  });
+});
+
+describe('trace lifecycle', () => {
+  it('starts, records, and stops a bundle', async () => {
+    await startTrace(dataDir, bundle);
+    const active = await readActiveTrace(dataDir);
+    expect(active?.dir).toBe(bundle);
+
+    await recordCommand(bundle, 'click', { ref: '@e1' }, { snapshot: snap });
+    await recordCommand(bundle, 'fill', { ref: '@e2', value: 'secret' });
+
+    const cmds = await readCommands(bundle);
+    expect(cmds.map((c) => c.name)).toEqual(['click', 'fill']);
+    expect(cmds[0].seq).toBe(1);
+    expect(cmds[0].snapshot).toBe('snapshots/0001.json');
+    // value redacted on write
+    expect(cmds[1].args.value).toBe('[redacted]');
+    expect(cmds[1].args.valueRedacted).toBe(true);
+    // snapshot persisted
+    expect(JSON.parse(readFileSync(join(bundle, 'snapshots/0001.json'), 'utf8')).title).toBe('X');
+
+    const stopped = await stopTrace(dataDir);
+    expect(stopped).toEqual({ dir: bundle, commands: 2 });
+    const meta = JSON.parse(readFileSync(join(bundle, 'metadata.json'), 'utf8'));
+    expect(meta.commands).toBe(2);
+    expect(meta.stoppedAt).toBeDefined();
+    // pointer cleared
+    expect(await readActiveTrace(dataDir)).toBeUndefined();
+  });
+
+  it('records an error alongside the command', async () => {
+    await startTrace(dataDir, bundle);
+    await recordCommand(bundle, 'click', { ref: '@e9' }, { error: 'STALE_REF' });
+    const errors = readFileSync(join(bundle, 'errors.jsonl'), 'utf8').trim();
+    expect(JSON.parse(errors).error).toBe('STALE_REF');
+  });
+
+  it('stop returns undefined when nothing is active', async () => {
+    expect(await stopTrace(dataDir)).toBeUndefined();
+  });
+
+  it('exposes the pointer path under the data dir', () => {
+    expect(tracePointerPath('/d')).toBe('/d/automation/trace.json');
+  });
+});
diff --git a/packages/browser-core/src/automation/trace.ts b/packages/browser-core/src/automation/trace.ts
new file mode 100644
index 0000000..c5915ef
--- /dev/null
+++ b/packages/browser-core/src/automation/trace.ts
@@ -0,0 +1,128 @@
+/**
+ * Trace bundle format for `tron trace` / `tron replay` (PRD M3.7 / §19).
+ *
+ * A `.trontrace` bundle is a directory of JSONL + JSON:
+ *   metadata.json         run info (version, started/stopped, command count)
+ *   commands.jsonl        one record per recorded command (values redacted)
+ *   snapshots/NNNN.json   page snapshot captured after a command
+ *   errors.jsonl          errors, keyed by command seq
+ *
+ * Recording is cross-process (each `tron` command is its own process), so an
+ * "active trace" pointer under the data dir tells commands where to append.
+ * Form values are redacted by default (PRD §20).
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import type { AgentSnapshot } from './snapshot-script.js';
+
+export const TRACE_VERSION = 1 as const;
+
+export interface TraceMetadata {
+  version: 1;
+  startedAt: string;
+  stoppedAt?: string;
+  commands: number;
+}
+
+export interface TraceCommandRecord {
+  seq: number;
+  t: string;
+  name: string;
+  args: Record<string, unknown>;
+  error?: string;
+  snapshot?: string; // relative path, e.g. "snapshots/0001.json"
+}
+
+export interface ActiveTracePointer {
+  dir: string;
+  startedAt: string;
+}
+
+/** Path of the active-trace pointer within a data dir. */
+export function tracePointerPath(dataDir: string): string {
+  return `${dataDir}/automation/trace.json`;
+}
+
+/** Redact sensitive command args (form values) before persisting. */
+export function redactArgs(name: string, args: Record<string, unknown>): Record<string, unknown> {
+  if ((name === 'fill' || name === 'type') && 'value' in args) {
+    return { ...args, value: '[redacted]', valueRedacted: true };
+  }
+  return { ...args };
+}
+
+async function readJsonl(path: string): Promise<string[]> {
+  try {
+    const raw = await readFile(path, 'utf8');
+    return raw.split('\n').filter((l) => l.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/** The active trace pointer, if recording is on. */
+export async function readActiveTrace(dataDir: string): Promise<ActiveTracePointer | undefined> {
+  try {
+    return JSON.parse(await readFile(tracePointerPath(dataDir), 'utf8')) as ActiveTracePointer;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Begin recording into `dir`, writing the pointer under `dataDir`. */
+export async function startTrace(dataDir: string, dir: string): Promise<void> {
+  await mkdir(`${dir}/snapshots`, { recursive: true });
+  const meta: TraceMetadata = { version: TRACE_VERSION, startedAt: new Date().toISOString(), commands: 0 };
+  await writeFile(`${dir}/metadata.json`, JSON.stringify(meta, null, 2) + '\n');
+  await writeFile(`${dir}/commands.jsonl`, '');
+  await mkdir(`${dataDir}/automation`, { recursive: true });
+  await writeFile(tracePointerPath(dataDir), JSON.stringify({ dir, startedAt: meta.startedAt }) + '\n');
+}
+
+/** Finalize the active trace and clear the pointer. */
+export async function stopTrace(dataDir: string): Promise<{ dir: string; commands: number } | undefined> {
+  const active = await readActiveTrace(dataDir);
+  if (!active) return undefined;
+  const commands = (await readJsonl(`${active.dir}/commands.jsonl`)).length;
+  let meta: TraceMetadata;
+  try {
+    meta = JSON.parse(await readFile(`${active.dir}/metadata.json`, 'utf8')) as TraceMetadata;
+  } catch {
+    meta = { version: TRACE_VERSION, startedAt: active.startedAt, commands };
+  }
+  meta.stoppedAt = new Date().toISOString();
+  meta.commands = commands;
+  await writeFile(`${active.dir}/metadata.json`, JSON.stringify(meta, null, 2) + '\n');
+  await writeFile(tracePointerPath(dataDir), ''); // clear pointer (empty = inactive)
+  return { dir: active.dir, commands };
+}
+
+/** Append a command to the bundle, optionally with its resulting snapshot. */
+export async function recordCommand(
+  dir: string,
+  name: string,
+  args: Record<string, unknown>,
+  extra: { snapshot?: AgentSnapshot; error?: string } = {},
+): Promise<number> {
+  const seq = (await readJsonl(`${dir}/commands.jsonl`)).length + 1;
+  const record: TraceCommandRecord = { seq, t: new Date().toISOString(), name, args: redactArgs(name, args) };
+  if (extra.error) record.error = extra.error;
+  if (extra.snapshot) {
+    const rel = `snapshots/${String(seq).padStart(4, '0')}.json`;
+    await mkdir(`${dir}/snapshots`, { recursive: true });
+    await writeFile(`${dir}/${rel}`, JSON.stringify(extra.snapshot, null, 2) + '\n');
+    record.snapshot = rel;
+  }
+  await appendLine(`${dir}/commands.jsonl`, JSON.stringify(record));
+  if (extra.error) await appendLine(`${dir}/errors.jsonl`, JSON.stringify({ seq, error: extra.error }));
+  return seq;
+}
+
+async function appendLine(path: string, line: string): Promise<void> {
+  const existing = await readFile(path, 'utf8').catch(() => '');
+  await writeFile(path, existing + line + '\n');
+}
+
+/** Read the recorded commands from a bundle (for replay/inspection). */
+export async function readCommands(dir: string): Promise<TraceCommandRecord[]> {
+  return (await readJsonl(`${dir}/commands.jsonl`)).map((l) => JSON.parse(l) as TraceCommandRecord);
+}