elanous 0.2.18 → 0.2.20

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

@@ -0,0 +1,140 @@
+/**
+ * `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 { getUserConfig } from '../user-config.js';
+import { resolveRepositoryName } from './repository-name.js';
+import {
+  classifySalvageRetention,
+  formatSalvageRetention,
+  listDatedSalvageRefs,
+  listOpenPrRefs,
+  type DatedSalvageRef,
+  type SalvageReferenceSources,
+  type SalvageRetentionMode,
+  type SalvageRetentionReport,
+} from '../self-implement/salvage-retention.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;
+    });
+}
+
+export interface HarnessSalvageRetentionDeps {
+  repository?: () => string;
+  listRefs?: (repository: string) => DatedSalvageRef[];
+  listOpenPrs?: (repository: string) => SalvageReferenceSources['openPrs'];
+  listCards?: () => SalvageReferenceSources['cards'];
+  mode?: () => SalvageRetentionMode;
+  now?: () => Date;
+  print?: (line: string) => void;
+}
+
+async function defaultCards(): Promise<SalvageReferenceSources['cards']> {
+  const { readTaskAgentState, taskAgentStatePath } = await import('../task-agent/task-hand.js');
+  const tasks = readTaskAgentState<{ tasks?: Record<string, { id: string; runId?: string }> }>(taskAgentStatePath()).tasks ?? {};
+  return Object.values(tasks).map((card) => ({ id: card.id, ...(card.runId ? { runId: card.runId } : {}), text: JSON.stringify(card) }));
+}
+
+/** SALVAGE-RETENTION — 그림자 보고(지우지 않는다). 조회가 하나라도 실패하면 수를 내지 않고 실패로 끝난다(⛔ 부분 수를 «전체»로 안 읽는다). */
+export async function runHarnessSalvageRetention(deps: HarnessSalvageRetentionDeps = {}): Promise<SalvageRetentionReport> {
+  const repository = (deps.repository ?? (() => resolveRepositoryName({})))();
+  let mode: SalvageRetentionMode = 'shadow';
+  try {
+    mode = deps.mode ? deps.mode() : (getUserConfig().tools?.selfImplement?.salvageRetention?.mode ?? 'shadow');
+  } catch { mode = 'shadow'; }
+  const refs = (deps.listRefs ?? ((repo: string) => listDatedSalvageRefs(repo)))(repository);
+  const openPrs = (deps.listOpenPrs ?? ((repo: string) => listOpenPrRefs(repo)))(repository);
+  const cards = deps.listCards ? deps.listCards() : await defaultCards();
+  const report = classifySalvageRetention({ refs, sources: { openPrs, cards }, now: (deps.now ?? (() => new Date()))(), mode });
+  debug.log('self-implement.salvage-retention', 'shadow-report', { repository, ...report, openPrs: openPrs.length, cards: cards.length });
+  return report;
+}
+
+export function installHarnessSalvageRetentionCommand(harnessCmd: Command, deps: HarnessSalvageRetentionDeps = {}): Command {
+  return harnessCmd
+    .command('salvage-retention')
+    .description('원격 salvage/* 가지 보존 규칙(14일 초과 ⊕ 열린 PR·카드 참조 0) — 그림자: 지울 후보 수만 보고하고 지우지 않는다')
+    .option('--json', '{ mode, total, older, referenced, candidates, unknownAge, sample, deleted } JSON')
+    .action(async (opts: { json?: boolean }) => {
+      const print = deps.print ?? ((line: string) => console.log(line));
+      try {
+        const report = await runHarnessSalvageRetention(deps);
+        print(opts.json ? JSON.stringify(report) : formatSalvageRetention(report));
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        debug.log('self-implement.salvage-retention', 'shadow-report-failed', { error: reason });
+        print(`수확 가지 보존: 못 잼 — ${reason}`);
+        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/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/fence-outcomes.ts

@@ -0,0 +1,63 @@
+// LOOPCHECK-FENCE (0.2.20): an hq-fence cron execution is one process, not a loop.
+// Each wrapped run leaves its rc in a per-role streak file; the wrapper's owner alert
+// raises a seat request only when the same role failed in consecutive runs, keyed per
+// role so the seat request journal holds at most one `loopcheck:hq-fence:<role>` per day.
+// No loops/ import here: hq.ts records through this module and loops/registry imports hq.ts.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { debug } from '../debug/log.js';
+
+/** The role is the file name; `lastAt` is shown in the owner alert so TC sees when the streak last grew. */
+export interface FenceOutcome { consecutiveFailures: number; lastRc: number; lastAt: string }
+
+/** Two failures in a row: one rc=1 from a job that recovers on the next fire is not a fence fault. */
+export const FENCE_FAILURE_STREAK = 2;
+
+const safeRole = (role: string): string => role.replace(/[^\w.-]/g, '_') || 'unknown';
+
+export function fenceOutcomePath(dir: string, role: string): string {
+  return join(dir, `${safeRole(role)}.json`);
+}
+
+/** Default directory next to the host-local lease view (`<config>/hq/fence-outcomes`). */
+export function fenceOutcomeDir(localPath: string): string {
+  return join(dirname(localPath), 'fence-outcomes');
+}
+
+export function readFenceOutcome(dir: string, role: string): FenceOutcome | null {
+  try {
+    const parsed = JSON.parse(readFileSync(fenceOutcomePath(dir, role), 'utf8')) as Partial<FenceOutcome>;
+    return typeof parsed.consecutiveFailures === 'number' ? parsed as FenceOutcome : null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    debug.log('hq.fence-outcome', 'read-failed', { role, error: String(error) });
+    return null;
+  }
+}
+
+/** rc 0 resets the streak; any other rc extends it. A skipped (not-holder) run is not recorded.
+ * Overlapping runs of one role serialize the read-modify-write on an SQLite lock (released even on SIGKILL). */
+export function recordFenceOutcome(dir: string, role: string, rc: number, now: Date = new Date()): FenceOutcome {
+  const path = fenceOutcomePath(dir, role);
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = new Database(`${path}.lock.sqlite`);
+  try {
+    lock.exec('PRAGMA busy_timeout = 10000');
+    lock.exec('BEGIN EXCLUSIVE');
+    try {
+      const previous = readFenceOutcome(dir, role);
+      const outcome: FenceOutcome = { consecutiveFailures: rc === 0 ? 0 : (previous?.consecutiveFailures ?? 0) + 1, lastRc: rc, lastAt: now.toISOString() };
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(outcome));
+      renameSync(tmp, path);
+      lock.exec('COMMIT');
+      return outcome;
+    } catch (error) { lock.exec('ROLLBACK'); throw error; }
+  } finally { lock.close(); }
+}
+
+/** `hq-fence: fence failed (rc=1, role=seat-loop)` → `seat-loop`; other wrapper reasons have no role. */
+export function fenceAlertRole(reason: string): string | null {
+  return /\brole=([\w.-]+)/.exec(reason)?.[1] ?? null;
+}

package/src/hq/fence-wrapper.ts

@@ -3,6 +3,9 @@ import { chmodSync, constants, copyFileSync, lstatSync, mkdirSync, mkdtempSync,
 import { dirname, isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { createPatch } from 'diff';
+import { debug } from '../debug/log.js';
+import { notifyOwners } from '../loops/checker.js';
+import { FENCE_FAILURE_STREAK, fenceAlertRole, readFenceOutcome } from './fence-outcomes.js';
 
 const quote = (value: string): string => `'${value.replaceAll("'", "'\"'\"'")}'`;
 
@@ -121,3 +124,33 @@ export function installHqFenceWrapper(configDir: string, body: string, yes: bool
   } finally { rmSync(tempDir, { recursive: true, force: true }); }
   return { path, preview, ...(backup ? { backup } : {}) };
 }
+
+export interface FenceAlertDeps { root: string; outcomeDir: string; now?: Date }
+
+/**
+ * The wrapper's owner alert. Returns the number of seat requests queued (0 or 1).
+ * - `fence failed (rc, role)`: queued only when that role's streak reached FENCE_FAILURE_STREAK
+ *   (an unknown streak is not read as «first failure» — it is queued, still capped per role/day).
+ * - Any other wrapper failure (entry missing, bun missing, role missing): queued under `hq-fence:wrapper`.
+ */
+export function hqFenceAlert(reason: string, deps: FenceAlertDeps): number {
+  const now = deps.now ?? new Date();
+  const fenceFailure = /fence failed \(rc=/.test(reason);
+  const role = fenceAlertRole(reason);
+  let streak: number | null = null;
+  let lastAt: string | undefined;
+  if (fenceFailure && role) {
+    const outcome = readFenceOutcome(deps.outcomeDir, role);
+    streak = outcome?.consecutiveFailures ?? null;
+    lastAt = outcome?.lastAt;
+    if (streak !== null && streak < FENCE_FAILURE_STREAK) {
+      debug.log('hq.fence-wrapper', 'alert-suppressed', { role, streak, threshold: FENCE_FAILURE_STREAK, reason });
+      return 0;
+    }
+  }
+  const id = `hq-fence:${fenceFailure && role ? role : 'wrapper'}`;
+  const text = streak !== null ? `${reason} · ${streak} consecutive runs (last ${lastAt ?? 'unknown'})` : reason;
+  const added = notifyOwners([{ id, owner: 'TC', enabled: true, registered: true, state: 'failing', reason: text }], { root: deps.root, now });
+  debug.log('hq.fence-wrapper', added ? 'alert-queued' : 'alert-deduplicated', { id, role, streak, reason });
+  return added;
+}

package/src/hq/hq.ts

@@ -10,6 +10,7 @@ import { debug } from '../debug/log.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { getUserConfig, type HqConfig, type HqFenceRole } from '../user-config.js';
+import { fenceOutcomeDir, recordFenceOutcome } from './fence-outcomes.js';
 import { promoteHq, proposeHqPromotion, writeOpSeatRequest } from './promote.js';
 import type { HqOpRequestWriter, PromoteResult } from './promote.js';
 import {
@@ -42,6 +43,8 @@ export interface HqDeps {
   /** Holder/standby views and the arbiter's check use this tailnet probe — never ssh (OP 10-04 09:04). */
   probe?: HostProbe;
   localPath?: string;
+  /** Per-role streak files of wrapped-run rc (LOOPCHECK-FENCE · default next to localPath). */
+  outcomeDir?: string;
   /** Host-local identity, deliberately outside the replicated config/state directory. */
   hostPath?: string;
   /** Seen-generation marker (default hq.seenGenerationFile · ~/.elanous-hq/seen-generation). */
@@ -108,7 +111,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 +164,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;
@@ -386,5 +394,12 @@ export function hqFenceRun(role: HqFenceRole, command: string[], deps: HqDeps =
   const [cmd, ...args] = command;
   if (!cmd) throw new Error('hq fence: command required after --');
   const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...process.env, ELANOUS_HQ_GENERATION: String(decided.generation ?? '') } });
-  return r.status ?? 1;
+  const rc = r.status ?? 1;
+  // LOOPCHECK-FENCE: the wrapper's alert reads this streak, so a lone failure is not a seat request.
+  try {
+    const dir = deps.outcomeDir ?? fenceOutcomeDir(deps.localPath ?? join(getElanousConfigDir(), 'hq', 'local.json'));
+    const outcome = recordFenceOutcome(dir, role, rc, new Date(deps.now?.() ?? Date.now()));
+    if (rc !== 0) debug.log('hq.fence', 'run-failed', { role, rc, consecutiveFailures: outcome.consecutiveFailures });
+  } catch (error) { try { debug.log('hq.fence', 'outcome-record-failed', { role, rc, error: String(error) }); } catch { /* fail-soft */ } }
+  return rc;
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import type { SelfDevRunParticipant, SelfDevRunState } from './self-dev/run-stor
 import { applyConfigDirFlagFromArgv } from './cli/config-dir-flag.js';
 import { LOGS_SINCE_OPTION, registerLogsCommands } from './cli/logs-cli.js';
 import { registerDocsCommands } from './cli/docs-cli.js';
+import { registerRetroCommands } from './cli/retro-cli.js';
 import { registerA2ACommands } from './cli/a2a-cli.js';
 import { registerPluginCommands } from './cli/plugin-cli.js';
 import { registerMakeCommand } from './cli/make-cli.js';
@@ -51,6 +52,7 @@ import { registerRoleCommands } from './cli/role-cli.js';
 import { registerMachineCommands } from './cli/machine-cli.js';
 import { registerAgentEnvCommands } from './cli/agent-env-cli.js';
 import { registerScheduleCommands } from './cli/schedule-cli.js';
+import { registerGuardianCommands } from './cli/guardian-cli.js';
 export { runSchedule, scheduleCreatePlan } from './cli/schedule-cli.js';
 export type { ScheduleDispatch } from './cli/schedule-cli.js';
 import { registerReviewLoopOptions, buildReviewLoopOpts } from './agent-mission/review-loop-cli.js';
@@ -75,6 +77,7 @@ 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 { registerAwayCommand } from './cli/away-cli.js';
 import { registerLabelsCommands } from './cli/labels-cli.js';
 import { registerMsgCommands } from './cli/msg-cli.js';
 import { registerDoctorCommand } from './cli/doctor-cli.js';
@@ -215,6 +218,24 @@ export { cliVersion, setInstallMetadataRootForTesting };
 export const program = new Command();
 program.enablePositionalOptions();
 
+program.command('preview <target>')
+  .description('Isolated PR/branch-head TUI + PWA preview; publish the TUI-COMFORT friction table to a PR')
+  .option('--scenario <id>', 'TUI-COMFORT scenario IDs (comma-separated; default S2)', 'S2')
+  .option('--flag <path>', 'Enable an existing config feature flag in main-based preview (repeatable)', (value: string, all: string[]) => [...all, value], [] as string[])
+  .option('--bundle-pr <number>', 'Merge PR head into isolated main preview (repeatable; no flags)', (value: string, all: number[]) => [...all, Number(value)], [] as number[])
+  .option('--comment-pr <number>', 'PR to receive a branch/main preview report', (value: string) => Number(value))
+  .action(async (target: string, opts: { scenario: string; flag: string[]; bundlePr: number[]; commentPr?: number }) => {
+    try {
+      const { runPrPreview } = await import('./self-dev/pr-preview.js');
+      const result = await runPrPreview({ target, repoRoot: process.cwd(), scenario: opts.scenario, flags: opts.flag, bundlePrs: opts.bundlePr, ...(opts.commentPr === undefined ? {} : { commentPr: opts.commentPr }) });
+      console.log(`preview ${result.status} · ${result.head} · PR #${result.prNumber} · comment posted`);
+      if (result.status !== 'passed') process.exitCode = 1;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  });
+
 export { SELF_SEND_RECENT_FRAME_WINDOW_MS, SELF_SEND_STALE_HEARTBEAT_MS, formatSelfSendCandidateDisplay } from './harness/self-send-decide.js';
 export type { SelfSendCandidate, SelfSendCandidateDisplay } from './harness/self-send-decide.js';
 import { decideSelfSend, type SelfSendCandidate } from './harness/self-send-decide.js';
@@ -891,6 +912,7 @@ registerResearchCommand(program);
 registerReleaseCommands(program);
 registerKnowCommand(program);
 registerNotifyCommand(program);
+registerAwayCommand(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.
@@ -1039,10 +1061,12 @@ fenceWrapperCmd.command('install').description('래퍼 제안 또는 백업 후
 fenceWrapperCmd.command('alert <reason>').description('HQ 울타리 실패를 기존 루프 소유자 요청 원장에 적재')
   .action(async (reason: string) => {
     try {
-      const { notifyOwners } = await import('./loops/checker.js');
+      // LOOPCHECK-FENCE: keyed per role (not per pid) and only after consecutive failures of that role.
+      const { fenceOutcomeDir } = await import('./hq/fence-outcomes.js');
+      const { hqFenceAlert } = await import('./hq/fence-wrapper.js');
       const { getElanousConfigDir } = await import('./elanous-config-dir.js');
-      notifyOwners([{ id: `hq-fence:${Date.now()}:${process.pid}`, owner: 'TC', enabled: true, registered: true,
-        state: 'failing', reason }], { root: getElanousConfigDir() });
+      const root = getElanousConfigDir();
+      hqFenceAlert(reason, { root, outcomeDir: fenceOutcomeDir(_joinPath(root, 'hq', 'local.json')) });
     } catch (error) { console.error(`hq fence-wrapper alert: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
   });
 hqCmd.command('fence-audit').description('운영 crontab 의 HQ 울타리 밖 쓰기 잡 목록과 감싼 줄 제안(읽기 전용)')
@@ -1885,6 +1909,7 @@ program
   });
 
 registerAutopilotCommands(program);
+registerRetroCommands(program);
 
 // ── memory ──
 const memCmd = program.command('memory').description('Persistent memories injected into every chat turn (user / feedback / project / reference)');
@@ -5979,6 +6004,7 @@ program
   });
 
 registerScheduleCommands(program);
+registerGuardianCommands(program);
 
 /** `elanous decide*` 공통 — 보낼 곳과 자격을 정한다(설정 decide.endpoint > ELANOUS_JEV_ENDPOINT > Typesafe). 없으면 안내하고 rc 2. */
 async function loadJevAccessOrExit(): Promise<import('./decide/jev.js').JevAccess> {
@@ -7173,7 +7199,7 @@ const selfDevCmd = program
             const members = parsePodPool(devAskSubstrate.pool!);
             const host = podPoolHostLease(members);
             while (!authoringLease) {
-              const status = recommendConcurrency(measurePoolLease(members), { capacity: members.reduce((n, m) => n + m.capacity, 0), accounts: 0, perAccount: 0 });
+              const status = recommendConcurrency(measurePoolLease(members, { measureUsage: true }), { capacity: members.reduce((n, m) => n + m.capacity, 0), accounts: 0, perAccount: 0 });
               if (status.recommended !== null && status.recommended > 0) {
                 const { leaseHasPendingPod } = await import('./pod-lease/host-lease.js');
                 const pendingJobs = status.pendingJobs ?? [];
@@ -7328,7 +7354,23 @@ const selfDevCmd = program
         if (hasExplicitReviewerContext && loaded.failed.length > 0) throw new DevPipelineError(contextStatus);
         if (loaded.items.length > 0) spec = { ...spec, reviewerContext: loaded.items };
       }
-      if (devOpts.worktree === true) {
+      // ⭐ TUI-ONE-WORD-LAUNCH — 명시 격리 우주에서 `--cwd`·`--worktree` 둘 다 없으면 «자동» 갈래로
+      //    같은 `prepareDevWorktree` 를 탄다(새 생성 경로 없음). 명시 `--cwd` 는 그대로 이긴다.
+      const autoWorktreeDecision = await (async () => {
+        if (!devOpts.elanous || devOpts.worktree === true || devOpts.cwd !== undefined) {
+          return devCli.decideAutoWorktree({ explicitlyIsolated: false, ...devOpts });
+        }
+        const [{ resolveCurrentInstance }, { isExplicitlyIsolated }] = await Promise.all([
+          import('./instance/current.js'),
+          import('./cli/pty-drive-cli.js'),
+        ]);
+        return devCli.decideAutoWorktree({
+          explicitlyIsolated: isExplicitlyIsolated(resolveCurrentInstance(), devOpts.isolatedRoot),
+          ...devOpts,
+        });
+      })();
+      debug.log('dev-pipeline', 'auto-worktree-decision', { runId: devRunId, decision: autoWorktreeDecision });
+      if (autoWorktreeDecision === 'requested' || autoWorktreeDecision === 'auto') {
         const { prepareDevWorktree, renderPreparedDevWorktree } = await import('./harness/harness-worktree-auto.js');
         const goal = 'file' in input
           ? await (async () => {
@@ -7338,13 +7380,25 @@ const selfDevCmd = program
               return { id: goalId, file: input.file };
             })()
           : undefined;
-        const prepared = prepareDevWorktree(process.cwd(), devRunId, invokedAsDrive ? 'drive' : 'dev', goal);
+        const prepared = (() => {
+          try {
+            return prepareDevWorktree(process.cwd(), devRunId, invokedAsDrive ? 'drive' : 'dev', goal);
+          } catch (error) {
+            if (autoWorktreeDecision !== 'auto') throw error;
+            debug.log('dev-pipeline', 'auto-worktree-failed', { runId: devRunId, cwd: process.cwd(), msg: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+            throw new DevPipelineError(devCli.formatAutoWorktreeFailure(error));
+          }
+        })();
         preparedWorktree = prepared;
         if (spec.elanous) spec = { ...spec, elanous: { ...spec.elanous, cwd: prepared.worktree.path } };
         else if (spec.drive) spec = { ...spec, drive: { ...spec.drive, cwd: prepared.worktree.path } };
         else throw new DevPipelineError('--worktree 는 elanous 또는 셸 drive child에만 유효');
         if (!opts.json) console.log(renderPreparedDevWorktree(prepared).join('\n'));
         debug.log('dev-pipeline', 'auto-worktree-prepared', { runId: devRunId, ...prepared.environment, worktree: prepared.worktree });
+        if (autoWorktreeDecision === 'auto') {
+          if (!opts.json) console.log(devCli.formatAutoWorktreeNotice(prepared.worktree.path));
+          debug.log('dev-pipeline', 'auto-worktree-implied', { runId: devRunId, worktree: prepared.worktree.path });
+        }
       }
       // ⛔ 종전의 `const plan = planDevPipeline(spec)` 를 지운다(무인 리뷰 must-fix) — 쓰이지 않는
       //    데다 **잔여 조회보다 먼저 던질 수 있어** 관측 자체를 건너뛰게 만든다. 계획은 어차피
@@ -7630,6 +7684,11 @@ configCmd
   .description('Print all config or one dotted path, e.g. llm.provider (secrets redacted by default)')
   .option('--reveal', 'Print unredacted output and record the reveal')
   .action(async (path: string | undefined, opts: { reveal?: boolean }) => {
+    const { resolveCurrentInstance } = await import('./instance/current.js');
+    const instance = resolveCurrentInstance();
+    if (instance.kind === 'test' && instance.layer === 'tree-derived') {
+      console.error('⚠️ test 우주의 config를 읽습니다 — 운영 값은 --config-dir ~/.elanous');
+    }
     const cfg = getUserConfig() as unknown as Record<string, unknown>;
     const value = path ? getConfigPath(cfg, path) : cfg;
     if (value === undefined) {
@@ -7724,6 +7783,59 @@ configCmd
     ui.info(`unset ${path}`);
   });
 
+// ── config drift / explain (CFG-STORE1 · 0.2.20 · 2026-10-08) — 읽기 전용 «유효 config ⊕ 출처» ──
+// 집(~/.elanous)과 파생 시험 우주(<트리>/.elanous-test) config 사본의 드리프트를 한 명령으로.
+// ⛔ 쓰기 0 · 못 읽음 ≠ 같음 · 비밀 값 가림. 계산 = src/cli/config-drift.ts.
+async function configDriftDiscover(o: { registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) {
+  const { discoverUniverses } = await import('./cli/config-drift.js');
+  return discoverUniverses({
+    ...(o.registry === false ? { registryPath: null } : typeof o.registry === 'string' ? { registryPath: o.registry } : {}),
+    ...(o.treeScan === false ? { treeScanRoots: [] } : o.scanRoot?.length ? { treeScanRoots: o.scanRoot } : {}),
+  });
+}
+
+configCmd
+  .command('drift')
+  .description('읽기 전용 — 운영 config 와 파생 시험 우주(.elanous-test) config 사본이 다른 키 표 (CFG-STORE1)')
+  .option('--key <key>', '이 키(또는 그 아래)만')
+  .option('--json', 'JSON 출력')
+  .option('--limit <n>', '표시할 키 수 (0=전부 · 기본 50)', '50')
+  .option('--registry <path>', '인스턴스 레지스트리 경로 (기본 ~/.elanous/logs/instances.json)')
+  .option('--scan-root <dir...>', '명시 트리 뿌리 (기본 = config-drift.ts defaultTreeScanRoots)')
+  .option('--no-tree-scan', '트리 뿌리 훑기 끔 — 레지스트리만')
+  .option('--no-registry', '레지스트리 끔 — 명시 트리 뿌리(자리·작업 트리)만')
+  .option('--include-expected', 'sync-test 의 test-safe 변환(비밀 제거·발송 끔)과 _test 메타 키 차이도 드리프트로 센다')
+  .action(async (o: { key?: string; json?: boolean; limit: string; includeExpected?: boolean; registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) => {
+    const { computeDrift, renderDrift } = await import('./cli/config-drift.js');
+    const report = computeDrift(await configDriftDiscover(o), { key: o.key, includeExpected: o.includeExpected });
+    debug.log('config.drift', 'computed', {
+      key: o.key ?? null, rows: report.rows.length, prodStatus: report.prodStatus, ...report.universes,
+    });
+    debug.flush();
+    console.log(o.json ? JSON.stringify(report, null, 2) : renderDrift(report, { limit: Number(o.limit) || 0 }));
+    if (report.prodStatus !== 'ok') process.exit(1);
+  });
+
+configCmd
+  .command('explain <key>')
+  .description('읽기 전용 — 운영 값 ⊕ 출처 층 ⊕ 파생 시험 우주별 값 (CFG-STORE1)')
+  .option('--json', 'JSON 출력')
+  .option('--registry <path>', '인스턴스 레지스트리 경로')
+  .option('--scan-root <dir...>', '명시 트리 뿌리')
+  .option('--no-tree-scan', '트리 뿌리 훑기 끔 — 레지스트리만')
+  .option('--no-registry', '레지스트리 끔 — 명시 트리 뿌리만')
+  .action(async (key: string, o: { json?: boolean; registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) => {
+    const { computeExplain, renderExplain } = await import('./cli/config-drift.js');
+    const { buildUserConfig } = await import('./user-config.js');
+    const report = computeExplain(await configDriftDiscover(o), key, {
+      codeDefaults: () => buildUserConfig('/nonexistent/elanous-config-drift/config.json'),
+    });
+    debug.log('config.explain', 'computed', { key, layer: report.prod.layer, ...report.universes });
+    debug.flush();
+    console.log(o.json ? JSON.stringify(report, null, 2) : renderExplain(report));
+    if (report.prod.layer === 'prod-unreadable') process.exit(1);
+  });
+
 // ── config 격리 sync (ISO-1 · 2026-07-13) — 운영→테스트 물질화 동기화 ──
 // 격리 테스트 인스턴스는 운영 config 를 공유하지 않는다(overlay 은퇴 방향).
 configCmd