elanous 0.2.17 → 0.2.19

package/src/harness/harness-salvage-cli.ts

@@ -0,0 +1,78 @@
+/**
+ * `elanous harness salvage <runId...> [--json]` — 런마다 «PR #n | 수확 가지 <branch> (+a/-b · N files) | 없음 | 모름(<이유>)».
+ * SALVAGE-VISIBLE(0.2.19) — 판정은 `src/self-implement/salvage-branches.ts`, 여기는 배선·출력·관측만.
+ */
+import type { Command } from 'commander';
+import { debug } from '../debug/log.js';
+import { normalizeRunId } from './harness-space.js';
+import { loadFederatedRunLedger } from '../self-implement/run-ledger.js';
+import {
+  decideRunSalvage,
+  findRunSalvageBranches,
+  gitSalvageRunner,
+  listRemoteSalvageRefs,
+  prStateFromLedger,
+  type RunPrState,
+  type RunSalvageVerdict,
+  type SalvageGitRunner,
+} from '../self-implement/salvage-branches.js';
+
+export interface HarnessSalvageDeps {
+  git?: SalvageGitRunner;
+  readPr?: (runId: string) => RunPrState;
+  print?: (line: string) => void;
+}
+
+function defaultReadPr(runId: string): RunPrState {
+  try {
+    return prStateFromLedger(loadFederatedRunLedger(runId, { includeTest: true }));
+  } catch (error) {
+    return { status: 'unknown', reason: `원장 읽기 실패 · ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+/** 여러 런을 ls-remote «한 번»으로 판정한다. PR 이 있는 런은 git 을 더 부르지 않는다. */
+export function runHarnessSalvage(runIds: readonly string[], deps: HarnessSalvageDeps = {}): RunSalvageVerdict[] {
+  const git = deps.git ?? gitSalvageRunner(process.cwd());
+  const readPr = deps.readPr ?? defaultReadPr;
+  let listing: ReturnType<typeof listRemoteSalvageRefs> | undefined;
+  const verdicts: RunSalvageVerdict[] = [];
+  for (const raw of runIds) {
+    const runId = normalizeRunId(raw);
+    const pr = readPr(runId);
+    let verdict: RunSalvageVerdict;
+    if (pr.status === 'pr') {
+      verdict = decideRunSalvage(runId, pr, { status: 'not-checked' });
+    } else {
+      listing ??= listRemoteSalvageRefs(git);
+      verdict = decideRunSalvage(runId, pr, findRunSalvageBranches(runId, git, { listing }));
+    }
+    const top = verdict.salvage.status === 'found' ? verdict.salvage.branches[0] : undefined;
+    debug.log('harness.salvage', 'visible', {
+      runId,
+      outcome: verdict.outcome,
+      branch: top?.branch ?? null,
+      files: top?.diffstat.files ?? null,
+      ...(verdict.pr.status === 'pr' ? { prNumber: verdict.pr.number } : {}),
+      ...(verdict.salvage.status === 'unknown' ? { reason: verdict.salvage.reason } : {}),
+      ...(verdict.pr.status === 'unknown' ? { prReason: verdict.pr.reason } : {}),
+    });
+    verdicts.push(verdict);
+  }
+  return verdicts;
+}
+
+export function installHarnessSalvageCommand(harnessCmd: Command, deps: HarnessSalvageDeps = {}): Command {
+  return harnessCmd
+    .command('salvage')
+    .description('런 → PR | 수확 가지(salvage/*) | 없음 | 모름 — Pod 런이 멈추며 남긴 가지를 보인다')
+    .argument('<runIds...>', '런 id (run-xxxxxxxx-…)')
+    .option('--json', '런마다 { runId, outcome, pr, salvage } 를 JSON 배열로')
+    .action((runIds: string[], opts: { json?: boolean }) => {
+      const print = deps.print ?? ((line: string) => console.log(line));
+      const verdicts = runHarnessSalvage(runIds, deps);
+      if (opts.json) print(JSON.stringify(verdicts.map(({ line: _line, ...rest }) => rest)));
+      else for (const verdict of verdicts) print(verdict.line);
+      if (verdicts.some((verdict) => verdict.outcome === 'unknown')) process.exitCode = 1;
+    });
+}

package/src/harness/harness-worktree-add.ts

@@ -2,6 +2,7 @@ import { createWorktree, type CreateWorktreeResult } from '../git-fs/worktree.js
 import { runGitCommand } from '../git-fs/runner.js';
 import { configuredWorktreeRoot } from '../user-config.js';
 import { debug } from '../debug/log.js';
+import { join, resolve } from 'node:path';
 
 const OWNER_CONFIG_KEY = 'elanous.harness.owner';
 const COMMAND_CONFIG_KEY = 'elanous.harness.command';
@@ -87,8 +88,75 @@ function restoreWorktreeProvenance(worktreePath: string, snapshot: WorktreeConfi
   }
 }
 
+/** Keys that must leave the shared config once `extensions.worktreeConfig` is on (`git help worktree` §CONFIGURATION FILE).
+ *  `core.bare=false` is harmless when shared (linked trees default to non-bare), so only a true value moves. */
+const MAIN_TREE_ONLY_CONFIG_KEYS = ['core.bare', 'core.worktree'] as const;
+
+/** Moves `core.bare=true` / `core.worktree` from `$GIT_COMMON_DIR/config` to `$GIT_COMMON_DIR/config.worktree`.
+ *  Runs every time (also when the extension is already on) and throws before the caller enables the extension.
+ *  Incident 10-07 (HQ-WORKTREE-CONFIG): a shared `core.bare=true` made every linked worktree of a bare repo unusable. */
+/** Values are moved byte-for-byte (a `core.worktree` path may carry edge whitespace), so read them NUL-terminated. */
+function nulTerminatedValue(stdout: unknown, key: string): string {
+  const text = String(stdout ?? '');
+  if (!text.endsWith('\0')) throw new Error(`harness worktree ${key} read failed — git config emitted an unterminated value`);
+  return text.slice(0, -1);
+}
+
+function moveMainTreeOnlyConfig(worktreePath: string): void {
+  const common = gitAt(worktreePath, ['rev-parse', '--git-common-dir']);
+  const commonOut = String(common.stdout ?? '').trim();
+  if (common.status !== 0 || !commonOut) {
+    throw new Error(`harness worktree common git dir lookup failed — ${gitConfigFailure(common)}`);
+  }
+  const commonDir = resolve(worktreePath, commonOut);
+  const shared = join(commonDir, 'config');
+  const perTree = join(commonDir, 'config.worktree');
+  // `null` = absent. Typed reads judge meaning (`yes`/`TRUE` are true); raw reads carry the bytes that move.
+  const readValue = (file: string, key: string, typed: boolean): string | null => {
+    const read = gitAt(worktreePath, ['config', '--file', file, ...(typed ? ['--type=bool'] : []), '--null', '--get', key]);
+    if (read.status === 1) return null;
+    if (read.status !== 0) throw new Error(`harness worktree ${key} read failed (${file}) — ${gitConfigFailure(read)}`);
+    return nulTerminatedValue(read.stdout, key);
+  };
+  for (const key of MAIN_TREE_ONLY_CONFIG_KEYS) {
+    const typed = key === 'core.bare';
+    const meaning = readValue(shared, key, typed);
+    if (meaning === null) continue;
+    if (typed && meaning !== 'true') continue;
+    const raw = typed ? readValue(shared, key, false) : meaning;
+    if (raw === null) throw new Error(`harness worktree shared ${key} vanished during the move`);
+    // A valueless `bare` means true; writing its empty raw form would mean false.
+    const value = typed && raw === '' ? 'true' : raw;
+    // A conflicting per-tree value would flip the main tree once the extension is on — refuse instead of guessing.
+    // Every per-tree value must agree (not just the last one), so a mixed list also fails closed.
+    const existingRead = gitAt(worktreePath, ['config', '--file', perTree, ...(typed ? ['--type=bool'] : []), '--null', '--get-all', key]);
+    if (existingRead.status !== 0 && existingRead.status !== 1) {
+      throw new Error(`harness worktree ${key} read failed (${perTree}) — ${gitConfigFailure(existingRead)}`);
+    }
+    const existingValues = existingRead.status === 0 ? nulTerminatedValue(existingRead.stdout, key).split('\0') : [];
+    if (existingValues.some((existing) => existing !== meaning)) {
+      throw new Error(`harness worktree ${key} conflict — ${shared} has ${JSON.stringify(meaning)} but ${perTree} has ${JSON.stringify(existingValues)}; resolve by hand before enabling extensions.worktreeConfig`);
+    }
+    const existingMeaning = existingValues.length > 0 ? meaning : null;
+    if (existingMeaning === null) {
+      const write = gitAt(worktreePath, ['config', '--file', perTree, key, value]);
+      if (write.status !== 0) throw new Error(`harness worktree ${key} move failed — ${gitConfigFailure(write)}`);
+    }
+    const unset = gitAt(worktreePath, ['config', '--file', shared, '--unset-all', key]);
+    if (unset.status !== 0) throw new Error(`harness worktree shared ${key} unset failed — ${gitConfigFailure(unset)}`);
+    debug.log('harness.worktree', 'core-bare-moved', {
+      key,
+      value,
+      commonDir,
+      perTreeHadValue: existingMeaning !== null,
+      worktreePath,
+    }, { level: 'warn' });
+  }
+}
+
 /** Records the shared worktree-scoped provenance used by both manual and self-implement creation paths. */
 export function recordHarnessWorktreeProvenance(worktreePath: string, provenance: HarnessWorktreeProvenance): void {
+  moveMainTreeOnlyConfig(worktreePath);
   const enable = gitAt(worktreePath, ['config', 'extensions.worktreeConfig', 'true']);
   if (enable.status !== 0) {
     throw new Error(`harness worktree owner declaration failed — ${gitConfigFailure(enable)}`);

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/ledger-write-guard.ts

@@ -1,19 +1,7 @@
-import { realpathSync } from 'node:fs';
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { isAbsolute, relative, sep } from 'node:path';
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
-
-function physicalPath(path: string): string {
-  const absolute = resolve(path);
-  try {
-    return realpathSync(absolute);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    const parent = dirname(absolute);
-    if (parent === absolute) throw error;
-    return resolve(physicalPath(parent), relative(parent, absolute));
-  }
-}
+import { isInsideOpsRoot, physicalPath, testProcessSignal } from '../instance/test-write-guard.js';
 
 /** Refuse a test's write to the production instance, including an explicitly supplied ledger directory. */
 export function refuseProductionLedgerWriteInTest(
@@ -23,11 +11,13 @@ export function refuseProductionLedgerWriteInTest(
   productionRoot = prodInstanceRoot(),
   instanceRoot = effectiveInstanceRoot(),
 ): boolean {
-  if (env.NODE_ENV !== 'test' && !env.ELANOUS_TEST_HOME) return false;
+  if (!testProcessSignal(env, env === process.env ? undefined : '')) return false;
   const target = physicalPath(root);
   const production = physicalPath(productionRoot);
   const withinProduction = relative(production, target);
-  if (withinProduction === '..' || withinProduction.startsWith(`..${sep}`) || isAbsolute(withinProduction)) return false;
+  const outsideHomeRoot = withinProduction === '..' || withinProduction.startsWith(`..${sep}`) || isAbsolute(withinProduction);
+  // The account's real ~/.elanous is production too when a runner redirected HOME (TEST-PROD-LEAK).
+  if (outsideHomeRoot && !isInsideOpsRoot(root)) return false;
   try {
     debug.log('harness.incidents', 'write-refused', { store, root: target, effectiveInstanceRoot: instanceRoot });
   } catch { /* Observation cannot reopen a closed write boundary. */ }

package/src/hq/hq.ts

@@ -108,7 +108,7 @@ function resolve(deps: HqDeps = {}): Resolved {
     ssh,
     probe: deps.probe ?? tailnetProbe(config),
     localPath: deps.localPath ?? join(getElanousConfigDir(), 'hq', 'local.json'),
-    seenPath: deps.seenPath ?? config.seenGenerationFile ?? (deps.localPath ? `${deps.localPath}.seen-generation` : join(homedir(), '.elanous-hq', 'seen-generation')),
+    seenPath: deps.seenPath ?? (deps.localPath && !config.seenGenerationFile ? `${deps.localPath}.seen-generation` : hqSeenGenerationPath(config)),
     now: deps.now ?? (() => Math.floor(Date.now() / 1000)),
     log,
   };
@@ -161,6 +161,11 @@ function writeLocal(path: string, state: LocalHqState): void {
 }
 
 /** 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 {
+  return config.seenGenerationFile ?? join(homedir(), '.elanous-hq', 'seen-generation');
+}
+
 export function readSeenGeneration(path: string): number | null {
   try {
     if (!existsSync(path)) return null;

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' };
+}