elanous 0.2.34 → 0.2.35

package/graphs/research-loop.yaml

@@ -9,7 +9,8 @@
 
 graph_id: research-loop
 version: 5
-entry_node: investigate
+journey_stages: [entry, author, dispatch, run, land, recover, end]
+entry_node: intake
 terminal_nodes: [landed, needs-human]
 runner_inputs: [goal, worktree, branch, review-intent, head-sha, base-branch, ask, context, prior]
 # ⛔ 키 이름은 파서(`src/self-implement/graph-yaml.ts:201`)가 아는 것뿐이다 — 다른 이름은 «조용히» 무시된다.
@@ -121,7 +122,122 @@ nodes:
   - { node_id: landed, kind: gate, recipe: none, max_visits: 1 }
   - { node_id: needs-human, kind: gate, recipe: none, max_visits: 1 }
 
+  # Entry and Pod dispatch reuse the existing ARG-UNIT-LIB units.
+  - node_id: intake
+    kind: observe
+    recipe: harness-entrance
+    journey_stage: entry
+    max_visits: 1
+    contract: { inputs: [ask, context, prior], tools: read-only, outputs: [route, reason] }
+  - node_id: queue
+    kind: gate
+    recipe: harness-queue
+    journey_stage: entry
+    max_visits: 1
+    contract: { inputs: [goal], tools: read-only, outputs: [queue_status, card_id] }
+  - node_id: launch-gate
+    kind: gate
+    recipe: pre-launch-gate
+    journey_stage: entry
+    max_visits: 1
+    contract: { inputs: [goal], tools: read-only, outputs: [decision, reason] }
+  - node_id: entry-unit
+    kind: subgraph
+    recipe: none
+    journey_stage: entry
+    max_visits: 1
+    call: entry@1
+    budget: { inner_steps: 4 }
+    contract: { inputs: [ask, context, prior], tools: read-only, outputs: [result, evidence] }
+  - node_id: dispatch
+    kind: judge
+    recipe: harness-substrate-select
+    journey_stage: dispatch
+    max_visits: 2
+    contract: { inputs: [launch_decision], tools: read-only, outputs: [substrate] }
+  - node_id: pool-admit
+    kind: gate
+    recipe: pod-pool-admission
+    journey_stage: dispatch
+    max_visits: 4
+    contract: { inputs: [goal, substrate], tools: read-only, outputs: [admission, reason] }
+  - node_id: dispatch-pod-unit
+    kind: subgraph
+    recipe: none
+    journey_stage: dispatch
+    max_visits: 4
+    call: dispatch-pod@1
+    budget: { inner_steps: 4 }
+    contract: { inputs: [ask, context, prior], tools: worktree-write, outputs: [result, evidence] }
+  - node_id: freeze-check
+    kind: gate
+    recipe: landing-freeze-admission
+    journey_stage: land
+    max_visits: 4
+    contract: { inputs: [worktree, changed-files], tools: read-and-run-tests, outputs: [decision, reason] }
+  - node_id: hold
+    kind: hitl
+    recipe: frozen-merge-queue
+    journey_stage: land
+    max_visits: 4
+    contract: { inputs: [pr-number, freeze-state], tools: human-selection, outputs: [decision] }
+  - node_id: cleanup
+    kind: git
+    recipe: post-merge-cleanup
+    journey_stage: land
+    max_visits: 1
+    contract: { inputs: [pr-number, merge-sha, worktree], tools: git-write, outputs: [cleaned, worktree] }
+  - node_id: result-parse
+    kind: observe
+    recipe: pod-failure-reason
+    journey_stage: recover
+    max_visits: 4
+    contract: { inputs: [failure-log], tools: read-only, outputs: [failure-class, evidence] }
+  - node_id: salvage
+    kind: git
+    recipe: salvage-branch
+    journey_stage: recover
+    max_visits: 4
+    contract: { inputs: [worktree, branch], tools: git-write, outputs: [salvage-branch, ref] }
+  - node_id: heal
+    kind: judge
+    recipe: heal-intake
+    journey_stage: recover
+    max_visits: 4
+    contract: { inputs: [failure-class, evidence], tools: read-only, outputs: [repair-plan, reason] }
+  - node_id: next-move
+    kind: judge
+    recipe: task-agent-judge
+    journey_stage: recover
+    max_visits: 4
+    contract: { inputs: [repair-results, card-state], tools: read-only, outputs: [next-action, reason] }
+  - node_id: ready
+    kind: gate
+    recipe: none
+    journey_stage: land
+    max_visits: 1
+    contract: { inputs: [pr-number, head-sha], tools: read-only, outputs: [ready, reason] }
+  - node_id: pr-head-checkout
+    kind: gate
+    recipe: none
+    journey_stage: land
+    max_visits: 1
+    contract: { inputs: [pr-number, worktree], tools: git-write, outputs: [checked-out-head, worktree] }
+
 edges:
+  - { from: intake, on: outcome, map: { queued: queue, direct: launch-gate, ok: launch-gate, fail: needs-human } }
+  - { from: queue, on: outcome, map: { launched: launch-gate, waiting: needs-human, refused: needs-human, ok: launch-gate, fail: needs-human } }
+  - { from: launch-gate, on: outcome, map: { pass: entry-unit, refuse: needs-human, ok: entry-unit, fail: needs-human } }
+  - from: entry-unit
+    on: outcome
+    map: { done: dispatch, rework: investigate, needs-human: needs-human, failed: needs-human }
+  - from: dispatch
+    on: outcome
+    map: { local: investigate, pod: pool-admit, fresh: investigate, pr-source: pool-admit, ok: investigate, fail: needs-human }
+  - { from: pool-admit, on: outcome, map: { admitted: dispatch-pod-unit, refused: needs-human, ok: dispatch-pod-unit, fail: needs-human } }
+  - from: dispatch-pod-unit
+    on: outcome
+    map: { done: investigate, rework: investigate, needs-human: needs-human, failed: result-parse }
   # ⛔⭐ 유일하게 implement-loop 과 «다른» 자리 — gate 를 «건너뛸 수 있다».
   #   조건은 코드가 낸다: 변경 파일에 «코드»가 있나(routeGate). 못 세면 «돈다»(fail-safe).
   - from: investigate
@@ -161,11 +277,29 @@ edges:
     to: open-pr
 
   - from: open-pr
-    to: merge
+    to: freeze-check
+  - from: freeze-check
+    on: outcome
+    map: { open: merge, frozen: hold, taken: needs-human, ok: merge, fail: needs-human }
+  - from: hold
+    to: freeze-check
 
   - from: merge
     on: outcome
-    map: { merged: landed, land-refused: recover, ok: needs-human, fail: needs-human }
+    map: { merged: cleanup, land-refused: recover, draft: ready, head-branch: pr-head-checkout, not-ancestor: main-sync, review-missing: judge, other: next-move, ok: needs-human, fail: needs-human }
+  - from: cleanup
+    to: landed
+  - from: result-parse
+    to: salvage
+  - from: salvage
+    to: heal
+  - from: heal
+    to: next-move
+  - { from: ready, to: next-move }
+  - { from: pr-head-checkout, to: next-move }
+  - from: next-move
+    on: outcome
+    map: { narrow-relaunch: dispatch, salvage-relaunch: dispatch, alternative: dispatch, wait-retry: dispatch, decision-card: needs-human, wait: needs-human, ok: needs-human, fail: needs-human }
 
   # The train/TA owns retry effects; the unit only classifies the refusal.
   - from: recover

package/graphs/test-diet/test-diet.yaml

@@ -1,5 +1,8 @@
 # TD2 — daily test review (shadow): pick a cost-weighted slice from the cursor ledger, measure each file alone on a
 # remote host, judge mechanically, append one ledger line «#a~#b» and draft a card. It never deletes or moves a test.
+# pick weighs the gate's own failure history (preexisting · knownEnv · flaky · repeated introduced) on top of cost, so
+# the files most likely to fail come first; record turns each verdict into exactly one T1~T7 prescription card draft and
+# writes the slice's preexisting ⊕ knownEnv totals (with their delta) into the same ledger line. Deletion stays human.
 # Inputs: budgetSecs (default 1800) · remote (default node-b) · mirror (default ~/mirror/elanous-agent.git)
 graph_id: test-diet
 loop:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elanous",
   "mcpName": "io.github.ElanvitalAI/elanous",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "description": "Self-healing coding harness where eyes, hands, and memory all turn on one sentence — it authors its own goals, implements them in isolated worktrees, and reviews its own work.",
   "license": "Apache-2.0",
   "author": "Elanvital AI",

package/scripts/coord-role-pack.ts

@@ -21,9 +21,17 @@ export interface RolePack {
 
 const KNOWHOW_PATH = 'docs/roles/OP/KNOWHOW.md';
 
+/**
+ * 카드 제목 문법은 src/seat-loop/knowhow-lint.ts 의 CARD_HEADING 과 같아야 한다.
+ * 다르면 린트가 카드로 못 본 제목이 자를 때 조용히 사라지거나, 번호만 잘려 엉뚱한 아이디로 제외 기록에 남는다.
+ */
+const CARD_HEADING = /^[ \t]{0,3}##\s+(K-[A-Za-z]+-\d+)(?=$|\s|:|—)(.*)$/u;
+const CARD_HEADING_LIKE = /^[ \t]{0,3}##\s*(K-[^\s:]*)/iu;
+const SECTION_HEADING = /^[ \t]{0,3}##\s/u;
+
 /**
  * KNOWHOW.md 를 `##` 제목 단위 카드로 자른다(코드 울타리 안은 본문으로 본다).
- * 유효한 `## K-<role>-<number>` 제목을 가진 카드만 반환한다.
+ * 린트 문법을 지킨 `## K-<role>-<number>` 제목만 카드로 반환하고, 카드처럼 보이지만 문법을 벗어난 제목은 파일 단위 린트처럼 실패한다.
  */
 export function splitKnowhowCards(body: string): Array<{ id: string; title: string; text: string }> {
   const segments: Array<{ heading: string | null; lines: string[] }> = [{ heading: null, lines: [] }];
@@ -40,7 +48,7 @@ export function splitKnowhowCards(body: string): Array<{ id: string; title: stri
       segments.at(-1)!.lines.push(line);
       continue;
     }
-    if (/^##\s/u.test(line)) {
+    if (SECTION_HEADING.test(line)) {
       segments.push({ heading: line, lines: [] });
       continue;
     }
@@ -49,9 +57,14 @@ export function splitKnowhowCards(body: string): Array<{ id: string; title: stri
   const cards: Array<{ id: string; title: string; text: string }> = [];
   for (const segment of segments) {
     if (!segment.heading) continue;
-    const heading = segment.heading.match(/^##\s+(K-[A-Za-z]+-\d+)\s*(.*)$/u);
-    if (!heading) continue;
-    cards.push({ id: heading[1]!, title: heading[2]!.trim(), text: [segment.heading, ...segment.lines].join('\n') });
+    const heading = segment.heading.match(CARD_HEADING);
+    if (!heading) {
+      // 카드처럼 보이는 제목이 문법을 벗어나면 통과도 제외 기록도 불가능하다 — 조용히 빼지 않고 그 자리에서 실패한다.
+      const like = segment.heading.match(CARD_HEADING_LIKE);
+      if (like) throw new KnowhowLintError(KNOWHOW_PATH, like[1]!, '카드 제목 형식이 K-<자리>-<번호>를 벗어남');
+      continue;
+    }
+    cards.push({ id: heading[1]!, title: heading[2]!.replace(/^[:\s—]+/u, '').trim(), text: [segment.heading, ...segment.lines].join('\n') });
   }
   return cards;
 }
@@ -141,7 +154,7 @@ export function buildCoordRolePackManifest(role: RolePackRole, root = resolve(im
   // The pack body is inline. Source docs only contribute hashes, so an installed package without them still builds.
   const present = SOURCE_PATHS.filter((path) => existsSync(resolve(repo, path)));
   const missingSources = SOURCE_PATHS.filter((path) => !present.includes(path));
-  const sources = present.map((path) => ({ path, sha256: sha256(readFileSync(resolve(repo, path), 'utf8')) }));
+  const sources: RolePack['sources'] = present.map((path) => ({ path, sha256: sha256(readFileSync(resolve(repo, path), 'utf8')) }));
   const knowhow = collectVerifiedKnowhow(repo);
   if (knowhow.fileBody !== null) sources.push({ path: KNOWHOW_PATH, sha256: sha256(knowhow.fileBody) });
   const packageJson = resolve(repo, 'package.json');

package/scripts/hq/standby-snapshot.ts

@@ -198,28 +198,33 @@ export const SURVIVAL_VALUE_FLAGS = ['--survival-keep', '--survival-keep-daily',
 
 /** Throw when a survival-keep / prune-survival flag is present without its value/target — same rule as `${flag} requires a value`. */
 export function assertSurvivalKeepArgs(argv: string[]): void {
-  for (const flag of SURVIVAL_VALUE_FLAGS) {
-    for (let i = 0; i < argv.length; i += 1) {
-      const token = argv[i];
-      if (token.startsWith(`${flag}=`)) {
-        if (token === `${flag}=`) throw new Error(`${flag} requires a value`);
-        continue;
-      }
-      if (token !== flag) continue;
-      const value = argv[i + 1];
-      if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    const equalsAt = token.indexOf('=');
+    const flag = equalsAt < 0 ? token : token.slice(0, equalsAt);
+    if (!SURVIVAL_VALUE_FLAGS.some(candidate => candidate === flag)) continue;
+    if (equalsAt >= 0) {
+      if (token.slice(equalsAt + 1).length === 0) throw new Error(`${flag} requires a value`);
+      continue;
     }
+    const value = argv[i + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
   }
 }
 
-if (import.meta.main) {
-  const argv = process.argv.slice(2);
+function preflightStandbySnapshotArgs(argv: string[]): void {
+  // Preflight survival argument values before tier selection, staging, or snapshot work.
   try {
     assertSurvivalKeepArgs(argv);
   } catch (error) {
     console.error(`standby-snapshot: ${String(error)}`);
     process.exit(2);
   }
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  preflightStandbySnapshotArgs(argv);
   const val = (k: string) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : undefined; };
   const tier = (val('--tier') ?? 'core') as Tier;
   if (tier !== 'core' && tier !== 'big' && tier !== 'obs') { console.error('--tier core|big|obs'); process.exit(2); }

package/scripts/release-loop/docs-land-node.ts

@@ -1,14 +1,28 @@
 #!/usr/bin/env bun
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { listChecklist } from '../../src/release-loop/checklist.js';
 import type { ReleaseManifest } from '../../src/release-loop/manifest.js';
 import { recordDocsFollow, type DocsFollowItem } from './release-docs.js';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { errorResult, finishNode, nodeOutput, readGraphContext, runCommand, type CommandRunner } from './node-verdict.js';
+import { errorResult, finishNode, nodeOutput, readGraphContext, runCommand, type CommandRunner, type GraphContext } from './node-verdict.js';
 import { prereleaseKind } from './release-version.js';
 
+function isRunOwnedDocsPrefetchTree(worktree: string, context: GraphContext, ledgerRoot: string): boolean {
+  const runId = context.runId;
+  if (!runId || !/^[A-Za-z0-9._-]+$/.test(runId)) return false;
+  const prefetchRoot = join(ledgerRoot, 'graph-runs', 'release-loop', `${runId}.json.contexts`, 'docs-prefetch');
+  try {
+    // Resolve symlinks too: an in-run path that points outside this run does not establish ownership.
+    const owner = realpathSync(prefetchRoot);
+    const tree = realpathSync(worktree);
+    return dirname(tree) === owner && /^tree(?:-[0-9a-f-]{36})?$/.test(basename(tree));
+  } catch {
+    return false;
+  }
+}
+
 export function runDocsLand(run: CommandRunner = runCommand, stateRoot = effectiveInstanceRoot(), ledgerRoot = releaseLedgerRoot()) {
   const context = readGraphContext();
   const version = context.input.version;
@@ -18,7 +32,9 @@ export function runDocsLand(run: CommandRunner = runCommand, stateRoot = effecti
   if (branch !== `release-docs/${version}`) throw new Error('docs branch/version mismatch');
   const worktree = nodeOutput(context, 'docs', 'worktree');
   const scratch = dirname(worktree);
-  if (dirname(scratch) !== tmpdir() || !/^release-docs-[A-Za-z0-9]+$/.test(scratch.split('/').at(-1) ?? '') || worktree !== join(scratch, 'tree')) throw new Error('invalid docs worktree');
+  const tmpWorktree = dirname(scratch) === tmpdir() && /^release-docs-[A-Za-z0-9]+$/.test(basename(scratch))
+    && worktree === join(scratch, 'tree');
+  if (!tmpWorktree && !isRunOwnedDocsPrefetchTree(worktree, context, ledgerRoot)) throw new Error('invalid docs worktree');
   const recordFollow = (deployed: boolean) => {
     const releaseDir = join(stateRoot, 'release', version);
     const manifest: ReleaseManifest = JSON.parse(readFileSync(join(releaseDir, 'manifest.json'), 'utf8'));
@@ -88,7 +104,7 @@ export function runDocsLand(run: CommandRunner = runCommand, stateRoot = effecti
       const remove = run('git', ['worktree', 'remove', '--force', worktree]);
       if (remove.status !== 0) throw new Error(`docs worktree cleanup failed: ${remove.stderr}`);
     }
-    rmSync(scratch, { recursive: true, force: true });
+    if (tmpWorktree) rmSync(scratch, { recursive: true, force: true });
     // 배포 성공 — 후속 기록 실패(manifest 없음 등)는 결과를 «실패»로 바꾸지 않는다. 알리고 넘어간다.
     let follow: ReturnType<typeof recordFollow> | undefined;
     try { follow = recordFollow(true); }

package/scripts/release-loop/gate-baseline-receipt.ts

@@ -0,0 +1,155 @@
+/** A full gate's reusable identity. Missing evidence is recorded, never promoted to a clean baseline. */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { gateTestBaseline } from '../lib/gate-test-env.js';
+
+const SHA256 = /^[0-9a-f]{64}$/i;
+const IMAGE_DIGEST = /^sha256:[0-9a-f]{64}$/i;
+export const POD_SWEEP_INTEGRATION_ONLY: readonly string[] = ['scripts/install.test.ts', 'scripts/review-model-ab.test.ts'];
+
+/** Reconstruct the producer's tracked test selection at its pinned commit. Missing Git evidence is not a smaller set. */
+export function gateAssignableTestsAtCommit(repo: string, commit: string): string[] | null {
+  if (!/^[0-9a-f]{40}$/i.test(commit)) return null;
+  const tree = spawnSync('git', ['ls-tree', '-r', '--name-only', commit], { cwd: repo, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  const cdp = spawnSync('git', ['grep', '-l', '-e', 'requireCdpBase', '-e', '9333', commit, '--', 'test', 'scripts'],
+    { cwd: repo, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  if (tree.status !== 0 || tree.error || (cdp.status !== 0 && cdp.status !== 1) || cdp.error) return null;
+  const cdpFiles = new Set(cdp.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(commit.length + 1))
+    .filter((file) => file.endsWith('.test.ts')));
+  return tree.stdout.split(/\r?\n/).filter((file) => /\.test\.(?:tsx?|jsx?|mts|cts)$/.test(file)
+    && !cdpFiles.has(file) && !POD_SWEEP_INTEGRATION_ONLY.includes(file)
+    && !file.split('/').some((part) => part.startsWith('.'))).sort();
+}
+
+export interface GateBaselineReceipt {
+  schema: 1;
+  valid: boolean;
+  reason: string;
+  version: string;
+  commit: string;
+  graphSha: string | null;
+  recipeSha: string | null;
+  envFingerprint: string;
+  imageDigest: string | null;
+  files: number;
+  shards: number;
+}
+
+/** A direct hard rehearsal has no graph run state. Pin the graph and recipe bytes at its Git SHA. */
+export function gateSourcePins(repo: string, commit: string): { graphSha: string; recipeSha: string } | null {
+  if (!/^[0-9a-f]{40}$/i.test(commit)) return null;
+  const read = (file: string): string | null => {
+    const result = spawnSync('git', ['show', `${commit}:${file}`], { cwd: repo, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+    return result.status === 0 && !result.error ? result.stdout : null;
+  };
+  const graph = read('graphs/release/release-loop.yaml');
+  const recipe = read('graphs/release/recipes.yaml');
+  return graph === null || recipe === null ? null : {
+    graphSha: createHash('sha256').update(graph).digest('hex'),
+    recipeSha: createHash('sha256').update(recipe).digest('hex'),
+  };
+}
+
+/** Only Kubernetes' observed child container imageID is evidence; the requested image tag is not. */
+export function actualGatePodImageDigest(podJson: string): string | null {
+  try {
+    const pods = JSON.parse(podJson) as { items?: Array<{ status?: { containerStatuses?: Array<{ name?: string; imageID?: string }> } }> };
+    // A retry can create more than one Pod; collected test bytes are not bound to one of their UIDs.
+    if (pods.items?.length !== 1) return null;
+    const id = pods.items[0]?.status?.containerStatuses?.find((row) => row.name === 'child')?.imageID;
+    const digest = typeof id === 'string' ? /(?:^|@|:\/\/)(sha256:[0-9a-f]{64})$/i.exec(id)?.[1] : undefined;
+    return digest && IMAGE_DIGEST.test(digest) ? digest.toLowerCase() : null;
+  } catch { return null; }
+}
+
+export function gateEnvFingerprint(env: NodeJS.ProcessEnv): string {
+  const baseline = gateTestBaseline(env);
+  return createHash('sha256').update(JSON.stringify(Object.fromEntries(Object.entries(baseline).sort(([a], [b]) => a.localeCompare(b))))).digest('hex');
+}
+
+/** Graph runner pins these bytes in its run state. A direct gate without that state cannot mint a reusable receipt. */
+export function gateGraphPins(root: string, runId: string | undefined): { graphSha: string; recipeSha: string } | null {
+  if (!runId || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId)) return null;
+  try {
+    const state = JSON.parse(readFileSync(join(root, 'graph-runs', 'release-loop', `${runId}.json`), 'utf8')) as
+      { graphId?: string; runId?: string; graphSnapshot?: { graphSha?: string; recipesSha?: string } };
+    const graphSha = state.graphSnapshot?.graphSha;
+    const recipeSha = state.graphSnapshot?.recipesSha;
+    return state.graphId === 'release-loop' && state.runId === runId && graphSha && recipeSha
+      && SHA256.test(graphSha) && SHA256.test(recipeSha) ? { graphSha, recipeSha } : null;
+  } catch { return null; }
+}
+
+export function gateBaselineReceipt(input: { root: string; version: string; commit: string; fullSweep: boolean;
+  graphPins: { graphSha: string; recipeSha: string } | null; envFingerprint: string }): GateBaselineReceipt {
+  const { root, version, commit, graphPins, envFingerprint } = input;
+  const base = { schema: 1 as const, version, commit, graphSha: graphPins?.graphSha ?? null,
+    recipeSha: graphPins?.recipeSha ?? null, envFingerprint, imageDigest: null as string | null, files: 0, shards: 0 };
+  const invalid = (reason: string): GateBaselineReceipt => ({ ...base, valid: false, reason });
+  if (!input.fullSweep) return invalid('gate was not a complete clean full sweep');
+  if (!graphPins) return invalid('pinned graph or recipe SHA absent');
+  if (!SHA256.test(envFingerprint)) return invalid('gate environment fingerprint absent');
+  try {
+    const dir = join(root, 'release', version, 'gate-logs', 'cut');
+    if (!existsSync(dir)) return invalid('cut Pod logs absent');
+    const names = readdirSync(dir).filter((name) => /^pod-\d+(?:-[\w-]+)?\.json$/.test(name));
+    const roots = new Map<number, { files: string[]; shardCount: number; sweepId: string; attemptId: string }>();
+    const descendants: Array<{ name: string; commit?: string; imageDigest?: string; sweepId?: string; parentAttempt?: string; attemptId?: string }> = [];
+    const images = new Set<string>();
+    for (const name of names) {
+      const row = JSON.parse(readFileSync(join(dir, name), 'utf8')) as
+        { commit?: string; files?: unknown; shardCount?: number; sweepId?: string; imageDigest?: string; parentAttempt?: string; attemptId?: string };
+      const match = /^pod-(\d+)\.json$/.exec(name);
+      if (match) {
+        if (row.commit !== commit) return invalid(`root cut Pod ${name} belongs to another commit`);
+        if (!Array.isArray(row.files) || !row.files.length || !row.files.every((file) => typeof file === 'string'))
+          return invalid(`root cut Pod ${name} has no file list`);
+        if (!row.attemptId) return invalid(`root cut Pod ${name} has no attempt`);
+        if (!row.sweepId) return invalid(`root cut Pod ${name} has no sweep identity`);
+        roots.set(Number(match[1]), { files: row.files as string[], shardCount: row.shardCount ?? 0, sweepId: row.sweepId, attemptId: row.attemptId });
+      } else descendants.push({ name, commit: row.commit, imageDigest: row.imageDigest, sweepId: row.sweepId,
+        parentAttempt: row.parentAttempt, attemptId: row.attemptId });
+      if (match) {
+        if (!row.imageDigest || !IMAGE_DIGEST.test(row.imageDigest)) return invalid(`actual Pod image digest absent: ${name}`);
+        images.add(row.imageDigest.toLowerCase());
+      }
+    }
+    if (!roots.size) return invalid('root cut shards absent');
+    const count = roots.get(0)?.shardCount;
+    if (!count || !Number.isSafeInteger(count) || count !== roots.size
+      || [...roots.keys()].some((index) => index < 0 || index >= count)) return invalid('root cut shard set incomplete');
+    const sweepId = roots.get(0)!.sweepId;
+    if ([...roots.values()].some((row) => row.shardCount !== count || row.sweepId !== sweepId))
+      return invalid('root cut shards belong to different sweeps');
+    const files = [...roots.values()].flatMap((row) => row.files);
+    if (new Set(files).size !== files.length) return invalid('root cut file lists overlap');
+    // A new cut can leave older split descendants in the same directory. Bind only the current roots' attempt tree.
+    const attempts = new Set([...roots.values()].map((row) => row.attemptId));
+    let pending = descendants;
+    for (; pending.length;) {
+      const next = pending.filter((row) => !row.parentAttempt || !attempts.has(row.parentAttempt));
+      if (next.length === pending.length) break;
+      for (const row of pending) {
+        if (!row.parentAttempt || !attempts.has(row.parentAttempt)) continue;
+        if (row.commit !== commit) return invalid(`cut Pod ${row.name} belongs to another commit`);
+        if (row.sweepId !== sweepId) return invalid(`cut Pod ${row.name} belongs to another sweep`);
+        if (!row.imageDigest || !IMAGE_DIGEST.test(row.imageDigest)) return invalid(`actual Pod image digest absent: ${row.name}`);
+        if (!row.attemptId) return invalid(`cut Pod ${row.name} has no attempt`);
+        images.add(row.imageDigest.toLowerCase());
+        attempts.add(row.attemptId);
+      }
+      pending = next;
+    }
+    // A child carrying this sweep's identity must be connected to a root,
+    // even when its parentAttempt is missing or corrupt. Otherwise its image
+    // evidence is silently omitted and a mixed-image receipt can look valid.
+    for (const row of pending) {
+      if (row.sweepId === sweepId) return invalid(`cut Pod ${row.name} has no connected parent attempt`);
+      if (row.commit === commit && !row.sweepId) return invalid(`cut Pod ${row.name} has no sweep identity`);
+    }
+    if (images.size !== 1) return invalid('cut Pods used different image digests');
+    return { ...base, valid: true, reason: 'complete clean full sweep', imageDigest: [...images][0]!, files: files.length, shards: count };
+  } catch (error) { return invalid(`cut Pod evidence unreadable: ${String(error)}`); }
+}