Agent Session Capture Backup

Use this skill when Joel asks whether agent activity is being captured, indexed, or backed up across machines.

Canonical surfaces

Transcript/raw activity sources:

• Pi: ~/.pi/agent/sessions, ~/.pi/agent/run-history.jsonl, ~/.pi/notes-bridge/events.jsonl
• Claude Code: ~/.claude/projects
• Codex: ~/.codex/sessions, ~/.codex/archived_sessions, ~/.codex/session_index.jsonl
• joelclaw run capture: ~/.joelclaw/runs-dev
• failed run-capture posts: per-machine, per-runtime capture outboxes; see the private operator map for current paths. ~/.joelclaw/outbox is the legacy outbox, not complete capture coverage.

NAS audit mirror:

• /Volumes/services/joelclaw/sessions/<machine>/<source-key>/...
• receipts: /Volumes/services/joelclaw/sessions/receipts/*.json

The separate additive raw archive has full and priority server receipts plus local steward receipts. For its root and receipt paths, see the private operator map. Do not confuse this archive with the cross-machine audit mirror. An hourly priority job, com.joelclaw.raw-transcript-backup, is being added; verify its deployment and fresh receipts before treating it as active.

Capture routing:

• Flagg capture uses loopback: http://127.0.0.1:3111/api/runs; health: http://127.0.0.1:3111/api/runs/health.
• A local capture endpoint override file is being added; see the private operator map for its path and deployment status.
• Satellites need an approved reachable Central address. Never configure a satellite with Flagg's loopback URL.

Panda is retired, not a live capture host, Central, or relay. Remove it from routine host lists. Capture authentication uses Flagg's persistent local ~/.joelclaw/capture-auth.db; Typesense machines_dev is only its enrollment/migration mirror.

Manual verification / repair

From ~/Code/joelhooks/joelclaw-runtime, this Flagg-only metadata audit writes a receipt but does not sync, repair environment files, or replay payloads:

bun scripts/agent-session-audit-backup.ts \
  --hosts flagg \
  --central-url http://127.0.0.1:3111 \
  --backup-root /Volumes/services/joelclaw/sessions \
  --sync=false

For satellites, select active hosts and an approved Central URL reachable from each selected host. Do not rely on the script's historical host or endpoint defaults.

Audit script behavior:

1. verifies each host is reachable
2. verifies each host can reach the Central run-capture health endpoint
3. optionally repairs JOELCLAW_CENTRAL_URL in .zshrc, .zprofile, and ~/.config/system-bus.env
4. optionally rsyncs transcript/run/outbox sources to the NAS without deleting source files
5. writes a JSON receipt with source counts, backup counts, newest mtimes, byte totals, and legacy outbox metadata

--repair-env (repairEnv in the scheduled event), --sync=true, and outbox replay are mutations requiring a repair request. Authorization for verification alone does not authorize them. For metadata-only verification, use --sync=false and omit repair and replay flags. Raw transcript content still requires the session evidence receipt.

The audit script rejects its old --replay-outbox, --replay-limit, and --replay-max-bytes flags. Use scripts/replay-capture-outbox.ts for separately requested, bounded replay. Review its catalog, checkpoint, and per-batch receipts against stored hashes and index coverage. Preserve queued payloads. Check worker/Inngest health before replay; do not unleash a large backlog.

Durable scheduled workflow

Host worker function:

• system/agent-session.capture-backup.verify
• manual event: system/agent-session.capture-backup.requested
• daily cron: TZ=America/Los_Angeles 15 5 * * *

Manual trigger for a requested Flagg backup:

joelclaw send system/agent-session.capture-backup.requested -d '{
  "hosts": "flagg",
  "centralUrl": "http://127.0.0.1:3111",
  "repairEnv": false
}'

The scheduled worker syncs backups even with repairEnv:false; this is not metadata-only verification. It defaults repairEnv to true when omitted. Review cron repair ownership and explicit hosts/routing before relying on it. Replay is separate work, not part of this event.

Green criteria

• Every active machine reports centralHealthOk=true.
• Every local transcript source has a fresh per-source receipt confirming successful backup. Counts and preserved mtimes alone do not prove parity; partial rsync is not verified completion.
• Each active machine/runtime has reconciled namespaced outbox, replay checkpoint, stored hash, and index coverage. An empty legacy outbox is not a green verdict. Covered queued files may remain on disk.
• Audit receipts are written daily under /Volumes/services/joelclaw/sessions/receipts. Raw archive coverage needs its separate full/priority and local steward receipts; see the private operator map.
• A recent receipt covers Flagg and Blaine with fresh Pi, Claude, Codex, runs-dev, and outbox metadata. An unreachable host or failed source sync remains unverified.

Gotchas

• Panda is retired. Historical Central/relay instructions do not authorize routing or repair work there.
• Use current service configuration and fresh receipts for capture routing. Historical host names and endpoint examples are not current authority.
• Backups must be copies, not rotations. Do not delete or move live transcript files during backup.
• Outbox replay is a repair operation. Keep it bounded and leave receipts.
• Never print auth tokens from ~/.joelclaw/auth.json; the script reads them locally on each host.