spexcode 0.2.4 → 0.2.6

package/spec-cli/src/worktree-sources.ts

@@ -1,19 +1,58 @@
-import { existsSync, symlinkSync } from 'node:fs'
-import { join } from 'node:path'
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { git } from './git.js'
 
-// @@@ worktree-sources ([[private-overlay]]) - a fresh session worktree checks out only TRACKED content, and
-// private mode keeps `.spec` + `spexcode.json` untracked (spexcode.local.json is untracked in BOTH modes) —
-// so git alone hands a dispatched agent a worktree with NO spec tree: every hook handler script is absent
-// (the dispatcher silently runs nothing), spex sees zero nodes, and the gate re-renders per event over empty
-// config roots. Link those sources from the main checkout instead. On a default-mode repo the checkout
-// already carries them, so each link guard no-ops — one mechanism, never a mode branch. A failure degrades
-// that worker (no hooks, no specs), so it is reported, not swallowed.
-export function linkUntrackedSpecSources(main: string, wt: string): void {
-  for (const f of ['.spec', 'spexcode.json', 'spexcode.local.json']) {
+// @@@ worktree-sources ([[residence]]) - a fresh session worktree is fed by THREE transports, one per
+// source kind, and the kind decides the transport — never a mode branch:
+//   - TRACKED project state (`.spec`, `spexcode.json`) arrives by GIT CHECKOUT: the sources are always
+//     tracked (git is the database), so `git worktree add` alone delivers them. No symlink — a link is a
+//     WRITE-SEMANTICS declaration (write-through to the main tree), and spec writes go back through the
+//     branch/merge ritual, not through a side channel.
+//   - MATERIALIZED ARTIFACTS (contract blocks, shims, skills) are DERIVED — transported by re-materialize,
+//     not by link or copy:
+//     sessions.ts materializes into the worktree at creation, and the git-native anchors (pre-commit /
+//     post-checkout / post-merge — [[commit-surgery]]) re-materialize on change.
+//   - HOST state (`spexcode.local.json`, machine-local and never tracked) is COPIED — a snapshot: the worker
+//     reads the same launchers/policy the host had at dispatch, but its writes land on its own copy and die
+//     with the worktree, never on the host's real config (a worker once wrote "its" test config through the
+//     old symlink and wiped the host's launchers → every later dispatch 401'd).
+// This module owns only the third transport (plus hiding what it seeds). A failure degrades that worker
+// (default launchers/policy), so it is reported, not swallowed.
+export function seedWorktreeHostState(main: string, wt: string): void {
+  const f = 'spexcode.local.json'
+  try {
+    if (!existsSync(join(main, f)) || existsSync(join(wt, f))) return
+    copyFileSync(join(main, f), join(wt, f))
+  } catch (e) {
+    console.error(`spexcode: could not seed ${f} from ${main} into worktree ${wt} — that worker runs on defaults (${e})`)
+    return
+  }
+  hideSeededFromGit(wt, [f])
+}
+
+// what we seed, we hide: a seeded entry git still sees is force-add bait (a real PR once carried seeded
+// files into a product repo). `.git/info/exclude` lives in the COMMON git dir, so one write hides the entry
+// in every linked worktree AND the main checkout. Only entries seeded by THIS call and reported un-ignored
+// by `git check-ignore` are written: idempotent across dispatches, and a repo whose materialize already ignores
+// the overlay (materialize's block under any policy) writes nothing — the self-heal for a half-configured repo.
+function hideSeededFromGit(wt: string, seeded: string[]): void {
+  for (const f of seeded) {
     try {
-      if (existsSync(join(main, f)) && !existsSync(join(wt, f))) symlinkSync(join(main, f), join(wt, f))
+      if (isIgnored(wt, f)) continue
+      const exclude = join(git(['-C', wt, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim(), 'info', 'exclude')
+      mkdirSync(dirname(exclude), { recursive: true })
+      const cur = existsSync(exclude) ? readFileSync(exclude, 'utf8') : ''
+      appendFileSync(exclude, `${cur && !cur.endsWith('\n') ? '\n' : ''}${f}\n`)
     } catch (e) {
-      console.error(`spexcode: could not link ${f} from ${main} into worktree ${wt} — that worker runs without it (${e})`)
+      console.error(`spexcode: could not hide seeded ${f} in the shared info/exclude for ${wt} — it will show untracked there (${e})`)
     }
   }
 }
+
+function isIgnored(wt: string, f: string): boolean {
+  try { git(['-C', wt, 'check-ignore', '-q', f]); return true }
+  catch (e: any) {
+    if (e?.status === 1) return false   // check-ignore's documented "not ignored" exit
+    throw e
+  }
+}

package/spec-cli/templates/hooks/post-checkout

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# @@@ footprint refresh (post-checkout) ([[commit-surgery]]) - a branch checkout is one of the three git
+# transitions that can move the materialize's inputs: .spec/.config content changes across branches, and a
+# contract file's TRACKEDNESS can flip (switching to a branch that tracks CLAUDE.md checks out the pristine
+# index prose — the re-materialize here writes the block back into the working file, binds the clean/smudge
+# filter, and withdraws the exclude entry; the kind-transition heals itself). Git-native anchors only —
+# never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor (pre-commit's
+# unconditional materialize is the correctness backstop).
+#
+# args: <prev-HEAD> <new-HEAD> <flag>; flag=1 is a branch checkout, flag=0 a file checkout (git checkout --
+# <path> restores files and moves nothing the materialize depends on — skip those).
+[ "${3:-0}" = "1" ] || exit 0
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+if command -v spex >/dev/null 2>&1; then
+  spex internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  "$repo_root/node_modules/.bin/spex" internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  "$main_root/spec-cli/bin/spex.mjs" internal refresh-footprint >/dev/null 2>&1 || true
+fi
+exit 0

package/spec-cli/templates/hooks/post-merge

@@ -9,19 +9,25 @@
 # the feature is OFF in spexcode.json), so this hook is a THIN resolver + caller: resolve `spex` the same
 # three ways the pre-commit hook does, pass the merged node, echo whatever it prints. No CLI resolvable → no
 # nudge (safe degradation, same as the lint shim's advisory mode).
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+spex_run() {
+  if command -v spex >/dev/null 2>&1; then spex "$@"
+  elif [ -x "$repo_root/node_modules/.bin/spex" ]; then "$repo_root/node_modules/.bin/spex" "$@"
+  elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then "$main_root/spec-cli/bin/spex.mjs" "$@"
+  else return 127; fi
+}
+
+# @@@ footprint refresh ([[commit-surgery]]) - a merge is one of the three git transitions that can move the
+# materialize's inputs (.spec/.config content, contract-file trackedness), so re-materialize here — git-native
+# anchors only, never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor.
+spex_run internal refresh-footprint >/dev/null 2>&1 || true
+
 subj=$(git log -1 --format=%s 2>/dev/null)
 case "$subj" in
   "merge node/"*) ;;
   *) exit 0 ;;
 esac
 node=$(printf '%s' "$subj" | sed -n 's#^merge \(node/[^:]*\):.*#\1#p')
-main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
-repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
-if command -v spex >/dev/null 2>&1; then
-  spex issues nudge "$node"
-elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
-  "$repo_root/node_modules/.bin/spex" issues nudge "$node"
-elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
-  "$main_root/spec-cli/bin/spex.mjs" issues nudge "$node"
-fi
+spex_run issues nudge "$node"
 exit 0

package/spec-cli/templates/hooks/pre-commit

@@ -64,6 +64,16 @@ if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCOD
   exit 1
 fi
 
+# @@@ footprint surgery ([[commit-surgery]]) - the history anchor: an UNCONDITIONAL materialize (masks fresh
+# at the one moment history is written) + staged-index repair — strip the spexcode sentinel block from any
+# staged blob (source = the staged blob, so `git add -p` partial staging survives), unstage HEAD-untracked
+# generated artifacts. REPAIRS AND PROCEEDS, never rejects; one note per repair on stderr. Runs INSIDE the
+# hook env on purpose: the surgery honors GIT_INDEX_FILE so a pathspec/`-a` commit's TEMPORARY index is the
+# one repaired. Advisory when spex is unresolvable or errors (CI lint enforces); never blocks the commit.
+if [ -n "$spex_kind" ]; then
+  spex_cli internal commit-surgery || echo "• SpexCode: footprint surgery skipped (error above) — a generated artifact may be staged; CI still enforces." >&2
+fi
+
 # @@@ spec-lint - the hook is just a thin shim over `spex lint`. It blocks on errors only (broken
 # spec↔code links); coverage/drift are warnings. Bypass with SPEXCODE_SKIP_LINT=1. It shims through the
 # shared spex_cli() resolved above (repoRoot() discovers the cwd's toplevel via git.ts, which strips the

package/spec-cli/templates/spec/project/.config/core/stop-gate/spec.md

@@ -12,6 +12,6 @@ The blocking stop gate, with two jobs, each holding a hard loop-break so it neve
 
 The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand.
 
-The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end.
+The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end. The full block text (choices, each with its application condition, plus the discipline of declaring as the turn's LAST call — any later tool call re-flips the record to active) prints once per session, marked by a sentinel file beside the session record; later undeclared stops get a one-line reminder that stays self-explanatory — menu, declare-last, and the `spex help session` entry that recovers the full conditions.
 
 It is the enforcement edge of [[core]]: nothing leaves a session except as committed work under a truthful declaration. The freshness it reads is set by [[mark-active]].

package/spec-cli/templates/spec/project/.config/core/stop-gate/stop-gate.sh

@@ -109,12 +109,30 @@ if [ "$cont" = true ]; then
   exit 0
 fi
 
-# first stop in an undeclared state -> nudge exactly once. The reason names the PATH-independent CLI ($S)
-# ONCE as a shared `<CLI> session <choice>` prefix, then lists the five choices as a compact newline menu of
-# bare subcommands — so the terminal output stays legible instead of repeating the long abs path per option.
-# It EMPHASIZES that each state is a CLAIM others act on (not a box to tick to end the turn) and gives the
-# precise APPLICATION CONDITION for each — so the agent picks the TRUE one. park is policed hardest because
-# a false park (no real background task) reads on the board as "fine, self-resuming" when the agent actually
-# needs the human, which is the most damaging mislabel.
-printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply."}\n' "$S"
+# first stop in an undeclared state -> block. The FULL teaching text prints ONCE per session; every later
+# undeclared stop gets a ONE-LINE version (a heavy session hits this gate 15-20x a night — re-printing the
+# full menu each time is pure token noise). The once-sentinel is a plain file beside session.json in the
+# session's global store dir — the same per-session-sentinel mechanism as the CLI's note-echo-taught; $sdir
+# is already alias-resolved here, so a codex thread id lands on the same file, and an unwritable dir just
+# teaches again (never blocks the block). The terse line must stay SELF-EXPLANATORY: an agent whose context
+# was compacted may never have seen the full text, so the line carries the whole command menu, the
+# declare-LAST discipline, and the `help session` entry that re-explains each choice's condition — every bit
+# of the full-to-terse information gap is recoverable from the entry, none of it from memory.
+taught="$sdir/stop-gate-taught"
+if [ -f "$taught" ]; then
+  printf '{"decision":"block","reason":"undeclared stop — pick the ONE true state and declare it as the LAST call of your turn: `%s session <done --propose merge|nothing|close / park --note <what-you-await> / ask --note <your-question>>`. Which choice is true (and why park is never a default): `%s help session`."}\n' "$S" "$S"
+  exit 0
+fi
+touch "$taught" 2>/dev/null || true
+# The full reason names the PATH-independent CLI ($S) ONCE as a shared `<CLI> session <choice>` prefix, then
+# lists the five choices as a compact newline menu of bare subcommands — so the terminal output stays legible
+# instead of repeating the long abs path per option. It EMPHASIZES that each state is a CLAIM others act on
+# (not a box to tick to end the turn) and gives the precise APPLICATION CONDITION for each — so the agent
+# picks the TRUE one. park is policed hardest because a false park (no real background task) reads on the
+# board as "fine, self-resuming" when the agent actually needs the human, which is the most damaging mislabel.
+# It ends with the ORDERING discipline — declare LAST, then stop — because a declaration followed by more
+# tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
+# this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
+# kills the park->block->re-park loop at its source lives here.
+printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
 exit 0

package/spec-cli/templates/spec/project/.config/distill/digest.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// digest.mjs — locate a dead session's transcript on disk and print a compact markdown digest.
+// Usage: node digest.mjs <session-id | path/to/transcript.jsonl>
+// Read-only: never resumes, prompts, or mutates the session. Exit 1 (loud) when no transcript is found.
+//
+// Harness coverage: claude (projects/<enc-cwd>/<id>.jsonl) and codex (sessions/YYYY/MM/DD/rollout-*<id>.jsonl).
+// The digest keeps the high-signal stream — user prompts in full, assistant text, tool calls as one-liners,
+// error results — and drops the bulk (tool outputs, attachments, sidechains, reasoning).
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const arg = process.argv[2]
+if (!arg) { console.error('usage: digest.mjs <session-id | transcript.jsonl>'); process.exit(1) }
+
+const TRUNC = (s, n) => { s = String(s ?? '').trim(); return s.length > n ? s.slice(0, n) + ` …[+${s.length - n} chars]` : s }
+
+// ---- locate -------------------------------------------------------------
+const claudeRoots = () => {
+  const roots = []
+  if (process.env.CLAUDE_CONFIG_DIR) roots.push(process.env.CLAUDE_CONFIG_DIR)
+  for (const e of readdirSync(homedir(), { withFileTypes: true }))
+    if (e.isDirectory() && e.name.startsWith('.claude')) roots.push(join(homedir(), e.name))
+  return roots
+}
+const findClaude = (id) => {
+  for (const root of claudeRoots()) {
+    const proj = join(root, 'projects')
+    if (!existsSync(proj)) continue
+    for (const d of readdirSync(proj)) {
+      const f = join(proj, d, `${id}.jsonl`)
+      if (existsSync(f)) return f
+    }
+  }
+  return null
+}
+const findCodex = (id) => {
+  const root = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
+  if (!existsSync(root)) return null
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) stack.push(join(dir, e.name))
+      else if (e.name.startsWith('rollout-') && e.name.includes(id) && e.name.endsWith('.jsonl')) return join(dir, e.name)
+    }
+  }
+  return null
+}
+const file = arg.endsWith('.jsonl') ? arg : (findClaude(arg) || findCodex(arg))
+if (!file || !existsSync(file)) { console.error(`no transcript found for "${arg}" (searched claude projects/ and codex sessions/)`); process.exit(1) }
+
+// ---- parse --------------------------------------------------------------
+const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean)
+const out = []
+const meta = { cwd: null, branch: null, first: null, last: null }
+const filesTouched = new Set()
+let errors = 0
+const seen = new Set()
+
+// harness-injected preamble arrives typed as "user" (system-reminders, AGENTS.md folds, codex permission/skill
+// blocks) — it is noise to a digest, and real human prompts essentially never open with these markers.
+const isInjected = (t) => /^(<|# AGENTS\.md instructions|Caveat: The messages below)/.test(t.trimStart())
+const userBlock = (t) => { t = String(t ?? '').trim(); return t && !isInjected(t) ? `\n## user\n${t}` : null }
+
+const toolLine = (name, input = {}) => {
+  if ((name === 'Edit' || name === 'Write' || name === 'NotebookEdit') && input.file_path) filesTouched.add(input.file_path)
+  const hint = input.description || input.file_path || input.command || input.prompt || input.query || input.pattern || ''
+  return `→ ${name}${hint ? ` · ${TRUNC(hint, 160)}` : ''}`
+}
+
+for (const raw of lines) {
+  let l; try { l = JSON.parse(raw) } catch { continue }
+  const ts = l.timestamp
+  if (ts) { meta.first ||= ts; meta.last = ts }
+  if (l.cwd) meta.cwd ||= l.cwd
+  if (l.gitBranch && l.gitBranch !== 'HEAD') meta.branch ||= l.gitBranch
+
+  // claude shape: {type: user|assistant, message:{content}, isSidechain}
+  if (l.type === 'user' || l.type === 'assistant') {
+    if (l.isSidechain) continue // subagent noise
+    const c = l.message?.content
+    if (typeof c === 'string') { const u = userBlock(c); if (u) out.push(u); continue }
+    for (const item of c || []) {
+      if (item.type === 'text' && item.text?.trim()) {
+        if (l.type === 'user') { const u = userBlock(item.text); if (u) out.push(u) }
+        else out.push(TRUNC(item.text, 2000))
+      }
+      else if (item.type === 'tool_use') out.push(toolLine(item.name, item.input))
+      else if (item.type === 'tool_result' && item.is_error) {
+        errors++
+        const t = Array.isArray(item.content) ? item.content.map((x) => x.text || '').join(' ') : item.content
+        out.push(`⚠ tool error: ${TRUNC(t, 400)}`)
+      }
+    }
+    continue
+  }
+
+  // codex shape: {type: session_meta|response_item|event_msg, payload:{...}}. The same message is logged
+  // BOTH as a response_item and an event_msg (version-dependent which exists) — dedupe on the text.
+  const p = l.payload
+  if (!p) continue
+  if (l.type === 'session_meta') { meta.cwd ||= p.cwd; continue }
+  const pushMsg = (role, text) => {
+    text = String(text ?? '').trim()
+    if (!text || seen.has(text)) return
+    seen.add(text)
+    if (role === 'user') { const u = userBlock(text); if (u) out.push(u) }
+    else if (role === 'assistant') out.push(TRUNC(text, 2000)) // developer/system roles are harness plumbing
+  }
+  if (l.type === 'event_msg' && (p.type === 'user_message' || p.type === 'agent_message'))
+    pushMsg(p.type === 'user_message' ? 'user' : 'assistant', p.message)
+  else if (l.type === 'response_item') {
+    if (p.type === 'message') {
+      pushMsg(p.role, (p.content || []).map((x) => x.text || '').join('\n'))
+    } else if (p.type === 'function_call') {
+      let input = {}; try { input = JSON.parse(p.arguments || '{}') } catch {}
+      out.push(toolLine(p.name, input))
+    } else if (p.type === 'function_call_output' && /error/i.test(String(p.output).slice(0, 200))) {
+      errors++
+      out.push(`⚠ tool error: ${TRUNC(p.output, 400)}`)
+    }
+  }
+}
+
+// ---- emit ---------------------------------------------------------------
+const kb = Math.round(statSync(file).size / 1024)
+console.log(`# transcript digest — ${arg}`)
+console.log(`- file: ${file} (${kb} KB, ${lines.length} lines)`)
+if (meta.first) console.log(`- span: ${meta.first} → ${meta.last}`)
+if (meta.cwd) console.log(`- cwd: ${meta.cwd}`)
+if (meta.branch) console.log(`- branch: ${meta.branch}`)
+console.log(out.join('\n'))
+console.log(`\n---\n- transcript: ${file}\n- tool errors seen: ${errors}`)
+if (filesTouched.size) console.log(`- files edited:\n${[...filesTouched].map((f) => `  - ${f}`).join('\n')}`)

package/spec-cli/templates/spec/project/.config/distill/spec.md

@@ -0,0 +1,74 @@
+---
+title: distill
+surface: skill, command
+status: active
+hue: 210
+desc: Use when the human wants to inherit a past or dead session's knowledge and work — "distill session X / 继承那个 session 的经验 / 接手它的工作 / 把之前 session 的东西捞回来 / harvest, salvage a finished session". Given a session id, read its transcript from disk (NEVER resume or re-prompt it — its cache is cold and a re-prime is expensive), distill goal · decisions · traps · next steps into the current session, and if its worktree/branch never merged, carry the work over and retire the resources.
+---
+
+# distill
+
+Inherit a finished (or dead) session's **mind and desk** without waking it — mind = its transcript on disk,
+desk = its worktree/branch. The one iron rule: **never resume, reopen, send to, or otherwise re-prompt the
+old session** (cold cache: any turn pays a full re-prime). Everything below is read-only files and plain git.
+
+## 1 · resolve the session
+
+Input: a session id — SpexCode's, a bare harness id (claude / codex thread), or a transcript `.jsonl` path.
+
+- **SpexCode session** (first choice — the join is first-class): its record is
+  `~/.spexcode/projects/*/sessions/<id>/session.json` — glob for the id, prefix ok. Take `worktree_path`,
+  `branch`, `harness`, `harness_session_id`, `status`, `title`; the originating goal is
+  `spex session prompt <id>`. For a claude-harness session the transcript id IS the SpexCode session id;
+  for codex it is `harness_session_id`.
+- **Any other session**: treat the arg as the harness's own id. The transcript carries `cwd` (and, unless
+  the worktree was detached, a branch) — the digest header surfaces them; that is your join to its desk.
+
+## 2 · digest the transcript — mechanical first, model second
+
+`node .spec/<root>/.config/distill/digest.mjs <id-or-path>` locates the transcript (claude:
+`$CLAUDE_CONFIG_DIR` and every `~/.claude*` config dir → `projects/*/<id>.jsonl`; codex: `$CODEX_HOME` or
+`~/.codex` → `sessions/**/rollout-*<id>.jsonl`) and prints a compact digest: the human's prompts in full,
+the agent's own text, tool calls as one-liners, error results, and a footer with the files it edited and
+the raw transcript path. It exits loud when nothing is found — do not fall back to resuming the session.
+
+Read the digest yourself when small; big (>~100 KB) → a subagent returns only the distillation below, so
+the inheritance never floods your own context. Its ⚠ error lines and footer are step 3's trap material.
+
+## 3 · distill — forward-looking, not narrative
+
+Completed work is git's job to remember; do not re-narrate it — and never paste raw transcript. State in
+your reply, and work from, what the transcript knows that git does not:
+
+- **Goal & landing** — what it set out to do, and where it actually stopped (merged? proposal pending?
+  abandoned mid-flight?).
+- **Decisions & why** — the direction that was settled, including options weighed and rejected.
+- **Traps** — failures, dead ends, gotchas, and every correction the human made. These are the
+  highest-value lines in the whole transcript.
+- **Unfinished / next actions** — what it would have done next.
+- **Pointers** — files edited, spec nodes touched, and the raw transcript path itself, so later questions
+  drill into the source instead of inheriting everything up front.
+
+## 4 · salvage the desk
+
+The SpexCode record names the worktree/branch; otherwise the digest's `cwd` may be a linked worktree
+(`git -C <cwd> rev-parse --git-common-dir`). Salvage inside that repo — it need not be the one you sit in.
+Cross-check the digest's files-edited footer against that worktree: a manager-style session's edits often
+live OUTSIDE it (main-checkout config, other repos) — those need a by-hand look, not the recipe below.
+
+- **Already merged** (`git merge-base --is-ancestor <branch> <trunk>`) → nothing to salvage; note it and
+  go to cleanup. A tip that EQUALS the merge-base carried no commits — say "never committed", not "merged".
+- **Unmerged commits** → carry them onto your current branch: `git cherry-pick <base>..<branch>` (keeps
+  authorship and `Session:` trailers); fall back to applying `git diff <base> <branch>` when the history
+  is too messy to replay.
+- **Uncommitted changes** in the old worktree → `git -C <wt> status --porcelain`; apply its diff to your
+  tree and copy untracked files over. Commit the salvage in your own tree, naming the origin session in
+  the message.
+
+## 5 · clean up — only after the salvage LANDED
+
+Cleanup discards state — verify the salvaged commits are in your tree (or the branch genuinely merged) first.
+
+- SpexCode session: `spex session close <id>` retires the session and its worktree in one verb.
+- Bare worktree: `git worktree remove <wt>`, + `git branch -D <branch>` once confirmed carried or merged.
+- In doubt, keep the resources and say so — a kept worktree costs disk; a wrong cleanup costs the work.