elanous 0.2.28 → 0.2.31

package/src/self-implement/run-ledger.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
 import { tracedPathReferences, verbatimOriginalAsk } from './goal-author.js';
@@ -20,6 +20,7 @@ export interface RunLedgerEntry {
   event: string;
   data: Record<string, unknown>;
   goalId?: string;
+  devProject?: string;
   orchestrationId?: string;
   shardId?: string;
   siblingShardIds?: string[];
@@ -260,6 +261,8 @@ export interface FederatedRunLedgerLookupOptions {
 
 export interface RunLedgerLookupOptions extends FederatedRunLedgerLookupOptions {
   all?: boolean;
+  /** Single-directory scope for the non-federated lookup; default = `runLedgerDir()`. */
+  dir?: string;
   list?: (path: string) => string[];
 }
 
@@ -306,7 +309,7 @@ export function loadFederatedRunLedger(runId: string, options: FederatedRunLedge
 }
 
 function lookupRunLedgerTargets(options: RunLedgerLookupOptions): RunLedgerLookupTarget[] {
-  return options.all ? resolveFederatedRunLedgerTargets(options) : [{ ledgerDirectory: runLedgerDir(), targetName: null }];
+  return options.all ? resolveFederatedRunLedgerTargets(options) : [{ ledgerDirectory: options.dir ?? runLedgerDir(), targetName: null }];
 }
 
 /** Find exact canonical IDs first; otherwise scan canonical ledger filenames for a normalized unique prefix. */
@@ -410,8 +413,12 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return;
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const live = runLedgerPath(entry.runId, dir);
+  const devProject = process.env.ELANOUS_DEV_PROJECT;
+  const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+    ? { ...entry, devProject }
+    : entry;
   withRunLedgerLock(dir, entry.runId, () => {
-    const line = `${JSON.stringify(entry)}\n`;
+    const line = `${JSON.stringify(row)}\n`;
     if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
   });
 }
@@ -433,6 +440,95 @@ export function recordHumanStoppedRun(runId: string, options: HumanStopRunLedger
   }, options.dir);
 }
 
+/** Ledger-recording options shared by the non-blocking observers — never part of the recorded entry payload. */
+export interface NonBlockingRunLedgerOptions {
+  /** 관측 시각 — 생략하면 now */
+  timestamp?: string;
+  /** 원장 디렉터리 — 생략하면 정본 run ledger dir */
+  dir?: string;
+}
+
+/** The settled-result payload a non-blocking request records under its requestId. */
+export interface NonBlockingRunResultLedgerEntry {
+  kind: string;
+  reason?: string;
+  /** 런이 실제로 산출한 next만 담는다 — 값이 없으면 키를 생략한다(unknown 보존). */
+  next?: string;
+  ok?: boolean;
+  runId?: string;
+}
+
+/**
+ * Record a non-blocking request's immediate pending state under its minted requestId.
+ * Event-kind naming follows the `recordHumanStoppedRun` observer-event precedent; never changes a run itself.
+ */
+export function recordNonBlockingRunPending(requestId: string, options: NonBlockingRunLedgerOptions = {}): void {
+  const recordedAt = options.timestamp ?? new Date().toISOString();
+  appendRunLedgerEntry({
+    timestamp: recordedAt,
+    runId: requestId,
+    event: 'non-blocking-pending',
+    data: { requestId, kind: 'pending', recordedAt },
+  }, options.dir);
+}
+
+/**
+ * Record a non-blocking request's settled result (kind·reason·next) under the same requestId.
+ * The payload is the second argument; ledger placement options (timestamp·dir) stay a separate third argument
+ * so no option ever leaks into the recorded entry (RunLedgerEntry format stays unchanged).
+ * Event-kind naming follows the `recordHumanStoppedRun` observer-event precedent; never changes a run itself.
+ */
+export function recordNonBlockingRunResult(
+  requestId: string,
+  entry: NonBlockingRunResultLedgerEntry,
+  options: NonBlockingRunLedgerOptions = {},
+): void {
+  const recordedAt = options.timestamp ?? new Date().toISOString();
+  appendRunLedgerEntry({
+    timestamp: recordedAt,
+    runId: requestId,
+    event: 'non-blocking-result',
+    data: {
+      requestId,
+      kind: entry.kind,
+      ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+      ...(entry.next === undefined ? {} : { next: entry.next }),
+      ...(entry.ok === undefined ? {} : { ok: entry.ok }),
+      ...(entry.runId === undefined ? {} : { runId: entry.runId }),
+      recordedAt,
+    },
+  }, options.dir);
+}
+
+/** The non-blocking request record a ledger carries for its runId; latest result wins over the pending entry. */
+export interface NonBlockingRunLedgerRecord {
+  requestId: string;
+  kind: string;
+  reason?: string;
+  /** next는 런이 실제로 산출한 값만 담는다 — 원장에 적힌 값이 없으면 이 키도 없다(unknown 보존). */
+  next?: string | null;
+}
+
+/** Read the non-blocking request record from an already-loaded ledger; null when the ledger carries none. */
+export function readNonBlockingRunRecord(ledger: readonly RunLedgerEntry[]): NonBlockingRunLedgerRecord | null {
+  let record: NonBlockingRunLedgerRecord | null = null;
+  for (const entry of ledger) {
+    if (entry.event === 'non-blocking-pending' && record === null) {
+      record = { requestId: entry.runId, kind: 'pending', next: null };
+      continue;
+    }
+    if (entry.event !== 'non-blocking-result' || typeof entry.data.kind !== 'string') continue;
+    const reason = typeof entry.data.reason === 'string' ? entry.data.reason : undefined;
+    record = {
+      requestId: entry.runId,
+      kind: entry.data.kind,
+      ...(reason === undefined ? {} : { reason }),
+      ...(typeof entry.data.next === 'string' ? { next: entry.data.next } : {}),
+    };
+  }
+  return record;
+}
+
 function parseRunLedgerEntry(line: string, lineNumber: number, expectedRunId: string): RunLedgerEntry {
   let parsed: unknown;
   try {
@@ -1210,6 +1306,8 @@ export interface UnfinishedRunLedgerEntry {
   lastActivityStatus: LastActivityStatus;
   /** ⭐ 「남은 것」을 «가려» 보여 주는 등급 — 종전엔 이 조회가 한 값뿐이라 회고에서 못 갈랐다. */
   lifecycle: UnfinishedRunLifecycle;
+  /** Non-blocking request record (kind·reason·next) carried by this runId's ledger; absent for runs without one. */
+  nonBlocking?: NonBlockingRunLedgerRecord;
 }
 
 export interface UnfinishedRunLedgerQuery {
@@ -1222,6 +1320,10 @@ export interface UnfinishedRunLedgerQuery {
   terminalByTrailingRunStatus?: number;
   cacheHits?: number;
   cacheMisses?: number;
+  /** Hits served by the persisted cross-process scan index (subset of cacheHits). */
+  indexHits?: number;
+  /** Whether that index was loaded from disk, started fresh, or was bypassed. */
+  indexOrigin?: RunLedgerScanIndexOrigin;
   pathFilter?: string;
   matchingPathCount?: number;
   unknownPathCount?: number;
@@ -1294,7 +1396,10 @@ function hasCanonicalRunStatus(ledger: readonly RunLedgerEntry[]): boolean {
 }
 
 /** Events that may follow a terminal run-status without reopening the run. Anything else stays unfinished. */
-export const TRAILING_BOOKKEEPING_EVENTS = ['pipeline-traversal-shadow', 'run-rollup', 'progress-delivery', 'progress-delivery-outcome'] as const;
+// `non-blocking-pending`/`non-blocking-result` are observer records of the non-blocking request
+// surface (#26634 칸 NONBLOCKING-RESULT-LEDGER). They carry the requestId result, never a run
+// lifecycle, so appending them after a terminal run-status must not reopen the run.
+export const TRAILING_BOOKKEEPING_EVENTS = ['pipeline-traversal-shadow', 'run-rollup', 'progress-delivery', 'progress-delivery-outcome', 'non-blocking-pending', 'non-blocking-result'] as const;
 
 const TRAILING_BOOKKEEPING_EVENT_SET = new Set<string>(TRAILING_BOOKKEEPING_EVENTS);
 
@@ -1559,6 +1664,7 @@ interface UnfinishedLedgerFacts {
   targetRoot: string | null;
   goalFile: string | null;
   fixedLifecycle: UnfinishedRunLifecycle;
+  nonBlocking: NonBlockingRunLedgerRecord | null;
 }
 
 // A full federated scan can exceed 5,000 files; keep the previous scan resident for mtime-checked reuse.
@@ -1577,6 +1683,96 @@ function unfinishedLedgerCacheKey(path: string, read?: RunLedgerReader): string
   return `${path}\u0000reader:${id}`;
 }
 
+// ⭐ 프로세스 간 유효 스캔 색인(칸 CONTEXT-NOW-RUN-SCAN-INDEX).
+//   `/now`(contextNowInWorker)는 요청마다 «새 워커 프로세스»를 띄우므로 위 프로세스 캐시는 매번 빈 채로 시작한다
+//   (실측 2026-10-14: scanned=7893, cacheHits=0, 조회 6.3~8.9초). 색인은 파싱된 파일별 facts 를
+//   원장 옆에 (size, mtimeMs) 스탬프로 저장하고, 스탬프가 같으면 재사용한다. 원장에 무엇이 «붙으면»
+//   스탬프가 바뀌므로 무효화는 자동이다. 읽기 실패는 전부 fail-soft: 색인이 없으면 그냥 새로 읽는다.
+const RUN_LEDGER_SCAN_INDEX_FILE = '.unfinished-scan-index.json';
+const RUN_LEDGER_SCAN_INDEX_VERSION = 1;
+const RUN_LEDGER_SCAN_INDEX_LIMIT = 32_768;
+
+/** Where the persisted scan index lives: beside its ledgers, never mistaken for one (readdir filters canonical names). */
+export function runLedgerScanIndexPath(dir: string): string {
+  return join(dir, RUN_LEDGER_SCAN_INDEX_FILE);
+}
+
+export interface RunLedgerScanIndexRecord {
+  size: number;
+  mtimeMs: number;
+  facts: UnfinishedLedgerFacts;
+}
+
+/** Whether the persisted index was loaded, started fresh, or was bypassed (noCache or an injected reader). */
+export type RunLedgerScanIndexOrigin = 'loaded' | 'fresh' | 'bypassed';
+
+const UNFINISHED_LIFECYCLE_WORDS = new Set<string>([
+  'live', 'orphaned', 'human-stopped', 'terminal-other-vocabulary', 'terminal-run-status-superseded', 'unjudgeable',
+]);
+
+function isScanIndexFacts(value: unknown): value is UnfinishedLedgerFacts {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const facts = value as Record<string, unknown>;
+  return typeof facts.terminal === 'boolean'
+    && typeof facts.terminalByTrailingRunStatus === 'boolean'
+    && (facts.branch === null || typeof facts.branch === 'string')
+    && (facts.lastActivityTimestamp === null || typeof facts.lastActivityTimestamp === 'string')
+    && typeof facts.lastActivityStatus === 'string'
+    && (facts.targetRoot === null || typeof facts.targetRoot === 'string')
+    && (facts.goalFile === null || typeof facts.goalFile === 'string')
+    && typeof facts.fixedLifecycle === 'string' && UNFINISHED_LIFECYCLE_WORDS.has(facts.fixedLifecycle);
+}
+
+function isScanIndexRecord(value: unknown): value is RunLedgerScanIndexRecord {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return Number.isFinite(record.size) && Number.isFinite(record.mtimeMs) && isScanIndexFacts(record.facts);
+}
+
+const scanIndexCache = new Map<string, { stamp: string; entries: Map<string, RunLedgerScanIndexRecord> }>();
+
+function scanIndexFileStamp(path: string): string {
+  try { const stat = statSync(path); return `${stat.size}:${stat.mtimeMs}`; } catch { return 'missing'; }
+}
+
+/** Load (memoized by index-file stamp) the persisted per-directory scan index; malformed or absent behaves as fresh. */
+export function loadRunLedgerScanIndex(dir: string): Map<string, RunLedgerScanIndexRecord> {
+  const path = runLedgerScanIndexPath(dir);
+  const stamp = scanIndexFileStamp(path);
+  const cached = scanIndexCache.get(dir);
+  if (cached && cached.stamp === stamp) return cached.entries;
+  const entries = new Map<string, RunLedgerScanIndexRecord>();
+  if (stamp !== 'missing') {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+      const raw = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        && (parsed as Record<string, unknown>).version === RUN_LEDGER_SCAN_INDEX_VERSION
+        && typeof (parsed as Record<string, unknown>).entries === 'object'
+        && (parsed as Record<string, unknown>).entries !== null && !Array.isArray((parsed as Record<string, unknown>).entries)
+        ? (parsed as { entries: Record<string, unknown> }).entries : null;
+      if (raw) for (const [runId, record] of Object.entries(raw)) {
+        if (isScanIndexRecord(record)) entries.set(runId, record);
+      }
+    } catch { /* a malformed index behaves as absent */ }
+  }
+  scanIndexCache.set(dir, { stamp, entries });
+  return entries;
+}
+
+/** Persist the index beside its ledgers, best-effort: any failure just leaves the next scan reading fresh. */
+function persistRunLedgerScanIndex(dir: string, entries: ReadonlyMap<string, RunLedgerScanIndexRecord>): boolean {
+  if (refuseProductionLedgerWriteInTest(dir, 'run-ledger-scan-index')) return false;
+  const bounded = entries.size > RUN_LEDGER_SCAN_INDEX_LIMIT
+    ? new Map([...entries].slice(entries.size - RUN_LEDGER_SCAN_INDEX_LIMIT))
+    : entries;
+  try {
+    writeFileSync(runLedgerScanIndexPath(dir), JSON.stringify({ version: RUN_LEDGER_SCAN_INDEX_VERSION, entries: Object.fromEntries(bounded) }), 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function unfinishedLedgerFacts(ledger: readonly RunLedgerEntry[]): UnfinishedLedgerFacts {
   const last = ledger.at(-1)?.timestamp;
   const lastActivityTimestamp = last !== undefined && Number.isFinite(Date.parse(last)) ? last : null;
@@ -1589,10 +1785,17 @@ function unfinishedLedgerFacts(ledger: readonly RunLedgerEntry[]): UnfinishedLed
     targetRoot: ledgerTargetRoot(ledger),
     goalFile: ledgerGoalDocument(ledger),
     fixedLifecycle: classifyUnfinishedLifecycle(ledger, null, 0),
+    nonBlocking: readNonBlockingRunRecord(ledger),
   };
 }
 
-function readUnfinishedLedgerFacts(runId: string, dir: string, read?: RunLedgerReader, noCache?: boolean): { facts: UnfinishedLedgerFacts; hit: boolean } {
+function readUnfinishedLedgerFacts(
+  runId: string,
+  dir: string,
+  read?: RunLedgerReader,
+  noCache?: boolean,
+  index?: Map<string, RunLedgerScanIndexRecord>,
+): { facts: UnfinishedLedgerFacts; hit: boolean; source: 'process' | 'index' | 'read' } {
   const path = runLedgerPath(runId, dir);
   const key = noCache ? null : unfinishedLedgerCacheKey(path, read);
   const stamp = noCache ? null : statSync(path);
@@ -1600,9 +1803,18 @@ function readUnfinishedLedgerFacts(runId: string, dir: string, read?: RunLedgerR
   if (cached && stamp && key !== null && cached.size === stamp.size && cached.mtimeMs === stamp.mtimeMs) {
     unfinishedLedgerCache.delete(key);
     unfinishedLedgerCache.set(key, cached);
-    return { facts: cached.facts, hit: true };
+    return { facts: cached.facts, hit: true, source: 'process' };
   }
   if (key !== null) unfinishedLedgerCache.delete(key);
+  // ⭐ 프로세스 캐시가 비었어도(새 워커) 디스크 색인의 스탬프가 같으면 재사용한다.
+  //   주입된 reader 는 실제 파일 내용과 무관한 대역이라 색인에 넣지 «도», 색인에서 읽지 «도» 않는다.
+  if (index !== undefined && stamp && read === undefined) {
+    const record = index.get(runId);
+    if (record && record.size === stamp.size && record.mtimeMs === stamp.mtimeMs) {
+      if (key !== null) unfinishedLedgerCache.set(key, { size: stamp.size, mtimeMs: stamp.mtimeMs, facts: record.facts });
+      return { facts: record.facts, hit: true, source: 'index' };
+    }
+  }
   try {
     const ledger = loadRunLedger(runId, dir, read);
     if (ledger === null && stamp !== null) throw new Error(`run ledger disappeared after stat: ${path}`);
@@ -1614,9 +1826,14 @@ function readUnfinishedLedgerFacts(runId: string, dir: string, read?: RunLedgerR
         if (unfinishedLedgerCache.size > UNFINISHED_LEDGER_CACHE_LIMIT) unfinishedLedgerCache.delete(unfinishedLedgerCache.keys().next().value!);
       }
     }
-    return { facts, hit: false };
+    if (index !== undefined && stamp !== null && read === undefined) {
+      index.set(runId, { size: stamp.size, mtimeMs: stamp.mtimeMs, facts });
+    }
+    return { facts, hit: false, source: 'read' };
   } catch (error) {
     if (key !== null) unfinishedLedgerCache.delete(key);
+    // 원장이 사라졌거나 바뀐 사이에 읽었다 — 색인의 스탬프는 이미 무효이므로 치운다(무효화).
+    index?.delete(runId);
     throw error;
   }
 }
@@ -1636,6 +1853,11 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
   const goalsDir = resolve(options.goalsDir ?? resolveGoalDocumentsDir(process.cwd()).directory);
   const list = options.list ?? readdirSync;
   const liveWindowMs = options.liveWindowMs ?? DEFAULT_UNFINISHED_LIVE_WINDOW_MS;
+  // ⭐ 색인은 noCache 나 주입된 reader 가 아니어야만 켠다 — 그 둘은 «정직한 재읽기» 계약을 지켜야 한다.
+  const scanIndex = !options.noCache && options.read === undefined ? loadRunLedgerScanIndex(dir) : undefined;
+  const indexOrigin: RunLedgerScanIndexOrigin = scanIndex === undefined ? 'bypassed' : scanIndex.size > 0 ? 'loaded' : 'fresh';
+  let indexHits = 0;
+  let indexChanged = false;
   let fileNames: string[];
   try {
     fileNames = list(dir);
@@ -1650,6 +1872,8 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
         terminalByTrailingRunStatus: 0,
         cacheHits: 0,
         cacheMisses: 0,
+        indexHits: 0,
+        indexOrigin,
         ...(options.path === undefined ? {} : { pathFilter: options.path, matchingPathCount: 0, unknownPathCount: 0 }),
         scope: 'self-implement-run-ledger',
         note: UNFINISHED_RUN_LEDGER_NOTE,
@@ -1662,6 +1886,8 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
         terminalByTrailingRunStatus: 0,
         cacheHits: 0,
         cacheMisses: 0,
+        indexOrigin,
+        indexHits: 0,
         ms: Date.now() - startedAt,
       });
       return missing;
@@ -1684,12 +1910,18 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     scanned += 1;
     let facts: UnfinishedLedgerFacts;
     try {
-      const observed = readUnfinishedLedgerFacts(runId, dir, options.read, options.noCache);
+      const observed = readUnfinishedLedgerFacts(runId, dir, options.read, options.noCache, scanIndex);
       facts = observed.facts;
-      if (observed.hit) cacheHits += 1;
-      else cacheMisses += 1;
+      if (observed.hit) {
+        cacheHits += 1;
+        if (observed.source === 'index') indexHits += 1;
+      } else {
+        cacheMisses += 1;
+        if (scanIndex !== undefined) indexChanged = true;
+      }
     } catch {
       cacheMisses += 1;
+      if (scanIndex?.delete(runId)) indexChanged = true;
       unreadableLedgerCount += 1;
       entries.push({ runId, branch: null, status: 'ledger-unreadable', plannedPaths: [], plannedPathStatus: 'unknown', ...unknownDeclaredPaths(), pathMatchReasons: {}, goalDocumentPath: null, goalLookupBasis: 'caller-cwd', goalDocumentSearchDirectory: null, lastActivityTimestamp: null, lastActivityAgeMs: null, lastActivityStatus: 'ledger-unreadable', lifecycle: 'unjudgeable' });
       callerCwdCount += 1;
@@ -1698,7 +1930,9 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     if (facts.terminal) {
       terminal += 1;
       if (facts.terminalByTrailingRunStatus) terminalByTrailingRunStatus += 1;
-      continue;
+      // A run carrying a non-blocking request record stays queryable by requestId even after its
+      // terminal run-status; runs without one keep the exact previous skip behavior.
+      if (!facts.nonBlocking) continue;
     }
 
     const branch = facts.branch;
@@ -1726,7 +1960,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
           : goalDocument.status === 'directory-unreadable'
             ? 'goal-directory-unreadable'
             : 'goal-document-not-found';
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus, ...unknownDeclaredPaths(), pathMatchReasons: {}, goalDocumentPath: null, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus, ...unknownDeclaredPaths(), pathMatchReasons: {}, goalDocumentPath: null, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
       continue;
     }
     try {
@@ -1734,12 +1968,13 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
       const text = typeof document === 'string' ? document : document.toString('utf8');
       const paths = [...new Set(tracedPathReferences(text).map((reference) => reference.path))];
       const declared = declaredPathsFromGoalDocument(text);
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: paths, plannedPathStatus: paths.length > 0 ? goalDocument.source === 'ledger' ? 'found-ledger-goal-file' : 'found-branch-fallback' : 'no-traced-paths', ...declared, pathMatchReasons: pathMatchReasons(declared.declaredPaths, paths), goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: paths, plannedPathStatus: paths.length > 0 ? goalDocument.source === 'ledger' ? 'found-ledger-goal-file' : 'found-branch-fallback' : 'no-traced-paths', ...declared, pathMatchReasons: pathMatchReasons(declared.declaredPaths, paths), goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
     } catch {
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus: 'goal-document-unreadable', declaredPaths: [], declaredPathStatus: 'goal-document-unreadable', pathMatchReasons: {}, goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus: 'goal-document-unreadable', declaredPaths: [], declaredPathStatus: 'goal-document-unreadable', pathMatchReasons: {}, goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
     }
   }
   entries.sort((left, right) => left.runId.localeCompare(right.runId));
+  if (scanIndex !== undefined && indexChanged) persistRunLedgerScanIndex(dir, scanIndex);
   debug.log('self-implement.run-ledger', 'goal-lookup-basis', { ledgerTarget: ledgerTargetCount, callerCwd: callerCwdCount });
   debug.log('self-implement.run-ledger', 'unfinished-query', {
     scanned,
@@ -1748,10 +1983,12 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     terminalByTrailingRunStatus,
     cacheHits,
     cacheMisses,
+    indexOrigin,
+    indexHits,
     ms: Date.now() - startedAt,
   });
   if (options.path === undefined) {
-    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
+    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
   }
   const pathFilter = options.path;
   const unknownPathStatus = (entry: UnfinishedRunLedgerEntry): boolean => entry.plannedPathStatus !== 'found-ledger-goal-file'
@@ -1771,6 +2008,8 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     terminalByTrailingRunStatus,
     cacheHits,
     cacheMisses,
+    indexHits,
+    indexOrigin,
     pathFilter,
     matchingPathCount: matchingEntries.length,
     unknownPathCount: unknownEntries.length,
@@ -1808,6 +2047,8 @@ export interface FederatedUnfinishedRunLedgerQuery {
   reconciledTerminatedElsewhereCount: number;
   cacheHits?: number;
   cacheMisses?: number;
+  /** Hits served by the persisted cross-process scan index (subset of cacheHits). */
+  indexHits?: number;
   pathFilter?: string;
   matchingPathCount?: number;
   unknownPathCount?: number;
@@ -1847,6 +2088,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   let unknownPathCount = 0;
   let cacheHits = 0;
   let cacheMisses = 0;
+  let indexHits = 0;
   const recordDirectoryFailure = (kind: FederatedLedgerDirectoryFailureKind): void => {
     if (kind === 'missing') missingLedgerDirectoryCount += 1;
     else if (kind === 'unreadable') unreadableLedgerDirectoryAccessCount += 1;
@@ -1872,6 +2114,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
       unknownPathCount += result.unknownPathCount ?? 0;
       cacheHits += result.cacheHits ?? 0;
       cacheMisses += result.cacheMisses ?? 0;
+      indexHits += result.indexHits ?? 0;
       entries.push(...result.entries.map((entry) => ({ ...entry, ledgerDirectory })));
     } catch (error) {
       recordDirectoryFailure(classifyFederatedLedgerDirectoryReadFailure(error));
@@ -1885,11 +2128,16 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   //   📏 실측(2026-08-11): 미완 57 중 ***7*** 이 다른 원장에 종결을 갖고 있었다.
   // ⛔ 판정 술어는 스캐너와 «같은 것»을 쓴다(`run-status` 또는 `terminal`) — 어휘를 새로 만들지 않는다.
   const terminatedElsewhere = new Set<string>();
-  const unfinishedRunIds = requestedRunIds === undefined ? new Set(entries.map((entry) => entry.runId)) : new Set([...requestedRunIds].filter((runId) => entries.some((entry) => entry.runId === runId)));
+  // Runs carrying a non-blocking request record never drop out of the union: their requestId
+  // reason·next must survive restarts and cross-directory reconciliation alike.
+  const unfinishedRunIds = requestedRunIds === undefined
+    ? new Set(entries.filter((entry) => !entry.nonBlocking).map((entry) => entry.runId))
+    : new Set([...requestedRunIds].filter((runId) => entries.some((entry) => entry.runId === runId && !entry.nonBlocking)));
   for (const runId of unfinishedRunIds) {
     for (const ledgerDirectory of ledgerDirectories) {
       try {
-        if (readUnfinishedLedgerFacts(runId, ledgerDirectory, undefined, options.noCache).facts.terminal) { terminatedElsewhere.add(runId); break; }
+        const reconciliationIndex = options.noCache ? undefined : loadRunLedgerScanIndex(ledgerDirectory);
+        if (readUnfinishedLedgerFacts(runId, ledgerDirectory, undefined, options.noCache, reconciliationIndex).facts.terminal) { terminatedElsewhere.add(runId); break; }
       } catch { /* An absent or unreadable sibling cannot establish termination. */ }
     }
   }
@@ -1910,6 +2158,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
     reconciledTerminatedElsewhereCount,
     cacheHits,
     cacheMisses,
+    indexHits,
     ...(options.path === undefined ? {} : { pathFilter: options.path, matchingPathCount, unknownPathCount }),
     scope: 'self-implement-run-ledger-federated',
     note: FEDERATED_UNFINISHED_RUN_LEDGER_NOTE,

package/src/self-implement/run-stop.ts

@@ -15,7 +15,7 @@ import { appendRunLedgerEntry, type RunLedgerEntry, type RunLedgerWriter, type R
 /** 닫힌 목록 — 못 고르면 `unclassified`. */
 export const RUN_STOP_CLASSES = [
   'env-unrelated', 'main-sync', 'pod-died', 'review-repeat',
-  'review-out-of-scope', 'evidence-uncovered', 'fabric', 'launch-failed', 'unclassified',
+  'review-out-of-scope', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed', 'unclassified',
 ] as const;
 export type RunStopClass = typeof RUN_STOP_CLASSES[number];
 
@@ -68,8 +68,9 @@ export function classifyMergeHoldStop(mergeReason: string | undefined): RunStopC
   return 'unclassified';
 }
 
-/** Pod exit 분류 사유 → 닫힌 목록. */
-export function classifyPodExitStop(reason: string | undefined): RunStopClass {
+/** Pod exit 분류 사유 → 닫힌 목록. `stage` 가 호스트 재게이트 실패(`host-regate-failed`)면 `gate-failed`, 인자가 없으면 지금과 똑같이. */
+export function classifyPodExitStop(reason: string | undefined, stage?: string): RunStopClass {
+  if (stage === 'host-regate-failed') return 'gate-failed';
   switch (reason) {
     case 'pod-failure': case 'pod-error': case 'OOMKilled': case 'ENOBUFS': case 'signal': return 'pod-died';
     case 'no-launch': return 'launch-failed';

package/src/self-implement/run-ttl.ts

@@ -5,7 +5,9 @@
  * Past `tools.selfImplement.runTtlHours` (default 24) since its last commit, the sweep makes one pre-emptive move:
  *   · live owning run → one resync memo in its control inbox (same path as SIBLING-RESYNC #24893/#24899),
  *                       at most once per (PR, head sha) — a rebase moves the head and re-arms it
- *   · no live run     → the registered `elanous:needs-rebase` label, once (QUIET-PR-COMMENTS: never a comment)
+ *   · no live run     → the registered `elanous:needs-rebase` label, once (QUIET-PR-COMMENTS: never a comment);
+ *                       when `requestRegate` is supplied, at most one of those stale PRs is also selected
+ *                       for a re-gate request (shadow: would-regate observation only; live: one call)
  *
  * Mode `tools.selfImplement.runTtl.mode`: `shadow` (default) only logs what it would do; `live` writes.
  * Cost bound: a PR opened inside the TTL is still inside its own time-to-landing and is never fetched
@@ -63,6 +65,8 @@ export interface RunTtlResult {
   readonly memo: readonly number[];
   /** Label added (live) or would be added (shadow). */
   readonly label: readonly number[];
+  /** Re-gate requested (live) or would be requested (shadow). Empty when the adapter is omitted. */
+  readonly regate: readonly number[];
   readonly alreadyMarked: readonly number[];
   readonly alreadyMemoed: readonly number[];
   /** Owning run lookup failed — left alone (a failed lookup is not a dead run). */
@@ -109,6 +113,8 @@ export async function runRunTtlSweep(input: {
   concurrency?: number;
   now?: () => number;
   log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  /** Optional: among stale PRs with no live run, request a re-gate for at most one per sweep. */
+  requestRegate?: (pr: RunTtlCandidate) => Promise<void> | void;
 }): Promise<RunTtlResult> {
   const { adapters } = input;
   const now = input.now ?? Date.now;
@@ -132,6 +138,7 @@ export async function runRunTtlSweep(input: {
   const stale: number[] = [];
   const memo: number[] = [];
   const label: number[] = [];
+  const regate: number[] = [];
   const alreadyMarked: number[] = [];
   const alreadyMemoed: number[] = [];
   const unresolved: number[] = [];
@@ -139,17 +146,17 @@ export async function runRunTtlSweep(input: {
   const skippedFetchCap: number[] = [];
   const failed: number[] = [];
   const result = (reason?: string): RunTtlResult => ({
-    mode, ttlHours, considered, freshByCreation, fetched, fresh, unknown, stale, memo, label, alreadyMarked,
+    mode, ttlHours, considered, freshByCreation, fetched, fresh, unknown, stale, memo, label, regate, alreadyMarked,
     alreadyMemoed, unresolved, skippedOverCap, skippedFetchCap, failed, durationMs: Math.max(0, now() - startedAt),
     ...(reason ? { reason } : {}),
   });
   const summary = (out: RunTtlResult): RunTtlResult => {
     emit('summary', {
       ttlHours, cap, maxFetch, concurrency, considered, freshByCreation, fetched, fresh,
-      unknown: unknown.length, stale: stale.length, memo: memo.length, label: label.length,
+      unknown: unknown.length, stale: stale.length, memo: memo.length, label: label.length, regate: regate.length,
       alreadyMarked: alreadyMarked.length, alreadyMemoed: alreadyMemoed.length, unresolved: unresolved.length,
       skippedOverCap: skippedOverCap.length, skippedFetchCap: skippedFetchCap.length, failed: failed.length,
-      memoPrs: memo, labelPrs: label, durationMs: out.durationMs, ...(out.reason ? { reason: out.reason } : {}),
+      memoPrs: memo, labelPrs: label, regatePrs: regate, durationMs: out.durationMs, ...(out.reason ? { reason: out.reason } : {}),
     });
     return out;
   };
@@ -200,6 +207,7 @@ export async function runRunTtlSweep(input: {
   }
   stalePrs.sort((a, b) => b.ageMs - a.ageMs || a.pr.number - b.pr.number);
   let actions = 0;
+  let selectedRegate = false;
   for (const { pr, target, ageMs } of stalePrs) {
     const ageHours = ageMs / 3_600_000;
     const key = `${pr.number}:${pr.headSha}`;
@@ -240,9 +248,15 @@ export async function runRunTtlSweep(input: {
       }
     }
     const reason = target.alive ? 'memo-failed' : target.reason;
+    const canRegate = Boolean(input.requestRegate) && !target.alive && !selectedRegate;
     if (mode === 'shadow') {
       label.push(pr.number);
       emit('would-label', { pr: pr.number, label: RUN_TTL_MARKER_LABEL, reason, ageHours: Math.floor(ageHours) });
+      if (canRegate) {
+        selectedRegate = true;
+        regate.push(pr.number);
+        emit('would-regate', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+      }
       continue;
     }
     try {
@@ -253,6 +267,16 @@ export async function runRunTtlSweep(input: {
       failed.push(pr.number);
       emit('label-failed', { pr: pr.number, error: String(error) });
     }
+    if (canRegate) {
+      selectedRegate = true;
+      try {
+        await input.requestRegate!(pr);
+        regate.push(pr.number);
+        emit('regate-requested', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+      } catch (error) {
+        emit('regate-failed', { pr: pr.number, error: String(error) });
+      }
+    }
   }
   return summary(result());
 }