elanous 0.2.23 → 0.2.25

package/src/harness/launch-registry.ts

@@ -19,6 +19,10 @@ export interface LaunchBinding {
   readonly goalPath?: string;
   /** The `self-dev-runs` directory that holds this run's `pid.json` — tells a stop which universe launched it. */
   readonly runsDir?: string;
+  /** `ELANOUS_POD_NAME` at launch — a Pod child's run (TA backfill skips it like the launch-time hook does). */
+  readonly podName?: string;
+  /** `ELANOUS_TASK_CARD_ID` at launch — a handed run that already owns a card (TA backfill skips it). */
+  readonly taskCardId?: string;
 }
 
 const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -72,6 +76,8 @@ export function readLaunchBinding(runId: string, dir = launchRegistryDir()): Lau
       ...(typeof value.argv0 === 'string' ? { argv0: value.argv0 } : {}),
       ...(typeof value.goalPath === 'string' && isAbsolute(value.goalPath) ? { goalPath: value.goalPath } : {}),
       ...(typeof value.runsDir === 'string' && isAbsolute(value.runsDir) ? { runsDir: value.runsDir } : {}),
+      ...(typeof value.podName === 'string' && value.podName ? { podName: value.podName } : {}),
+      ...(typeof value.taskCardId === 'string' && value.taskCardId ? { taskCardId: value.taskCardId } : {}),
     };
   } catch { return null; }
 }

package/src/harness/worktree-branch-prefix.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { branchGoalId } from '../cli/pr-lineage.js';
 
 /** Prefix for disposable worktree branches created by self-implement and inspected by harness clean.
  * A successfully merged run cleans up its own worktree.
@@ -31,3 +32,11 @@ export function plannedSelfImplBranch(feature: string, goalId?: string, runId?:
   const digest = createHash('sha256').update(id).digest('hex').slice(0, 8);
   return `${WORKTREE_BRANCH_PREFIX}goalid-${id}-${readable}-${digest}${runSuffix}`;
 }
+
+/** 같은 골의 재실행이 공유하는 «안정한» 계보 키. `plannedSelfImplBranch` 가 싣는 `goalid-<id>-` 구간만 읽는다 —
+ *  feature 문구·다이제스트·런 접미(`-r<runId>`)는 재실행마다 달라지므로 키에 넣지 않는다.
+ *  ⛔ 골 식별자가 없는 옛 브랜치는 `null` — 읽기용 슬러그는 서로 다른 골이 같은 값을 낼 수 있어(`grounded-N-…`) 키가 될 수 없다. */
+export function branchLineageKey(branch: string): string | null {
+  const id = branchGoalId(branch);
+  return id ? `goalid:${id.toLowerCase()}` : null;
+}

package/src/hq/fence.ts

@@ -0,0 +1,187 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readlinkSync, readdirSync } from 'node:fs';
+import { cronMatches } from '../domains/cron-match.js';
+import { resolveTimeZone } from '../time/format.js';
+
+export interface CliProcess { pid: number; ppid: number; ageSeconds: number; cpuSeconds: number; command: string }
+export interface OrphanCandidate { process: CliProcess; tree: CliProcess[]; periodMinutes: number }
+export interface FenceGcDeps {
+  snapshot?: () => CliProcess[];
+  run?: (binary: string, args: string[]) => string;
+  sleep?: (ms: number) => Promise<void>;
+  kill?: (pid: number) => void;
+  timeZone?: string;
+}
+
+export function cliFingerprint(command: string): string {
+  return command.replace(/^\s*(?:\S*\/)?bun\s+(?:\S*\/)?elanous\.mjs\s+/, 'elanous ')
+    .replace(/^\s*(?:\S*\/)?(?:elanous\.mjs|eln)\s+/, 'elanous ')
+    .trim();
+}
+
+function seconds(text: string): number {
+  const parts = text.split(':').map(Number);
+  return parts.reduce((total, part) => total * 60 + part, 0);
+}
+
+/** ps gives command after the four numeric fields; never split command on whitespace. */
+export function processSnapshot(): CliProcess[] {
+  const result = spawnSync('ps', ['-axo', 'pid=,ppid=,etime=,time=,command='], { encoding: 'utf8', timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`ps failed: ${result.stderr}`);
+  return result.stdout.split('\n').flatMap(line => {
+    const fields = /^\s*(\d+)\s+(\d+)\s+([\d:-]+)\s+([\d:.]+)\s+(.+)$/.exec(line);
+    if (!fields) return [];
+    const elapsed = fields[3]!.split('-');
+    const ageSeconds = seconds(elapsed.at(-1)!) + (elapsed.length === 2 ? Number(elapsed[0]) * 86_400 : 0);
+    const cpuSeconds = seconds(fields[4]!);
+    if (!Number.isFinite(ageSeconds) || !Number.isFinite(cpuSeconds)) return [];
+    return [{ pid: Number(fields[1]), ppid: Number(fields[2]), ageSeconds, cpuSeconds, command: fields[5]! }];
+  });
+}
+
+/** Only installed elanous one-shot CLI launches, not shells, daemons, or an incidental flag inside a quoted payload. */
+export function oneShotCommand(command: string): boolean {
+  const invocation = /^(?:(?:\S*\/)?bun\s+(?:\S*\/)?elanous\.mjs|(?:\S*\/)?(?:elanous|elanous\.mjs|eln))\s+/.exec(command);
+  if (!invocation) return false;
+  const args = command.slice(invocation[0].length).split(/\s+--\s+|\s+-c\s+/)[0] ?? '';
+  const payload = /\s+--\s+(.+)$/.exec(command)?.[1] ?? '';
+  const shellBody = /\s+--\s+(?:\S*\/)?(?:sh|bash)\s+-c\s+(.+)$/.exec(command)?.[1];
+  if (shellBody !== undefined) {
+    if (!/^['"]?(?:\S*\/)?bun\s+(?:\S*\/)?elanous\.mjs\s+/.test(shellBody)
+      || /[;|`&]/.test(shellBody) || /\bnexus\s+run\b/.test(shellBody)
+      || !/(?:^|\s)(?:--once|tick|--refresh|--notify)(?:\s|['"]|$)/.test(shellBody)) return false;
+  }
+  // Test-universe and help invocations are never collected — on the fence itself, in its payload, or in a wrapped shell body.
+  for (const part of [args, payload, shellBody ?? '']) {
+    if (/(?:^|\s|['"])--test(?:\s|=|['"]|$)/.test(part) || /(?:^|\s)(?:--help|-h)(?:\s|['"]|$)/.test(part)) return false;
+  }
+  // The daemon is never a one-shot, whatever flag rides along (`nexus run --once`), directly or as a fence payload.
+  if (/(?:^|\s)nexus\s+run\b/.test(args) || /(?:^|\s)nexus\s+run\b/.test(payload) || /&&|\|\||[;|`&]/.test(payload)) return false;
+  if (/^hq\s+fence\s+--role\s+(?:cron|seat-loop|conatus|release-run)\b/.test(args) && payload) {
+    return /(?:^|\s)(?:--once|tick|--refresh|--notify)(?:\s|['"]|$)/.test(payload);
+  }
+  return /(?:^|\s)hq\s+fence\s+--role\s+(?:cron|seat-loop|conatus|release-run)\b/.test(args)
+    || /(?:^|\s)--once(?:\s|$)/.test(args)
+    || /(?:^|\s)(?:tick|--refresh|--notify)(?:\s|$)/.test(args);
+}
+
+/** Unknown/mismatched schedules are not assigned a made-up period. Match the launched action (including fence payload). */
+export function scheduledPeriodMinutes(command: string, schedules: readonly { command: string; cron: string }[], now: Date, timeZone = resolveTimeZone().timeZone): number | null {
+  const current = cliFingerprint(command);
+  const matches = schedules.filter(job => {
+    const action = job.command.trim().replace(/^cd\s+\S+\s*&&\s*/, '').replace(/\s+>>?\s+\S+(?:\s+2>&1)?\s*$/, '');
+    if (action.length < 16) return false;
+    if (current === cliFingerprint(action)) return true;
+    // The installed hq-fence shell wrapper execs the CLI with an explicit role and -- payload.
+    // Accept only a single, unambiguous quoted command; never infer a period from a substring.
+    const wrapper = /^(?:\S*\/)?hq-fence\s+(cron|seat-loop|conatus|release-run)\s+'([^']+)'$/.exec(action);
+    if (!wrapper) return false;
+    return current === `elanous hq fence --role ${wrapper[1]} -- ${wrapper[2]}`;
+  });
+  if (matches.length !== 1) return null;
+  const cron = matches[0]!.cron;
+  if (cron.trim().split(/\s+/).length !== 5) return null;
+  const start = Math.floor(now.getTime() / 60_000) * 60_000;
+  // A 7-day minute scan per process is costly with many hung trees; one tick asks the same (cron, zone, minute) often.
+  const memoKey = `${cron}\0${timeZone}\0${start}`;
+  if (periodMemo.has(memoKey)) return periodMemo.get(memoKey)!;
+  const period = cronPeriodMinutes(cron, start, timeZone);
+  if (periodMemo.size > 256) periodMemo.clear();
+  periodMemo.set(memoKey, period);
+  return period;
+}
+
+const periodMemo = new Map<string, number | null>();
+
+function cronPeriodMinutes(cron: string, start: number, timeZone: string): number | null {
+  const fires: number[] = [];
+  try {
+    // Every fire in the next 7 days, not just the first few: a weekday-hours cron (`0 9-17 * * 1-5`) is hourly
+    // for three gaps and then pauses for a night or a weekend — that is no single period.
+    for (let i = 0; i < 7 * 24 * 60; i++) {
+      const at = start + i * 60_000;
+      if (cronMatches(cron, new Date(at), { timeZone })) fires.push(at);
+    }
+  } catch { return null; }
+  // An irregular schedule (any unequal gap within the window, e.g. `0 9,18 * * *`, weekday hours) has no single period
+  // to multiply — unknown, never collected. Fewer than three fires in 7 days (weekly) is unknown too (safe side).
+  if (fires.length < 3) return null;
+  const gap = fires[1]! - fires[0]!;
+  for (let i = 2; i < fires.length; i++) if (fires[i]! - fires[i - 1]! !== gap) return null;
+  return gap / 60_000;
+}
+
+export function orphanCandidates(first: readonly CliProcess[], second: readonly CliProcess[], schedules: readonly { command: string; cron: string }[], now: Date, timeZone?: string): OrphanCandidate[] {
+  const byPid = new Map(second.map(row => [row.pid, row]));
+  const initial = new Map(first.map(row => [row.pid, row]));
+  const candidates: OrphanCandidate[] = [];
+  // The collector itself and every ancestor of it (the guardian tick's cron/fence parents) are never signalled.
+  const self = new Set<number>([process.pid]);
+  for (let pid: number | undefined = byPid.get(process.pid)?.ppid; pid !== undefined && pid > 1 && !self.has(pid); pid = byPid.get(pid)?.ppid) self.add(pid);
+  for (const root of first) {
+    if (root.pid === process.pid || !oneShotCommand(root.command)) continue;
+    const current = byPid.get(root.pid);
+    if (!current || current.command !== root.command || current.ppid !== root.ppid || current.cpuSeconds !== root.cpuSeconds) continue;
+    // Identity: a reused PID restarts its age; the same process can only have grown older between snapshots.
+    if (current.ageSeconds < root.ageSeconds) continue;
+    const periodMinutes = scheduledPeriodMinutes(root.command, schedules, now, timeZone);
+    if (!periodMinutes || root.ageSeconds <= periodMinutes * 3 * 60) continue;
+    // An old ancestor with an actively executing payload is not an orphan.
+    if (second.some(row => row.ppid === root.pid && !initial.has(row.pid))) continue;
+    const tree = [current];
+    for (let i = 0; i < tree.length; i++) {
+      for (const child of second) if (child.ppid === tree[i]!.pid && !tree.some(row => row.pid === child.pid)) tree.push(child);
+    }
+    if (tree.some(row => {
+      const before = initial.get(row.pid);
+      return !before || before.command !== row.command || before.cpuSeconds !== row.cpuSeconds || before.ppid !== row.ppid
+        || Math.abs((row.ageSeconds - before.ageSeconds) - (current.ageSeconds - root.ageSeconds)) > 2;
+    })) continue;
+    if (tree.some(row => self.has(row.pid))) continue;
+    candidates.push({ process: current, tree, periodMinutes });
+  }
+  return candidates.filter(candidate => !candidates.some(parent => parent !== candidate && parent.tree.some(row => row.pid === candidate.process.pid)));
+}
+
+export function gcTools(deps: FenceGcDeps = {}) {
+  return {
+    snapshot: deps.snapshot ?? processSnapshot,
+    sleep: deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))),
+    run: deps.run ?? ((binary: string, args: string[]) => {
+      // Linux has no macOS sample. Over one second, sample each thread's wait channel and state (readable by the
+      // process owner); the kernel stack is root-only on most hosts, so it is added only when readable.
+      if (binary === 'sample' && process.platform === 'linux') {
+        const pid = args[0];
+        const samples: string[] = [];
+        const deadline = Date.now() + 1_000;
+        do {
+          for (const tid of readdirSync(`/proc/${pid}/task`)) {
+            const base = `/proc/${pid}/task/${tid}`;
+            const state = /^State:\s*(.+)$/m.exec(readFileSync(`${base}/status`, 'utf8'))?.[1] ?? '?';
+            let stack = '';
+            // Root-only on most kernels: carried when readable, otherwise the evidence says so (not a collection gate).
+            try { stack = `\n${readFileSync(`${base}/stack`, 'utf8')}`; } catch (error) { stack = ` kernel-stack=unreadable(${(error as NodeJS.ErrnoException).code ?? 'error'})`; }
+            samples.push(`tid=${tid} state=${state} wchan=${readFileSync(`${base}/wchan`, 'utf8') || '0'}${stack}`);
+          }
+          if (Date.now() < deadline) Bun.sleepSync(Math.min(100, deadline - Date.now()));
+        } while (Date.now() < deadline);
+        if (samples.length === 0) throw new Error(`sample: no threads for PID ${pid}`);
+        return samples.join('\n');
+      }
+      // macOS `sample` by absolute path: a PATH shim (e.g. pyenv's `sample`) must not stand in for the profiler.
+      const resolved = binary === 'sample' && process.platform === 'darwin' ? '/usr/bin/sample' : binary;
+      // sample symbolicates a large Bun binary after its 1s window — allow time and room, or it would never succeed.
+      const result = spawnSync(resolved, args, { encoding: 'utf8', timeout: binary === 'sample' ? 30_000 : 10_000, maxBuffer: 8 * 1024 * 1024 });
+      if (result.status !== 0) throw new Error(`${binary}: ${result.error ?? result.stderr ?? 'failed'}`);
+      return result.stdout;
+    }),
+    kill: deps.kill ?? ((pid: number) => process.kill(pid, 'SIGTERM')),
+  };
+}
+
+/** The target's own Bun binary — read from the target PID, so a PID that died (or was reused) fails closed. */
+export function bunVersion(pid: number, run: (binary: string, args: string[]) => string): string {
+  const bin = process.platform === 'linux' ? readlinkSync(`/proc/${pid}/exe`) : run('ps', ['-o', 'comm=', '-p', String(pid)]).trim();
+  if (!/(?:^|\/)bun(?:$|\s)/.test(bin)) throw new Error(`PID ${pid} is not a Bun process`);
+  return run(bin, ['--version']).trim();
+}

package/src/hq/seats.ts

@@ -47,6 +47,12 @@ export function resolveHqLaunchSeat(role: string, home: string, options: { root?
   if (head.status !== 1) throw new Error(`git symbolic-ref --quiet HEAD: ${head.stderr.trim() || `exit ${head.status}`}`);
   return path;
 }
+
+/** Installed-CLI argv: absolute runtime + absolute CLI entry, so a launch never resolves `bin/elanous.mjs` against its cwd. */
+export function installedCliArgv(args: readonly string[] = []): string[] {
+  return [process.execPath, resolve(import.meta.dir, '../../bin/elanous.mjs'), ...args];
+}
+
 function readLedger(root: string): HouseLedger {
   const ledger = JSON.parse(readFileSync(ledgerPath(root), 'utf8')) as HouseLedger;
   if (!ledger.home?.path || !ledger.sandboxes || typeof ledger.sandboxes !== 'object') throw new Error('invalid house.json; refusing to guess houses');
@@ -157,7 +163,7 @@ export function proveMergedPr(repo: string, branch: string, tip: string, gh: (ar
     : { status: parsed.length >= MERGED_PR_QUERY_LIMIT ? 'unknown' : 'not-merged' };
 }
 
-// Every tip checked by done is tied to its own branch, including a different attached branch.
+// Attached tips use their branch; a detached HEAD is checked separately from the registered work tip.
 function landedTip(repo: string, branch: string, tip: string, gh: (args: string[]) => GhCliResult): 'ancestor' | 'pr-merged' | 'tree-equal' | null {
   if (mergedIntoMain(repo, tip)) return 'ancestor';
   if (proveMergedPr(repo, branch, tip, gh, 'main').status === 'pr-merged') return 'pr-merged';
@@ -170,8 +176,8 @@ function judgeLandedTip(repo: string, branch: string, tip: string, gh: (args: st
   return rule !== null;
 }
 
-// Squash changes the commit identity. Prove the original commit changed at least one path and
-// that every one of those paths has the same content and mode in the fetched main tree.
+// Squash changes commit identity. Check the changed paths together against a fetched main
+// snapshot, not merely the latest tree: a later main commit may have edited those paths again.
 function treeEqualToMain(repo: string, tip: string): boolean {
   const main = 'refs/remotes/origin/main';
   const base = git(repo, 'merge-base', tip, main);
@@ -179,9 +185,15 @@ function treeEqualToMain(repo: string, tip: string): boolean {
   if (changed.status !== 0) throw new Error(`cannot verify changed files: ${changed.stderr.trim() || `exit ${changed.status}`}`);
   const files = changed.stdout.split('\0').filter(Boolean);
   if (files.length === 0) return false;
-  const equal = runGitCommand(repo, ['diff', '--quiet', tip, main, '--', ...files], { encoding: 'utf8' });
-  if (equal.status !== 0 && equal.status !== 1) throw new Error(`cannot verify tree equality: ${equal.stderr.trim() || `exit ${equal.status}`}`);
-  return equal.status === 0;
+  const equalAt = (commit: string): boolean => {
+    const equal = runGitCommand(repo, ['diff', '--quiet', tip, commit, '--', ...files], { encoding: 'utf8' });
+    if (equal.status !== 0 && equal.status !== 1) throw new Error(`cannot verify tree equality: ${equal.stderr.trim() || `exit ${equal.status}`}`);
+    return equal.status === 0;
+  };
+  if (equalAt(main)) return true;
+  // Only first-parent main snapshots can establish a previous landing; a side branch alone cannot.
+  const history = git(repo, 'log', '--first-parent', '--format=%H', `${base}..${main}`, '--', ...files);
+  return history.split('\n').filter(Boolean).some(equalAt);
 }
 // Git lock files are created exclusively; ours carry our pid. A lock left by a killed `work done` is never
 // removed automatically (between our check and a delete, a live git could have re-taken it): the error names it.
@@ -398,49 +410,53 @@ export function hqWork(action: 'new' | 'done', value: string, nameValue: string,
     // Resume: an interrupted done left the work detached at its recorded merged tip, with the branch either
     // still at that tip (stopped before the delete) or already deleted (stopped before the removal).
     const branchPresent = branchTip.status === 0;
-    const resuming = attached.status !== 0 && entry.reclaiming !== undefined
-      && git(path, 'rev-parse', 'HEAD') === (entry.checkoutTip ?? entry.reclaiming)
+    const head = git(path, 'rev-parse', 'HEAD');
+    const resuming = attached.status === 1 && entry.reclaiming !== undefined
+      && head === (entry.checkoutTip ?? entry.reclaiming)
       && (!branchPresent || branchTip.stdout.trim() === entry.reclaiming);
-    if (!resuming && (attached.status !== 0 || !branchPresent)) throw new Error(`work branch mismatch: ${path}`);
+    if (!resuming && (attached.status !== 0 && attached.status !== 1 || !branchPresent)) throw new Error(`work branch mismatch: ${path}`);
     const ownTip = resuming ? entry.reclaiming! : branchTip.stdout.trim();
-    const checkoutBranch = resuming ? entry.checkoutBranch ?? branch : attached.stdout.trim();
+    const detached = !resuming && attached.status === 1;
+    const detachedCheckout = detached || (resuming && entry.checkoutBranch === branch && entry.checkoutTip !== undefined && entry.checkoutTip !== ownTip);
+    const checkoutBranch = resuming ? entry.checkoutBranch ?? branch : detached ? branch : attached.stdout.trim();
     const checkoutRef = `refs/heads/${checkoutBranch}`;
     const differentBranch = checkoutBranch !== branch;
-    const tip = differentBranch
-      ? (resuming ? entry.checkoutTip! : git(repo, 'rev-parse', '--verify', checkoutRef))
-      : ownTip;
-    if (!resuming && differentBranch && git(path, 'rev-parse', 'HEAD') !== tip) throw new Error(`work branch moved before the merge check: ${checkoutBranch}`);
+    const tip = detached ? head : resuming && entry.checkoutTip ? entry.checkoutTip : differentBranch
+      ? git(repo, 'rev-parse', '--verify', checkoutRef) : ownTip;
+    if (!resuming && !detached && differentBranch && head !== tip) throw new Error(`work branch moved before the merge check: ${checkoutBranch}`);
     // The ancestor check is against origin/main, not bare HEAD (which may still point to master).
     if (!judgeLandedTip(repo, checkoutBranch, tip, options.gh ?? runGhCliWithResult)) throw new Error(`work is not merged into origin/main: ${checkoutBranch}`);
-    if (differentBranch && !judgeLandedTip(repo, branch, ownTip, options.gh ?? runGhCliWithResult)) throw new Error(`work is not merged into origin/main: ${branch}`);
+    if ((differentBranch || detachedCheckout) && tip !== ownTip && !judgeLandedTip(repo, branch, ownTip, options.gh ?? runGhCliWithResult)) throw new Error(`work is not merged into origin/main: ${branch}`);
     if (differentBranch && !resuming) {
       const current = runGitCommand(repo, ['rev-parse', '--verify', checkoutRef], { encoding: 'utf8' });
       if (current.status !== 0 || current.stdout.trim() !== tip || git(path, 'rev-parse', 'HEAD') !== tip) throw new Error(`work branch moved before removal: ${checkoutBranch}`);
     }
     // Removal order keeps every interruption resumable: record the proven checkout tip and original branch tip
     // → detach → hold the work's git locks → compare-and-delete the original branch → remove the worktree
-    // → drop the registration last. A different attached branch is proven but its ref is never deleted.
+    // → drop the registration last. A different attached branch is proven but its ref is never deleted;
+    // a pre-existing detached HEAD is checked independently and never reattached on a failed removal.
     // Holding this worktree's HEAD.lock and index.lock makes git refuse every commit and `add` in it until the
     // removal ends (`worktree remove` itself does not need them), so no commit can land between the last
     // check and the removal. The locks live in the worktree's admin dir, which the removal deletes.
     updateLedgerLocked(root, ledger => { ledger.sandboxes[path] = { ...entry, reclaiming: ownTip,
-      ...(differentBranch ? { checkoutTip: tip, checkoutBranch } : {}) }; });
+      ...(differentBranch || (detachedCheckout && tip !== ownTip) ? { checkoutTip: tip, checkoutBranch } : {}) }; });
     const admin = git(path, 'rev-parse', '--absolute-git-dir');
     const held: string[] = [];
     const release = (): void => { for (const lock of held.splice(0)) rmSync(lock, { force: true }); };
     const restore = (): string => {
       release();
       const head = runGitCommand(path, ['rev-parse', '--verify', 'HEAD'], { encoding: 'utf8' });
-      runGitCommand(repo, ['update-ref', ref, differentBranch ? ownTip : head.status === 0 ? head.stdout.trim() : tip, ''], { encoding: 'utf8' });
-      const reattached = runGitCommand(path, ['symbolic-ref', 'HEAD', checkoutRef], { encoding: 'utf8' }).status === 0;
-      // If HEAD could not be re-attached (e.g. a stale HEAD.lock), keep `reclaiming` so the next done resumes.
+      runGitCommand(repo, ['update-ref', ref, differentBranch || detachedCheckout ? ownTip : head.status === 0 ? head.stdout.trim() : tip, ''], { encoding: 'utf8' });
+      const reattached = detachedCheckout ? head.status === 0 && head.stdout.trim() === tip
+        : runGitCommand(path, ['symbolic-ref', 'HEAD', checkoutRef], { encoding: 'utf8' }).status === 0;
+      // If HEAD could not be restored (e.g. a stale HEAD.lock), keep `reclaiming` so the next done resumes.
       const restored = reattached ? { kind: entry.kind, path: entry.path, owner: entry.owner } : { ...entry, reclaiming: ownTip,
-        ...(differentBranch ? { checkoutTip: tip, checkoutBranch } : {}) };
+        ...(differentBranch || (detachedCheckout && tip !== ownTip) ? { checkoutTip: tip, checkoutBranch } : {}) };
       try { updateLedgerLocked(root, ledger => { ledger.sandboxes[path] = restored; }); return reattached ? 'registration restored' : 'left resumable'; }
       catch (error) { return `REGISTRATION NOT RESTORED (fix ${path} in house.json by hand): ${error instanceof Error ? error.message : String(error)}`; }
     };
     const fail = (message: string): never => { throw new Error(`${message}; nothing removed: ${path} · ${restore()}`); };
-    if (!resuming) git(path, 'checkout', '--quiet', '--detach');
+    if (!resuming && !detached) git(path, 'checkout', '--quiet', '--detach');
     for (const name of ['HEAD.lock', 'index.lock']) {
       const lock = join(admin, name);
       try { takeLock(lock); held.push(lock); }

package/src/images/image-ledger.ts

@@ -0,0 +1,179 @@
+/**
+ * IMAGE-LEDGER-TAGS (RFC-adaptive-graph-ops §9.11) — first slice: the image ledger.
+ *
+ * The registry tag itself carries only the 12-char commit (docker/harness/build.sh:276), so the
+ * identity of an image (why it exists, how long to keep it) lives in a small append-only ledger
+ * next to the config that pins it (`<config dir>/image-ledger.jsonl`). Writers append events;
+ * readers fold them per tag. A registry tag with no ledger row is `transient` (RFC §9.11).
+ *
+ * Writers in this slice: the baseline pin (`config set harness.imageCommit <commit>` — the rail
+ * pins through that command). Launch · gate · release writers and `image tag` are later slices.
+ *
+ * Unreadable is never "none": a ledger line that fails to parse is counted, and a registry that
+ * cannot be read is reported as `null` (not as an empty tag list).
+ */
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export const IMAGE_ROLES = ['baseline', 'release', 'gate', 'demo', 'candidate', 'transient'] as const;
+export type ImageRole = typeof IMAGE_ROLES[number];
+export const IMAGE_KEEPS = ['pin', 'long', 'short', 'gc'] as const;
+export type ImageKeep = typeof IMAGE_KEEPS[number];
+export const IMAGE_ORIGIN_REASONS = ['rail', 'launch', 'gate', 'release', 'manual', 'config-set'] as const;
+export type ImageOriginReason = typeof IMAGE_ORIGIN_REASONS[number];
+
+export interface ImageLedgerEvent {
+  readonly v: 1;
+  readonly ts: string;
+  /** Registry tag = first 12 hex chars of the commit (build.sh:276). */
+  readonly tag: string;
+  readonly commit: string;
+  readonly role: ImageRole;
+  readonly keep: ImageKeep;
+  readonly origin: { readonly host: string; readonly reason: ImageOriginReason };
+}
+
+export interface ImageLedgerRead {
+  readonly path: string;
+  readonly exists: boolean;
+  readonly events: readonly ImageLedgerEvent[];
+  /** Lines that were present but did not parse as a ledger event. */
+  readonly unreadableLines: number;
+}
+
+export interface ImageLedgerRow {
+  readonly tag: string;
+  readonly commit: string;
+  readonly role: ImageRole;
+  readonly keep: ImageKeep;
+  /** Origin of the first event for this tag · null for a registry-only (unledgered) tag — its origin is unknown. */
+  readonly origin: { readonly host: string; readonly reason: ImageOriginReason } | null;
+  readonly firstTs: string;
+  readonly lastTs: string;
+  /** For `baseline`: true only for the most recently pinned baseline. */
+  readonly current: boolean;
+  /** true when the tag is on the registry · false when not · null when the registry was not read. */
+  readonly inRegistry: boolean | null;
+  /** true when the row comes only from the registry (no ledger event) — always role `transient`. */
+  readonly unledgered: boolean;
+}
+
+const HEX = /^[0-9a-f]{12,40}$/u;
+
+export function imageLedgerPath(configDir: string = getElanousConfigDir()): string {
+  return join(configDir, 'image-ledger.jsonl');
+}
+
+export function imageTag(commit: string): string {
+  return commit.trim().toLowerCase().slice(0, 12);
+}
+
+function isEvent(value: unknown): value is ImageLedgerEvent {
+  if (!value || typeof value !== 'object') return false;
+  const e = value as Record<string, unknown>;
+  const origin = e.origin as Record<string, unknown> | undefined;
+  return e.v === 1 && typeof e.ts === 'string' && typeof e.tag === 'string' && /^[0-9a-f]{12}$/u.test(e.tag)
+    && typeof e.commit === 'string' && HEX.test(e.commit)
+    && (IMAGE_ROLES as readonly unknown[]).includes(e.role) && (IMAGE_KEEPS as readonly unknown[]).includes(e.keep)
+    && !!origin && typeof origin.host === 'string' && (IMAGE_ORIGIN_REASONS as readonly unknown[]).includes(origin.reason);
+}
+
+export function readImageLedger(path: string = imageLedgerPath()): ImageLedgerRead {
+  if (!existsSync(path)) return { path, exists: false, events: [], unreadableLines: 0 };
+  const events: ImageLedgerEvent[] = [];
+  let unreadableLines = 0;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isEvent(parsed)) events.push(parsed); else unreadableLines += 1;
+    } catch { unreadableLines += 1; }
+  }
+  return { path, exists: true, events, unreadableLines };
+}
+
+export function appendImageLedgerEvent(event: ImageLedgerEvent, path: string = imageLedgerPath()): void {
+  if (!isEvent(event)) throw new Error(`invalid image ledger event: ${JSON.stringify(event)}`);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+}
+
+/** The baseline pin event — what `config set harness.imageCommit <commit>` records. */
+export function baselinePinEvent(commit: string, deps: { now?: () => Date; host?: string } = {}): ImageLedgerEvent {
+  const c = commit.trim().toLowerCase();
+  if (!HEX.test(c)) throw new Error(`not a commit (hex 12~40): ${commit}`);
+  return {
+    v: 1,
+    ts: (deps.now?.() ?? new Date()).toISOString(),
+    tag: imageTag(c),
+    commit: c,
+    role: 'baseline',
+    keep: 'pin',
+    origin: { host: deps.host ?? hostname(), reason: 'config-set' },
+  };
+}
+
+/**
+ * Fold events per tag (the last event decides role and keep), then add registry tags that have no
+ * ledger event as `transient`. `registryTags === null` means the registry was not read.
+ * Non-commit registry tags (`latest`) are moving aliases and are not rows.
+ */
+export function foldImageLedger(events: readonly ImageLedgerEvent[], registryTags: readonly string[] | null): ImageLedgerRow[] {
+  const byTag = new Map<string, { first: ImageLedgerEvent; last: ImageLedgerEvent }>();
+  // Events for one tag may carry the 12-char tag or the full 40-char commit; the row keeps the longest one seen.
+  const fullCommit = new Map<string, string>();
+  for (const e of events) {
+    const seen = byTag.get(e.tag);
+    if (!seen) byTag.set(e.tag, { first: e, last: e });
+    else if (e.ts >= seen.last.ts) seen.last = e;
+    if (e.commit.length > (fullCommit.get(e.tag)?.length ?? 0)) fullCommit.set(e.tag, e.commit);
+  }
+  let currentBaseline: string | null = null;
+  let currentTs = '';
+  for (const e of events) if (e.role === 'baseline' && e.ts >= currentTs) { currentBaseline = e.tag; currentTs = e.ts; }
+  const registry = registryTags === null ? null : new Set(registryTags.filter((t) => /^[0-9a-f]{12}$/u.test(t)));
+  const rows: ImageLedgerRow[] = [...byTag.values()].map(({ first, last }) => ({
+    tag: last.tag,
+    commit: fullCommit.get(last.tag) ?? last.commit,
+    role: last.role,
+    keep: last.keep,
+    origin: first.origin,
+    firstTs: first.ts,
+    lastTs: last.ts,
+    current: last.role === 'baseline' && last.tag === currentBaseline,
+    inRegistry: registry === null ? null : registry.has(last.tag),
+    unledgered: false,
+  }));
+  if (registry) for (const tag of [...registry].sort()) {
+    if (byTag.has(tag)) continue;
+    rows.push({ tag, commit: tag, role: 'transient', keep: 'short', origin: null, firstTs: '', lastTs: '', current: false, inRegistry: true, unledgered: true });
+  }
+  return rows.sort((a, b) => (b.lastTs || '').localeCompare(a.lastTs || '') || a.tag.localeCompare(b.tag));
+}
+
+export type RegistryRead = { readonly ok: true; readonly tags: readonly string[] } | { readonly ok: false; readonly reason: string };
+
+/**
+ * Read `elanous-harness` tags from the registry the way the rail does (`/v2/elanous-harness/tags/list`
+ * on the registry node's localhost port). `sshHost` runs it on that node; otherwise on this machine.
+ */
+export function readRegistryTags(opts: { port: string; sshHost?: string; run?: (cmd: string, args: readonly string[]) => { status: number | null; stdout: string; stderr?: string } }): RegistryRead {
+  const url = `http://localhost:${opts.port}/v2/elanous-harness/tags/list`;
+  const run = opts.run ?? ((cmd, args) => {
+    const r = spawnSync(cmd, [...args], { encoding: 'utf8', timeout: 25_000 });
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? (r.error ? String(r.error) : '') };
+  });
+  const r = opts.sshHost
+    ? run('ssh', ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', opts.sshHost, `curl -fsS --max-time 15 ${url}`])
+    : run('curl', ['-fsS', '--max-time', '15', url]);
+  if (r.status !== 0) return { ok: false, reason: `registry read failed (exit ${r.status ?? 'timeout'})${r.stderr ? `: ${r.stderr.trim().slice(0, 200)}` : ''}` };
+  try {
+    const tags = (JSON.parse(r.stdout) as { tags?: unknown }).tags;
+    if (tags === null) return { ok: true, tags: [] };
+    if (!Array.isArray(tags) || !tags.every((t) => typeof t === 'string')) return { ok: false, reason: 'registry answered without a tags list' };
+    return { ok: true, tags };
+  } catch { return { ok: false, reason: 'registry answered non-JSON' }; }
+}