elanous 0.2.35 → 0.2.37

package/src/loops/checker.ts

@@ -33,6 +33,9 @@ export interface CheckEntry {
   expectedVersion?: string;
   /** Registry graph path, supplied only by graph inventory. */
   file?: string;
+  /** LOOP-PRUNE-1021-FU 판정 재료 — cron-shell·미등록 행이 실은 crontab 명세(그래프 루프에는 없다). */
+  cron?: string;
+  command?: string;
   enabled: boolean;
   registered: boolean;
 }
@@ -317,3 +320,100 @@ export function observeLoopCheck(results: CheckResult[], scope: LoopScope, deps:
   catch (error) { if (existsSync(tmp)) unlinkSync(tmp); throw error; }
   return counts;
 }
+
+// ── LOOP-PRUNE-1021-FU 정리 판정 (내부 문서 `loop-lineage-1021` · 0.2.36) ─────
+/** 무실행 은퇴 한계 — off 상태가 원장으로 최근 14일 실행이 증명될 때만 은퇴 후보가 된다. */
+export const PRUNE_IDLE_DAYS = 14;
+/** 활성 루프 상한 — alive 가 25 를 넘으면 접기·은퇴 판정을 먼저 치른다. */
+export const PRUNE_ALIVE_LIMIT = 25;
+
+export interface PruneFoldGroup { family: string; ids: string[]; }
+export interface PruneUnregisteredRow { id: string; cron?: string; command?: string; }
+export interface PruneJudgment {
+  /** 14일 무실행이 원장으로 증명된 은퇴 후보(off). */
+  idleRetire: string[];
+  /** 실행 기록이 없어 무실행을 증명할 수 없는 항목 — 은퇴 후보에서 제외한다. */
+  idleUnproven: string[];
+  /** 등록되지 않은 elanous 크론 행 — 등록/제거 판정에 넘긴다. */
+  unregistered: PruneUnregisteredRow[];
+  /** 같은 일을 하는 elanous:* 형제 슬롯 가족 — 그래프 루프·원장 해시는 접지 않는다. */
+  foldGroups: PruneFoldGroup[];
+  /** 활성 루프 수와 25 한도 판정. */
+  alive: { count: number; limit: number; within: boolean };
+  /** 운영 이름이 없는 원장 해시 id — 명명 대상. */
+  unnamed: string[];
+}
+
+/** elanous:* 슬롯의 가족 이름 — namedCronIds 의 -N 접미와 자리 슬롯(:SEAT)을 원래 가족으로 되돌린다. */
+function pruneFoldFamily(id: string): string | undefined {
+  if (!id.startsWith('elanous:')) return undefined;
+  const seat = /^elanous:([^:]+):[^:]+$/.exec(id);
+  if (seat) return `elanous:${seat[1]}`;
+  const sibling = /^elanous:(.+)-\d+$/.exec(id);
+  return `elanous:${sibling ? sibling[1] : id.slice('elanous:'.length)}`;
+}
+
+/** LOOP-PRUNE-1021-FU — CheckResult 원장 위에서 무실행 은퇴·미등록 정리·형제 접기·alive ≤ 25·이름 없는 해시를 판정한다. */
+export function pruneJudgment(results: readonly CheckResult[], opts: { now?: Date } = {}): PruneJudgment {
+  const now = opts.now ?? new Date();
+  const idleMs = PRUNE_IDLE_DAYS * 24 * 60 * 60_000;
+  const idleRetire: string[] = [];
+  const idleUnproven: string[] = [];
+  const unregistered: PruneUnregisteredRow[] = [];
+  const unnamed: string[] = [];
+  const families = new Map<string, string[]>();
+  let aliveCount = 0;
+  for (const result of results) {
+    if (result.state === 'alive') aliveCount++;
+    if (result.state === 'unregistered') {
+      unregistered.push({
+        id: result.id,
+        ...(result.cron ? { cron: result.cron } : {}),
+        ...(result.command ? { command: result.command } : {}),
+      });
+    }
+    if (result.state === 'off') {
+      const ran = result.lastRunAt && Number.isFinite(Date.parse(result.lastRunAt)) ? Date.parse(result.lastRunAt) : undefined;
+      if (ran === undefined) idleUnproven.push(result.id);
+      else if (now.getTime() - ran > idleMs) idleRetire.push(result.id);
+    }
+    if (/^[0-9a-f]{8,}$/.test(result.id)) unnamed.push(result.id);
+    const family = pruneFoldFamily(result.id);
+    if (family) {
+      const group = families.get(family) ?? [];
+      group.push(result.id);
+      families.set(family, group);
+    }
+  }
+  const foldGroups: PruneFoldGroup[] = [];
+  for (const [family, ids] of families) {
+    if (ids.length < 2) continue;
+    foldGroups.push({ family, ids: [...ids].sort() });
+  }
+  const judgment: PruneJudgment = {
+    idleRetire,
+    idleUnproven,
+    unregistered,
+    foldGroups,
+    alive: { count: aliveCount, limit: PRUNE_ALIVE_LIMIT, within: aliveCount <= PRUNE_ALIVE_LIMIT },
+    unnamed,
+  };
+  debug.log('loop.checker', 'prune', {
+    idleRetire: idleRetire.length, idleUnproven: idleUnproven.length, unregistered: unregistered.length,
+    folds: foldGroups.length, alive: aliveCount, unnamed: unnamed.length,
+  });
+  return judgment;
+}
+
+/** LOOP-PRUNE-1021-FU — PruneJudgment 을 사람용 정리 판정 줄로 렌더한다(loop status --all 인간 출력 꼬리). */
+export function pruneText(judgment: PruneJudgment): string {
+  const lines = [
+    `무실행 은퇴 ${judgment.idleRetire.length}: ${judgment.idleRetire.join(', ') || '없음'}`,
+    `무실행 미증명 ${judgment.idleUnproven.length}: ${judgment.idleUnproven.join(', ') || '없음'}`,
+    `미등록 ${judgment.unregistered.length}: ${judgment.unregistered.map(row => row.command ? `${row.id} (${row.command})` : row.id).join(', ') || '없음'}`,
+    `형제 접기 ${judgment.foldGroups.length}: ${judgment.foldGroups.map(group => `${group.family}[${group.ids.join('+')}]`).join(', ') || '없음'}`,
+    `alive ${judgment.alive.count}/${judgment.alive.limit} ${judgment.alive.within ? '한도 이내' : '한도 초과'}`,
+    `이름 없는 해시 ${judgment.unnamed.length}: ${judgment.unnamed.join(', ') || '없음'}`,
+  ];
+  return lines.join('\n');
+}

package/src/loops/consensus.ts

@@ -45,6 +45,8 @@ export const CROWN_MARK = String.fromCodePoint(0x1F451);
 export interface ProposalCard {
   id: string;
   category: ConsensusCategory;
+  /** Stable orchestrator work key (orch:<card>:<cell>) for a cross-branch split cell. */
+  workKey?: string;
   title: string;
   /** 사실 id — 제안의 근거 관측. */
   factId: string;
@@ -152,8 +154,14 @@ export class ConsensusEngine {
 
   propose(input: {
     by: ConsensusRepresentative; category: ConsensusCategory; title: string; factId: string; cost: string; undo: string;
-    thresholds?: DecisionCategory[]; provider?: string;
+    thresholds?: DecisionCategory[]; provider?: string; workKey?: string;
   }): ProposalCard {
+    if (input.workKey !== undefined) {
+      if (input.category !== 'cross-branch-change' || !/^orch:[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+$/.test(input.workKey))
+        throw new Error('invalid cross-branch work key');
+      const existing = this.list().find(proposal => proposal.workKey === input.workKey);
+      if (existing) throw new Error(`cross-branch work already proposed: ${existing.id}`);
+    }
     if (!CONSENSUS_REPRESENTATIVES.includes(input.by)) throw new Error(`invalid representative: ${input.by} (coordinator|guardian)`);
     if (!CONSENSUS_CATEGORIES.includes(input.category)) throw new Error(`invalid consensus category: ${input.category} (${CONSENSUS_CATEGORIES.join('|')})`);
     const thresholds = [...new Set(input.thresholds ?? [])];
@@ -164,6 +172,7 @@ export class ConsensusEngine {
     const proposal: ProposalCard = {
       id: this.nextId('C', at),
       category: input.category,
+      ...(input.workKey ? { workKey: input.workKey } : {}),
       title: oneLine(input.title, 'title'),
       factId: oneLine(input.factId, 'fact id'),
       cost: oneLine(input.cost, 'cost'),
@@ -210,11 +219,24 @@ export class ConsensusEngine {
     return proposal;
   }
 
+  proposalForWork(workKey: string): ProposalCard | undefined {
+    return this.list().find(entry => entry.workKey === workKey);
+  }
+
   crownCards(): CrownCard[] {
     return [...this.state().cards]
       .sort((a, b) => b.raisedAt.localeCompare(a.raisedAt) || a.id.localeCompare(b.id));
   }
 
+  /** The same durable execution gate is used by CLI replies, hooks and loop consumers. */
+  canExecute(id: string): boolean {
+    const proposal = this.show(id);
+    return proposal.status === 'agreed' && proposal.thresholds.length === 0
+      && proposal.roundTrips >= 1 && proposal.roundTrips <= MAX_REVIEW_ROUND_TRIPS
+      && proposal.reviews.at(-1)?.verdict === 'agree'
+      && proposal.reviews.at(-1)?.by !== proposal.proposedBy;
+  }
+
   /** 판정선 — 합의 원장의 agreed 이벤트를 ISO 주 단위로 센다 (한 주 N건의 기전). */
   weeklyAgreementCounts(): Array<{ week: string; count: number }> {
     const counts = new Map<string, number>();
@@ -230,7 +252,9 @@ export class ConsensusEngine {
   private conclude(id: string, verdict: ReviewRecord['verdict'], input: { by: ConsensusRepresentative; claim?: string; provider?: string }): { proposal: ProposalCard; crownCard?: CrownCard } {
     const proposal = this.show(id);
     if (proposal.status !== 'open') throw new Error(`합의가 이미 결론났다: ${id} (${proposal.status === 'agreed' ? '합의' : '불합의'})`);
+    if (!CONSENSUS_REPRESENTATIVES.includes(input.by)) throw new Error(`invalid representative: ${input.by}`);
     if (input.by === proposal.proposedBy) throw new Error('메아리 방지 — 제안한 대표는 자기 제안을 검토하지 않는다');
+    if (proposal.roundTrips >= MAX_REVIEW_ROUND_TRIPS) throw new Error(`상대 검토는 최대 ${MAX_REVIEW_ROUND_TRIPS}왕복이다`);
     if (verdict === 'revise' && proposal.roundTrips + 1 >= MAX_REVIEW_ROUND_TRIPS)
       throw new Error(`상대 검토는 최대 ${MAX_REVIEW_ROUND_TRIPS}왕복이다 — 마지막 왕복에는 합의 또는 불합의로 끝낸다`);
     const claim = oneLine(input.claim ?? (verdict === 'agree' ? '동의 — 제안대로 실행한다' : ''), 'claim');
@@ -249,7 +273,7 @@ export class ConsensusEngine {
     this.appendLens(input.by, { action: 'reviewed', proposalId: proposal.id, at, verdict, ...(provider ? { provider } : {}) });
     debug.log('loops.consensus', 'reviewed', { proposalId: proposal.id, verdict, roundTrip: review.roundTrip, by: input.by });
     const updated = this.show(proposal.id);
-    if (verdict === 'agree') this.executeHook(updated);
+    if (this.canExecute(updated.id)) this.executeHook(updated);
     return { proposal: updated, ...(crownCard ? { crownCard } : {}) };
   }
 

package/src/loops/loop-cli.ts

@@ -1,7 +1,7 @@
 import type { Command } from 'commander';
 import { writeStdoutJson } from '../cli/stdout-json.js';
 import { listAllLoops, listLoops, loopStatus, runLoop, setLoopEnabled, unregisteredCronLoops, type AllLoopEntry, type LoopRegistryOptions } from './registry.js';
-import { checkLoops, countLoopStates, entriesFromRegistry, LOOP_STATES, notifyOwners, observeLoopCheck, type RegistryAdapterDeps } from './checker.js';
+import { checkLoops, countLoopStates, entriesFromRegistry, LOOP_STATES, notifyOwners, observeLoopCheck, pruneJudgment, pruneText, type RegistryAdapterDeps } from './checker.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { verifyLoopPackage } from './package/verify.js';
 import { loopActivity } from './activity.js';
@@ -56,7 +56,8 @@ export function registerLoopCommands(program: Command, checkerDeps: RegistryAdap
     }));
   loop.command('status [id]').option('--all', 'Check all registered loops')
     .option('--json', 'Print JSON').option('--notify', 'Queue late/failing loops for their owners')
-    .action((id: string | undefined, opts: { all?: boolean; json?: boolean; notify?: boolean }) => handle(async () => {
+    .option('--prune', 'Judge idle retire · unregistered cleanup · sibling folding · alive ≤ 25')
+    .action((id: string | undefined, opts: { all?: boolean; json?: boolean; notify?: boolean; prune?: boolean }) => handle(async () => {
       if (!opts.all) {
         if (!id) throw new Error('loop status requires an id or --all');
         await output(loopStatus(id), !!opts.json);
@@ -65,15 +66,19 @@ export function registerLoopCommands(program: Command, checkerDeps: RegistryAdap
       if (id) throw new Error('loop status --all does not take an id');
       const now = checkerDeps.now ?? new Date();
       const root = checkerDeps.root ?? effectiveInstanceRoot();
-      const { entries, scope } = entriesFromRegistry({ ...checkerDeps, now });
+      const registryOpts = checkerDeps.registryOptions;
+      const { entries, scope } = entriesFromRegistry({ ...checkerDeps, now,
+        listAllLoops: checkerDeps.listAllLoops ?? (registryOpts ? () => listAllLoops(registryOpts) : undefined) });
       const results = checkLoops(entries, now);
       const counts = countLoopStates(results);
+      const prune = pruneJudgment(results, { now });
       observeLoopCheck(results, scope, { root, now });
       if (opts.notify) notifyOwners(results, { root, now });
-      if (opts.json) { await output({ results, counts, scope }, true); return; }
+      if (opts.json) { await output({ results, counts, scope, prune }, true); return; }
       console.log('id\tstate\tlast run\texpected interval\towner\treason');
       for (const result of results) console.log(`${result.id}\t${result.state}\t${result.lastRunAt ?? '—'}\t${result.expectEveryMinutes === undefined ? '—' : `${result.expectEveryMinutes}m`}\t${result.owner ?? '—'}\t${result.reason}`);
       console.log(`${LOOP_STATES.map(state => `${state} ${counts[state]}`).join(' · ')} · scope ${scope}`);
+      if (opts.prune) console.log(pruneText(prune));
     }));
   for (const [name, enabled] of [['start', true], ['stop', false]] as const) {
     loop.command(`${name} <id>`).option('--yes', 'Apply the crontab change (otherwise preview only)')

package/src/loops/msg-wake.ts

@@ -5,7 +5,8 @@
 //   sse        — 아무것도 안 한다(구독자가 이미 듣는다)
 //   cron       — 다음 틱에 읽는다 · `wake-deferred` 로그만
 //   pty-inject — elanous TUI(pty 별명 = 자리 소문자)가 턴 idle 일 때만 한 줄 주입
-//   herdr      — 자리 폴더 `herdr.pane` 의 pane 이 agent_status=idle 일 때만 한 줄 주입
+//   herdr      — 자리 폴더 `herdr.pane` 의 pane 이 idle(·done) 일 때만 한 줄 주입 — `eln herdr prompt` 와 같은 생산 함수
+//                (`herdrPrompt` · `agent get` 상태 확인 → bracketed `pane run` 한 번). working/blocked 는 넣지 않고 busy.
 //   none       — stderr 경고 한 줄 · 해석 실패는 «모름»으로 남긴다(«없다»로 위장 금지)
 // ⛔ 우편은 입력칸에 넣지 않는다(대표 10-15 01:20) — 기본은 입력칸 주입 0. 10-15 01:10 사고: 대표 가 치던 문장에
 //    깨움 한 줄 ⊕ Enter 가 섞여 제출됐다(«에이전트 idle ≠ 사람이 안 친다»). 자리 폴더에서 푼 대상(pty 별명·
@@ -20,7 +21,6 @@
 //    상한(시도 3 · 2시간) → `gave-up`. 관측 = `loops.msg-wake` deferred | redelivered | gave-up.
 //    재두드림 «전»에 그 주소 미읽음을 잰다 — 0 이면 두드리지 않고 줄을 지운다(`dropped-read` · H4-FOLLOW ③).
 
-import { spawn } from 'node:child_process';
 import { Database } from 'bun:sqlite';
 import { randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
@@ -30,6 +30,7 @@ import { dirname, join } from 'node:path';
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
 import { readUnreadCount } from '../msg/msg-store.js';
+import { herdrPrompt, type HerdrCliRunner } from '../pty-shell/herdr-prompt.js';
 import { listPtyManifestRows } from '../pty-shell/pty-manifest.js';
 import { messageRouteFor, type MessageWake } from './msg-address.js';
 
@@ -75,8 +76,8 @@ export interface WakeDeps {
   hasOptIn?: (path: string) => boolean;
   /** Loads the pty writer (the CLI module is heavy, so it is imported only when a pty wake is due). */
   ptyInjector?: () => Promise<(ptyId: string, line: string) => Promise<void>>;
-  herdrStatus?: (paneId: string, signal: AbortSignal) => Promise<string>;
-  herdrInject?: (paneId: string, line: string, signal: AbortSignal) => Promise<void>;
+  /** The herdr CLI runner `herdrPrompt` drives (`agent get` · `pane run`). Default: the real `herdr` (HERDR_BIN_PATH · PATH). */
+  herdrRun?: HerdrCliRunner;
   warn?: (line: string) => void;
   /** Unread count for an address before a deferred re-knock (H4-FOLLOW ③). null = «모름» (never drops). Default: the msg ledger. */
   readUnread?: (address: string) => number | null;
@@ -178,29 +179,6 @@ function releaseClaim(claim: WakeClaim): void {
   } catch { /* a stale claim only delays the next wake by one window */ }
 }
 
-function run(cmd: string, args: string[], timeoutMs: number, signal: AbortSignal): Promise<string> {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted) { reject(new Error(`${cmd} aborted`)); return; }
-    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], signal });
-    let out = '';
-    const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error(`${cmd} timeout`)); }, timeoutMs);
-    child.stdout.on('data', chunk => { out += String(chunk); });
-    child.on('error', error => { clearTimeout(timer); reject(error); });
-    child.on('close', code => { clearTimeout(timer); code === 0 ? resolve(out) : reject(new Error(`${cmd} exit ${code}`)); });
-  });
-}
-
-async function defaultHerdrStatus(paneId: string, signal: AbortSignal): Promise<string> {
-  const parsed = JSON.parse(await run('herdr', ['pane', 'get', paneId], WAKE_TIMEOUT_MS, signal)) as { result?: { pane?: { agent_status?: unknown } } };
-  const status = parsed.result?.pane?.agent_status;
-  return typeof status === 'string' ? status : 'unknown';
-}
-
-async function defaultHerdrInject(paneId: string, line: string, signal: AbortSignal): Promise<void> {
-  // `pane run` = send-text ⊕ Enter 한 번에.
-  await run('herdr', ['pane', 'run', paneId, line], WAKE_TIMEOUT_MS, signal);
-}
-
 async function defaultPtyInjector(): Promise<(ptyId: string, line: string) => Promise<void>> {
   const { runPtyText } = await import('../cli/pty-takeover-cli.js');
   return async (ptyId, line) => {
@@ -261,17 +239,35 @@ export async function wakeRecipient(address: string, msgId: number, message: { f
         injecting = true;
         await inject(resolution.target!, line);
       } else {
-        const status = await (deps.herdrStatus ?? defaultHerdrStatus)(resolution.target!, controller.signal);
-        if (status !== 'idle') return done('busy', `agent_status=${status}`);
-        // 조회 사이 자리의 pane 이 바뀌었으면 옛 pane 에 넣지 않는다 — 주소→대상을 다시 푼다.
-        const again = resolveWake(address, deps);
-        // opt-in 은 주입 직전에 «먼저» 다시 본다 — 기다리는 사이 `wake-inject` 를 지웠으면(대상이 바뀌었어도) 주입 0.
-        if (!seatOptedIn(address, deps)) { resolution = { ...resolution, optIn: false }; return done('skipped', 'human-pane-no-opt-in'); }
-        if (again.wake !== 'herdr' || again.target !== resolution.target) return done('busy', `target-moved:${again.target ?? again.wake}`);
-        // ⛔ 마감은 «주입 바로 앞»에서 — 재해석이 늦어 넘겼어도 새 주입 0.
-        if (expired()) return done('timeout');
-        injecting = true;
-        await (deps.herdrInject ?? defaultHerdrInject)(resolution.target!, line, controller.signal);
+        // `eln herdr prompt` 와 같은 생산 함수 — 상태 확인(idle·done 만) → 제출 앞 관문 → bracketed `pane run` 한 번.
+        // 라벨은 묻지 않는다(anyAgent): 자리 폴더가 이미 대상을 정했고, claude/codex pane 도 예전처럼 깨운다.
+        const target = resolution.target!;
+        const prompted = await herdrPrompt({ target, text: line, anyAgent: true, paneFallback: true, timeoutMs: Math.max(1, deadline - Date.now()) }, {
+          ...(deps.herdrRun ? { run: deps.herdrRun } : {}),
+          beforeSubmit: () => {
+            // opt-in 은 주입 직전에 «먼저» 다시 본다 — 기다리는 사이 `wake-inject` 를 지웠으면(대상이 바뀌었어도) 주입 0.
+            if (!seatOptedIn(address, deps)) { resolution = { ...resolution, optIn: false }; return 'human-pane-no-opt-in'; }
+            // 조회 사이 자리의 pane 이 바뀌었으면 옛 pane 에 넣지 않는다 — 주소→대상을 다시 푼다.
+            const again = resolveWake(address, deps);
+            if (again.wake !== 'herdr' || again.target !== target) return `target-moved:${again.target ?? again.wake}`;
+            // ⛔ 마감은 «주입 바로 앞»에서 — 재해석이 늦어 넘겼어도 새 주입 0.
+            if (expired()) return 'timeout';
+            injecting = true;
+            return undefined;
+          },
+        });
+        if (!prompted.accepted) injecting = false;
+        const reason = prompted.reason;
+        const result: WakeResult = reason === 'submitted' ? 'injected'
+          : reason === 'human-pane-no-opt-in' ? 'skipped'
+            : reason === 'timeout' ? 'timeout'
+              : reason.startsWith('target-moved:') || reason === 'agent_working' || reason === 'agent_blocked' || reason === 'agent_unknown' ? 'busy'
+                : 'failed';
+        const outReason = result === 'busy' && !reason.startsWith('target-moved:') ? `agent_status=${prompted.status ?? 'unknown'}`
+          : result === 'injected' || result === 'timeout' ? undefined : reason;
+        logPending('herdr-prompt', { seat: address.trim().toUpperCase(), msgId, target, result, accepted: prompted.accepted, reason,
+          ...(prompted.status ? { status: prompted.status } : {}), ...(prompted.agent ? { agent: prompted.agent } : {}), ms: prompted.ms });
+        if (result !== 'injected') return done(result, outReason);
       }
       return done('injected');
     } catch (error) {
@@ -309,7 +305,7 @@ export async function wakeRecipient(address: string, msgId: number, message: { f
 
 interface PendingWakeRow { address: string; first_msg_id: number; last_msg_id: number; last_from: string; count: number; since: number; attempts: number; reason: string }
 
-export type PendingWakeEvent = 'deferred' | 'redelivered' | 'gave-up' | 'dropped-read' | 'skip';
+export type PendingWakeEvent = 'deferred' | 'redelivered' | 'gave-up' | 'dropped-read' | 'skip' | 'herdr-prompt';
 
 function logPending(event: PendingWakeEvent, data: Record<string, unknown>): void {
   try { debug.log('loops.msg-wake', event, data); } catch { /* observability is fail-open */ }

package/src/loops/orchestrator/anomaly-cluster.ts

@@ -0,0 +1,243 @@
+/**
+ * ANOMALY-CLUSTER-PRODUCT — repeated failure signatures hold relaunches.
+ *
+ * Reference contract (read-only, unchanged): `seat-state/OP/tools/anomaly-cluster.{sh,py}` groups the same
+ * failures for an OP seat by eye and never holds anything automatically. This module is the product
+ * transfer of that reading contract: it computes a signature and turns it into a hold/release decision.
+ *
+ * Boundary: when the SAME signature shows up in 3+ DIFFERENT runs, relaunches of that goal·host are held
+ * automatically until a cause verdict (`release`) clears them. The host is a hold key, never part of the
+ * signature. When there is nothing measured for a goal·host, the hold reason says so ("원천 미측정").
+ *
+ * Pure module: no fs, no network, no clock reads unless a `now` seam is injected.
+ */
+
+/** Runs of the same signature required before relaunches are held. */
+export const ANOMALY_HOLD_THRESHOLD = 3;
+
+/** Signature components: failure kind · container exit · stage · tail of `lastLines` reason. */
+export interface FailureObservation {
+  /** Goal identifier — a hold key, not part of the signature. */
+  goal: string;
+  /** Host (seat / surface / launch host) — a hold key, not part of the signature. */
+  host: string;
+  /** Run identifier — the unit counted as "a different run". */
+  runId: string;
+  /** Failure kind (`preflight` · `exit` · `timeout` · adapter name …). */
+  kind: string;
+  /** Container exit code when observed; `null`/absent when the failure never reached a container. */
+  containerExit?: number | null;
+  /** Stage the failure was observed at (`launch` · `delegate` · `monitor` …). */
+  stage: string;
+  /** Tail lines of the failure; the last non-empty line is the "reason tail" that splits signatures. */
+  lastLines?: readonly string[];
+  at?: string;
+}
+
+export interface HoldDecision {
+  /** `true` when relaunches of this goal·host are held. */
+  hold: boolean;
+  /** Korean explanation — includes "원천 미측정" when nothing was measured. */
+  reason: string;
+  signature?: string;
+  /** Distinct runs counted for the holding signature. */
+  runs?: number;
+}
+
+export interface ReleaseDecision {
+  released: boolean;
+  reason: string;
+}
+
+const REASON_TAIL_LIMIT = 160;
+
+/** Collapse whitespace and cap length — the reason tail is a signature component, not a payload. */
+function reasonTail(lines: readonly string[] | undefined): string {
+  if (!lines || lines.length === 0) return 'none';
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = (lines[i] ?? '').replace(/\s+/g, ' ').trim().replace(/^reason\s*[:=]\s*/i, '');
+    if (line) return line.slice(0, REASON_TAIL_LIMIT);
+  }
+  return 'none';
+}
+
+/** Pull a container exit code out of free text (`exited with code 137`, `exit status 1`, `exit=137`). */
+export function extractContainerExit(text: string): number | null {
+  const match = /(?:exit(?:ed)?(?: with)?(?: code| status)?|exit=)\s*[:=]?\s*(\d+)/i.exec(text ?? '');
+  if (!match) return null;
+  const value = Number.parseInt(match[1]!, 10);
+  return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Signature = kind · exit · stage · reason tail. Host and run are deliberately excluded: the host is a
+ * hold key and the run is the counter.
+ */
+export function failureSignature(obs: FailureObservation): string {
+  const exit = obs.containerExit === undefined || obs.containerExit === null ? 'none' : String(obs.containerExit);
+  return `kind=${obs.kind}|exit=${exit}|stage=${obs.stage}|reason=${reasonTail(obs.lastLines)}`;
+}
+
+interface ClusterState {
+  goal: string;
+  host: string;
+  signature: string;
+  runs: Set<string>;
+  held: boolean;
+  /** First `FailureObservation.at` read into this cluster — the observation window shown in the reason. */
+  firstAt?: string;
+  /** Latest `FailureObservation.at` read into this cluster. */
+  lastAt?: string;
+}
+
+function keyOf(goal: string, host: string): string {
+  return `${goal}\u0000${host}`;
+}
+
+/** In-memory grouping state — written by the failure observation point, read by the relaunch point. */
+export class AnomalyCluster {
+  private readonly threshold: number;
+  private readonly now: () => Date;
+  private readonly clusters = new Map<string, ClusterState>();
+  /**
+   * Observations of a DIFFERENT signature that arrived while its goal·host was held. They are kept
+   * counting in a side bucket so a late-arriving observation can never drop a hold before a cause
+   * verdict — the hold is only ever cleared by `release`.
+   */
+  private readonly parked = new Map<string, ClusterState>();
+
+  constructor(opts: { threshold?: number; now?: () => Date } = {}) {
+    this.threshold = Math.max(1, Math.trunc(opts.threshold ?? ANOMALY_HOLD_THRESHOLD));
+    this.now = opts.now ?? (() => new Date());
+  }
+
+  /** Record one failure observation and return the resulting hold decision for its goal·host. */
+  record(obs: FailureObservation): { signature: string; runs: number; hold: HoldDecision } {
+    const signature = failureSignature(obs);
+    const key = keyOf(obs.goal, obs.host);
+    const at = typeof obs.at === 'string' && obs.at.trim() ? obs.at.trim() : undefined;
+    let cluster = this.clusters.get(key);
+    if (cluster && cluster.signature !== signature && cluster.held) {
+      // Held: the signature is frozen until a cause verdict. A late observation of another signature is
+      // counted in the parked bucket — replacing the cluster here would silently drop the hold.
+      const parkedKey = keyOf(key, signature);
+      let parked = this.parked.get(parkedKey);
+      if (!parked) {
+        parked = { goal: obs.goal, host: obs.host, signature, runs: new Set(), held: false };
+        this.parked.set(parkedKey, parked);
+      }
+      this.touch(parked, obs.runId, at);
+      const held = this.describe(cluster);
+      return {
+        signature: cluster.signature,
+        runs: cluster.runs.size,
+        hold: {
+          ...held,
+          reason: `${held.reason} · 보류 중 도착한 다른 서명 ${parked.runs.size}건은 해제 없이 별도 보관(판정 뒤 재판정)`,
+        },
+      };
+    }
+    if (!cluster || cluster.signature !== signature) {
+      // Not held: a different signature takes over. A parked bucket of that same signature keeps its runs.
+      const parkedKey = keyOf(key, signature);
+      const resumed = this.parked.get(parkedKey);
+      for (const stale of [...this.parked.keys()]) {
+        if (stale !== parkedKey && stale.startsWith(`${key}\u0000`)) this.parked.delete(stale);
+      }
+      if (resumed) this.parked.delete(parkedKey);
+      cluster = resumed ?? { goal: obs.goal, host: obs.host, signature, runs: new Set(), held: false };
+      this.clusters.set(key, cluster);
+    }
+    this.touch(cluster, obs.runId, at);
+    return { signature, runs: cluster.runs.size, hold: this.describe(cluster) };
+  }
+
+  /** Relaunch gate. A hold is decided before any cause verdict; the reason names an unmeasured source. */
+  hold(goal: string, host: string): HoldDecision {
+    const cluster = this.clusters.get(keyOf(goal, host));
+    if (!cluster) {
+      return { hold: false, reason: `원천 미측정: ${goal}·${host} 의 실패 관측이 없다 — 보류 판정 근거 없음` };
+    }
+    return this.describe(cluster);
+  }
+
+  isHeld(goal: string, host: string): boolean {
+    return this.clusters.get(keyOf(goal, host))?.held ?? false;
+  }
+
+  /** Cause verdict — clears the hold. Returns `released: false` when nothing was held. */
+  release(goal: string, host: string, cause: string): ReleaseDecision {
+    const key = keyOf(goal, host);
+    const cluster = this.clusters.get(key);
+    if (!cluster || !cluster.held) {
+      return { released: false, reason: `${goal}·${host} 는 보류 상태가 아니다` };
+    }
+    const judged = cluster.signature;
+    const judgedRuns = cluster.runs.size;
+    cluster.held = false;
+    cluster.runs.clear();
+    cluster.firstAt = undefined;
+    cluster.lastAt = undefined;
+    const promoted = this.takeStrongestParked(key);
+    if (promoted) this.clusters.set(key, promoted);
+    const head = `보류 해제: ${cause} (${this.now().toISOString()}) — 판정한 서명 ${judged} ${judgedRuns}건`;
+    return {
+      released: true,
+      reason: promoted
+        ? `${head} · 보류 중 보관한 다른 서명 ${promoted.signature} ${promoted.runs.size}건을 재판정 대상으로 승격${promoted.held ? ' (임계 도달 — 새 서명 기준 재보류)' : ''}`
+        : head,
+    };
+  }
+
+  private touch(cluster: ClusterState, runId: string, at: string | undefined): void {
+    cluster.runs.add(runId);
+    if (at) {
+      cluster.firstAt ??= at;
+      cluster.lastAt = at;
+    }
+    if (cluster.runs.size >= this.threshold) cluster.held = true;
+  }
+
+  /** The parked bucket of this goal·host with the most runs — the next signature to judge. */
+  private takeStrongestParked(key: string): ClusterState | undefined {
+    let best: ClusterState | undefined;
+    let bestKey: string | undefined;
+    for (const [parkedKey, state] of this.parked) {
+      if (!parkedKey.startsWith(`${key}\u0000`)) continue;
+      if (!best || state.runs.size > best.runs.size) {
+        best = state;
+        bestKey = parkedKey;
+      }
+    }
+    if (best && bestKey) this.parked.delete(bestKey);
+    return best;
+  }
+
+  private describe(cluster: ClusterState): HoldDecision {
+    const runs = cluster.runs.size;
+    const window = cluster.firstAt ? ` · 관측 ${cluster.firstAt}${cluster.lastAt && cluster.lastAt !== cluster.firstAt ? `..${cluster.lastAt}` : ''}` : '';
+    if (cluster.held) {
+      return {
+        hold: true,
+        reason: `같은 서명 ${runs}건(임계 ${this.threshold}) — 원인 판정 전 ${cluster.goal}·${cluster.host} 재발사 보류${window}`,
+        signature: cluster.signature,
+        runs,
+      };
+    }
+    return {
+      hold: false,
+      reason: `같은 서명 ${runs}건 < 임계 ${this.threshold} — 보류하지 않는다${window}`,
+      signature: cluster.signature,
+      runs,
+    };
+  }
+}
+
+/** Process-wide cluster shared by the tick failure record point and the dispatcher relaunch gate. */
+let shared: AnomalyCluster | undefined;
+
+/** Lazily created shared instance — no fs side effects, process-wide by design. */
+export function defaultAnomalyCluster(): AnomalyCluster {
+  shared ??= new AnomalyCluster();
+  return shared;
+}