elanous 0.2.17 → 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/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' };
+}

package/src/index.ts

@@ -74,6 +74,7 @@ import { registerModelWatchCommand } from './cli/model-watch-cli.js';
 import { registerIntakeCommands } from './cli/intake-cli.js';
 import { registerTasksCommands } from './cli/tasks-cli.js';
 import { registerBriefCommands } from './cli/brief-cli.js';
+import { registerNotifyCommand } from './cli/notify-cli.js';
 import { registerLabelsCommands } from './cli/labels-cli.js';
 import { registerMsgCommands } from './cli/msg-cli.js';
 import { registerDoctorCommand } from './cli/doctor-cli.js';
@@ -135,6 +136,7 @@ import type { ReviewResult } from './agent-substrate/pr-reviewer.js';
 import type { ReviewVerdict } from './agent-mission/review-loop.js';
 import type { SyncMode } from './types.js';
 import { runOnboarding, runOnboardingStep, runOnboardingNonInteractive, needsOnboarding, needsFirstRun, handleOnboardingRefusal, type OnboardingStepId } from './onboarding.js';
+import { firstChatGate } from './onboarding/first-chat-gate.js';
 import {
   getUserConfig, reloadUserConfig, userConfigPath, saveUserConfig,
   backupUserConfig, backupConfigPath, addRotationEntry, type RotationEntry,
@@ -888,6 +890,7 @@ registerLiveCommands(program);
 registerResearchCommand(program);
 registerReleaseCommands(program);
 registerKnowCommand(program);
+registerNotifyCommand(program);
 registerFreezeCommands(program);
 registerFlowCommands(program);
 // HQ-HB · HQ-FENCE (10-04): one writer across mbp · node-b · cloud-vm — lease on the arbiter, 2-of-3 quorum, generation fencing.
@@ -985,6 +988,37 @@ hqCmd.command('seen').description('이 호스트가 본 가장 높은 임대 세
     process.exitCode = result.seen ? 0 : 3;
   });
 registerHqMovePlanCommand(hqCmd);
+hqCmd.command('init').description('한 저장소의 bare 미러와 집 원장을 만들고 5분 fetch 크론 줄만 출력')
+  .option('--root <dir>', 'HQ 폴더 (기본 ~/elanous-hq)')
+  .action(async (opts: { root?: string }) => {
+    try {
+      const { hqInit } = await import('./hq/seats.js');
+      const { getElanousConfigDir } = await import('./elanous-config-dir.js');
+      const result = hqInit({ ...opts, home: getElanousConfigDir() });
+      console.log(`hq init: ${result.created ? 'created' : 'already exists'} ${result.root}\n# OP installs this line; nothing was installed:\n${result.cron}`);
+    } catch (error) { console.error(`hq init: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
+  });
+hqCmd.command('seat <role>').description('OP|MK|TC|UX 자리 워크트리 (깨끗할 때만 갱신)')
+  .option('--refresh', 'origin/main으로 깨끗한 자리만 최신화')
+  .option('--root <dir>', 'HQ 폴더')
+  .action(async (role: string, opts: { refresh?: boolean; root?: string }) => {
+    try {
+      const { hqSeat } = await import('./hq/seats.js');
+      const result = hqSeat(role, opts);
+      if (result.outcome === 'dirty') console.warn(`hq seat ${role}: dirty — refresh skipped; move edits to hq work new`);
+      else console.log(`hq seat ${role}: ${result.outcome} ${result.path}`);
+    } catch (error) { console.error(`hq seat: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
+  });
+const hqWorkCmd = hqCmd.command('work').description('고칠 때만 작업 워크트리를 만들고 병합 후 회수');
+for (const action of ['new', 'done'] as const) hqWorkCmd.command(`${action} <role> <name>`)
+  .option('--root <dir>', 'HQ 폴더')
+  .action(async (role: string, name: string, opts: { root?: string }) => {
+    try {
+      const { hqWork } = await import('./hq/seats.js');
+      const result = hqWork(action, role, name, opts);
+      console.log(`hq work ${action}: ${result.outcome} ${result.path}`);
+    } catch (error) { console.error(`hq work ${action}: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
+  });
 const fenceWrapperCmd = hqCmd.command('fence-wrapper').description('설치본 HQ 울타리 크론 래퍼');
 fenceWrapperCmd.command('install').description('래퍼 제안 또는 백업 후 원자적 설치')
   .option('--dry-run', '변경 내용만 출력 (기본)')
@@ -1042,6 +1076,40 @@ hqCmd.command('fence').description('이 호스트가 임대를 쥐었을 때만
   });
 const seatCmd = program.command('seat').description('분배된 자리의 하루 루프와 보고');
 registerSeatRequestsCommands(seatCmd);
+seatCmd.command('asks').description('최근 CTO 되묻기 왕복과 10분 판정')
+  .option('--since <duration>', '조회 창 (예: 24h)', '24h')
+  .option('--json', 'JSON 출력')
+  .action(async (opts: { since: string; json?: boolean }) => {
+    try {
+      const duration = /^(\d+)([mhd])$/.exec(opts.since);
+      if (!duration || !Number.isSafeInteger(Number(duration[1]))) throw new Error('--since: 24h, 30m, 7d 형식 필요');
+      const ms = Number(duration[1]) * ({ m: 60_000, h: 3_600_000, d: 86_400_000 }[duration[2]!] ?? 0);
+      if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error('--since: 양의 시간 필요');
+      const { defaultMsgStorePath } = await import('./msg/msg-store.js');
+      const path = defaultMsgStorePath();
+      if (!(await import('node:fs')).existsSync(path)) {
+        if (opts.json) await writeStdoutJson('[]\n');
+        else console.log(`원장 없음 — ${path}`);
+        return;
+      }
+      const { listSeatAskRoundTrips } = await import('./seat-dispatch/seat-ask.js');
+      const now = Date.now();
+      const rows = listSeatAskRoundTrips({ since: now - ms, now });
+      if (!rows.length) {
+        if (opts.json) await writeStdoutJson('[]\n');
+        else console.log('이 창에 되묻기 0건');
+        return;
+      }
+      if (opts.json) { await writeStdoutJson(`${JSON.stringify(rows)}\n`); return; }
+      const clock = (value: number | null) => value === null ? '-' : new Intl.DateTimeFormat('ko-KR', {
+        timeZone: 'Asia/Seoul', hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+      }).format(value);
+      console.log('id · 표면 · 물음 HH:MM KST · 답 · 도착 · 왕복 분 · 판정');
+      for (const row of rows) console.log(`${row.id} · ${row.surface} · ${clock(row.askedAt)} KST · ${clock(row.answeredAt)} · ${clock(row.deliveredAt)} · ${row.roundTripMs === null ? '-' : (row.roundTripMs / 60_000).toFixed(1)}분 · ${row.verdict}`);
+      const count = (verdict: string) => rows.filter(row => row.verdict === verdict).length;
+      console.log(`10분 안 ${count('10분 안')} / 넘음 ${count('10분 넘음')} / 미답 ${count('미답')} / 대기 ${count('답 대기') + count('전달 대기')} / 미상 ${count('시각 미상')}`);
+    } catch (error) { console.error(`seat asks: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
+  });
 seatCmd.command('answer <askId> <answer>').description('자리 질문에 답을 남기고 원래 표면으로 회신 예약')
   .action(async (askId: string, answer: string) => {
     try {
@@ -3299,11 +3367,20 @@ contextCmd.command('day')
   .description('자리 넷과 외부 세션의 최근 맥락 이벤트 수·마지막 시각 (읽기 전용)')
   .option('--since <hours>', '최근 시간 창 (예: 24h)', '24h')
   .option('--json', '구조화된 JSON 출력')
-  .action(async (opts: { since: string; json?: boolean }) => {
+  .option('--timeline', '시간순 사건 한 줄씩 (KST)')
+  .option('--seat <source>', '한 출처만 (OP|TC|MK|UX|claude-code|codex-agent-mission|harness-child)')
+  .action(async (opts: { since: string; json?: boolean; timeline?: boolean; seat?: string }) => {
     try {
-      const { contextDay, renderContextDay } = await import('./context-bus/context-day.js');
-      const report = contextDay(opts.since);
-      await writeStdoutJson(`${opts.json ? JSON.stringify(report) : renderContextDay(report)}\n`);
+      const { contextDay, contextDayTimeline, renderContextDay, renderContextDayTimeline, CONTEXT_DAY_SOURCES } = await import('./context-bus/context-day.js');
+      if (opts.seat && !CONTEXT_DAY_SOURCES.some(source => source === opts.seat)) throw new Error(`unknown --seat: ${opts.seat}`);
+      if (opts.seat && !opts.timeline) throw new Error('--seat requires --timeline');
+      if (opts.timeline) {
+        const report = contextDayTimeline(opts.since, { seat: opts.seat as typeof CONTEXT_DAY_SOURCES[number] | undefined });
+        await writeStdoutJson(`${opts.json ? JSON.stringify(report) : renderContextDayTimeline(report)}\n`);
+      } else {
+        const report = contextDay(opts.since);
+        await writeStdoutJson(`${opts.json ? JSON.stringify(report) : renderContextDay(report)}\n`);
+      }
     } catch (error) {
       console.error(`context day: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 2;
@@ -4337,16 +4414,52 @@ selfCmd
   .option('--base <ref>', '커밋됐지만 PR 없는 변경의 비교 기준(ref...HEAD)')
   .option('--pr <number>', '열린 PR 번호에서 gh pr view files로 변경 파일을 읽는다')
   .option('--shards [number]', '메모리 예산에 맞춰 시험을 별도 프로세스로 분할한다 (기본 2)')
-  .action((opts: { changed?: boolean; base?: string; pr?: string; shards?: string | boolean }) => {
+  .option('--remote [host]', 'GATE-REMOTE — 같은 커밋을 원격 호스트(기본 config gateRemote.host=node-b)에서 돌리고 결과만 가져온다(깨끗한 트리 · --pr 은 로컬)')
+  .option('--local', '원격 자동 분배(로컬 1분 부하 > gateRemote.loadThreshold=20)를 끄고 로컬에서 돌린다')
+  .action(async (opts: { changed?: boolean; base?: string; pr?: string; shards?: string | boolean; remote?: string | boolean; local?: boolean }) => {
     if (!opts.changed && opts.shards === undefined) { ui.error('self gate requires --changed or --shards'); process.exitCode = 2; return; }
+    // The root strips `--local` from argv anywhere (remote-bookmark attach · src/cli/remote-resolve.ts) before Commander
+    // sees it, so this subcommand reads it from the untouched process.argv.
+    opts.local = !!opts.local || process.argv.slice(2).includes('--local');
+    if (opts.remote !== undefined && opts.local) { ui.error('self gate: --remote and --local cannot be combined'); process.exitCode = 2; return; }
+    if (typeof opts.remote === 'string') {
+      const { isValidGateHost } = await import('./self-implement/gate-remote.js');
+      if (!isValidGateHost(opts.remote)) { ui.error(`self gate: invalid --remote host: ${opts.remote}`); process.exitCode = 2; return; }
+    }
+    const shards = opts.shards === undefined ? undefined : opts.shards === true ? 2 : Number(opts.shards);
+    const runLocal = () => {
+      try {
+        const { runSelfGateCli } = require('./self-implement/gate-cli.js') as typeof import('./self-implement/gate-cli.js');
+        const result = runSelfGateCli(process.cwd(), { base: opts.base, pr: opts.pr, shards });
+        console.log(result.lines.join('\n'));
+        return result.exitCode;
+      } catch (error) {
+        ui.error(`self gate failed: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+      }
+    };
     try {
-      const { runSelfGateCli } = require('./self-implement/gate-cli.js') as typeof import('./self-implement/gate-cli.js');
-      const result = runSelfGateCli(process.cwd(), { base: opts.base, pr: opts.pr, shards: opts.shards === undefined ? undefined : opts.shards === true ? 2 : Number(opts.shards) });
-      console.log(result.lines.join('\n'));
-      process.exitCode = result.exitCode;
+      const { dispatchHeavyCheck } = await import('./self-implement/gate-remote.js');
+      const { execFileSync } = await import('node:child_process');
+      const repo = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+      // Only a committed --base range is reproducible on another host: the default mode measures uncommitted files, --pr
+      // reads files through gh on this host, and the remote checkout runs from the repository root — those stay local.
+      const { realpathSync } = await import('node:fs');
+      const localOnlyReason = opts.pr ? 'self gate --pr reads PR files through gh on this host'
+        : !opts.base ? 'self gate without --base measures uncommitted files on this host'
+        : realpathSync(repo) !== realpathSync(process.cwd()) ? 'self gate run from a sub-directory' : undefined;
+      // origin/main is pinned to this machine's origin/main on the host; any other base is passed as its resolved sha.
+      const remoteArgv = (sha: (ref: string) => string) => ['bun', 'bin/elanous.mjs', 'self', 'gate', '--local', ...(opts.changed ? ['--changed'] : []),
+        ...(opts.base ? ['--base', opts.base === 'origin/main' ? opts.base : sha(opts.base)] : []), ...(shards !== undefined ? ['--shards', String(shards)] : [])];
+      process.exitCode = await dispatchHeavyCheck({
+        tool: 'self-gate', repo, installPwa: true, remoteArgv, refs: opts.base ? [opts.base] : [],
+        localOnlyReason,
+        flags: { remote: typeof opts.remote === 'string' ? opts.remote : opts.remote ? true : undefined, local: !!opts.local },
+        runLocal,
+      });
     } catch (error) {
-      ui.error(`self gate failed: ${error instanceof Error ? error.message : String(error)}`);
-      process.exitCode = 1;
+      ui.error(`self gate dispatch failed: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = runLocal();
     }
   });
 
@@ -8599,10 +8712,15 @@ program
     }
     if (opts.tools) announceChatToolsCompatibility();
     const cfg = getUserConfig();
-    if (needsOnboarding(cfg)) {
-      if (cfg.onboarding.webFirst === false) ui.info('No config yet — launching setup wizard first.');
-      if (!await runFirstSetupForCli(cfg, true)) return;
-    }
+    if (await firstChatGate(cfg, {
+      isTTY: process.stdin.isTTY === true,
+      runFirstRun: async (deps) => (await import('./onboarding/first-run.js')).runFirstRun(deps),
+      runInteractive: () => {
+        if (cfg.onboarding.webFirst === false) ui.info('No config yet — launching setup wizard first.');
+        return runFirstSetupForCli(cfg, true);
+      },
+      print: (line) => console.log(line),
+    }) === 'stop') return;
     const refreshed = reloadUserConfig();
     // ★ 관측갭 수리(2026-07-21·제1원칙·트랙A) — self-implement 자식 goal-loop(`chat --goal-loop`)은 데몬과
     //   별개 독립 프로세스라 nexus StoreSink 를 상속 안 한다. 부모 `self implement`(위 self 커맨드)는 sink 를