elanous 0.2.16 → 0.2.18

package/src/harness/helper-scan.ts

@@ -81,9 +81,16 @@ export function classifyStoppedPr({ body, comments }: { body: string; comments:
     action = '증거 재측 — 인용된 판정 명령을 호스트에서 다시 돌려 결과를 PR 에 남김; 코드 수정 아님';
   } else if (/review-budget/i.test(stopEvidence) || basis === 'must-fix-reported') {
     // Real supervisor bodies (UNCONVERGEABLE · implementation-deficit) carry `classificationBasis: must-fix-reported` instead of the RFC word.
-    if (basis === 'must-fix-reported') signals.push('classificationBasis=must-fix-reported → review-budget');
-    category = 'review-budget';
-    action = latest?.count ? '헬퍼 자식 spawn — must-fix 원문과 기존 시험 설계로 한 라운드' : '하지 않음 — must-fix 0 또는 미관측; 수리 자식 대상 아님';
+    const previous = latest && reviews.find((review) => review.round === latest.round - 1);
+    if (latest && previous && latest.round >= 2 && latest.count > 0 && latest.count >= previous.count) {
+      category = 'review-oscillation';
+      signals.push(`must-fix ${previous.count}→${latest.count} (round ${previous.round}→${latest.round}) → review-oscillation`);
+      action = '헬퍼 자식 spawn — 기존 시험 설계 보존 후 한 라운드';
+    } else {
+      if (basis === 'must-fix-reported') signals.push('classificationBasis=must-fix-reported → review-budget');
+      category = 'review-budget';
+      action = latest?.count ? '헬퍼 자식 spawn — must-fix 원문과 기존 시험 설계로 한 라운드' : '하지 않음 — must-fix 0 또는 미관측; 수리 자식 대상 아님';
+    }
   } else if (/no-progress/i.test(stopEvidence) || basis === 'no-must-fix-without-clean-worktree-or-completed-without-changes') {
     if (basis === 'no-must-fix-without-clean-worktree-or-completed-without-changes') signals.push(`classificationBasis=${basis} → no-progress`);
     category = 'no-progress';

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

@@ -13,6 +13,7 @@
 // an allow flag is ignored and the launch stays refused.
 
 import { debug } from '../debug/log.js';
+import { getUserConfig } from '../user-config.js';
 
 export const ELANOUS_NESTED_DEPTH_ENV = 'ELANOUS_NESTED_DEPTH';
 
@@ -26,7 +27,7 @@ export interface NestedElanousDecision {
   readonly depth: number;
   /** True when depth >= 1 supplied allow and it was ignored. */
   readonly allowIgnored: boolean;
-  readonly reason: 'depth-0' | 'depth-0-allow' | 'depth-unknown' | 'nested-refused' | 'allow-ignored';
+  readonly reason: 'depth-0' | 'depth-0-allow' | 'depth-unknown' | 'nested-refused' | 'allow-ignored' | 'depth-cap';
 }
 
 /** Current process depth from the nested-depth marker. Unset or unreadable = 0 (outer launcher). */
@@ -56,11 +57,25 @@ export function nestedDepthCodexArgs(backendName: string, childDepth: number): s
  * Allow decision. Depth 0 allows only when `allow` is true.
  * Depth >= 1 always refuses; a supplied allow is ignored and logged.
  */
+/** Nested depth cap: explicit value, else `harness.nestedElanousMaxDepth`, else 2. */
+export function resolveNestedDepthCap(maxDepth?: number): number {
+  const configured = maxDepth ?? getUserConfig().harness?.nestedElanousMaxDepth;
+  return typeof configured === 'number' && Number.isSafeInteger(configured) && configured > 0 ? configured : 2;
+}
+
 export function decideNestedElanousLaunch(input: {
   readonly depth: number;
   readonly allow?: boolean;
+  readonly maxDepth?: number;
+  /** False for an ordinary mission spawn that did not request a nested launch — no cap log. */
+  readonly logCap?: boolean;
 }): NestedElanousDecision {
   const depth = Number.isInteger(input.depth) && input.depth >= 0 ? input.depth : 0;
+  const cap = resolveNestedDepthCap(input.maxDepth);
+  if (depth >= cap) {
+    if (input.logCap !== false) debug.log('agent-mission.nested', 'depth-cap', { depth, cap });
+    return { allowed: false, depth, allowIgnored: input.allow === true, reason: 'depth-cap' };
+  }
   if (depth >= 1) {
     if (input.allow === true) {
       debug.log('agent-mission.nested', 'allow-ignored', { depth });
@@ -101,14 +116,18 @@ export function gateNestedElanousLaunch(input: {
   readonly nestedLaunchRequested: boolean;
   readonly allow?: boolean;
   readonly configAllow?: boolean;
+  readonly maxDepth?: number;
 }): NestedElanousDecision {
   const depth = Number.isInteger(input.depth) && input.depth >= 0 ? input.depth : 0;
+  const allow = input.nestedLaunchRequested && (input.allow === true || (depth === 0 && input.configAllow === true));
   if (!input.nestedLaunchRequested) {
-    return decideNestedElanousLaunch({ depth, allow: false });
+    return decideNestedElanousLaunch({ depth, allow: false, logCap: false, ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }) });
   }
   if (!backendCarriesNestedDepth(input.backendName)) {
+    // The depth-unknown refusal stands; reaching the cap is still recorded.
+    const cap = resolveNestedDepthCap(input.maxDepth);
+    if (depth >= cap) debug.log('agent-mission.nested', 'depth-cap', { depth, cap, backend: input.backendName });
     return { allowed: false, depth, allowIgnored: false, reason: 'depth-unknown' };
   }
-  const allow = input.allow === true || (depth === 0 && input.configAllow === true);
-  return decideNestedElanousLaunch({ depth, allow });
+  return decideNestedElanousLaunch({ depth, allow, ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }) });
 }

package/src/hq/fence-wrapper.ts

@@ -0,0 +1,123 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, constants, copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createPatch } from 'diff';
+
+const quote = (value: string): string => `'${value.replaceAll("'", "'\"'\"'")}'`;
+
+/** Only the installed entrypoint runs the fence; never use a checkout as a fallback.
+ * Arbiter (cloud-vm) outage retains the current lease and forbids promotion;
+ * this wrapper does not change the fence's lease or promotion decisions.
+ * cron runs with PATH=/usr/bin:/bin, so bun is baked in as an absolute path (OP 10-06 NO-GO). */
+export function renderHqFenceWrapper({ entry, configDir, bun, logFile }: { entry: string; configDir: string; bun: string; logFile?: string }): string {
+  if (!isAbsolute(bun)) throw new Error(`hq-fence: bun must be an absolute path: ${bun}`);
+  const log = logFile ?? join(configDir, 'logs', 'hq-fence.log');
+  return `#!/bin/sh
+# Arbiter (cloud-vm) outage: retain the lease, do not promote; hq fence owns that decision.
+ENTRY=${quote(entry)}
+CONFIG_DIR=${quote(configDir)}
+# cron has no PATH for bun — the absolute path was resolved when this wrapper was installed.
+BUN=${quote(bun)}
+LOG=${quote(log)}
+# Last resort when no alert path works: one line in a log file, no bun needed.
+log_line() {
+  mkdir -p "$(dirname "$LOG")" 2>/dev/null
+  printf '%s %s\\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" >> "$LOG" 2>/dev/null
+}
+# The alert goes through the same installed entry; PATH \`elanous\` is only a fallback when the entry itself is missing.
+# Alert bun: the installed one first, then usual absolute install locations (still no PATH lookup).
+alert_bun() {
+  for b in "$BUN" "$HOME/.bun/bin/bun" /opt/homebrew/bin/bun /usr/local/bin/bun; do
+    if [ -x "$b" ]; then echo "$b"; return 0; fi
+  done
+  return 1
+}
+alert() {
+  if [ -f "$ENTRY" ] && AB=$(alert_bun); then
+    if "$AB" "$ENTRY" --config-dir "$CONFIG_DIR" hq fence-wrapper alert "$1"; then return 0; fi
+    echo "hq-fence: owner alert failed: $1" >&2
+    log_line "owner alert failed: $1"
+    return 0
+  fi
+  if command -v elanous >/dev/null 2>&1 && elanous --config-dir "$CONFIG_DIR" hq fence-wrapper alert "$1"; then return 0; fi
+  echo "hq-fence: owner alert failed: $1" >&2
+  log_line "owner alert failed: $1"
+}
+if [ ! -x "$BUN" ]; then
+  echo "hq-fence: bun missing or not executable: $BUN" >&2
+  # Exactly one line on disk; the alert is tried only through an absolute fallback bun (never PATH).
+  log_line "bun missing or not executable: $BUN (rc=127)"
+  if [ -f "$ENTRY" ] && AB=$(alert_bun); then
+    "$AB" "$ENTRY" --config-dir "$CONFIG_DIR" hq fence-wrapper alert "hq-fence: bun missing or not executable: $BUN (rc=127)" || echo "hq-fence: owner alert failed (fallback bun $AB)" >&2
+  fi
+  exit 127
+fi
+if [ ! -f "$ENTRY" ] || [ ! -r "$ENTRY" ]; then
+  echo "hq-fence: installed entrypoint missing: $ENTRY" >&2
+  alert "hq-fence: installed entrypoint missing: $ENTRY"
+  exit 1
+fi
+cd "$(dirname "$ENTRY")/.." || { alert "hq-fence: installed directory missing"; exit 1; }
+if [ $# -lt 1 ] || [ -z "$1" ]; then
+  echo "hq-fence: role required" >&2
+  alert "hq-fence: role required"
+  exit 2
+fi
+ROLE=$1
+shift
+"$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
+exit "$rc"
+`;
+}
+
+/** Absolute bun for the wrapper: this process when it is bun, else `command -v bun` resolved now (install time). */
+export function resolveHqFenceBun(deps: { isBun?: boolean; execPath?: string; lookup?: () => string } = {}): string {
+  const isBun = deps.isBun ?? typeof process.versions.bun === 'string';
+  const candidate = isBun
+    ? (deps.execPath ?? process.execPath)
+    : (deps.lookup ?? (() => spawnSync('/bin/sh', ['-c', 'command -v bun'], { encoding: 'utf8' }).stdout ?? ''))().trim();
+  if (!candidate || !isAbsolute(candidate)) throw new Error(`hq-fence: cannot resolve an absolute bun path (got ${JSON.stringify(candidate)})`);
+  return realpathSync(candidate);
+}
+
+export function installedHqFenceEntry(home = homedir()): string {
+  return join(home, '.local', 'share', 'elanous', 'current', 'node_modules', 'elanous', 'bin', 'elanous.mjs');
+}
+
+/** Literal \`cd <path>\` lines only — a worktree path built from a variable is not detected. */
+export function repositoryWorktreeCdWarning(body: string): string | undefined {
+  return body.split('\n').some(line => /^\s*cd\s+(?:['"]?[^\s'";]+\/)?(?:wt-[^\s'";]+|[^\s'";]+\/repo\.worktrees\/[^\s'";]+)(?:['"]?\s*(?:&&|\|\||;|#|$))/.test(line))
+    ? 'hq fence-audit: warning — hq-fence wrapper cd targets a repository worktree' : undefined;
+}
+
+export function installHqFenceWrapper(configDir: string, body: string, yes: boolean, deps: {
+  now?: () => Date;
+} = {}): { path: string; preview: string; backup?: string } {
+  const path = join(configDir, 'bin', 'hq-fence');
+  let present = false;
+  try { present = !!lstatSync(path); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  if (present && !lstatSync(path).isFile()) throw new Error(`hq-fence: refusing non-regular wrapper: ${path}`);
+  const old = present ? readFileSync(path, 'utf8') : undefined;
+  const preview = `hq-fence proposed: ${path}\n${body}\n${createPatch(path, old ?? '', body, 'existing', 'proposed')}`;
+  if (!yes) return { path, preview };
+  let backup: string | undefined;
+  if (present) {
+    const backups = join(configDir, 'backups');
+    mkdirSync(backups, { recursive: true });
+    const stamp = (deps.now ?? (() => new Date()))().toISOString().replaceAll(':', '-');
+    backup = join(backups, `hq-fence.${stamp}`);
+    copyFileSync(path, backup, constants.COPYFILE_EXCL);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const tempDir = mkdtempSync(join(dirname(path), '.hq-fence-'));
+  try {
+    const temp = join(tempDir, 'hq-fence');
+    writeFileSync(temp, body, { flag: 'wx', mode: 0o755 });
+    chmodSync(temp, 0o755);
+    renameSync(temp, path);
+  } finally { rmSync(tempDir, { recursive: true, force: true }); }
+  return { path, preview, ...(backup ? { backup } : {}) };
+}

package/src/hq/hq.ts

@@ -205,6 +205,14 @@ function mutate(r: Resolved, decide: (record: LeaseRecord | null, now: number) =
   return { ok: false, reason: 'lost the race five times', record: null };
 }
 
+/** Snapshot for read-only consumers: never advances the seen-generation marker or CASes the arbiter. */
+export function readHqLease(deps: HqDeps = {}) {
+  const { store } = resolve(deps);
+  const { now, raw } = store.read();
+  const record = parseLease(raw);
+  return { record, ageSeconds: record ? now - record.renewedAt : null, expired: record ? leaseExpired(record, now) : null };
+}
+
 export type LeaseAction = 'acquire' | 'renew' | 'status' | 'release';
 export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: string; expectedHolder?: string; expectedGeneration?: number } = {}) {
   const r0 = resolve(deps);

package/src/hq/seats.ts

@@ -0,0 +1,369 @@
+// HQ seat folders are disposable views of one bare repository. No scheduler or human checkout is modified here.
+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';
+
+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 }>;
+}
+
+function hqRoot(home = process.env.HOME): string {
+  if (!home) throw new Error('HOME is required (or pass --root)');
+  return join(home, 'elanous-hq');
+}
+
+// A first fetch or checkout of the real monorepo takes minutes; only fetch gets the long ceiling.
+function git(cwd: string, ...args: string[]): string {
+  const result = runGitCommand(cwd, args, { encoding: 'utf8', timeout: args.includes('fetch') ? 1_800_000 : 600_000 });
+  if (result.status !== 0) throw new Error(`git ${args.join(' ')}: ${result.stderr.trim() || `exit ${result.status}`}`);
+  return result.stdout.trim();
+}
+
+function repository(root: string): string {
+  const repo = join(root, 'repo.git');
+  if (git(repo, 'rev-parse', '--is-bare-repository') !== 'true') throw new Error(`not a bare repository: ${repo}`);
+  return repo;
+}
+
+function ledgerPath(root: string): string { return join(root, 'house.json'); }
+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');
+  return ledger;
+}
+function saveLedger(root: string, ledger: HouseLedger): void {
+  const path = ledgerPath(root);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  try { renameSync(tmp, path); }
+  catch (error) { rmSync(tmp, { force: true }); throw error; }
+}
+// The lock covers the read as well as the atomic rename: a rename alone cannot prevent lost updates.
+// It also serializes repo.git worktree/branch mutations: the git runner retries lock contention, and a
+// retried `worktree add -b` that already created its branch fails with "branch already exists".
+function withLedgerLock<T>(root: string, update: () => T, waitMs = 120_000): T {
+  const lock = `${ledgerPath(root)}.lock`;
+  const deadline = Date.now() + waitMs;
+  while (true) {
+    try { mkdirSync(lock); break; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw new Error(`house.json lock timed out: ${lock}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+  try { return update(); }
+  finally { rmdirSync(lock); }
+}
+/** Caller must hold the ledger lock. */
+function updateLedgerLocked(root: string, update: (ledger: HouseLedger) => void): void {
+  const ledger = readLedger(root);
+  update(ledger);
+  saveLedger(root, ledger);
+}
+function roleOf(value: string): HqSeatRole {
+  if (!ROLES.includes(value)) throw new Error(`invalid seat role: ${value} (OP|MK|TC|UX)`);
+  return value as HqSeatRole;
+}
+function workName(name: string): string {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) throw new Error(`invalid work name: ${name}`);
+  return name;
+}
+function clean(path: string): boolean { return git(path, 'status', '--porcelain') === ''; }
+function assertRegisteredWorktree(repo: string, path: string): void {
+  // The path itself must be the registered worktree: a symlink to another registered worktree
+  // (e.g. seats/TC -> work/TC-fix1) would otherwise pass and let a refresh detach that work.
+  if (lstatSync(path).isSymbolicLink()) throw new Error(`not a worktree of ${repo}: ${path} (symlink)`);
+  const own = join(realpathSync(dirname(path)), basename(path));
+  const entries = git(repo, 'worktree', 'list', '--porcelain').split('\n');
+  const registered = entries.some(line => line.startsWith('worktree ') && line.slice(9) === own);
+  if (!registered) throw new Error(`not a worktree of ${repo}: ${path}`);
+  if (realpathSync(git(path, 'rev-parse', '--git-common-dir')) !== realpathSync(repo)) {
+    throw new Error(`not a worktree of ${repo}: ${path}`);
+  }
+}
+const SANDBOX_IGNORE = '/.elanous-test/';
+// The sandbox is filled by ordinary work, so every view of repo.git ignores it: `status` stays clean and
+// `worktree remove` (no --force) deletes it with the worktree instead of refusing a merged work.
+function ensureSandboxIgnored(repo: string): void {
+  const exclude = join(repo, 'info', 'exclude');
+  const current = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+  if (current.split('\n').includes(SANDBOX_IGNORE)) return;
+  mkdirSync(join(repo, 'info'), { recursive: true });
+  writeFileSync(exclude, `${current}${current && !current.endsWith('\n') ? '\n' : ''}${SANDBOX_IGNORE}\n`);
+}
+// A local relative origin (`../remote.git`) is relative to the calling checkout, not to repo.git. Git itself
+// resolves it from the checkout's top level even when run from a subdirectory, so the same base is used here.
+function callerOrigin(): string {
+  const origin = git(process.cwd(), 'remote', 'get-url', 'origin');
+  const url = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(origin);
+  const scpLike = /^[^/]*:/.test(origin);
+  if (url || scpLike || isAbsolute(origin)) return origin;
+  return resolve(git(process.cwd(), 'rev-parse', '--show-toplevel'), origin);
+}
+function mergedIntoMain(repo: string, commit: string): boolean {
+  const merged = runGitCommand(repo, ['merge-base', '--is-ancestor', commit, 'refs/remotes/origin/main'], { encoding: 'utf8' });
+  if (merged.status !== 0 && merged.status !== 1) throw new Error(`cannot verify merge: ${merged.stderr.trim()}`);
+  return merged.status === 0;
+}
+// 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 {
+  try { writeFileSync(lock, `hq-done ${process.pid}\n`, { flag: 'wx' }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    let content = '';
+    try { content = readFileSync(lock, 'utf8').trim(); } catch { /* gone or unreadable: report as held */ }
+    const owner = /^hq-done (\d+)$/.exec(content);
+    if (owner && !processAlive(Number(owner[1]))) throw new Error(`stale lock from a stopped hq work done (pid ${owner[1]}): remove ${lock} and rerun`);
+    throw error;
+  }
+}
+function processAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+// Scoped `worktree prune`: drop only the admin entry whose checkout is `path` and is already gone.
+function removeStaleWorktreeAdmin(repo: string, path: string): void {
+  const admins = join(repo, 'worktrees');
+  if (!existsSync(admins) || existsSync(path)) return;
+  for (const name of readdirSync(admins)) {
+    const gitdir = join(admins, name, 'gitdir');
+    if (existsSync(gitdir) && readFileSync(gitdir, 'utf8').trim() === join(path, '.git')) rmSync(join(admins, name), { recursive: true, force: true });
+  }
+}
+function quoteShell(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+/** Origin is read from the calling checkout; nothing in that checkout is moved or reconfigured. */
+export function hqInit(options: { root?: string; home?: string } = {}): { root: string; created: boolean; cron: string } {
+  const root = resolve(options.root ?? hqRoot());
+  const repo = join(root, 'repo.git');
+  if (!options.home) throw new Error('resolved home house is required to register house.json');
+  mkdirSync(options.home, { recursive: true });
+  const home = realpathSync(options.home);
+  mkdirSync(root, { recursive: true });
+  // Concurrent inits serialize here: the repo.git setup and the first house.json registration are both
+  // decided under the ledger lock, so neither side can overwrite the other or miss a home mismatch.
+  const created = withLedgerLock(root, () => {
+    if (existsSync(ledgerPath(root))) {
+      const registered = readLedger(root).home.path;
+      if (registered !== home) throw new Error(`house.json home mismatch: registered ${registered}; requested ${home}`);
+    }
+    const fresh = !existsSync(repo);
+    if (fresh) {
+      const source = callerOrigin();
+      git(root, 'init', '--bare', repo);
+      git(repo, 'remote', 'add', 'origin', source);
+    }
+    repository(root);
+    if (!fresh) {
+      // An existing mirror must be of the repository init is run for; never re-point or reuse another one.
+      const mirrored = runGitCommand(repo, ['remote', 'get-url', 'origin'], { encoding: 'utf8' });
+      const caller = callerOrigin();
+      if (mirrored.status === 0 && mirrored.stdout.trim() !== caller) throw new Error(`repo.git mirrors ${mirrored.stdout.trim()}, not ${caller}; refusing to reuse ${root}`);
+    }
+    // An interrupted first fetch leaves a bare repository but no origin/main. Finish it on retry.
+    const remote = runGitCommand(repo, ['remote', 'get-url', 'origin'], { encoding: 'utf8' });
+    if (remote.status !== 0) {
+      // Only an empty, just-initialized repo.git (an init stopped before `remote add`) is finished here.
+      if (git(repo, 'for-each-ref') !== '' || existsSync(join(repo, 'worktrees'))) throw new Error(`repo.git has no origin but is not empty; refusing to adopt ${repo}`);
+      const source = callerOrigin();
+      git(repo, 'remote', 'add', 'origin', source);
+    }
+    const main = runGitCommand(repo, ['rev-parse', '--verify', 'refs/remotes/origin/main'], { encoding: 'utf8' });
+    if (fresh || remote.status !== 0 || main.status !== 0) {
+      git(repo, 'config', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*');
+      git(repo, 'fetch', 'origin');
+    }
+    git(repo, 'rev-parse', '--verify', 'refs/remotes/origin/main');
+    if (!existsSync(ledgerPath(root))) {
+      saveLedger(root, { home: { kind: 'home', path: home, source: 'cli-resolved' }, sandboxes: {} });
+    }
+    return fresh;
+  }, 2_100_000); // longer than the 30-minute first fetch, so a concurrent init reaches the home check
+  // Print only: OP installs the line. Only existing role views can be refreshed; init never creates seats.
+  // cron runs with a minimal PATH, so the line names this runtime and CLI entry by absolute path.
+  const cli = [process.execPath, process.argv[1]].filter((part): part is string => Boolean(part)).map(part => quoteShell(resolve(part))).join(' ');
+  const script = `git --git-dir=${quoteShell(repo)} fetch origin && ${ROLES.map(role => `( [ ! -d ${quoteShell(join(root, 'seats', role))} ] || ${cli} hq seat ${role} --refresh --root ${quoteShell(root)} )`).join(' && ')}`;
+  const cron = `*/5 * * * * ${script}`;
+  return { root, created, cron };
+}
+
+export function hqSeat(value: string, options: { root?: string; refresh?: boolean } = {}): { path: string; outcome: 'created' | 'unchanged' | 'refreshed' | 'dirty' } {
+  const role = roleOf(value);
+  const root = resolve(options.root ?? hqRoot());
+  const repo = repository(root);
+  readLedger(root);
+  const path = join(root, 'seats', role);
+  // A new seat starts from the current origin/main, not from whatever the mirror last fetched.
+  if (!existsSync(path)) git(repo, 'fetch', 'origin');
+  const created = withLedgerLock(root, () => {
+    if (existsSync(path)) return false;
+    mkdirSync(join(root, 'seats'), { recursive: true });
+    // A seat folder deleted by hand leaves its git registration behind; drop only that one so the seat is recreated.
+    removeStaleWorktreeAdmin(repo, join(realpathSync(join(root, 'seats')), role));
+    git(repo, 'worktree', 'add', '--detach', path, 'refs/remotes/origin/main');
+    return true;
+  });
+  if (created) return { path, outcome: 'created' };
+  // Refuse an unrelated checkout even when it is clean; do not touch its HEAD.
+  assertRegisteredWorktree(repo, path);
+  // Seats are always detached; a worktree on a branch here (e.g. a work moved into seats/) is someone's work.
+  const onBranch = runGitCommand(path, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { encoding: 'utf8' });
+  if (onBranch.status === 0) throw new Error(`not a seat: ${path} is on branch ${onBranch.stdout.trim()}; refusing to touch it`);
+  // A dirty seat must be byte-for-byte untouched, including its detached HEAD.
+  if (options.refresh && !clean(path)) return { path, outcome: 'dirty' };
+  if (!options.refresh) return { path, outcome: 'unchanged' };
+  git(repo, 'fetch', 'origin');
+  // Concurrent refreshes of one seat (cron and a person) serialize on the house lock; each re-checks first.
+  return withLedgerLock(root, () => {
+    assertRegisteredWorktree(repo, path);
+    if (runGitCommand(path, ['symbolic-ref', '--quiet', 'HEAD'], { encoding: 'utf8' }).status === 0) throw new Error(`not a seat: ${path} is on a branch; refusing to touch it`);
+    if (!clean(path)) return { path, outcome: 'dirty' as const };
+    // Commits made on the detached seat are not on origin/main; moving HEAD would orphan them. Treat as dirty.
+    if (!mergedIntoMain(repo, git(path, 'rev-parse', 'HEAD'))) return { path, outcome: 'dirty' as const };
+    git(path, 'checkout', '--detach', 'refs/remotes/origin/main');
+    return { path, outcome: 'refreshed' as const };
+  });
+}
+
+export function hqWork(action: 'new' | 'done', value: string, nameValue: string, options: { root?: string } = {}): { path: string; outcome: 'created' | 'removed' } {
+  const role = roleOf(value);
+  const name = workName(nameValue);
+  const root = resolve(options.root ?? hqRoot());
+  const repo = repository(root);
+  readLedger(root);
+  const branch = `work/${role}-${name}`;
+  const path = join(root, 'work', `${role}-${name}`);
+  if (action === 'new') {
+    if (existsSync(path)) throw new Error(`work already exists: ${path}`);
+    // fetch stays outside the lock: it only moves remote-tracking refs, is idempotent and lock-retried, and the
+    // cron line runs it unlocked anyway. Branch, worktree and ledger changes below are all under the lock.
+    git(repo, 'fetch', 'origin');
+    withLedgerLock(root, () => {
+      if (existsSync(path)) throw new Error(`work already exists: ${path}`);
+      mkdirSync(join(root, 'work'), { recursive: true });
+      ensureSandboxIgnored(repo);
+      const base = git(repo, 'rev-parse', '--verify', 'refs/remotes/origin/main');
+      git(repo, 'worktree', 'add', '-b', branch, path, base);
+      try {
+        const sandbox = join(path, '.elanous-test');
+        mkdirSync(sandbox);
+        updateLedgerLocked(root, ledger => {
+          ledger.sandboxes[path] = { kind: 'sandbox', path: realpathSync(sandbox), owner: role };
+        });
+      } catch (error) {
+        // Roll back only a work that is still exactly what was just created (clean, at base, branch at base),
+        // without --force and with a compare-and-delete; anything a hook or another writer added is kept.
+        let untouched = false;
+        // `--ignored` also sees files in the (ignored) sandbox; only the empty sandbox dir we made is invisible to it.
+        try { untouched = git(path, 'rev-parse', '--verify', 'HEAD') === base && git(path, 'status', '--porcelain', '--ignored') === ''; } catch { /* unreadable: keep it */ }
+        const removed = untouched ? runGitCommand(repo, ['worktree', 'remove', path], { encoding: 'utf8' }) : undefined;
+        const unbranched = removed?.status === 0 ? runGitCommand(repo, ['update-ref', '-d', `refs/heads/${branch}`, base], { encoding: 'utf8' }) : undefined;
+        const rolledBack = !untouched ? `work kept: it changed after creation: ${path}`
+          : removed?.status !== 0 ? `work kept: ${removed?.stderr.trim()}`
+          : unbranched?.status !== 0 ? `rollback incomplete; branch kept: ${unbranched?.stderr.trim()}`
+          : 'rolled back';
+        throw new Error(`work registration failed (${rolledBack}): ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+    return { path, outcome: 'created' };
+  }
+  git(repo, 'fetch', 'origin');
+  withLedgerLock(root, () => {
+    if (!existsSync(path)) {
+      // Reconcile a done that removed the worktree but failed before the ledger or branch caught up.
+      if (!readLedger(root).sandboxes[path]) throw new Error(`work does not exist: ${path}`);
+      // A moved worktree (`git worktree move`) is still live work on this branch: never reclaim it from here.
+      // Only this work's own stale registration is cleaned below; other (maybe briefly missing) worktrees are left.
+      const own = join(existsSync(dirname(path)) ? realpathSync(dirname(path)) : dirname(path), basename(path));
+      const elsewhere = git(repo, 'worktree', 'list', '--porcelain').split('\n\n')
+        .filter(block => block.split('\n').includes(`branch refs/heads/${branch}`))
+        .map(block => block.split('\n')[0]!.slice(9))
+        .find(location => location !== own);
+      if (elsewhere) throw new Error(`work branch ${branch} is checked out at ${elsewhere}; refusing to reclaim ${path}`);
+      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}`);
+        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}`);
+      // 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]; });
+      const deleted = runGitCommand(repo, ['update-ref', '-d', `refs/heads/${branch}`, tip], { encoding: 'utf8' });
+      if (deleted.status !== 0) {
+        // The branch moved after the merge check: put the registration back so done can be retried.
+        updateLedgerLocked(root, ledger => { ledger.sandboxes[path] = entry; });
+        throw new Error(`work branch moved after the merge check; registration kept: ${branch}: ${deleted.stderr.trim()}`);
+      }
+      removeStaleWorktreeAdmin(repo, own);
+      return;
+    }
+    // Only work that `hq work new` registered is reclaimed; a hand-made worktree at the same path is not ours.
+    const entry = readLedger(root).sandboxes[path];
+    if (entry?.owner !== role) throw new Error(`work is not registered in house.json; refusing to remove: ${path}`);
+    assertRegisteredWorktree(repo, path);
+    if (!clean(path)) throw new Error(`work is dirty; refusing to remove: ${path}`);
+    const ref = `refs/heads/${branch}`;
+    const attached = runGitCommand(path, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { encoding: 'utf8' });
+    const branchTip = runGitCommand(repo, ['rev-parse', '--verify', '--quiet', ref], { encoding: 'utf8' });
+    // 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
+      && (!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();
+    // 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.
+    // 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 }; });
+    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 };
+      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');
+    for (const name of ['HEAD.lock', 'index.lock']) {
+      const lock = join(admin, name);
+      try { takeLock(lock); held.push(lock); }
+      catch (error) { fail(`work is busy (another git process holds ${name}): ${error instanceof Error ? error.message : String(error)}`); }
+    }
+    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' });
+      if (deleted.status !== 0) fail(`work branch moved after the merge check: ${deleted.stderr.trim()}`);
+    }
+    if (!clean(path)) fail('work changed during done');
+    // 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()}`);
+    updateLedgerLocked(root, ledger => { delete ledger.sandboxes[path]; });
+  });
+  return { path, outcome: 'removed' };
+}