elanous 0.2.22 → 0.2.24

package/src/harness/nested-elanous-policy.ts

@@ -2,7 +2,7 @@
 //
 // Codex children drop parent env under shell_environment_policy inherit=core, so a
 // depth marker that only lives in the environment never arrives. Depth is therefore
-// carried on the codex argv (`-c shell_environment_policy.set.ELANOUS_NESTED_DEPTH=<n>`).
+// carried on the codex argv (`-c shell_environment_policy.set.ELANOUS_NESTED_DEPTH="<n>"` — TOML 문자열).
 //
 // Unset ELANOUS_NESTED_DEPTH is depth 0 (the outer launcher). A missing marker is
 // not "depth unknown" and does not refuse an ordinary mission spawn.
@@ -50,7 +50,9 @@ export function backendCarriesNestedDepth(backendName: string): boolean {
 export function nestedDepthCodexArgs(backendName: string, childDepth: number): string[] {
   if (backendName !== 'codex') return [];
   if (!Number.isInteger(childDepth) || childDepth < 0) return [];
-  return ['-c', `${CODEX_NESTED_DEPTH_CONFIG_KEY}=${childDepth}`];
+  // 🩸 CODEX-NESTED-DEPTH-QUOTE(2026-10-09): `-c` 값은 TOML 이고 shell_environment_policy.set 은 «문자열» 맵이다.
+  //   맨 정수(`=1`)는 codex 0.159.3 에서 «failed to load bootstrap configuration» 으로 자식을 바로 죽인다 → 따옴표로 문자열.
+  return ['-c', `${CODEX_NESTED_DEPTH_CONFIG_KEY}="${childDepth}"`];
 }
 
 /**

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-wrapper.ts

@@ -69,6 +69,13 @@ if [ $# -lt 1 ] || [ -z "$1" ]; then
 fi
 ROLE=$1
 shift
+# FENCE-LIGHT: only when this host's heartbeat left a lease-cache file and the installed package ships the light fence.
+# No cache file = exactly the CLI path below. The sourced script always exits; returning is a fail-closed error.
+if [ -f "$CONFIG_DIR/hq/lease-cache" ] && [ -f scripts/hq/hq-fence-wrapper.sh ]; then
+  . scripts/hq/hq-fence-wrapper.sh
+  log_line "light fence returned without a decision (role=$ROLE)"
+  exit 1
+fi
 "$BUN" "$ENTRY" --config-dir "$CONFIG_DIR" hq fence --role "$ROLE" -- /bin/sh -c "$*"
 rc=$?
 if [ "$rc" -ne 0 ]; then alert "hq-fence: fence failed (rc=$rc, role=$ROLE)"; fi

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/hq.ts

@@ -14,8 +14,8 @@ import { fenceOutcomeDir, recordFenceOutcome } from './fence-outcomes.js';
 import { promoteHq, proposeHqPromotion, writeOpSeatRequest } from './promote.js';
 import type { HqOpRequestWriter, PromoteResult } from './promote.js';
 import {
-  DEFAULT_TTL_SECONDS, decideAcquire, decideArbiterCheck, decideFence, decideRelease, decideRenew, defaultSshRunner,
-  fileLeaseStore, leaseExpired, parseLease, probeReachable, recordView, serializeLease, sshLeaseStore, sshReachable, localShellRunner,
+  DEFAULT_TTL_SECONDS, LOCAL_LEASE_CACHE_SECONDS, decideAcquire, decideArbiterCheck, decideFence, decideRelease, decideRenew, defaultSshRunner,
+  fileLeaseStore, leaseExpired, parseLease, probeReachable, recordView, serializeLease, serializeLocalLeaseCache, sshLeaseStore, sshReachable, localShellRunner,
   type HostProbe, type LeaseRecord, type LeaseStore, type LocalHqState, type SshRunner,
 } from './lease.js';
 
@@ -163,6 +163,30 @@ function writeLocal(path: string, state: LocalHqState): void {
   renameSync(tmp, path);
 }
 
+/** FENCE-LIGHT host-local hint (`<config>/hq/lease-cache`), not authority: only a successful holder renewal writes it. */
+const leaseCachePath = (r: Resolved): string => join(dirname(r.localPath), 'lease-cache');
+function dropHeartbeatCache(r: Resolved): void {
+  try { rmSync(leaseCachePath(r), { force: true }); }
+  catch (error) { observe(r, 'hq.lease', 'cache-invalidate-failed', { error: String(error).slice(0, 200) }); }
+}
+function writeHeartbeatCache(r: Resolved, record: LeaseRecord): void {
+  const path = leaseCachePath(r);
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const confirmedAt = r.now();
+    const expiresAt = Math.min(confirmedAt + LOCAL_LEASE_CACHE_SECONDS, record.renewedAt + record.ttlSeconds);
+    if (expiresAt <= confirmedAt) return;
+    const tempDir = mkdtempSync(`${path}.`);
+    try {
+      const tmp = join(tempDir, 'cache');
+      writeFileSync(tmp, serializeLocalLeaseCache({ holder: record.holder, generation: record.generation, expiresAt, host: r.me, machine: hostname().replace(/\.local$/, ''), confirmedAt }), { mode: 0o600 });
+      renameSync(tmp, path);
+    } finally { rmSync(tempDir, { recursive: true, force: true }); }
+  } catch (error) {
+    observe(r, 'hq.lease', 'cache-write-failed', { error: String(error).slice(0, 200) });
+  }
+}
+
 /** Highest lease generation this host ever observed (null = never). */
 /** The seen-generation marker this host keeps (hq.seenGenerationFile · default ~/.elanous-hq/seen-generation). */
 export function hqSeenGenerationPath(config: Pick<HqConfig, 'seenGenerationFile'>): string {
@@ -241,6 +265,7 @@ export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: s
   const result = mutate(r, (record, now) => action === 'acquire' ? decideAcquire(record, r.me, now, r.ttl)
     : action === 'renew' ? decideRenew(record, r.me, local.generation, now) : decideRelease(record, r.me, expected));
   noteSeen(r, result.record);
+  if (result.ok) dropHeartbeatCache(r);
   if (result.ok && action !== 'release') writeLocal(r.localPath, { holder: result.record.holder, generation: result.record.generation, confirmedAt: r.now(), ttlSeconds: result.record.ttlSeconds });
   if (result.ok && action === 'release') writeLocal(r.localPath, { ...local, holder: undefined, confirmedAt: undefined });
   observe(r, 'hq.lease', result.ok ? (action === 'acquire' ? 'acquired' : action === 'renew' ? 'renewed' : 'released') : `${action}-refused`,
@@ -255,6 +280,8 @@ export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: s
 export function hqHeartbeat(deps: HqDeps = {}) {
   const r = resolve(deps);
   const local = readLocal(r.localPath);
+  // Never extend a prior positive hint through an unreachable/refused heartbeat.
+  dropHeartbeatCache(r);
   let read: { now: number; raw: string | null };
   try { read = r.store.read(); } catch (error) {
     const standbyUp = local.holder === r.me ? sshReachable(r.standby, r.ssh) : false;
@@ -273,6 +300,7 @@ export function hqHeartbeat(deps: HqDeps = {}) {
     if (renewed.ok) {
       noteSeen(r, renewed.record);
       writeLocal(r.localPath, { holder: r.me, generation: renewed.record.generation, confirmedAt: r.now(), ttlSeconds: renewed.record.ttlSeconds });
+      if (record.renewedAt !== 0 && !leaseExpired(renewed.record, r.now())) writeHeartbeatCache(r, renewed.record);
       observe(r, 'hq.lease', 'renewed', { generation: renewed.record.generation });
       return { outcome: 'renewed' as const, generation: renewed.record.generation };
     }
@@ -282,6 +310,7 @@ export function hqHeartbeat(deps: HqDeps = {}) {
   // Not the holder: report the view, keep the granted generation, stay standby.
   const seen = probeReachable(record.holder, r.probe);
   const reachable = seen.reachable;
+  // FENCE-LIGHT: a standby never writes the cache (the shell fence only fast-paths a fresh «this host holds» line).
   mutate(r, (current) => current ? { ok: true, next: recordView(current, r.me, reachable, read.now) } : { ok: false, reason: 'no lease' });
   if (leaseExpired(record, read.now)) observe(r, 'hq.lease', 'expired-seen', { holder: record.holder, generation: record.generation });
   writeLocal(r.localPath, { holder: record.holder, generation: record.generation, ttlSeconds: record.ttlSeconds });
@@ -365,6 +394,8 @@ export function hqFenceDecision(role: HqFenceRole, deps: HqDeps = {}) {
     failOpen: role !== 'ledger-cli' && r.failOpen.has(role),
     ...(seenGeneration !== null ? { seenGeneration } : {}),
   });
+  // FENCE-LIGHT: any CLI «do not run» on this host retires a lingering fast-path hint at once.
+  if (!decided.run) dropHeartbeatCache(r);
   if (decided.run && record !== 'unreachable' && record) writeLocal(r.localPath, { holder: r.me, generation: record.generation, confirmedAt: r.now(), ttlSeconds: record.ttlSeconds });
   observe(r, 'hq.fence', decided.run ? 'allowed' : 'skipped', { role, reason: decided.reason, holder: decided.holder, generation: decided.generation });
   return decided;

package/src/hq/lease.ts

@@ -36,6 +36,19 @@ export function parseLease(raw: string | null): LeaseRecord | null {
 export const serializeLease = (record: LeaseRecord): string => `${JSON.stringify(record)}\n`;
 export const leaseExpired = (record: LeaseRecord, now: number): boolean => record.renewedAt + record.ttlSeconds < now;
 
+/** Host-local, short-lived shell fence snapshot; never the arbiter's CAS lease ledger. */
+export interface LocalLeaseCache { holder: string; generation: number; expiresAt: number; host: string; machine: string; confirmedAt: number }
+export const LOCAL_LEASE_CACHE_SECONDS = 660; // heartbeat cadence 600s + 60s scheduling slack; still below the 1500s lease TTL
+/** A single whitespace-delimited line so /bin/sh can read it without bun or JSON tools. */
+export function serializeLocalLeaseCache(cache: LocalLeaseCache): string {
+  if (![cache.holder, cache.host, cache.machine].every(value => /^[A-Za-z0-9_.-]+$/.test(value))
+    || !Number.isSafeInteger(cache.generation) || cache.generation < 1
+    || !Number.isSafeInteger(cache.expiresAt) || cache.expiresAt < 1
+    || !Number.isSafeInteger(cache.confirmedAt) || cache.confirmedAt < 1
+    || cache.expiresAt <= cache.confirmedAt || cache.expiresAt - cache.confirmedAt > LOCAL_LEASE_CACHE_SECONDS) throw new Error('invalid local lease cache');
+  return `${cache.holder} ${cache.generation} ${cache.expiresAt} ${cache.host} ${cache.machine} ${cache.confirmedAt}\n`;
+}
+
 /** acquire: only when there is no lease or it has expired; a new holder gets the next generation. */
 export function decideAcquire(record: LeaseRecord | null, me: string, now: number, ttlSeconds = DEFAULT_TTL_SECONDS):
   { ok: true; next: LeaseRecord } | { ok: false; reason: string } {

package/src/hq/seats.ts

@@ -2,13 +2,16 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { runGitCommand } from '../git-fs/runner.js';
+import { runGhCliWithResult, type GhCliResult } from '../git-fs/gh-cli.js';
+import { registeredSeats } from '../seat-address/seat-address.js';
+import { debug } from '../debug/log.js';
 
 type HqSeatRole = 'OP' | 'MK' | 'TC' | 'UX';
 const ROLES: readonly string[] = ['OP', 'MK', 'TC', 'UX'];
 interface HouseLedger {
   home: { kind: 'home'; path: string; source: 'cli-resolved' };
-  // `reclaiming` = the merged tip a `work done` proved before it started removing; it lets an interrupted done resume.
-  sandboxes: Record<string, { kind: 'sandbox'; path: string; owner: HqSeatRole; reclaiming?: string }>;
+  // `reclaiming` records the original work branch tip; checkoutTip is needed if done detached a different branch.
+  sandboxes: Record<string, { kind: 'sandbox'; path: string; owner: HqSeatRole; reclaiming?: string; checkoutTip?: string; checkoutBranch?: string }>;
 }
 
 function hqRoot(home = process.env.HOME): string {
@@ -30,6 +33,26 @@ function repository(root: string): string {
 }
 
 function ledgerPath(root: string): string { return join(root, 'house.json'); }
+
+/** Read-only launch lookup: the registered home and detached seat must exist; never create or refresh a view. */
+export function resolveHqLaunchSeat(role: string, home: string, options: { root?: string } = {}): string {
+  if (!registeredSeats().some(seat => seat.id === role)) throw new Error(`unregistered seat: ${role}`);
+  const root = resolve(options.root ?? hqRoot());
+  const registeredHome = readLedger(root).home.path;
+  if (realpathSync(home) !== realpathSync(registeredHome)) throw new Error(`house.json home mismatch: registered ${registeredHome}; requested ${home}`);
+  const path = join(root, 'seats', role);
+  assertRegisteredWorktree(repository(root), path);
+  const head = runGitCommand(path, ['symbolic-ref', '--quiet', 'HEAD'], { encoding: 'utf8' });
+  if (head.status === 0) throw new Error(`not a detached seat: ${path}`);
+  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');
@@ -110,6 +133,68 @@ function mergedIntoMain(repo: string, commit: string): boolean {
   if (merged.status !== 0 && merged.status !== 1) throw new Error(`cannot verify merge: ${merged.stderr.trim()}`);
   return merged.status === 0;
 }
+
+export type MergedPrProof = { status: 'pr-merged'; number: number } | { status: 'not-merged' | 'unknown' };
+const MERGED_PR_QUERY_LIMIT = 1000;
+
+/** Read-only PR evidence from the HQ mirror's origin, never the caller's current repository. */
+export function proveMergedPr(repo: string, branch: string, tip: string, gh: (args: string[]) => GhCliResult = runGhCliWithResult, base?: string): MergedPrProof {
+  if (!repo || !branch || !tip) return { status: 'unknown' };
+  let result: GhCliResult;
+  try {
+    // Read the unexpanded URL: `git remote get-url` applies url.*.insteadOf, possibly turning a
+    // hosted origin into a local mirror and losing the repository identity gh must query.
+    const origin = git(repo, 'config', '--local', '--get', 'remote.origin.url');
+    const url = /^(?:https?:\/\/|ssh:\/\/)(?:[^@/]+@)?([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(origin);
+    const scp = /^(?:[^@]+@)?([^:/]+):([^/]+)\/([^/]+?)(?:\.git)?$/.exec(origin);
+    if (!url && !scp) return { status: 'unknown' };
+    const target = url ? `${url[1]}/${url[2]}/${url[3]}` : `${scp![1]}/${scp![2]}/${scp![3]}`;
+    result = gh(['pr', 'list', '--state', 'merged', '--head', branch, ...(base ? ['--base', base] : []), '--json', 'number,headRefOid', '--limit', String(MERGED_PR_QUERY_LIMIT), '--repo', target]);
+  } catch { return { status: 'unknown' }; }
+  if (!result.ok || result.maybeTruncated) return { status: 'unknown' };
+  let parsed: unknown;
+  try { parsed = JSON.parse(result.stdout.toString('utf8')); }
+  catch { return { status: 'unknown' }; }
+  if (!Array.isArray(parsed) || !parsed.every((pr): pr is { number: number; headRefOid: string } =>
+    pr !== null && typeof pr === 'object' && Number.isSafeInteger(pr.number) && pr.number > 0
+    && typeof pr.headRefOid === 'string' && pr.headRefOid.length > 0)) return { status: 'unknown' };
+  const matching = parsed.find(pr => pr.headRefOid === tip);
+  return matching ? { status: 'pr-merged', number: matching.number }
+    : { status: parsed.length >= MERGED_PR_QUERY_LIMIT ? 'unknown' : 'not-merged' };
+}
+
+// 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';
+  return treeEqualToMain(repo, tip) ? 'tree-equal' : null;
+}
+
+function judgeLandedTip(repo: string, branch: string, tip: string, gh: (args: string[]) => GhCliResult): boolean {
+  const rule = landedTip(repo, branch, tip, gh);
+  try { debug.log('hq.work', 'done-judged', { branch, tip, rule: rule ?? 'not-merged' }); } catch { /* observation must not change the verdict */ }
+  return rule !== null;
+}
+
+// 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);
+  const changed = runGitCommand(repo, ['diff', '--name-only', '-z', base, tip], { encoding: 'utf8' });
+  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 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.
 function takeLock(lock: string): void {
@@ -231,7 +316,7 @@ export function hqSeat(value: string, options: { root?: string; refresh?: boolea
   });
 }
 
-export function hqWork(action: 'new' | 'done', value: string, nameValue: string, options: { root?: string } = {}): { path: string; outcome: 'created' | 'removed' } {
+export function hqWork(action: 'new' | 'done', value: string, nameValue: string, options: { root?: string; gh?: (args: string[]) => GhCliResult } = {}): { path: string; outcome: 'created' | 'removed' } {
   const role = roleOf(value);
   const name = workName(nameValue);
   const root = resolve(options.root ?? hqRoot());
@@ -289,15 +374,19 @@ export function hqWork(action: 'new' | 'done', value: string, nameValue: string,
       const ref = runGitCommand(repo, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { encoding: 'utf8' });
       if (ref.status !== 0) {
         // Without the branch, the only merge proof is the tip an interrupted done recorded before removing.
-        const recorded = readLedger(root).sandboxes[path]?.reclaiming;
-        if (!recorded || !mergedIntoMain(repo, recorded)) throw new Error(`cannot verify merge: branch ${branch} is missing; house.json entry kept: ${path}`);
+        const recordedEntry = readLedger(root).sandboxes[path];
+        const recorded = recordedEntry?.reclaiming;
+        const checkout = recordedEntry?.checkoutTip;
+        if (!recorded || !judgeLandedTip(repo, branch, recorded, options.gh ?? runGhCliWithResult)
+          || (checkout && (!recordedEntry.checkoutBranch || !judgeLandedTip(repo, recordedEntry.checkoutBranch, checkout, options.gh ?? runGhCliWithResult)))) {
+          throw new Error(`cannot verify merge: branch ${branch} is missing; house.json entry kept: ${path}`);
+        }
         updateLedgerLocked(root, ledger => { delete ledger.sandboxes[path]; });
         removeStaleWorktreeAdmin(repo, own);
         return;
       }
       const tip = ref.stdout.trim();
-      const merged = runGitCommand(repo, ['merge-base', '--is-ancestor', tip, 'refs/remotes/origin/main'], { encoding: 'utf8' });
-      if (merged.status !== 0) throw new Error(merged.status === 1 ? `work is not merged into origin/main: ${branch}` : `cannot verify merge: ${merged.stderr}`);
+      if (!judgeLandedTip(repo, branch, tip, options.gh ?? runGhCliWithResult)) throw new Error(`work is not merged into origin/main: ${branch}`);
       // Same order as a normal done: the entry goes first, so a save that fails again keeps the branch (the proof).
       const entry = readLedger(root).sandboxes[path];
       updateLedgerLocked(root, ledger => { delete ledger.sandboxes[path]; });
@@ -321,34 +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.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 || attached.stdout.trim() !== branch)) throw new Error(`work branch mismatch: ${path}`);
-    const tip = resuming ? entry.reclaiming! : branchTip.stdout.trim();
+    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 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 = 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 (!mergedIntoMain(repo, tip)) throw new Error(`work is not merged into origin/main: ${branch}`);
-    // Removal order keeps every interruption resumable: record the proven tip → detach → hold the work's git
-    // locks → compare-and-delete the branch → remove the worktree → drop the registration last.
+    if (!judgeLandedTip(repo, checkoutBranch, tip, options.gh ?? runGhCliWithResult)) throw new Error(`work is not merged into origin/main: ${checkoutBranch}`);
+    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;
+    // 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: tip }; });
+    updateLedgerLocked(root, ledger => { ledger.sandboxes[path] = { ...entry, reclaiming: ownTip,
+      ...(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, head.status === 0 ? head.stdout.trim() : tip, ''], { encoding: 'utf8' });
-      const reattached = runGitCommand(path, ['symbolic-ref', 'HEAD', ref], { encoding: 'utf8' }).status === 0;
-      // If HEAD could not be re-attached (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: tip };
+      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 || (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); }
@@ -356,10 +464,14 @@ export function hqWork(action: 'new' | 'done', value: string, nameValue: string,
     }
     if (git(path, 'rev-parse', 'HEAD') !== tip) fail('work gained a commit after the merge check');
     if (branchPresent) {
-      const deleted = runGitCommand(repo, ['update-ref', '-d', ref, tip], { encoding: 'utf8' });
+      const deleted = runGitCommand(repo, ['update-ref', '-d', ref, ownTip], { encoding: 'utf8' });
       if (deleted.status !== 0) fail(`work branch moved after the merge check: ${deleted.stderr.trim()}`);
     }
     if (!clean(path)) fail('work changed during done');
+    if (differentBranch) {
+      const current = runGitCommand(repo, ['rev-parse', '--verify', checkoutRef], { encoding: 'utf8' });
+      if (current.status !== 0 || current.stdout.trim() !== tip) fail(`work branch moved after the merge check: ${checkoutBranch}`);
+    }
     // Without --force, git also refuses a worktree that became dirty after the check above.
     const removed = runGitCommand(repo, ['worktree', 'remove', path], { encoding: 'utf8' });
     if (removed.status !== 0) fail(`git worktree remove failed: ${removed.stderr.trim()}`);