elanous 0.2.29 → 0.2.32

package/src/steward/resync-tick.ts

@@ -1,11 +1,12 @@
 /** Resync labeled PRs before the steward's TA rejudge node sees their heads. */
 import { debug } from '../debug/log.js';
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { dlopen, FFIType } from 'bun:ffi';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { resolveHqLaunchSeat } from '../hq/seats.js';
-import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { effectiveInstanceRoot, normRoot, releaseLedgerRoot } from '../instance/resolve.js';
 import { runResyncShadow, type ResyncShadowSummary } from '../loops/orchestrator/resync-shadow.js';
 import { listSchedules, type ReleaseSchedule } from '../release-loop/release-schedule.js';
 
@@ -71,6 +72,90 @@ export function defaultResyncRun(
   execute: typeof runResyncShadow = runResyncShadow,
 ): Promise<ResyncShadowSummary> { return execute(3, { repoRoot }, 'live'); }
 
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+type FlockFn = (fd: number, op: number) => number;
+let flockFn: FlockFn | undefined;
+
+function osFlock(): FlockFn {
+  if (flockFn) return flockFn;
+  const names = process.platform === 'darwin'
+    ? ['/usr/lib/libSystem.B.dylib', 'libc.dylib']
+    : ['libc.so.6', `libc.musl-${process.arch === 'arm64' ? 'aarch64' : 'x86_64'}.so.1`];
+  let lastError: unknown;
+  for (const name of names) {
+    try {
+      const lib = dlopen(name, { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } });
+      flockFn = (fd, op) => lib.symbols.flock(fd, op) as number;
+      return flockFn;
+    } catch (error) { lastError = error; }
+  }
+  throw new Error(`OP seat flock unavailable (${names.join(', ')}): ${String(lastError)}`);
+}
+
+/**
+ * The one root every OP-seat locker resolves to (steward resync · manual resume · unattended release). It is the
+ * release ledger root — an explicit `--config-dir` universe, otherwise machine-wide prod — because the OP seat is
+ * machine-wide: a resync from a tree-derived test universe and a release run must still meet on the same lock file.
+ * An injected root (tests, a caller that already decided) is used as is. Normalized so `x` and `x/` share one inode.
+ */
+export function opSeatLockRoot(explicit?: string): string {
+  return normRoot(explicit ?? releaseLedgerRoot());
+}
+
+/** Persistent inode for the shared OP-seat kernel flock. Never unlink: a replacement inode would split lockers. */
+export function opSeatFlockPath(root?: string): string {
+  return join(opSeatLockRoot(root), 'steward', 'op-seat.flock');
+}
+
+export interface OpSeatFlock {
+  path: string;
+  release(): void;
+}
+
+/** Exclusive kernel flock covering OP-seat HEAD, index, and workfile mutation. Released on every exit, including throw. */
+export async function acquireOpSeatFlock(root?: string, waitMs = 120_000): Promise<OpSeatFlock> {
+  const path = opSeatFlockPath(root);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const flock = osFlock();
+  const fd = openSync(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+  let acquired = false;
+  try {
+    const stat = fstatSync(fd);
+    const current = lstatSync(path);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.ino !== current.ino || stat.dev !== current.dev) {
+      throw new Error('OP seat flock must be a private regular file (0600)');
+    }
+    const deadline = Date.now() + waitMs;
+    while (flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+      if (Date.now() >= deadline) throw new Error(`OP seat flock timed out: ${path}`);
+      await Bun.sleep(25);
+    }
+    acquired = true;
+    const locked = lstatSync(path);
+    if (stat.ino !== locked.ino || stat.dev !== locked.dev) throw new Error('OP seat flock changed');
+  } catch (error) {
+    try { if (acquired) flock(fd, LOCK_UN); } finally { closeSync(fd); }
+    throw error;
+  }
+  let released = false;
+  return {
+    path,
+    release() {
+      if (released) return;
+      released = true;
+      try { flock(fd, LOCK_UN); } finally { closeSync(fd); }
+    },
+  };
+}
+
+export async function withOpSeatFlock<T>(action: () => Promise<T> | T, root?: string): Promise<T> {
+  const held = await acquireOpSeatFlock(root);
+  try { return await action(); }
+  finally { held.release(); }
+}
+
 export async function resyncTick(
   run: () => Promise<ResyncShadowSummary> = () => defaultResyncRun(),
   log: (event: string, data: Record<string, unknown>) => void = (event, data) => debug.log('loop.steward', event, data),
@@ -84,32 +169,38 @@ export async function resyncTickWithReleaseProbe(
   releaseProbe: () => ReleaseRunState,
   windowProbe: () => ReleaseWindowState = releaseWindowState,
 ): Promise<ResyncTickResult> {
-  let result: ResyncTickResult;
+  // Acquisition failure (unreadable lock file, 120s timeout) is a tick failure: it takes the same
+  // `{ decision: 'failed' }` + log path as any other resync error instead of escaping to the caller.
+  let held: OpSeatFlock | undefined;
   try {
-    const release = releaseProbe();
-    if (release !== 'idle') {
-      result = { decision: 'skipped-release', reason: release === 'active' ? 'release run active' : 'release process probe unavailable' };
-    } else {
-      const window = windowProbe();
-      if (window !== 'outside') {
-        result = { decision: 'skipped-release-window', reason: window === 'inside' ? 'scheduled release window' : 'release schedule unavailable' };
+    let result: ResyncTickResult;
+    try {
+      held = await acquireOpSeatFlock();
+      const release = releaseProbe();
+      if (release !== 'idle') {
+        result = { decision: 'skipped-release', reason: release === 'active' ? 'release run active' : 'release process probe unavailable' };
       } else {
-        const summary = await run();
-        if (summary.saved > 0) {
-          mkdirSync(dirname(pendingPath), { recursive: true });
-          writeFileSync(pendingPath, JSON.stringify({ savedAt: new Date().toISOString() }));
+        const window = windowProbe();
+        if (window !== 'outside') {
+          result = { decision: 'skipped-release-window', reason: window === 'inside' ? 'scheduled release window' : 'release schedule unavailable' };
+        } else {
+          const summary = await run();
+          if (summary.saved > 0) {
+            mkdirSync(dirname(pendingPath), { recursive: true });
+            writeFileSync(pendingPath, JSON.stringify({ savedAt: new Date().toISOString() }));
+          }
+          result = { decision: 'ran', summary };
         }
-        result = { decision: 'ran', summary };
       }
     }
-  }
-  catch (error) { result = { decision: 'failed', reason: (error instanceof Error ? error.message : String(error)).slice(-300) }; }
-  try { log('resync-tick', { ...result }); }
-  catch (error) {
-    result = { decision: 'failed', reason: `log failed: ${error instanceof Error ? error.message : String(error)}`.slice(-300) };
-    console.error(`steward resync: ${result.reason}`);
-  }
-  return result;
+    catch (error) { result = { decision: 'failed', reason: (error instanceof Error ? error.message : String(error)).slice(-300) }; }
+    try { log('resync-tick', { ...result }); }
+    catch (error) {
+      result = { decision: 'failed', reason: `log failed: ${error instanceof Error ? error.message : String(error)}`.slice(-300) };
+      console.error(`steward resync: ${result.reason}`);
+    }
+    return result;
+  } finally { held?.release(); }
 }
 
 if (import.meta.main) {

package/src/steward/ta-repair-event-collect.ts

@@ -0,0 +1,158 @@
+/** Immediate TA repair collection. The card and atomic worker result remain authoritative. */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { spawnElanous } from '../instance/spawn-elanous.js';
+import { acquireLockSync } from '../storage/file-lock.js';
+import { subscribeInsideEvent, type InsideLiveEvent } from '../nexus/api/inside-events.js';
+import type { NexusEventBus } from '../nexus/api/event-bus.js';
+import { parseRepairWorkerResult } from '../task-agent/repair-worker.js';
+import { readTaskCard, taskAgentStatePath } from '../task-agent/task-hand.js';
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+const CARD = /^ta-[a-z0-9-]{1,80}$/;
+const TIMEOUT_MS = 10 * 60_000;
+const OUTPUT_LIMIT = 1024 * 1024;
+
+export interface TaRepairCompleted {
+  kind: 'ta.repair.completed'; schema: 1; card: string; pr: number; head: string;
+  runId: string; resultPath: string; completedAt: string;
+}
+
+export function parseTaRepairCompleted(value: unknown): TaRepairCompleted | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const v = value as Record<string, unknown>;
+  if (v.kind !== 'ta.repair.completed' || v.schema !== 1 || typeof v.card !== 'string' || !CARD.test(v.card)
+    || !Number.isSafeInteger(v.pr) || Number(v.pr) < 1 || typeof v.head !== 'string' || !SHA40.test(v.head)
+    || typeof v.runId !== 'string' || !/^run-[a-z0-9-]{1,100}$/i.test(v.runId)
+    || typeof v.resultPath !== 'string' || !v.resultPath.startsWith('/')
+    || typeof v.completedAt !== 'string' || !Number.isFinite(Date.parse(v.completedAt))) return null;
+  return v as unknown as TaRepairCompleted;
+}
+
+export interface TaRepairCollectDeps {
+  statePath?: string;
+  /** Test entry for a child that runs the real tasks CLI with isolated dependencies. */
+  cliBin?: string;
+  read?: (path: string) => string;
+  run?: (card: string) => Promise<{ code: number | null; output: string; truncated?: boolean }>;
+  now?: () => Date;
+  log?: (data: Record<string, unknown>) => void;
+}
+
+function defaultRun(card: string, statePath: string, cliBin?: string): Promise<{ code: number | null; output: string; truncated?: boolean }> {
+  return new Promise(done => {
+    const child = spawnElanous(['tasks', 'rejudge', card, '--json'], { stateDir: dirname(statePath),
+      ...(cliBin ? { bin: cliBin } : {}), stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    let truncated = false;
+    let settled = false;
+    let force: ReturnType<typeof setTimeout> | undefined;
+    const finish = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (force) clearTimeout(force);
+      done({ code, output, truncated });
+    };
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      // Keep the card lock until close confirms the child has stopped writing the card.
+      force = setTimeout(() => { child.kill('SIGKILL'); }, 5000);
+    }, TIMEOUT_MS);
+    const append = (chunk: unknown) => {
+      const next = output + String(chunk);
+      if (next.length > OUTPUT_LIMIT) { truncated = true; output = next.slice(-OUTPUT_LIMIT); }
+      else output = next;
+    };
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+    // Node emits close after error, including spawn failure. An error can also
+    // describe a failed kill while the child is still alive: keep the lock.
+    child.once('error', (error) => { append(`\nchild error: ${String(error)}`); });
+    child.once('close', finish);
+  });
+}
+
+function childConsumedRepair(output: string, event: TaRepairCompleted): boolean {
+  for (const line of output.split(/\r?\n/).reverse()) {
+    if (!line.trimStart().startsWith('[')) continue;
+    try {
+      const rows: unknown = JSON.parse(line);
+      if (Array.isArray(rows) && rows.some(row => row && typeof row === 'object' && row.card === event.card
+        && row.pr === event.pr && row.repairRunId === event.runId && row.repairHead === event.head
+        && row.step === 'repair' && (row.decision === 'repair-applied' || row.decision === 'repair-failed'))) return true;
+    } catch { /* not a JSON result line */ }
+  }
+  return false;
+}
+
+/** One event may start one card rejudge. A periodic rejudge can race; its existing card CAS still owns side effects. */
+export async function collectTaRepairCompleted(input: unknown, deps: TaRepairCollectDeps = {}): Promise<'invalid' | 'duplicate' | 'deferred' | 'collected'> {
+  const event = parseTaRepairCompleted(input);
+  if (!event) return 'invalid';
+  const statePath = deps.statePath ?? taskAgentStatePath();
+  const emit = (outcome: string, extra: Record<string, unknown> = {}) => {
+    const collectedAt = (deps.now?.() ?? new Date()).toISOString();
+    const data = { card: event.card, pr: event.pr, runId: event.runId, completedAt: event.completedAt,
+      collectedAt, ...(outcome === 'collected' ? { latencyMs: Date.parse(collectedAt) - Date.parse(event.completedAt) } : {}),
+      delivery: 'event', outcome, ...extra };
+    try { (deps.log ?? ((d) => debug.log('task-agent', 'ta.repair.collected', d)))(data); } catch { /* observability cannot change the result */ }
+  };
+  let card;
+  try { card = readTaskCard(event.card, statePath); } catch { emit('deferred', { reason: 'card unreadable' }); return 'deferred'; }
+  const repair = Array.isArray(card?.repairs) ? card.repairs.find(entry => entry && typeof entry === 'object' && entry.runId === event.runId) : undefined;
+  if (!repair || repair.pr !== event.pr || typeof repair.head !== 'string' || repair.head.toLowerCase() !== event.head.toLowerCase()
+    || typeof repair.resultPath !== 'string' || !repair.resultPath.startsWith('/')
+    || resolve(repair.resultPath) !== resolve(event.resultPath)) { emit('invalid', { reason: 'event differs from card binding' }); return 'invalid'; }
+  if (repair.status !== 'requested') { emit('duplicate', { reason: `repair ${repair.status}` }); return 'duplicate'; }
+  let result;
+  try { result = parseRepairWorkerResult((deps.read ?? ((path) => readFileSync(path, 'utf8')))(repair.resultPath), event.pr, event.head, event.runId); }
+  catch { /* periodic tick can recover a missing result */ }
+  if (!result) { emit('deferred', { reason: 'worker result missing or invalid' }); return 'deferred'; }
+
+  // Existing PID-aware lock recovers a dead daemon without making later events wait forever.
+  // A live holder keeps the lock through the child process; the card CAS covers periodic-tick races.
+  const lock = join(dirname(statePath), 'steward', 'ta-repair-collect', `${event.card}.lock`);
+  let release: () => void;
+  try {
+    mkdirSync(dirname(lock), { recursive: true });
+    release = acquireLockSync(lock, { breakDeadHolder: true, staleMs: TIMEOUT_MS + 60_000, maxTries: 2 });
+  }
+  catch { emit('deferred', { reason: 'collector busy; periodic fallback remains' }); return 'deferred'; }
+  try {
+    // Recheck after claiming: another collector or the periodic tick may have consumed the file.
+    const current = readTaskCard(event.card, statePath);
+    const latest = Array.isArray(current?.repairs) ? current.repairs.find(entry => entry && typeof entry === 'object' && entry.runId === event.runId) : undefined;
+    if (!latest || latest.status !== 'requested' || latest.pr !== event.pr || typeof latest.head !== 'string'
+      || latest.head.toLowerCase() !== event.head.toLowerCase() || typeof latest.resultPath !== 'string'
+      || !latest.resultPath.startsWith('/') || resolve(latest.resultPath) !== resolve(event.resultPath)) { emit('duplicate'); return 'duplicate'; }
+    const child = await (deps.run ?? ((card) => defaultRun(card, statePath, deps.cliBin)))(event.card);
+    const after = readTaskCard(event.card, statePath)?.repairs?.find(entry => entry.runId === event.runId);
+    const consumed = child.code === 0 && !child.truncated && after?.status !== 'requested' && after !== undefined
+      && childConsumedRepair(child.output, event);
+    const outcome = consumed ? 'collected' : child.truncated ? 'deferred' : after && after.status !== 'requested' ? 'duplicate' : 'deferred';
+    emit(outcome, { rc: child.code, repairStatus: after?.status,
+      ...(child.truncated ? { reason: 'rejudge output exceeded 1 MiB; event attribution unmeasured' } : {}),
+      detail: child.output.slice(-300) });
+    return consumed ? 'collected' : outcome === 'duplicate' ? 'duplicate' : 'deferred';
+  } catch (error) {
+    emit('deferred', { reason: String(error).slice(-300) });
+    return 'deferred';
+  } finally { release(); }
+}
+
+/** Bridge child-process inside events to Nexus pub/sub; keep the handler nonblocking. */
+export function startTaRepairEventCollector(bus: NexusEventBus, deps: TaRepairCollectDeps = {}): () => void {
+  const unsubscribeBus = bus.subscribe(event => {
+    void collectTaRepairCompleted(event.detail, deps).catch(error => {
+      try { debug.log('task-agent', 'ta.repair.collect-error', { reason: String(error).slice(-300) }, { level: 'warn' }); }
+      catch { /* observer failure cannot reject the Nexus callback */ }
+    });
+  }, ['ta.repair.completed']);
+  const unsubscribeInside = subscribeInsideEvent((event: InsideLiveEvent) => {
+    if (event.kind !== 'ta.repair.completed') return;
+    bus.publish({ kind: 'ta.repair.completed', ts: Date.now(), detail: event as unknown as Record<string, unknown> });
+  });
+  return () => { unsubscribeInside(); unsubscribeBus(); };
+}

package/src/steward/triage.ts

@@ -24,6 +24,7 @@ import { CardStore } from '../task-cards/card-store.js';
 import { draftWithinBudget, triageWithinBudget } from './triage-budget.js';
 import { askSteward, classifyIssue, installedCapabilities, planIssues, ruleJudgment, unsafeReason, type ClassifiedIssue, type StewardAsk } from './triage-plan.js';
 import { failureAlertText, markStageStart, markStageEnd, readFailureStreak, shouldAlert, writeFailureStreak, type FailureStreak, type StewardStage } from './failure-streak.js';
+import { briefVerdictChange } from './digest-delivery.js';
 
 export type Rung = 0 | 1 | 2 | 3 | 4 | 5 | 'hitl';
 /** `other` = the judge chose human review for a reason outside the four named ones (kept as HITL, never downgraded). */
@@ -56,6 +57,8 @@ export interface StewardDeps {
   judge?: (issue: TriageIssue, issues: TriageIssue[], tracks?: Record<string, string>) => Promise<unknown>;
   decide?: typeof emitDecision;
   sendDigest?: (text: string) => Promise<void>;
+  /** 흐름 판정 변화 브리핑 한 줄 발송(OVW-BRIEF) — 생략하면 킨드 `ops-report`(운영 봇)이 기본. */
+  sendBrief?: (text: string) => Promise<void>;
   now?: () => Date;
   root?: string;
   cardStore?: StewardCardDeps['store'];
@@ -602,6 +605,13 @@ export async function runStewardStage(stage: 'sync' | 'triage' | 'schedule' | 'r
       writeFileSync(path, JSON.stringify(state));
       digested = true;
     }
+    try {
+      await briefVerdictChange(root, { send: deps.sendBrief });
+    } catch (error) {
+      const message = `steward report: verdict brief failed: ${redactSecretText(error instanceof Error ? error.message : String(error))}`;
+      debug.log('steward.verdict-brief', 'failed', { error: message });
+      (deps.warn ?? console.warn)(message);
+    }
     const launched = readLaunchDecision(root);
     if (launched) logTickDecision(root, launched.verdict, launched.reason, launched.goalId);
     else if (outcomes.length || digested) logTickDecision(root, 'reported', outcomes.length ? `${outcomes.length} outcome(s) reported` : 'daily digest sent');

package/src/surface/shell-runner-boot.ts

@@ -7,7 +7,7 @@ interface BackgroundSurfaceLike<Handle> {
 
 export interface DashboardShellRunnerBootDeps<Handle> {
   createBackgroundSurface: (deps: {
-    onUpdate: (rollup: { running: number; backgrounded: number }) => void;
+    onUpdate: (rollup: { running: number; backgrounded: number; background: number }) => void;
   }) => BackgroundSurfaceLike<Handle>;
   initShellRegistry: (deps: {
     onRegister: (handle: Handle) => void;
@@ -19,7 +19,7 @@ export interface DashboardShellRunnerBootDeps<Handle> {
     registry: ShellRegistryLike<Handle>;
     fileEngine?: unknown;
   }): void;
-  setLatestShellRollup: (rollup: { running: number; backgrounded: number }) => void;
+  setLatestShellRollup: (rollup: { running: number; backgrounded: number; background: number }) => void;
 }
 
 export function bootDashboardShellRunner<Handle>(
@@ -30,6 +30,9 @@ export function bootDashboardShellRunner<Handle>(
       deps.setLatestShellRollup({
         running: rollup.running,
         backgrounded: rollup.backgrounded,
+        // TUI-BG-JOB-VISIBILITY — turn-outliving jobs (bg mode ⊕ backgrounded).
+        //   Required: guessing it from `backgrounded` would under-count running bg-mode jobs.
+        background: rollup.background,
       });
     },
   });

package/src/task-agent/card-evidence.ts

@@ -76,7 +76,27 @@ export function podChildRunIds(host: readonly RunLedgerEntry[] | null, runId?: s
     && RUN_ID.test(entry.data.childRunId) && entry.data.childRunId !== runId).map((entry) => entry.data.childRunId as string))];
 }
 
-/** 순수 — 카드 런의 골 id · PR. PR 은 호스트 → 자식(나중 자식 먼저) → job-finished 순으로 처음 찾은 것. */
+/**
+ * TA-BIND-PR-TERMINAL — 부모(호스트) 원장의 `pr-terminal{childRunId, prNumber, prUrl}`(draft-residue `applyPodTerminal`).
+ * gate-failed draft 자식은 `pr-opened` 없이 `rework-blocked-draft-pr`·`pr.comment.mode` 만 남겨서, PR 근거는 부모의 이 줄뿐이다.
+ * 자식은 부모의 `pod-child-run` 자식이어야 하고, url 은 같은 번호의 PR 주소여야 한다. 나중 줄이 먼저다.
+ */
+export function podTerminalPr(host: readonly RunLedgerEntry[] | null, childRunIds: readonly string[]): { number: number; url: string; childRunId: string } | undefined {
+  const children = new Set(childRunIds);
+  for (let at = (host?.length ?? 0) - 1; at >= 0; at--) {
+    const entry = host![at]!;
+    if (entry.event !== 'pr-terminal') continue;
+    const childRunId = entry.data?.childRunId;
+    const number = entry.data?.prNumber;
+    const url = entry.data?.prUrl;
+    if (typeof childRunId !== 'string' || !children.has(childRunId) || !Number.isSafeInteger(number) || (number as number) <= 0
+      || typeof url !== 'string' || PR_URL.exec(url)?.[1] !== String(number)) continue;
+    return { number: number as number, url, childRunId };
+  }
+  return undefined;
+}
+
+/** 순수 — 카드 런의 골 id · PR. PR 은 호스트 → 자식(나중 자식 먼저) → 호스트 `pr-terminal` → job-finished 순으로 처음 찾은 것. */
 export function bindCardEvidence(card: Pick<TaskCard, 'runId'>, snapshot: CardRunSnapshot): CardRunEvidence {
   if (!card.runId || !snapshot.host) return { ledgerFound: false };
   const children = podChildRunIds(snapshot.host, card.runId).reverse();
@@ -88,6 +108,10 @@ export function bindCardEvidence(card: Pick<TaskCard, 'runId'>, snapshot: CardRu
     const found = entries ? lastPr(entries) : undefined;
     if (found) { pr = found; childRunId = id; }
   }
+  if (!pr) {
+    const terminal = podTerminalPr(snapshot.host, children);
+    if (terminal) { pr = { number: terminal.number, url: terminal.url }; childRunId = terminal.childRunId; }
+  }
   for (const id of children) {
     if (pr) break;
     const finish = [...(snapshot.podFinishes ?? [])].reverse().find((row) => row.childRunId === id && PR_URL.test(row.prUrl));

package/src/task-agent/green-sweep.ts

@@ -19,6 +19,7 @@ export interface GreenSweepPr {
   state: string;
   mergeSha?: string;
   url?: string;
+  viaTrain?: { integrationPr: number };
 }
 export interface GreenSweepDecision {
   cell: string;
@@ -112,7 +113,8 @@ export function decideGreenSweep(input: {
   const { item, candidate, pr } = input;
   const mergeSha = pr?.mergeSha && /^[a-f0-9]{40}$/i.test(pr.mergeSha) ? pr.mergeSha : null;
   const result = (verdict: GreenSweepVerdict, reason: string): GreenSweepDecision => {
-    const evidence = `GREEN-FROM-LEDGER: PR #${candidate.pr}${mergeSha ? ` merged ${mergeSha}` : ''} · ${verdict} · ${reason}`;
+    const landing = pr?.viaTrain ? ` via train #${pr.viaTrain.integrationPr}` : '';
+    const evidence = `GREEN-FROM-LEDGER: PR #${candidate.pr}${landing}${mergeSha ? ` merged ${mergeSha}` : ''} · ${verdict} · ${reason}`;
     return { cell: item.id, pr: candidate.pr, mergeSha, source: candidate.source, verdict, reason,
       evidence, existingEvidence: item.evidence ?? '', plannedEvidence: appendGreenSweepEvidence(item.evidence, evidence) };
   };
@@ -122,6 +124,9 @@ export function decideGreenSweep(input: {
   if (input.repositoryMatches === false) return result('skip', 'repository-mismatch');
   if (input.repositoryMatches !== true) return result('record-only', 'repository-unreadable');
   if (pr.state !== 'MERGED') return result('skip', `pr-${pr.state.toLowerCase()}`);
+  if (pr.viaTrain && (candidate.card?.trainLanding?.componentPr !== candidate.pr
+    || candidate.card.trainLanding.integrationPr !== pr.viaTrain.integrationPr
+    || candidate.card.trainLanding.mergeSha !== pr.mergeSha)) return result('skip', 'train-binding-mismatch');
   if (!mergeSha) return result('skip', 'merge-sha-unreadable');
   if (input.ancestor === null) return result('record-only', 'origin-main-ref-unverified');
   if (!input.ancestor) return result('skip', 'merge-sha-not-on-origin-main');
@@ -159,8 +164,8 @@ export function decideGreenSweep(input: {
   if (typeof card.pr === 'object' && pr.url && card.pr.url
     && card.pr.url.replace(/\/+$/, '') !== pr.url.replace(/\/+$/, ''))
     return result('record-only', 'card-pr-url-mismatch');
-  if (card.prTerminal?.state === 'CLOSED') return result('record-only', 'card-terminal-conflict');
-  return result('green', card.postLand?.outcome === 'complete' ? 'bound-card-complete' : 'bound-card-merged');
+  if (card.prTerminal?.state === 'CLOSED' && !pr.viaTrain) return result('record-only', 'card-terminal-conflict');
+  return result('green', card.postLand?.outcome === 'complete' ? 'bound-card-complete' : pr.viaTrain ? 'bound-card-train-merged' : 'bound-card-merged');
 }
 
 /** Every candidate emits one structured decision, including refusals. */

package/src/task-agent/judge.ts

@@ -24,6 +24,8 @@ export interface TaskJudgeInput {
   stopReason?: SupervisorStopReason;
   prState?: 'OPEN' | 'MERGED' | 'CLOSED';
   pr?: string | number;
+  /** Complete PR target paths when measured. Unknown is omitted, never treated as zero code diff. */
+  prTargetPaths?: readonly string[];
   /** `self review --json` 판정. 관측 못 했으면 비운다(«통과»로 읽지 않는다). */
   review?: 'pass' | 'fail';
   mustFix?: readonly string[];
@@ -36,6 +38,42 @@ export interface TaskJudgeInput {
   evidence?: { ok: boolean; ref: string };
   /** Only classified terminal evidence; an absent input preserves the existing stop-reason table. */
   terminalRun?: { kind: typeof STOP_CLASS_POD_FAILURE | typeof STOP_CLASS_NO_LAUNCH; reason: string; hasPr: boolean; hasHarvestBranch: boolean };
+  /**
+   * 같은 칸(checklistId)의 앞 런들 — 재발사 계열 수를 고르기 «전»에 받는 «선례»(RFC adaptive-graph-ops §9.10).
+   * 없으면 지금 표 그대로(입력이 비어도 동작한다 — RUN-TAG-REWORK 가 원장에 서명을 달면 여기 입력이 된다).
+   */
+  precedents?: readonly TaskPrecedent[];
+  /** 판정 관측 훅 — `task-agent.judge` 이벤트에 precedent {matched, priorRunId, signature} 를 싣는다. 없으면 관측 없이 종전 동작. */
+  observe?: (event: 'task-agent.judge', data: { precedent: { matched: boolean; priorRunId?: string; signature?: string } }) => void;
+}
+
+/** 같은 칸의 앞 런 한 건 — 결말(outcome)과 must-fix 서명. `outcome: 'alternative-failed'` 는 «대안도 같은 서명으로 실패했다»는 예약 결말이다. */
+export interface TaskPrecedent {
+  runId: string;
+  outcome: string;
+  signature: string;
+}
+
+/** must-fix 서명의 분류 축(남은 must-fix 의 성격) — 해시에 함께 박는다. */
+export const MUST_FIX_CLASSIFICATION = 'implementation-deficit';
+
+/**
+ * 남은 must-fix 원문을 정규화(공백 접기·trim·정렬)한 해시 ⊕ 분류 — 같은 칸의 앞 런과 비교하는 «서명».
+ * must-fix 가 비면 서명도 없다(선례 비교 없음).
+ */
+export function mustFixSignature(mustFix?: readonly string[]): string | undefined {
+  const normalized = [...(mustFix ?? [])]
+    .map(fix => (typeof fix === 'string' ? fix.trim().replace(/\s+/gu, ' ') : ''))
+    .filter(Boolean)
+    .sort();
+  if (!normalized.length) return undefined;
+  let hash = 0x811c9dc5;
+  const text = `${MUST_FIX_CLASSIFICATION}:${JSON.stringify(normalized)}`;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return `fnv1a-${hash.toString(16).padStart(8, '0')}`;
 }
 
 export interface TaskJudgement {
@@ -83,12 +121,22 @@ const RETRY_MOVE_OF_VARIANT: Record<RetryVariant, LiveRetryMove> = {
   alternative: 'alternative',
 };
 
+/** Only a measured complete file list can establish zero implementation target diff. */
+export function isGoalOnlyPr(paths: readonly string[] | undefined): boolean {
+  return paths !== undefined && paths.every((path) => /^docs\/goals\/[^/]+(?:\/.*)?$/.test(path));
+}
+
 /** 실행부 `retry` 가 어느 수인가 — 갈래 없는 재발사(리뷰 fail 의 must-fix 재발사)는 «좁혀 재발사»다. */
 export function retryMoveOf(variant?: RetryVariant): LiveRetryMove {
   return RETRY_MOVE_OF_VARIANT[variant ?? 'narrow'];
 }
 
 function base(input: TaskJudgeInput): Omit<TaskJudgement, 'executorKind'> {
+  // A goal document is a launch artifact. Its PR cannot prove implementation progress,
+  // even when the PR has merged. Waiting also prevents the same goal's live retry.
+  if (input.pr && isGoalOnlyPr(input.prTargetPaths)) {
+    return { move: 'wait', stage: 'escalated', reason: `goal-only-pr — PR ${input.pr} target diff 0; 같은 골 재큐 중지·구현 근거 필요` };
+  }
   if (input.deliveryEvidence) return input.deliveryEvidence.ok
     ? { move: 'propose-green', stage: 'closing', reason: `전달 근거 확인: ${input.deliveryEvidence.files.join(', ')}` }
     : { move: 'wait', stage: 'waiting', reason: input.deliveryEvidence.reason };
@@ -139,16 +187,34 @@ function base(input: TaskJudgeInput): Omit<TaskJudgement, 'executorKind'> {
 /** 재발사 계열 — 대안(alternative)이 실패한 «같은 실패 흐름»에 속하는 수. */
 const RETRY_FAMILY: ReadonlySet<TaskMove> = new Set<TaskMove>(['narrow-relaunch', 'wait-retry', 'salvage-relaunch']);
 
+/**
+ * 선례가 «같은 수로 재발사»를 막는 수 — narrow·salvage·그 자신(alternative).
+ * 대기 후 재시도(wait-retry)는 «같은 수로 재발사»가 아니므로 선례 승격에서는 제외.
+ */
+const PRECEDENT_RELAUNCH_FAMILY: ReadonlySet<TaskMove> = new Set<TaskMove>(['narrow-relaunch', 'salvage-relaunch']);
+
 /**
  * 종료 어휘·관측에서 다음 한 수를 고른다. 같은 수 2회 실패 → 다른 수 → 그것도 실패 → 결정 카드.
  *
  * ⭐ 새 관측이 이긴다(사후 리뷰 must-fix · #24453): 병합된 PR(propose-green)·종료 미관측(wait)·표 밖 어휘(decision-card)는
  * 실패 셈과 무관하게 그대로 간다. 「대안도 실패 → 결정 카드」 승격은 지금 수가 같은 실패 흐름일 때만 —
  * 재발사 계열이거나, 그 수 자신이 이미 같은 수 한도만큼 실패했을 때다.
+ *
+ * ⭐ 선례(RFC adaptive-graph-ops §9.10): 이번 런의 must-fix 서명이 앞 런 서명과 같으면 같은 수로 재발사하지 않는다 —
+ * narrow/salvage → alternative, alternative 자신(또는 선례 결말이 `alternative-failed`)이면 결정 카드.
+ * 선례가 없으면 지금 표 그대로.
  */
 export function judgeNextMove(input: TaskJudgeInput): TaskJudgement {
   const failures = input.failures ?? {};
   let judged = base(input);
+  const signature = mustFixSignature(input.mustFix);
+  // 같은 서명 일치 «전체»를 스캔한다 — `alternative-failed` 유무는 목록 어느 위치에 있든 먼저 판정한다(anyMatch 우선, 순서 무관).
+  const sameSignature = signature !== undefined
+    ? (input.precedents ?? []).filter(prec => typeof prec?.signature === 'string' && prec.signature === signature
+      && typeof prec?.runId === 'string' && prec.runId !== '')
+    : [];
+  const matched = sameSignature[0];
+  input.observe?.('task-agent.judge', { precedent: { matched: matched !== undefined, priorRunId: matched?.runId, signature } });
   const escalatable = judged.move !== 'wait' && judged.move !== 'decision-card' && judged.move !== 'propose-green';
   const exhausted = escalatable && (failures[judged.move] ?? 0) >= SAME_MOVE_FAILURE_LIMIT;
   const inFailingFlow = RETRY_FAMILY.has(judged.move) || exhausted;
@@ -157,6 +223,16 @@ export function judgeNextMove(input: TaskJudgeInput): TaskJudgement {
   } else if (exhausted) {
     judged = { move: 'alternative', stage: 'repairing', reason: `같은 수 ${SAME_MOVE_FAILURE_LIMIT}회 실패 — 다른 수 선택 (${judged.move})` };
   }
+  // 선례 승격 — 실패 승격 다음: 이번 수가 같은 서명 앞 런의 수와 겹치지 않게 한다(같은 수로 재발사 차단).
+  if (matched !== undefined && (PRECEDENT_RELAUNCH_FAMILY.has(judged.move) || judged.move === 'alternative')) {
+    if (judged.move === 'alternative' || sameSignature.some(prec => prec.outcome === 'alternative-failed')) {
+      judged = { move: 'decision-card', stage: 'escalated',
+        reason: `같은 must-fix 서명 선례 ${matched.runId} — 대안도 같은 서명으로 실패 — 사람 결정 (서명 ${signature})` };
+    } else {
+      judged = { move: 'alternative', stage: 'repairing',
+        reason: `같은 must-fix 서명 선례 ${matched.runId} — 같은 수로 재발사하지 않고 다른 수 선택 (서명 ${signature})` };
+    }
+  }
   const executorKind = EXECUTOR_KIND[judged.move];
   const executorVariant = EXECUTOR_VARIANT[judged.move];
   if (!executorKind) return judged;