From 19ee33b87c19fc0ba1280f145f38f139e1c10035 Mon Sep 17 00:00:00 2001
From: PatrickJS <github@patrickjs.com>
Date: Sat, 20 Jun 2026 00:10:37 -0700
Subject: [PATCH] feat(ledger): record sanitized thread handoffs

---
 docs/gists/auto-git.md                        |  13 +-
 gists/auto-git/README.md                      |  13 +-
 gists/auto-git/auto-git.SKILL.md              |  13 +-
 .../auto-git.script-auto-git-finish.mjs       | 111 ++++++-
 .../auto-git.script-auto-git-ledger.mjs       | 289 +++++++++++++++++-
 skills/auto-git/SKILL.md                      |  13 +-
 skills/auto-git/scripts/auto-git-finish.mjs   | 111 ++++++-
 skills/auto-git/scripts/auto-git-ledger.mjs   | 289 +++++++++++++++++-
 tests/skill-suite.test.js                     | 208 +++++++++++++
 9 files changed, 1030 insertions(+), 30 deletions(-)

diff --git a/docs/gists/auto-git.md b/docs/gists/auto-git.md
index 7ae557d..738df58 100644
--- a/docs/gists/auto-git.md
+++ b/docs/gists/auto-git.md
@@ -51,7 +51,7 @@ Gist file mapping:
 - Uses a compact snapshot helper to detect Git index write capability, run locks, package-manager hints, ledger occupancy, PR handoffs, PR readiness, and the recommended verification profile before expensive commands.
 - Writes a sanitized start decision receipt on claimed runs, including the normalized route, selected workflow, required gates, branch/worktree context, release-preflight requirement, and follow-up thread handoff requirement without storing raw transcript text.
 - Supports two workflows: local review for single-chat code review and coordinated branch for multi-chat conflicts, PR handoffs, experiments, and fanouts.
-- Tracks cooperative run state and PR handoffs under `~/.async/auto-git/v1/repos/<repo-hash>/ledger.json`, with live leases under `~/.async/locks/auto-git/`, without storing raw diffs, prompts, full command output, environment dumps, or secrets.
+- Tracks cooperative run state, PR handoffs, and sanitized thread handoff metadata under `~/.async/auto-git/v1/repos/<repo-hash>/ledger.json`, with live leases under `~/.async/locks/auto-git/`, without storing raw diffs, prompts, transcripts, full command output, environment dumps, secrets, or local absolute worktree paths in handoff records.
 - Commits by change intent instead of making one vague bulk commit.
 - Reads the code and diffs when there are many unstaged changes, then builds the best commit split.
 - Optionally routes large or unclear worktrees to `git-intent-audit` before committing.
@@ -331,6 +331,7 @@ Controller helpers:
 ```sh
 auto-git start --cwd "$PWD" --task "fix this"
 auto-git ledger list --cwd "$PWD"
+auto-git ledger record-thread --cwd "$PWD" --run-id "<id>" --action create --thread-id "<thread-id>" --target "ADR 4" --repo "async/auto-git" --package "@async/auto-git" --next-adr "ADR 4"
 auto-git finish --cwd "$PWD" --run-id "<id>" --complete
 auto-git release-preflight --cwd "$PWD" --run-id "<id>" --require-verification
 ```
@@ -343,13 +344,21 @@ explicit deferral, follow-up thread handoff, return to main/default, and the
 final ledger update. Blockers are short command-class hints and do not include
 raw diffs, command output, transcripts, or secret-looking values.
 
+Use `auto-git ledger record-thread` when a coordinated follow-up route creates,
+sends to, reads, or hands off another thread. The record keeps only sanitized
+coordination metadata: source session id when available, thread id, action,
+target ADR or work item, repository/package labels, branch, worktree class or
+basename, PR reference, release-check status, and the next ADR label. It rejects
+or excludes transcript-like and secret-looking values.
+
 For release and yolo routes, `auto-git release-preflight` records successful
 preflight evidence to the active or requested run using safe metadata only.
 If release execution is intentionally deferred, finish requires an explicit
 `--defer-release`.
 
 Completion from main/default still preserves the completed branch/head in the
-ledger so later chats can find the exact handoff.
+ledger so later chats can find the exact handoff. When thread handoff evidence
+is present, finish preserves that sanitized metadata through completion.
 
 For long or environment-sensitive gates, use:
 
diff --git a/gists/auto-git/README.md b/gists/auto-git/README.md
index 7ae557d..738df58 100644
--- a/gists/auto-git/README.md
+++ b/gists/auto-git/README.md
@@ -51,7 +51,7 @@ Gist file mapping:
 - Uses a compact snapshot helper to detect Git index write capability, run locks, package-manager hints, ledger occupancy, PR handoffs, PR readiness, and the recommended verification profile before expensive commands.
 - Writes a sanitized start decision receipt on claimed runs, including the normalized route, selected workflow, required gates, branch/worktree context, release-preflight requirement, and follow-up thread handoff requirement without storing raw transcript text.
 - Supports two workflows: local review for single-chat code review and coordinated branch for multi-chat conflicts, PR handoffs, experiments, and fanouts.
-- Tracks cooperative run state and PR handoffs under `~/.async/auto-git/v1/repos/<repo-hash>/ledger.json`, with live leases under `~/.async/locks/auto-git/`, without storing raw diffs, prompts, full command output, environment dumps, or secrets.
+- Tracks cooperative run state, PR handoffs, and sanitized thread handoff metadata under `~/.async/auto-git/v1/repos/<repo-hash>/ledger.json`, with live leases under `~/.async/locks/auto-git/`, without storing raw diffs, prompts, transcripts, full command output, environment dumps, secrets, or local absolute worktree paths in handoff records.
 - Commits by change intent instead of making one vague bulk commit.
 - Reads the code and diffs when there are many unstaged changes, then builds the best commit split.
 - Optionally routes large or unclear worktrees to `git-intent-audit` before committing.
@@ -331,6 +331,7 @@ Controller helpers:
 ```sh
 auto-git start --cwd "$PWD" --task "fix this"
 auto-git ledger list --cwd "$PWD"
+auto-git ledger record-thread --cwd "$PWD" --run-id "<id>" --action create --thread-id "<thread-id>" --target "ADR 4" --repo "async/auto-git" --package "@async/auto-git" --next-adr "ADR 4"
 auto-git finish --cwd "$PWD" --run-id "<id>" --complete
 auto-git release-preflight --cwd "$PWD" --run-id "<id>" --require-verification
 ```
@@ -343,13 +344,21 @@ explicit deferral, follow-up thread handoff, return to main/default, and the
 final ledger update. Blockers are short command-class hints and do not include
 raw diffs, command output, transcripts, or secret-looking values.
 
+Use `auto-git ledger record-thread` when a coordinated follow-up route creates,
+sends to, reads, or hands off another thread. The record keeps only sanitized
+coordination metadata: source session id when available, thread id, action,
+target ADR or work item, repository/package labels, branch, worktree class or
+basename, PR reference, release-check status, and the next ADR label. It rejects
+or excludes transcript-like and secret-looking values.
+
 For release and yolo routes, `auto-git release-preflight` records successful
 preflight evidence to the active or requested run using safe metadata only.
 If release execution is intentionally deferred, finish requires an explicit
 `--defer-release`.
 
 Completion from main/default still preserves the completed branch/head in the
-ledger so later chats can find the exact handoff.
+ledger so later chats can find the exact handoff. When thread handoff evidence
+is present, finish preserves that sanitized metadata through completion.
 
 For long or environment-sensitive gates, use:
 
diff --git a/gists/auto-git/auto-git.SKILL.md b/gists/auto-git/auto-git.SKILL.md
index 6c7a6f3..080d7b0 100644
--- a/gists/auto-git/auto-git.SKILL.md
+++ b/gists/auto-git/auto-git.SKILL.md
@@ -248,6 +248,13 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
   - prints active runs, stale runs, completed runs, PR handoffs, branches,
     worktrees, leases, decision receipts, and verification state from safe
     ledger metadata
+- `auto-git ledger record-thread --cwd "$PWD" --run-id "<id>" --action <create|send|read|handoff> [--thread-id "<id>"] [--source-session "<id>"] [--target "<ADR or work item>"] [--repo "<owner/repo>"] [--package "<package>"] [--branch "<branch>"] [--worktree "<path or label>"] [--pr-url "<url>"] [--pr-number "<n>"] [--release-check <not-in-scope|passed|failed|blocked|deferred|unknown>] [--next-adr "<label>"]`
+  - records sanitized follow-up thread handoff metadata on a run without
+    storing prompts, transcripts, raw command output, environment values,
+    secrets, or local absolute worktree paths
+  - stores only thread ids, action type, source session id when available,
+    target work label, repository/package labels, branch, worktree class or
+    basename, PR reference, release-check status, and next ADR label
   - never deletes ledger entries
 - `auto-git finish --cwd "$PWD" --run-id "<id>" [--complete]`
   - checks dirty state, unresolved index state, HEAD/upstream, active run
@@ -261,7 +268,9 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
   - blocks release/yolo completion until release-preflight evidence is recorded
     and release execution is recorded or explicitly deferred with
     `--defer-release`
-  - blocks follow-up-thread completion until thread handoff evidence exists
+  - blocks follow-up-thread completion until thread handoff evidence exists,
+    and preserves sanitized thread handoff metadata when completion writes the
+    final ledger receipt
   - preserves the completed branch/head in the ledger even when completion is
     run from main/default after cleanup
   - records PR metadata when asked and completes the run only when safe
@@ -277,7 +286,7 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
 
 ## Global Async State
 
-Auto Git may use global advisory state under `~/.async/auto-git/v1/repos/<repo-hash>/` to avoid repeating expensive inspection and to coordinate across chats. Live runtime leases use Async-compatible lock records under `~/.async/locks/auto-git/repos/<repo-hash>/runs/*.lease.json`; completion removes the live lease and writes a receipt under `~/.async/locks/auto-git/history/`. This state is a cache of safe metadata: fingerprints, file path lists, commit ids, command names, exit codes, timestamps, lock classifications, process ids started by Auto Git, execution profiles, generated env override names/values, durations, recovery hints, run ids, task slugs, lifecycle modes, coordinated intents, branch names, worktree paths, base branches, lease expirations, lease paths, verification keys, release-preflight evidence, release deferral state, thread handoff ids/status, and PR URLs/statuses.
+Auto Git may use global advisory state under `~/.async/auto-git/v1/repos/<repo-hash>/` to avoid repeating expensive inspection and to coordinate across chats. Live runtime leases use Async-compatible lock records under `~/.async/locks/auto-git/repos/<repo-hash>/runs/*.lease.json`; completion removes the live lease and writes a receipt under `~/.async/locks/auto-git/history/`. This state is a cache of safe metadata: fingerprints, file path lists, commit ids, command names, exit codes, timestamps, lock classifications, process ids started by Auto Git, execution profiles, generated env override names/values, durations, recovery hints, run ids, task slugs, lifecycle modes, coordinated intents, branch names, worktree paths, base branches, lease expirations, lease paths, verification keys, release-preflight evidence, release deferral state, sanitized thread handoff action/source/thread/target/repo/package/branch/worktree-class/PR/release-check/next-ADR metadata, and PR URLs/statuses.
 
 The ledger is cooperative. Auto Git can reliably detect stale or inactive chats
 only when those chats used Auto Git and wrote ledger state. A run is active
diff --git a/gists/auto-git/auto-git.script-auto-git-finish.mjs b/gists/auto-git/auto-git.script-auto-git-finish.mjs
index 78bbd68..e7968f1 100644
--- a/gists/auto-git/auto-git.script-auto-git-finish.mjs
+++ b/gists/auto-git/auto-git.script-auto-git-finish.mjs
@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 const SNAPSHOT_SCRIPT = new URL("./auto-git-snapshot.mjs", import.meta.url);
+const THREAD_ACTIONS = ["create", "send", "read", "handoff"];
+const RELEASE_CHECK_STATUSES = ["not-in-scope", "passed", "failed", "blocked", "deferred", "unknown"];
 
 function usage() {
   return [
@@ -112,6 +114,10 @@ function readJson(path, fallback) {
   }
 }
 
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
 function currentRun(snapshot, requestedId) {
   const runs = [
     ...(snapshot.occupancy?.activeRuns ?? []),
@@ -219,6 +225,102 @@ function git(cwd, args) {
   return spawnSync("git", args, { cwd, encoding: "utf8" });
 }
 
+function looksSecretish(value) {
+  return /(?:TOKEN|SECRET|PASSWORD|PASSWD|_authToken|ACCESS_KEY|PRIVATE_KEY)\s*[=:]/i.test(String(value ?? ""));
+}
+
+function looksTranscriptish(value) {
+  const text = String(value ?? "");
+  return /(?:BEGIN TRANSCRIPT|END TRANSCRIPT|<codex_delegation>|<conversation|raw transcript|full transcript|full prompt|assistant:|user:)/i.test(
+    text
+  );
+}
+
+function safeText(value, maxLength = 120) {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim().replace(/\s+/g, " ");
+  if (!text || looksSecretish(text) || looksTranscriptish(text)) return undefined;
+  return text.slice(0, maxLength);
+}
+
+function safeLabel(value, maxLength = 120) {
+  const text = safeText(value, maxLength);
+  if (!text) return undefined;
+  if (isAbsolute(text)) return basename(text).slice(0, maxLength);
+  return text;
+}
+
+function safePrUrl(value) {
+  const text = safeText(value, 300);
+  if (!text || /[?&](?:token|auth|secret|password|key)=/i.test(text)) return undefined;
+  try {
+    const parsed = new URL(text);
+    if (parsed.username || parsed.password) return undefined;
+  } catch {
+    return undefined;
+  }
+  return text;
+}
+
+function sanitizeThreadHandoff(handoff) {
+  if (!handoff || typeof handoff !== "object") return undefined;
+  const action = THREAD_ACTIONS.includes(handoff.action) ? handoff.action : undefined;
+  const status = safeText(handoff.status, 40);
+  const threadId = safeText(handoff.threadId, 120);
+  const prUrl = safePrUrl(handoff.pr?.url);
+  const prNumber = Number.isInteger(Number(handoff.pr?.number)) ? Number(handoff.pr.number) : undefined;
+  const releaseStatus = RELEASE_CHECK_STATUSES.includes(handoff.releaseCheck?.status)
+    ? handoff.releaseCheck.status
+    : undefined;
+  const worktree =
+    handoff.worktree && typeof handoff.worktree === "object"
+      ? {
+          class: safeText(handoff.worktree.class, 80),
+          basename: safeText(handoff.worktree.basename, 80)
+        }
+      : undefined;
+  const sanitized = {
+    schemaVersion: 1,
+    status: status ?? (threadId || action ? "recorded" : undefined),
+    action,
+    sourceSessionId: safeText(handoff.sourceSessionId, 120),
+    threadId,
+    target: safeLabel(handoff.target, 120),
+    repository: safeLabel(handoff.repository, 120),
+    package: safeLabel(handoff.package, 120),
+    branch: safeLabel(handoff.branch, 160),
+    worktree: worktree?.class || worktree?.basename ? worktree : undefined,
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: releaseStatus ? { status: releaseStatus } : undefined,
+    nextAdr: safeLabel(handoff.nextAdr, 120),
+    recordedAt: typeof handoff.recordedAt === "string" ? handoff.recordedAt : undefined
+  };
+  return Object.fromEntries(Object.entries(sanitized).filter(([, value]) => value !== undefined));
+}
+
+function rawLedgerPath(snapshot) {
+  return join(stateRoot(), "repos", snapshot.repo.hash, "ledger.json");
+}
+
+function readRawRun(snapshot, runId) {
+  const ledger = readJson(rawLedgerPath(snapshot), { runs: [] });
+  return Array.isArray(ledger.runs) ? ledger.runs.find((entry) => entry?.id === runId) : undefined;
+}
+
+function preserveThreadHandoff(snapshot, runId, handoff) {
+  const sanitized = sanitizeThreadHandoff(handoff);
+  if (!sanitized) return false;
+  const path = rawLedgerPath(snapshot);
+  const ledger = readJson(path, { runs: [] });
+  if (!Array.isArray(ledger.runs)) return false;
+  const index = ledger.runs.findIndex((entry) => entry?.id === runId);
+  if (index === -1) return false;
+  const runs = [...ledger.runs];
+  runs[index] = { ...runs[index], threadHandoff: sanitized };
+  writeJson(path, { ...ledger, runs });
+  return true;
+}
+
 function defaultBaseBranch(snapshot, run) {
   if (run?.baseBranch) return run.baseBranch;
   const remoteHead = snapshot.topology.defaultRemoteHead;
@@ -610,6 +712,7 @@ function buildReceipt(options) {
   let snapshot = inspect(cwd, options.runId);
   let run = currentRun(snapshot, options.runId);
   const runId = options.runId ?? run?.id;
+  const rawThreadHandoff = runId ? readRawRun(snapshot, runId)?.threadHandoff : undefined;
   const mutations = [];
 
   if (options.recordPr) {
@@ -650,6 +753,10 @@ function buildReceipt(options) {
     mutations.push("complete-run");
     completed = true;
     snapshot = inspect(cwd, runId);
+    if (preserveThreadHandoff(snapshot, runId, rawThreadHandoff)) {
+      mutations.push("preserve-thread-handoff");
+      snapshot = inspect(cwd, runId);
+    }
   }
   const ledger = ledgerStatus(snapshot, runId);
 
diff --git a/gists/auto-git/auto-git.script-auto-git-ledger.mjs b/gists/auto-git/auto-git.script-auto-git-ledger.mjs
index 8f01a46..0dc3fad 100644
--- a/gists/auto-git/auto-git.script-auto-git-ledger.mjs
+++ b/gists/auto-git/auto-git.script-auto-git-ledger.mjs
@@ -1,22 +1,48 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 
 const SNAPSHOT_SCRIPT = new URL("./auto-git-snapshot.mjs", import.meta.url);
+const THREAD_ACTIONS = ["create", "send", "read", "handoff"];
+const RELEASE_CHECK_STATUSES = ["not-in-scope", "passed", "failed", "blocked", "deferred", "unknown"];
 
 function usage() {
   return [
     "Usage: auto-git-ledger.mjs <list|show|stale|handoffs> [run-id] [--cwd <repo>] [--json]",
+    "       auto-git-ledger.mjs record-thread --run-id <id> --action <create|send|read|handoff>",
+    "         [--source-session <id>] [--thread-id <id>] [--target <label>]",
+    "         [--repo <label>] [--package <label>] [--branch <name>]",
+    "         [--worktree <path-or-label>] [--worktree-class <class>]",
+    "         [--pr-url <url>] [--pr-number <n>] [--release-check <status>]",
+    "         [--next-adr <label>] [--cwd <repo>] [--json]",
     "",
-    "Reads the cooperative Auto Git ledger without deleting or mutating entries."
+    "Reads the cooperative Auto Git ledger and records sanitized thread handoff metadata."
   ].join("\n");
 }
 
 function parseArgs(argv) {
-  const parsed = { cwd: process.cwd(), command: undefined, runId: undefined, json: false };
+  const parsed = {
+    cwd: process.cwd(),
+    command: undefined,
+    runId: undefined,
+    json: false,
+    action: undefined,
+    sourceSession: undefined,
+    threadId: undefined,
+    target: undefined,
+    repoLabel: undefined,
+    packageLabel: undefined,
+    branch: undefined,
+    worktree: undefined,
+    worktreeClass: undefined,
+    prUrl: undefined,
+    prNumber: undefined,
+    releaseCheck: undefined,
+    nextAdr: undefined
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") {
@@ -31,6 +57,62 @@ function parseArgs(argv) {
       parsed.json = true;
       continue;
     }
+    if (arg === "--run-id") {
+      parsed.runId = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--action" || arg === "--thread-action") {
+      parsed.action = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--source-session") {
+      parsed.sourceSession = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--thread-id") {
+      parsed.threadId = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--target") {
+      parsed.target = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--repo") {
+      parsed.repoLabel = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--package") {
+      parsed.packageLabel = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--branch") {
+      parsed.branch = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--worktree") {
+      parsed.worktree = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--worktree-class") {
+      parsed.worktreeClass = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--pr-url") {
+      parsed.prUrl = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--pr-number") {
+      parsed.prNumber = Number(requireValue(argv, ++index, arg));
+      continue;
+    }
+    if (arg === "--release-check") {
+      parsed.releaseCheck = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--next-adr") {
+      parsed.nextAdr = requireValue(argv, ++index, arg);
+      continue;
+    }
     if (!parsed.command) {
       parsed.command = arg;
       continue;
@@ -42,8 +124,20 @@ function parseArgs(argv) {
     throw new Error(`Unexpected argument: ${arg}`);
   }
   parsed.command = parsed.command ?? "list";
-  if (!["list", "show", "stale", "handoffs"].includes(parsed.command)) {
-    throw new Error("command must be one of list, show, stale, or handoffs.");
+  if (!["list", "show", "stale", "handoffs", "record-thread"].includes(parsed.command)) {
+    throw new Error("command must be one of list, show, stale, handoffs, or record-thread.");
+  }
+  if (parsed.command === "record-thread") {
+    if (!parsed.runId) throw new Error("record-thread requires --run-id <id>.");
+    if (!THREAD_ACTIONS.includes(parsed.action)) {
+      throw new Error("--action must be one of create, send, read, or handoff.");
+    }
+    if (parsed.releaseCheck !== undefined && !RELEASE_CHECK_STATUSES.includes(parsed.releaseCheck)) {
+      throw new Error("--release-check must be one of not-in-scope, passed, failed, blocked, deferred, or unknown.");
+    }
+    if (parsed.prNumber !== undefined && !Number.isInteger(parsed.prNumber)) {
+      throw new Error("--pr-number must be an integer.");
+    }
   }
   return parsed;
 }
@@ -70,6 +164,11 @@ function readJson(path, fallback) {
   }
 }
 
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
 function runSnapshot(cwd) {
   const result = spawnSync(process.execPath, [SNAPSHOT_SCRIPT.pathname, "--cwd", cwd], {
     encoding: "utf8",
@@ -81,6 +180,168 @@ function runSnapshot(cwd) {
   return payload.snapshot;
 }
 
+function nowIso() {
+  const fixture = process.env.AUTO_GIT_NOW;
+  if (fixture) {
+    const parsed = new Date(fixture);
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+  }
+  return new Date().toISOString();
+}
+
+function looksSecretish(value) {
+  return /(?:TOKEN|SECRET|PASSWORD|PASSWD|_authToken|ACCESS_KEY|PRIVATE_KEY)\s*[=:]/i.test(String(value ?? ""));
+}
+
+function looksTranscriptish(value) {
+  const text = String(value ?? "");
+  return /(?:BEGIN TRANSCRIPT|END TRANSCRIPT|<codex_delegation>|<conversation|raw transcript|full transcript|full prompt|assistant:|user:)/i.test(
+    text
+  );
+}
+
+function safeText(value, maxLength = 120) {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim().replace(/\s+/g, " ");
+  if (!text || looksSecretish(text) || looksTranscriptish(text)) return undefined;
+  return text.slice(0, maxLength);
+}
+
+function sanitizeRunId(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_.:-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function safeLabel(value, maxLength = 120) {
+  const text = safeText(value, maxLength);
+  if (!text) return undefined;
+  if (isAbsolute(text)) return basename(text).slice(0, maxLength);
+  return text;
+}
+
+function sanitizePrUrl(value) {
+  const text = safeText(value, 300);
+  if (!text) return undefined;
+  if (/[?&](?:token|auth|secret|password|key)=/i.test(text)) return undefined;
+  try {
+    const parsed = new URL(text);
+    if (parsed.username || parsed.password) return undefined;
+  } catch {
+    return undefined;
+  }
+  return text;
+}
+
+function worktreePathClass(snapshot, value, explicitClass) {
+  const classLabel = safeLabel(explicitClass, 80);
+  const raw = typeof value === "string" && value.trim() ? value.trim() : snapshot.repo.root;
+  const base = safeLabel(basename(raw), 80);
+  if (classLabel) return base ? { class: classLabel, basename: base } : { class: classLabel };
+  if (raw.includes("/.codex/worktrees/")) return { class: "codex-worktree", basename: base };
+  if (raw.includes("/_worktrees/")) return { class: "repo-worktree", basename: base };
+  if (isAbsolute(raw)) return { class: "local-worktree", basename: base };
+  if (raw.startsWith("../")) return { class: "relative-worktree", basename: base };
+  return { class: "worktree", basename: base };
+}
+
+function sanitizeThreadHandoff(handoff) {
+  if (!handoff || typeof handoff !== "object") return undefined;
+  const action = THREAD_ACTIONS.includes(handoff.action) ? handoff.action : undefined;
+  const threadId = safeText(handoff.threadId, 120);
+  const status = safeText(handoff.status, 40);
+  const prUrl = sanitizePrUrl(handoff.pr?.url);
+  const prNumber = Number.isInteger(Number(handoff.pr?.number)) ? Number(handoff.pr.number) : undefined;
+  const releaseStatus = RELEASE_CHECK_STATUSES.includes(handoff.releaseCheck?.status)
+    ? handoff.releaseCheck.status
+    : undefined;
+  const worktree =
+    handoff.worktree && typeof handoff.worktree === "object"
+      ? {
+          class: safeLabel(handoff.worktree.class, 80),
+          basename: safeLabel(handoff.worktree.basename, 80)
+        }
+      : undefined;
+  const sanitized = {
+    schemaVersion: 1,
+    status: status ?? (threadId || action ? "recorded" : undefined),
+    action,
+    sourceSessionId: safeText(handoff.sourceSessionId, 120),
+    threadId,
+    target: safeLabel(handoff.target, 120),
+    repository: safeLabel(handoff.repository, 120),
+    package: safeLabel(handoff.package, 120),
+    branch: safeLabel(handoff.branch, 160),
+    worktree: worktree?.class || worktree?.basename ? worktree : undefined,
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: releaseStatus ? { status: releaseStatus } : undefined,
+    nextAdr: safeLabel(handoff.nextAdr, 120),
+    recordedAt: typeof handoff.recordedAt === "string" ? handoff.recordedAt : undefined
+  };
+  return Object.fromEntries(Object.entries(sanitized).filter(([, value]) => value !== undefined));
+}
+
+function buildThreadHandoff(snapshot, run, options, recordedAt) {
+  const threadId = safeText(options.threadId, 120);
+  const existingPr = run.pr && typeof run.pr === "object" ? run.pr : undefined;
+  const prUrl = sanitizePrUrl(options.prUrl) ?? sanitizePrUrl(existingPr?.url);
+  const prNumber = Number.isInteger(options.prNumber)
+    ? options.prNumber
+    : Number.isInteger(Number(existingPr?.number))
+      ? Number(existingPr.number)
+      : undefined;
+  const handoff = {
+    schemaVersion: 1,
+    status: "recorded",
+    action: options.action,
+    sourceSessionId: safeText(options.sourceSession, 120),
+    threadId,
+    target: safeLabel(options.target, 120),
+    repository: safeLabel(options.repoLabel, 120),
+    package: safeLabel(options.packageLabel, 120),
+    branch: safeLabel(options.branch ?? run.branch ?? snapshot.topology.branch, 160),
+    worktree: worktreePathClass(snapshot, options.worktree ?? run.worktreePath, options.worktreeClass),
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: options.releaseCheck ? { status: options.releaseCheck } : undefined,
+    nextAdr: safeLabel(options.nextAdr, 120),
+    recordedAt
+  };
+  if (!handoff.threadId && ["create", "send", "handoff"].includes(handoff.action)) {
+    throw new Error("--thread-id is required for create, send, and handoff actions.");
+  }
+  if (!handoff.target && options.target !== undefined) {
+    throw new Error("Refusing unsafe --target value.");
+  }
+  if (!handoff.repository && options.repoLabel !== undefined) {
+    throw new Error("Refusing unsafe --repo value.");
+  }
+  if (!handoff.package && options.packageLabel !== undefined) {
+    throw new Error("Refusing unsafe --package value.");
+  }
+  return sanitizeThreadHandoff(handoff);
+}
+
+function recordThreadHandoff(snapshot, repoDir, options) {
+  const ledgerFile = join(repoDir, "ledger.json");
+  const ledger = readJson(ledgerFile, { schemaVersion: 3, runs: [] });
+  const runs = Array.isArray(ledger.runs) ? ledger.runs : [];
+  const id = sanitizeRunId(options.runId);
+  const index = runs.findIndex((run) => run?.id === id);
+  if (index === -1) throw new Error(`Cannot record thread handoff for unknown Auto Git run: ${id}`);
+  const recordedAt = nowIso();
+  const nextRun = {
+    ...runs[index],
+    threadHandoff: buildThreadHandoff(snapshot, runs[index], options, recordedAt)
+  };
+  const nextRuns = [...runs];
+  nextRuns[index] = nextRun;
+  const nextLedger = { ...ledger, schemaVersion: 3, updatedAt: recordedAt, runs: nextRuns };
+  writeJson(ledgerFile, nextLedger);
+  return { ledger: nextLedger, run: nextRun };
+}
+
 function publicRun(run, statusById) {
   return {
     id: run.id,
@@ -111,7 +372,7 @@ function publicRun(run, statusById) {
     releasePreflight: run.releasePreflight,
     releaseExecution: run.releaseExecution,
     releaseDeferral: run.releaseDeferral,
-    threadHandoff: run.threadHandoff,
+    threadHandoff: sanitizeThreadHandoff(run.threadHandoff),
     decisionReceipt: run.decisionReceipt
   };
 }
@@ -120,7 +381,11 @@ function buildReceipt(options) {
   const cwd = resolve(options.cwd);
   const snapshot = runSnapshot(cwd);
   const repoDir = join(stateRoot(), "repos", snapshot.repo.hash || sha256(snapshot.repo.root, 24));
-  const ledger = readJson(join(repoDir, "ledger.json"), { schemaVersion: 3, runs: [] });
+  let mutation;
+  if (options.command === "record-thread") {
+    mutation = recordThreadHandoff(snapshot, repoDir, options);
+  }
+  const ledger = mutation?.ledger ?? readJson(join(repoDir, "ledger.json"), { schemaVersion: 3, runs: [] });
   const statusById = new Map();
   for (const run of snapshot.occupancy?.activeRuns ?? []) statusById.set(run.id, run.status);
   for (const run of snapshot.occupancy?.staleRuns ?? []) statusById.set(run.id, run.status);
@@ -136,6 +401,8 @@ function buildReceipt(options) {
     selectedRuns = staleRuns;
   } else if (options.command === "handoffs") {
     selectedRuns = handoffs;
+  } else if (options.command === "record-thread") {
+    selectedRuns = runs.filter((run) => run.id === options.runId);
   }
 
   return {
@@ -155,6 +422,7 @@ function buildReceipt(options) {
       runCount: runs.length
     },
     occupancy: snapshot.occupancy,
+    mutation: mutation ? { type: "record-thread", runId: options.runId } : undefined,
     runs: selectedRuns,
     handoffs,
     staleRuns
@@ -171,8 +439,11 @@ function printText(receipt) {
   }
   for (const run of receipt.runs) {
     const pr = run.pr?.url ? ` pr=${run.pr.url}` : "";
+    const thread = run.threadHandoff?.action
+      ? ` thread=${run.threadHandoff.action}${run.threadHandoff.threadId ? `:${run.threadHandoff.threadId}` : ""}`
+      : "";
     const decision = run.decisionReceipt?.normalizedIntentLabel ? ` decision=${run.decisionReceipt.normalizedIntentLabel}` : "";
-    console.log(`${run.id} status=${run.status} lifecycle=${run.lifecycle} intent=${run.intent}${decision} branch=${run.branch ?? "none"}${pr}`);
+    console.log(`${run.id} status=${run.status} lifecycle=${run.lifecycle} intent=${run.intent}${decision} branch=${run.branch ?? "none"}${pr}${thread}`);
   }
 }
 
diff --git a/skills/auto-git/SKILL.md b/skills/auto-git/SKILL.md
index 6c7a6f3..080d7b0 100644
--- a/skills/auto-git/SKILL.md
+++ b/skills/auto-git/SKILL.md
@@ -248,6 +248,13 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
   - prints active runs, stale runs, completed runs, PR handoffs, branches,
     worktrees, leases, decision receipts, and verification state from safe
     ledger metadata
+- `auto-git ledger record-thread --cwd "$PWD" --run-id "<id>" --action <create|send|read|handoff> [--thread-id "<id>"] [--source-session "<id>"] [--target "<ADR or work item>"] [--repo "<owner/repo>"] [--package "<package>"] [--branch "<branch>"] [--worktree "<path or label>"] [--pr-url "<url>"] [--pr-number "<n>"] [--release-check <not-in-scope|passed|failed|blocked|deferred|unknown>] [--next-adr "<label>"]`
+  - records sanitized follow-up thread handoff metadata on a run without
+    storing prompts, transcripts, raw command output, environment values,
+    secrets, or local absolute worktree paths
+  - stores only thread ids, action type, source session id when available,
+    target work label, repository/package labels, branch, worktree class or
+    basename, PR reference, release-check status, and next ADR label
   - never deletes ledger entries
 - `auto-git finish --cwd "$PWD" --run-id "<id>" [--complete]`
   - checks dirty state, unresolved index state, HEAD/upstream, active run
@@ -261,7 +268,9 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
   - blocks release/yolo completion until release-preflight evidence is recorded
     and release execution is recorded or explicitly deferred with
     `--defer-release`
-  - blocks follow-up-thread completion until thread handoff evidence exists
+  - blocks follow-up-thread completion until thread handoff evidence exists,
+    and preserves sanitized thread handoff metadata when completion writes the
+    final ledger receipt
   - preserves the completed branch/head in the ledger even when completion is
     run from main/default after cleanup
   - records PR metadata when asked and completes the run only when safe
@@ -277,7 +286,7 @@ PATH, use the installed skill's `scripts/*.mjs` helper paths as a fallback.
 
 ## Global Async State
 
-Auto Git may use global advisory state under `~/.async/auto-git/v1/repos/<repo-hash>/` to avoid repeating expensive inspection and to coordinate across chats. Live runtime leases use Async-compatible lock records under `~/.async/locks/auto-git/repos/<repo-hash>/runs/*.lease.json`; completion removes the live lease and writes a receipt under `~/.async/locks/auto-git/history/`. This state is a cache of safe metadata: fingerprints, file path lists, commit ids, command names, exit codes, timestamps, lock classifications, process ids started by Auto Git, execution profiles, generated env override names/values, durations, recovery hints, run ids, task slugs, lifecycle modes, coordinated intents, branch names, worktree paths, base branches, lease expirations, lease paths, verification keys, release-preflight evidence, release deferral state, thread handoff ids/status, and PR URLs/statuses.
+Auto Git may use global advisory state under `~/.async/auto-git/v1/repos/<repo-hash>/` to avoid repeating expensive inspection and to coordinate across chats. Live runtime leases use Async-compatible lock records under `~/.async/locks/auto-git/repos/<repo-hash>/runs/*.lease.json`; completion removes the live lease and writes a receipt under `~/.async/locks/auto-git/history/`. This state is a cache of safe metadata: fingerprints, file path lists, commit ids, command names, exit codes, timestamps, lock classifications, process ids started by Auto Git, execution profiles, generated env override names/values, durations, recovery hints, run ids, task slugs, lifecycle modes, coordinated intents, branch names, worktree paths, base branches, lease expirations, lease paths, verification keys, release-preflight evidence, release deferral state, sanitized thread handoff action/source/thread/target/repo/package/branch/worktree-class/PR/release-check/next-ADR metadata, and PR URLs/statuses.
 
 The ledger is cooperative. Auto Git can reliably detect stale or inactive chats
 only when those chats used Auto Git and wrote ledger state. A run is active
diff --git a/skills/auto-git/scripts/auto-git-finish.mjs b/skills/auto-git/scripts/auto-git-finish.mjs
index 78bbd68..e7968f1 100755
--- a/skills/auto-git/scripts/auto-git-finish.mjs
+++ b/skills/auto-git/scripts/auto-git-finish.mjs
@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 const SNAPSHOT_SCRIPT = new URL("./auto-git-snapshot.mjs", import.meta.url);
+const THREAD_ACTIONS = ["create", "send", "read", "handoff"];
+const RELEASE_CHECK_STATUSES = ["not-in-scope", "passed", "failed", "blocked", "deferred", "unknown"];
 
 function usage() {
   return [
@@ -112,6 +114,10 @@ function readJson(path, fallback) {
   }
 }
 
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
 function currentRun(snapshot, requestedId) {
   const runs = [
     ...(snapshot.occupancy?.activeRuns ?? []),
@@ -219,6 +225,102 @@ function git(cwd, args) {
   return spawnSync("git", args, { cwd, encoding: "utf8" });
 }
 
+function looksSecretish(value) {
+  return /(?:TOKEN|SECRET|PASSWORD|PASSWD|_authToken|ACCESS_KEY|PRIVATE_KEY)\s*[=:]/i.test(String(value ?? ""));
+}
+
+function looksTranscriptish(value) {
+  const text = String(value ?? "");
+  return /(?:BEGIN TRANSCRIPT|END TRANSCRIPT|<codex_delegation>|<conversation|raw transcript|full transcript|full prompt|assistant:|user:)/i.test(
+    text
+  );
+}
+
+function safeText(value, maxLength = 120) {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim().replace(/\s+/g, " ");
+  if (!text || looksSecretish(text) || looksTranscriptish(text)) return undefined;
+  return text.slice(0, maxLength);
+}
+
+function safeLabel(value, maxLength = 120) {
+  const text = safeText(value, maxLength);
+  if (!text) return undefined;
+  if (isAbsolute(text)) return basename(text).slice(0, maxLength);
+  return text;
+}
+
+function safePrUrl(value) {
+  const text = safeText(value, 300);
+  if (!text || /[?&](?:token|auth|secret|password|key)=/i.test(text)) return undefined;
+  try {
+    const parsed = new URL(text);
+    if (parsed.username || parsed.password) return undefined;
+  } catch {
+    return undefined;
+  }
+  return text;
+}
+
+function sanitizeThreadHandoff(handoff) {
+  if (!handoff || typeof handoff !== "object") return undefined;
+  const action = THREAD_ACTIONS.includes(handoff.action) ? handoff.action : undefined;
+  const status = safeText(handoff.status, 40);
+  const threadId = safeText(handoff.threadId, 120);
+  const prUrl = safePrUrl(handoff.pr?.url);
+  const prNumber = Number.isInteger(Number(handoff.pr?.number)) ? Number(handoff.pr.number) : undefined;
+  const releaseStatus = RELEASE_CHECK_STATUSES.includes(handoff.releaseCheck?.status)
+    ? handoff.releaseCheck.status
+    : undefined;
+  const worktree =
+    handoff.worktree && typeof handoff.worktree === "object"
+      ? {
+          class: safeText(handoff.worktree.class, 80),
+          basename: safeText(handoff.worktree.basename, 80)
+        }
+      : undefined;
+  const sanitized = {
+    schemaVersion: 1,
+    status: status ?? (threadId || action ? "recorded" : undefined),
+    action,
+    sourceSessionId: safeText(handoff.sourceSessionId, 120),
+    threadId,
+    target: safeLabel(handoff.target, 120),
+    repository: safeLabel(handoff.repository, 120),
+    package: safeLabel(handoff.package, 120),
+    branch: safeLabel(handoff.branch, 160),
+    worktree: worktree?.class || worktree?.basename ? worktree : undefined,
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: releaseStatus ? { status: releaseStatus } : undefined,
+    nextAdr: safeLabel(handoff.nextAdr, 120),
+    recordedAt: typeof handoff.recordedAt === "string" ? handoff.recordedAt : undefined
+  };
+  return Object.fromEntries(Object.entries(sanitized).filter(([, value]) => value !== undefined));
+}
+
+function rawLedgerPath(snapshot) {
+  return join(stateRoot(), "repos", snapshot.repo.hash, "ledger.json");
+}
+
+function readRawRun(snapshot, runId) {
+  const ledger = readJson(rawLedgerPath(snapshot), { runs: [] });
+  return Array.isArray(ledger.runs) ? ledger.runs.find((entry) => entry?.id === runId) : undefined;
+}
+
+function preserveThreadHandoff(snapshot, runId, handoff) {
+  const sanitized = sanitizeThreadHandoff(handoff);
+  if (!sanitized) return false;
+  const path = rawLedgerPath(snapshot);
+  const ledger = readJson(path, { runs: [] });
+  if (!Array.isArray(ledger.runs)) return false;
+  const index = ledger.runs.findIndex((entry) => entry?.id === runId);
+  if (index === -1) return false;
+  const runs = [...ledger.runs];
+  runs[index] = { ...runs[index], threadHandoff: sanitized };
+  writeJson(path, { ...ledger, runs });
+  return true;
+}
+
 function defaultBaseBranch(snapshot, run) {
   if (run?.baseBranch) return run.baseBranch;
   const remoteHead = snapshot.topology.defaultRemoteHead;
@@ -610,6 +712,7 @@ function buildReceipt(options) {
   let snapshot = inspect(cwd, options.runId);
   let run = currentRun(snapshot, options.runId);
   const runId = options.runId ?? run?.id;
+  const rawThreadHandoff = runId ? readRawRun(snapshot, runId)?.threadHandoff : undefined;
   const mutations = [];
 
   if (options.recordPr) {
@@ -650,6 +753,10 @@ function buildReceipt(options) {
     mutations.push("complete-run");
     completed = true;
     snapshot = inspect(cwd, runId);
+    if (preserveThreadHandoff(snapshot, runId, rawThreadHandoff)) {
+      mutations.push("preserve-thread-handoff");
+      snapshot = inspect(cwd, runId);
+    }
   }
   const ledger = ledgerStatus(snapshot, runId);
 
diff --git a/skills/auto-git/scripts/auto-git-ledger.mjs b/skills/auto-git/scripts/auto-git-ledger.mjs
index 8f01a46..0dc3fad 100755
--- a/skills/auto-git/scripts/auto-git-ledger.mjs
+++ b/skills/auto-git/scripts/auto-git-ledger.mjs
@@ -1,22 +1,48 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 
 const SNAPSHOT_SCRIPT = new URL("./auto-git-snapshot.mjs", import.meta.url);
+const THREAD_ACTIONS = ["create", "send", "read", "handoff"];
+const RELEASE_CHECK_STATUSES = ["not-in-scope", "passed", "failed", "blocked", "deferred", "unknown"];
 
 function usage() {
   return [
     "Usage: auto-git-ledger.mjs <list|show|stale|handoffs> [run-id] [--cwd <repo>] [--json]",
+    "       auto-git-ledger.mjs record-thread --run-id <id> --action <create|send|read|handoff>",
+    "         [--source-session <id>] [--thread-id <id>] [--target <label>]",
+    "         [--repo <label>] [--package <label>] [--branch <name>]",
+    "         [--worktree <path-or-label>] [--worktree-class <class>]",
+    "         [--pr-url <url>] [--pr-number <n>] [--release-check <status>]",
+    "         [--next-adr <label>] [--cwd <repo>] [--json]",
     "",
-    "Reads the cooperative Auto Git ledger without deleting or mutating entries."
+    "Reads the cooperative Auto Git ledger and records sanitized thread handoff metadata."
   ].join("\n");
 }
 
 function parseArgs(argv) {
-  const parsed = { cwd: process.cwd(), command: undefined, runId: undefined, json: false };
+  const parsed = {
+    cwd: process.cwd(),
+    command: undefined,
+    runId: undefined,
+    json: false,
+    action: undefined,
+    sourceSession: undefined,
+    threadId: undefined,
+    target: undefined,
+    repoLabel: undefined,
+    packageLabel: undefined,
+    branch: undefined,
+    worktree: undefined,
+    worktreeClass: undefined,
+    prUrl: undefined,
+    prNumber: undefined,
+    releaseCheck: undefined,
+    nextAdr: undefined
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") {
@@ -31,6 +57,62 @@ function parseArgs(argv) {
       parsed.json = true;
       continue;
     }
+    if (arg === "--run-id") {
+      parsed.runId = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--action" || arg === "--thread-action") {
+      parsed.action = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--source-session") {
+      parsed.sourceSession = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--thread-id") {
+      parsed.threadId = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--target") {
+      parsed.target = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--repo") {
+      parsed.repoLabel = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--package") {
+      parsed.packageLabel = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--branch") {
+      parsed.branch = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--worktree") {
+      parsed.worktree = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--worktree-class") {
+      parsed.worktreeClass = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--pr-url") {
+      parsed.prUrl = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--pr-number") {
+      parsed.prNumber = Number(requireValue(argv, ++index, arg));
+      continue;
+    }
+    if (arg === "--release-check") {
+      parsed.releaseCheck = requireValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--next-adr") {
+      parsed.nextAdr = requireValue(argv, ++index, arg);
+      continue;
+    }
     if (!parsed.command) {
       parsed.command = arg;
       continue;
@@ -42,8 +124,20 @@ function parseArgs(argv) {
     throw new Error(`Unexpected argument: ${arg}`);
   }
   parsed.command = parsed.command ?? "list";
-  if (!["list", "show", "stale", "handoffs"].includes(parsed.command)) {
-    throw new Error("command must be one of list, show, stale, or handoffs.");
+  if (!["list", "show", "stale", "handoffs", "record-thread"].includes(parsed.command)) {
+    throw new Error("command must be one of list, show, stale, handoffs, or record-thread.");
+  }
+  if (parsed.command === "record-thread") {
+    if (!parsed.runId) throw new Error("record-thread requires --run-id <id>.");
+    if (!THREAD_ACTIONS.includes(parsed.action)) {
+      throw new Error("--action must be one of create, send, read, or handoff.");
+    }
+    if (parsed.releaseCheck !== undefined && !RELEASE_CHECK_STATUSES.includes(parsed.releaseCheck)) {
+      throw new Error("--release-check must be one of not-in-scope, passed, failed, blocked, deferred, or unknown.");
+    }
+    if (parsed.prNumber !== undefined && !Number.isInteger(parsed.prNumber)) {
+      throw new Error("--pr-number must be an integer.");
+    }
   }
   return parsed;
 }
@@ -70,6 +164,11 @@ function readJson(path, fallback) {
   }
 }
 
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
 function runSnapshot(cwd) {
   const result = spawnSync(process.execPath, [SNAPSHOT_SCRIPT.pathname, "--cwd", cwd], {
     encoding: "utf8",
@@ -81,6 +180,168 @@ function runSnapshot(cwd) {
   return payload.snapshot;
 }
 
+function nowIso() {
+  const fixture = process.env.AUTO_GIT_NOW;
+  if (fixture) {
+    const parsed = new Date(fixture);
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+  }
+  return new Date().toISOString();
+}
+
+function looksSecretish(value) {
+  return /(?:TOKEN|SECRET|PASSWORD|PASSWD|_authToken|ACCESS_KEY|PRIVATE_KEY)\s*[=:]/i.test(String(value ?? ""));
+}
+
+function looksTranscriptish(value) {
+  const text = String(value ?? "");
+  return /(?:BEGIN TRANSCRIPT|END TRANSCRIPT|<codex_delegation>|<conversation|raw transcript|full transcript|full prompt|assistant:|user:)/i.test(
+    text
+  );
+}
+
+function safeText(value, maxLength = 120) {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim().replace(/\s+/g, " ");
+  if (!text || looksSecretish(text) || looksTranscriptish(text)) return undefined;
+  return text.slice(0, maxLength);
+}
+
+function sanitizeRunId(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_.:-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function safeLabel(value, maxLength = 120) {
+  const text = safeText(value, maxLength);
+  if (!text) return undefined;
+  if (isAbsolute(text)) return basename(text).slice(0, maxLength);
+  return text;
+}
+
+function sanitizePrUrl(value) {
+  const text = safeText(value, 300);
+  if (!text) return undefined;
+  if (/[?&](?:token|auth|secret|password|key)=/i.test(text)) return undefined;
+  try {
+    const parsed = new URL(text);
+    if (parsed.username || parsed.password) return undefined;
+  } catch {
+    return undefined;
+  }
+  return text;
+}
+
+function worktreePathClass(snapshot, value, explicitClass) {
+  const classLabel = safeLabel(explicitClass, 80);
+  const raw = typeof value === "string" && value.trim() ? value.trim() : snapshot.repo.root;
+  const base = safeLabel(basename(raw), 80);
+  if (classLabel) return base ? { class: classLabel, basename: base } : { class: classLabel };
+  if (raw.includes("/.codex/worktrees/")) return { class: "codex-worktree", basename: base };
+  if (raw.includes("/_worktrees/")) return { class: "repo-worktree", basename: base };
+  if (isAbsolute(raw)) return { class: "local-worktree", basename: base };
+  if (raw.startsWith("../")) return { class: "relative-worktree", basename: base };
+  return { class: "worktree", basename: base };
+}
+
+function sanitizeThreadHandoff(handoff) {
+  if (!handoff || typeof handoff !== "object") return undefined;
+  const action = THREAD_ACTIONS.includes(handoff.action) ? handoff.action : undefined;
+  const threadId = safeText(handoff.threadId, 120);
+  const status = safeText(handoff.status, 40);
+  const prUrl = sanitizePrUrl(handoff.pr?.url);
+  const prNumber = Number.isInteger(Number(handoff.pr?.number)) ? Number(handoff.pr.number) : undefined;
+  const releaseStatus = RELEASE_CHECK_STATUSES.includes(handoff.releaseCheck?.status)
+    ? handoff.releaseCheck.status
+    : undefined;
+  const worktree =
+    handoff.worktree && typeof handoff.worktree === "object"
+      ? {
+          class: safeLabel(handoff.worktree.class, 80),
+          basename: safeLabel(handoff.worktree.basename, 80)
+        }
+      : undefined;
+  const sanitized = {
+    schemaVersion: 1,
+    status: status ?? (threadId || action ? "recorded" : undefined),
+    action,
+    sourceSessionId: safeText(handoff.sourceSessionId, 120),
+    threadId,
+    target: safeLabel(handoff.target, 120),
+    repository: safeLabel(handoff.repository, 120),
+    package: safeLabel(handoff.package, 120),
+    branch: safeLabel(handoff.branch, 160),
+    worktree: worktree?.class || worktree?.basename ? worktree : undefined,
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: releaseStatus ? { status: releaseStatus } : undefined,
+    nextAdr: safeLabel(handoff.nextAdr, 120),
+    recordedAt: typeof handoff.recordedAt === "string" ? handoff.recordedAt : undefined
+  };
+  return Object.fromEntries(Object.entries(sanitized).filter(([, value]) => value !== undefined));
+}
+
+function buildThreadHandoff(snapshot, run, options, recordedAt) {
+  const threadId = safeText(options.threadId, 120);
+  const existingPr = run.pr && typeof run.pr === "object" ? run.pr : undefined;
+  const prUrl = sanitizePrUrl(options.prUrl) ?? sanitizePrUrl(existingPr?.url);
+  const prNumber = Number.isInteger(options.prNumber)
+    ? options.prNumber
+    : Number.isInteger(Number(existingPr?.number))
+      ? Number(existingPr.number)
+      : undefined;
+  const handoff = {
+    schemaVersion: 1,
+    status: "recorded",
+    action: options.action,
+    sourceSessionId: safeText(options.sourceSession, 120),
+    threadId,
+    target: safeLabel(options.target, 120),
+    repository: safeLabel(options.repoLabel, 120),
+    package: safeLabel(options.packageLabel, 120),
+    branch: safeLabel(options.branch ?? run.branch ?? snapshot.topology.branch, 160),
+    worktree: worktreePathClass(snapshot, options.worktree ?? run.worktreePath, options.worktreeClass),
+    pr: prUrl || prNumber ? { url: prUrl, number: prNumber } : undefined,
+    releaseCheck: options.releaseCheck ? { status: options.releaseCheck } : undefined,
+    nextAdr: safeLabel(options.nextAdr, 120),
+    recordedAt
+  };
+  if (!handoff.threadId && ["create", "send", "handoff"].includes(handoff.action)) {
+    throw new Error("--thread-id is required for create, send, and handoff actions.");
+  }
+  if (!handoff.target && options.target !== undefined) {
+    throw new Error("Refusing unsafe --target value.");
+  }
+  if (!handoff.repository && options.repoLabel !== undefined) {
+    throw new Error("Refusing unsafe --repo value.");
+  }
+  if (!handoff.package && options.packageLabel !== undefined) {
+    throw new Error("Refusing unsafe --package value.");
+  }
+  return sanitizeThreadHandoff(handoff);
+}
+
+function recordThreadHandoff(snapshot, repoDir, options) {
+  const ledgerFile = join(repoDir, "ledger.json");
+  const ledger = readJson(ledgerFile, { schemaVersion: 3, runs: [] });
+  const runs = Array.isArray(ledger.runs) ? ledger.runs : [];
+  const id = sanitizeRunId(options.runId);
+  const index = runs.findIndex((run) => run?.id === id);
+  if (index === -1) throw new Error(`Cannot record thread handoff for unknown Auto Git run: ${id}`);
+  const recordedAt = nowIso();
+  const nextRun = {
+    ...runs[index],
+    threadHandoff: buildThreadHandoff(snapshot, runs[index], options, recordedAt)
+  };
+  const nextRuns = [...runs];
+  nextRuns[index] = nextRun;
+  const nextLedger = { ...ledger, schemaVersion: 3, updatedAt: recordedAt, runs: nextRuns };
+  writeJson(ledgerFile, nextLedger);
+  return { ledger: nextLedger, run: nextRun };
+}
+
 function publicRun(run, statusById) {
   return {
     id: run.id,
@@ -111,7 +372,7 @@ function publicRun(run, statusById) {
     releasePreflight: run.releasePreflight,
     releaseExecution: run.releaseExecution,
     releaseDeferral: run.releaseDeferral,
-    threadHandoff: run.threadHandoff,
+    threadHandoff: sanitizeThreadHandoff(run.threadHandoff),
     decisionReceipt: run.decisionReceipt
   };
 }
@@ -120,7 +381,11 @@ function buildReceipt(options) {
   const cwd = resolve(options.cwd);
   const snapshot = runSnapshot(cwd);
   const repoDir = join(stateRoot(), "repos", snapshot.repo.hash || sha256(snapshot.repo.root, 24));
-  const ledger = readJson(join(repoDir, "ledger.json"), { schemaVersion: 3, runs: [] });
+  let mutation;
+  if (options.command === "record-thread") {
+    mutation = recordThreadHandoff(snapshot, repoDir, options);
+  }
+  const ledger = mutation?.ledger ?? readJson(join(repoDir, "ledger.json"), { schemaVersion: 3, runs: [] });
   const statusById = new Map();
   for (const run of snapshot.occupancy?.activeRuns ?? []) statusById.set(run.id, run.status);
   for (const run of snapshot.occupancy?.staleRuns ?? []) statusById.set(run.id, run.status);
@@ -136,6 +401,8 @@ function buildReceipt(options) {
     selectedRuns = staleRuns;
   } else if (options.command === "handoffs") {
     selectedRuns = handoffs;
+  } else if (options.command === "record-thread") {
+    selectedRuns = runs.filter((run) => run.id === options.runId);
   }
 
   return {
@@ -155,6 +422,7 @@ function buildReceipt(options) {
       runCount: runs.length
     },
     occupancy: snapshot.occupancy,
+    mutation: mutation ? { type: "record-thread", runId: options.runId } : undefined,
     runs: selectedRuns,
     handoffs,
     staleRuns
@@ -171,8 +439,11 @@ function printText(receipt) {
   }
   for (const run of receipt.runs) {
     const pr = run.pr?.url ? ` pr=${run.pr.url}` : "";
+    const thread = run.threadHandoff?.action
+      ? ` thread=${run.threadHandoff.action}${run.threadHandoff.threadId ? `:${run.threadHandoff.threadId}` : ""}`
+      : "";
     const decision = run.decisionReceipt?.normalizedIntentLabel ? ` decision=${run.decisionReceipt.normalizedIntentLabel}` : "";
-    console.log(`${run.id} status=${run.status} lifecycle=${run.lifecycle} intent=${run.intent}${decision} branch=${run.branch ?? "none"}${pr}`);
+    console.log(`${run.id} status=${run.status} lifecycle=${run.lifecycle} intent=${run.intent}${decision} branch=${run.branch ?? "none"}${pr}${thread}`);
   }
 }
 
diff --git a/tests/skill-suite.test.js b/tests/skill-suite.test.js
index a461c6c..9aaa1be 100644
--- a/tests/skill-suite.test.js
+++ b/tests/skill-suite.test.js
@@ -711,6 +711,214 @@ test("auto-git finish blocks follow-up routes without thread evidence", async ()
   }
 });
 
+test("auto-git ledger records sanitized thread handoff actions", async () => {
+  const repo = await createFixtureRepo("auto-git-thread-ledger-");
+  const stateHome = await mkdtemp(path.join(tmpdir(), "auto-git-thread-ledger-state-"));
+  try {
+    for (const action of ["create", "send", "read", "handoff"]) {
+      snapshot(
+        repo,
+        ["--write-state", "--claim-run", `create a follow-up chat for ADR 3 ${action}`, "--run-id", `thread-${action}-run`],
+        { AUTO_GIT_STATE_HOME: stateHome }
+      );
+    }
+    snapshot(repo, ["--write-state", "--claim-run", "checkpoint this locally", "--run-id", "local-no-thread-run"], {
+      AUTO_GIT_STATE_HOME: stateHome
+    });
+
+    for (const action of ["create", "send", "read", "handoff"]) {
+      const result = script(
+        "auto-git-ledger.mjs",
+        repo,
+        [
+          "record-thread",
+          "--run-id",
+          `thread-${action}-run`,
+          "--action",
+          action,
+          "--source-session",
+          "019ee3c0-9580-7e70-b322-418f130b8303",
+          "--thread-id",
+          `019ee3ce-${action}`,
+          "--target",
+          `ADR 3 ${action}`,
+          "--repo",
+          "async/auto-git",
+          "--package",
+          "@async/auto-git",
+          "--branch",
+          "codex/adr-3-thread-handoff-ledger",
+          "--worktree",
+          "/Users/patrickjs/.codex/worktrees/8bd1/auto-git",
+          "--pr-url",
+          "https://github.com/async/auto-git/pull/99",
+          "--pr-number",
+          "99",
+          "--release-check",
+          "not-in-scope",
+          "--next-adr",
+          "ADR 4",
+          "--json"
+        ],
+        { AUTO_GIT_STATE_HOME: stateHome }
+      );
+      assert.equal(result.status, 0, result.stderr || result.stdout);
+    }
+
+    const ledgerResult = script("auto-git-ledger.mjs", repo, ["list", "--json"], { AUTO_GIT_STATE_HOME: stateHome });
+    assert.equal(ledgerResult.status, 0, ledgerResult.stderr || ledgerResult.stdout);
+    const ledgerPayload = JSON.parse(ledgerResult.stdout);
+    for (const action of ["create", "send", "read", "handoff"]) {
+      const run = ledgerPayload.runs.find((entry) => entry.id === `thread-${action}-run`);
+      assert.equal(run.threadHandoff.action, action);
+      assert.equal(run.threadHandoff.sourceSessionId, "019ee3c0-9580-7e70-b322-418f130b8303");
+      assert.equal(run.threadHandoff.threadId, `019ee3ce-${action}`);
+      assert.equal(run.threadHandoff.repository, "async/auto-git");
+      assert.equal(run.threadHandoff.package, "@async/auto-git");
+      assert.equal(run.threadHandoff.branch, "codex/adr-3-thread-handoff-ledger");
+      assert.equal(run.threadHandoff.worktree.class, "codex-worktree");
+      assert.equal(run.threadHandoff.worktree.basename, "auto-git");
+      assert.equal(run.threadHandoff.pr.url, "https://github.com/async/auto-git/pull/99");
+      assert.equal(run.threadHandoff.pr.number, 99);
+      assert.equal(run.threadHandoff.releaseCheck.status, "not-in-scope");
+      assert.equal(run.threadHandoff.nextAdr, "ADR 4");
+    }
+    assert.equal(ledgerPayload.runs.find((entry) => entry.id === "local-no-thread-run").threadHandoff, undefined);
+    assert.doesNotMatch(JSON.stringify(ledgerPayload.runs), /\/Users\/patrickjs/);
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+    await rm(stateHome, { recursive: true, force: true });
+  }
+});
+
+test("auto-git ledger excludes transcript-like and secret-looking handoff content", async () => {
+  const repo = await createFixtureRepo("auto-git-thread-ledger-safety-");
+  const stateHome = await mkdtemp(path.join(tmpdir(), "auto-git-thread-ledger-safety-state-"));
+  try {
+    const result = snapshot(
+      repo,
+      ["--write-state", "--claim-run", "create a follow-up chat after ADR 3", "--run-id", "unsafe-thread-run"],
+      { AUTO_GIT_STATE_HOME: stateHome }
+    );
+    const ledgerPath = path.join(stateHome, "repos", result.snapshot.repo.hash, "ledger.json");
+    const ledger = JSON.parse(await readFile(ledgerPath, "utf8"));
+    const run = ledger.runs.find((entry) => entry.id === "unsafe-thread-run");
+    run.threadHandoff = {
+      status: "recorded",
+      action: "create",
+      sourceSessionId: "SESSION_TOKEN=secret",
+      threadId: "thread-safe",
+      target: "BEGIN TRANSCRIPT user: TOKEN=secret",
+      repository: "/Users/patrickjs/code/async/auto-git",
+      package: "@async/auto-git",
+      branch: "codex/thread",
+      worktree: {
+        class: "codex-worktree",
+        basename: "auto-git",
+        path: "/Users/patrickjs/.codex/worktrees/8bd1/auto-git"
+      },
+      pr: {
+        url: "https://github.com/async/auto-git/pull/123?token=secret",
+        number: 123
+      },
+      nextAdr: "ADR 4"
+    };
+    await writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`);
+
+    const ledgerResult = script("auto-git-ledger.mjs", repo, ["show", "unsafe-thread-run", "--json"], {
+      AUTO_GIT_STATE_HOME: stateHome
+    });
+    assert.equal(ledgerResult.status, 0, ledgerResult.stderr || ledgerResult.stdout);
+    const payload = JSON.parse(ledgerResult.stdout);
+    const handoffText = JSON.stringify(payload.runs[0].threadHandoff);
+    assert.match(handoffText, /thread-safe/);
+    assert.doesNotMatch(handoffText, /TOKEN=secret|BEGIN TRANSCRIPT|\/Users\/patrickjs|\?token=secret/);
+    assert.equal(payload.runs[0].threadHandoff.repository, "auto-git");
+    assert.equal(payload.runs[0].threadHandoff.pr.url, undefined);
+
+    const rejected = script(
+      "auto-git-ledger.mjs",
+      repo,
+      [
+        "record-thread",
+        "--run-id",
+        "unsafe-thread-run",
+        "--action",
+        "create",
+        "--thread-id",
+        "thread-safe",
+        "--target",
+        "BEGIN TRANSCRIPT TOKEN=secret"
+      ],
+      { AUTO_GIT_STATE_HOME: stateHome }
+    );
+    assert.equal(rejected.status, 1);
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+    await rm(stateHome, { recursive: true, force: true });
+  }
+});
+
+test("auto-git finish completes follow-up routes with preserved thread evidence", async () => {
+  const repo = await createFixtureRepo("auto-git-finish-thread-evidence-");
+  const stateHome = await mkdtemp(path.join(tmpdir(), "auto-git-finish-thread-evidence-state-"));
+  try {
+    const start = snapshot(
+      repo,
+      ["--write-state", "--claim-run", "create a follow-up chat after ADR 3", "--run-id", "follow-up-recorded-run"],
+      { AUTO_GIT_STATE_HOME: stateHome }
+    );
+    const record = script(
+      "auto-git-ledger.mjs",
+      repo,
+      [
+        "record-thread",
+        "--run-id",
+        "follow-up-recorded-run",
+        "--action",
+        "create",
+        "--source-session",
+        "019ee3c0-9580-7e70-b322-418f130b8303",
+        "--thread-id",
+        "019ee3ce-bc3f-73b3-8ae4-4e57458cb6a8",
+        "--target",
+        "ADR 4",
+        "--repo",
+        "async/auto-git",
+        "--package",
+        "@async/auto-git",
+        "--worktree-class",
+        "codex-worktree",
+        "--next-adr",
+        "ADR 4",
+        "--json"
+      ],
+      { AUTO_GIT_STATE_HOME: stateHome }
+    );
+    assert.equal(record.status, 0, record.stderr || record.stdout);
+
+    const result = script("auto-git-finish.mjs", repo, ["--run-id", "follow-up-recorded-run", "--complete", "--json"], {
+      AUTO_GIT_STATE_HOME: stateHome
+    });
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, "completed");
+    assert.equal(payload.contract.threadHandoff.satisfied, true);
+    assert.ok(payload.mutations.includes("preserve-thread-handoff"));
+
+    const ledger = JSON.parse(await readFile(path.join(stateHome, "repos", start.snapshot.repo.hash, "ledger.json"), "utf8"));
+    const ledgerRun = ledger.runs.find((entry) => entry.id === "follow-up-recorded-run");
+    assert.equal(ledgerRun.status, "completed");
+    assert.equal(ledgerRun.threadHandoff.action, "create");
+    assert.equal(ledgerRun.threadHandoff.target, "ADR 4");
+    assert.equal(ledgerRun.threadHandoff.nextAdr, "ADR 4");
+    assert.equal(ledgerRun.threadHandoff.worktree.class, "codex-worktree");
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+    await rm(stateHome, { recursive: true, force: true });
+  }
+});
+
 test("auto-git finish completes a satisfied local-review route", async () => {
   const repo = await createFixtureRepo("auto-git-finish-local-review-");
   const stateHome = await mkdtemp(path.join(tmpdir(), "auto-git-finish-local-review-state-"));