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: ~/.joelclaw/outbox

NAS backup target:

/Volumes/three-body/sessions/<machine>/<source-key>/...
receipts: /Volumes/three-body/sessions/receipts/*.json

Current live capture endpoint, per 2026-07-09 repair receipt:

http://joels-mac-studio.tail7af24.ts.net:3111/api/runs
health: http://joels-mac-studio.tail7af24.ts.net:3111/api/runs/health

Important drift note: older system-architecture docs say Panda is Central. Flagg/Mac Studio is the working capture endpoint for Blaine. 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:

bun scripts/agent-session-audit-backup.ts \
  --hosts flagg,blaine,panda \
  --central-url http://joels-mac-studio.tail7af24.ts.net:3111 \
  --backup-root /Volumes/three-body/sessions \
  --repair-env \
  --sync=true \
  --replay-outbox \
  --replay-limit 250 \
  --replay-max-bytes 10485760

What it does:

verifies each host is reachable
verifies each host can reach the Central run-capture health endpoint
optionally repairs JOELCLAW_CENTRAL_URL in .zshrc, .zprofile, and ~/.config/system-bus.env
rsyncs transcript/run/outbox sources to the NAS without deleting source files
replays a bounded number of outbox JSON payloads to /api/runs
writes a JSON receipt with source counts, backup counts, newest mtimes, byte totals, and outbox before/after

For a metadata-only audit, use --sync=false and omit both --repair-env and --replay-outbox. Those flags mutate state independently of sync. Discover the current Central endpoint and host set from service configuration; historical endpoint examples are not current authority. Raw transcript content still requires the session evidence receipt.

Use a low --replay-limit first when clearing a huge outbox. Do not unleash tens of thousands of run-capture events without checking worker/Inngest health.

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:

joelclaw send system/agent-session.capture-backup.requested -d '{
  "hosts": "flagg,blaine,panda",
  "centralUrl": "http://joels-mac-studio.tail7af24.ts.net:3111",
  "repairEnv": true,
  "replayLimit": 250,
  "replayMaxBytes": 10485760
}'

Green criteria

Every active machine reports centralHealthOk=true.
Every transcript source that exists locally has matching or increasing backup file counts on NAS.
~/.joelclaw/outbox count trends toward zero on each machine.
Receipts are written daily under /Volumes/three-body/sessions/receipts.
A recent receipt includes Flagg and Blaine with fresh Pi, Claude, Codex, runs-dev, and outbox counts.

Gotchas

Do not use http://panda:3000; that endpoint is stale and fails.
Do not use Panda's /api/runs until its local Typesense auth lookup is healthy again.
Flagg may have live local capture even when docs still say Panda is Central. Verify system-architecture and recent receipts before changing authority language.
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.

agent-session-capture-backup