elanous 0.2.35 → 0.2.37

package/src/task-agent/map-host-adapter.ts

@@ -0,0 +1,134 @@
+/** Host graph-run transport for the small C2 map. No Pod or write authority is implied. */
+import { resolve } from 'node:path';
+import { lastJsonObject, runGraph, type GraphRunOptions, type GraphRunState } from '../graph-runner/runner.js';
+import type { MapCard, MapContext, MapItem } from './map-reduce.js';
+import type { MapRecipe, MapRunRow } from './map-run-ledger.js';
+
+export interface HostMapItem extends MapItem {
+  /** Immutable, complete recipe input captured with the inventory, not a display title. */
+  graphInput: Record<string, unknown>;
+}
+export interface MapHostPorts {
+  recipeRoot: string;
+  run?: (path: string, options: GraphRunOptions) => Promise<GraphRunState>;
+}
+
+const EMITTERS: Record<MapRecipe, ReadonlySet<string>> = {
+  'green-close': new Set(['result']),
+  'draft-close': new Set(['harvest', 'close-candidate', 'hold']),
+};
+const SHA = /^[a-f0-9]{40}$/i;
+function obj(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+function strings(value: unknown): string[] | null {
+  return Array.isArray(value) && value.every((part) => typeof part === 'string') ? value as string[] : null;
+}
+function hold(card: MapCard, reason: string, graph?: GraphRunState): MapRunRow {
+  return { event: 'row', mapRunId: card.mapRunId, itemId: card.itemId, recipe: card.recipe,
+    kind: 'hold', verdict: 'hold', reason, evidence: [],
+    ...(graph ? { startedAt: graph.startedAt ?? null, endedAt: graph.finishedAt ?? null,
+      result: { cardId: card.id, transport: 'host-graph-run', graphRunId: graph.runId,
+        graphStatePath: graph.statePath, sourceHash: graph.sourceHash ?? null } } : {}) };
+}
+function validInput(card: MapCard, item: HostMapItem): boolean {
+  const input = item.graphInput;
+  if (card.itemId !== item.id || !input || typeof input !== 'object' || Array.isArray(input)) return false;
+  if (card.recipe === 'green-close') {
+    const main = obj(input.main);
+    return input.cellId === item.id && typeof input.version === 'string' && !!input.version
+      && main?.ref === 'origin/main' && typeof main.sha === 'string' && SHA.test(main.sha)
+      && Array.isArray(input.paths) && input.paths.length > 0 && strings(input.paths) !== null
+      && Array.isArray(input.candidates) && input.candidates.length === 1;
+  }
+  const draft = obj(input.item);
+  const inventory = obj(input.inventory);
+  return input.mapRunId === card.mapRunId && input.inventoryComplete === true
+    && typeof input.snapshotTime === 'string' && !!input.snapshotTime
+    && typeof input.mainSha === 'string' && SHA.test(input.mainSha)
+    && inventory?.complete === true && inventory.snapshotTime === input.snapshotTime
+    && inventory.mainSha === input.mainSha && draft !== null
+    && Number.isSafeInteger(draft.pr) && Number(draft.pr) > 0
+    && item.id === `pr-${draft.pr}` && typeof draft.headOid === 'string' && SHA.test(draft.headOid);
+}
+function emitterResult(graph: GraphRunState, recipe: MapRecipe): Record<string, unknown> | null {
+  const emitter = [...graph.nodes].reverse().find((node) => node.executed && EMITTERS[recipe].has(node.nodeId));
+  if (!emitter?.ok || emitter.exit !== 0) return null;
+  return lastJsonObject(emitter.output) ?? obj(emitter.output);
+}
+function convertGreen(card: MapCard, input: Record<string, unknown>, graph: GraphRunState, output: Record<string, unknown>): MapRunRow | null {
+  if (output.outcome !== 'ok' || output.cellId !== card.itemId || output.version !== input.version
+    || typeof output.reason !== 'string' || !strings(output.evidence)) return null;
+  const kind = output.kind;
+  if (kind !== 'green-candidate' && kind !== 'mock-pr' && kind !== 'implementation-remains' && kind !== 'hold') return null;
+  const base: MapRunRow = { event: 'row', mapRunId: card.mapRunId, itemId: card.itemId, recipe: card.recipe,
+    kind, verdict: kind, reason: output.reason, evidence: output.evidence as string[] };
+  if (kind !== 'green-candidate') return base;
+  const e1 = graph.nodes.find((node) => node.nodeId === 'e1');
+  const e2 = graph.nodes.find((node) => node.nodeId === 'e2');
+  const e3 = graph.nodes.find((node) => node.nodeId === 'e3');
+  const produce = graph.nodes.find((node) => node.nodeId === 'produce');
+  const boundary = graph.nodes.find((node) => node.nodeId === 'boundary');
+  const p1 = e1 && (lastJsonObject(e1.output) ?? obj(e1.output));
+  const p2 = e2 && (lastJsonObject(e2.output) ?? obj(e2.output));
+  const p3 = e3 && (lastJsonObject(e3.output) ?? obj(e3.output));
+  const produced = produce && (lastJsonObject(produce.output) ?? obj(produce.output));
+  const p4 = boundary && (lastJsonObject(boundary.output) ?? obj(boundary.output));
+  const candidate = obj((input.candidates as unknown[])[0]);
+  const prUrl = candidate?.prUrl;
+  if (p1?.outcome !== 'pass' || p2?.outcome !== 'pass' || p3?.outcome !== 'pass'
+    || produced?.outcome !== 'pass' || p4?.outcome !== 'pass'
+    || produced.proofRef !== `boundary-proofs/${card.itemId}/${graph.runId}.json`
+    || input.mapRunId !== card.mapRunId || input.cardId !== card.id
+    || !SHA.test(String(p1.mergeSha ?? '')) || p1.mergeSha !== output.mergeSha
+    || !Number.isSafeInteger(p1.pr) || p1.pr !== output.pr || candidate?.pr !== p1.pr
+    || typeof prUrl !== 'string' || !prUrl
+    || typeof p2.command !== 'string' || !p2.command.trim() || p2.exitCode !== 0
+    || typeof p3.reason !== 'string' || !p3.reason.trim()) return null;
+  return { ...base, pr: p1.pr as number, prUrl,
+    e1: { verdict: 'pass', mergeSha: p1.mergeSha as string, mainAncestor: true },
+    e2: { verdict: 'pass', command: p2.command, exitCode: 0 }, e2Source: 'completion-boundary',
+    e3: { verdict: 'pass', reason: p3.reason } };
+}
+function convertDraft(card: MapCard, input: Record<string, unknown>, output: Record<string, unknown>): MapRunRow | null {
+  const row = obj(output.result);
+  const item = obj(input.item);
+  if (output.outcome !== 'done' || !row || !item || row.mapRunId !== card.mapRunId
+    || row.snapshotTime !== input.snapshotTime || row.pr !== item.pr || row.headOid !== item.headOid
+    || !strings(row.evidence) || typeof row.reason !== 'string') return null;
+  const kind = row.kind;
+  if (kind !== 'harvest' && kind !== 'close-candidate' && kind !== 'hold') return null;
+  return { event: 'row', mapRunId: card.mapRunId, itemId: card.itemId, recipe: card.recipe,
+    kind, verdict: kind, reason: row.reason, evidence: row.evidence as string[],
+    pr: row.pr as number, headOid: row.headOid as string };
+}
+
+/** mapInventory owns the two-worker bound and the only ledger append. */
+export function createMapHostLauncher(ports: MapHostPorts):
+  (card: MapCard, item: HostMapItem, context: MapContext) => Promise<MapRunRow> {
+  return async (card, item, context) => {
+    if (context.dryRun || context.mapRunId !== card.mapRunId || context.recipe !== card.recipe || !validInput(card, item))
+      return hold(card, 'host-map-input-mismatch');
+    const recipePath = resolve(ports.recipeRoot, `${card.recipe}.yaml`);
+    let graph: GraphRunState;
+    const boundInput = card.recipe === 'green-close'
+      ? { ...item.graphInput, mapRunId: card.mapRunId, cardId: card.id } : item.graphInput;
+    try { graph = await (ports.run ?? runGraph)(recipePath, { input: boundInput, quiet: true, dryRun: false }); }
+    catch { return hold(card, 'host-graph-launch-failed'); }
+    const expectedGraphId = card.recipe === 'green-close' ? 'green-close' : 'work-draft-close';
+    if (graph.graphId !== expectedGraphId || graph.graphPath !== recipePath || !graph.runId
+      || graph.dryRun || JSON.stringify(graph.input) !== JSON.stringify(boundInput))
+      return hold(card, 'host-graph-provenance-mismatch', graph);
+    if (graph.status !== 'done') return hold(card, 'host-graph-not-done', graph);
+    const output = emitterResult(graph, card.recipe);
+    if (!output) return hold(card, 'host-graph-result-missing', graph);
+    const row = card.recipe === 'green-close'
+      ? convertGreen(card, boundInput, graph, output)
+      : convertDraft(card, item.graphInput, output);
+    if (!row || (row.kind !== 'hold' && row.evidence.length === 0) || (row.kind === 'hold' && !row.reason.trim()))
+      return hold(card, 'host-graph-result-invalid', graph);
+    return { ...row, startedAt: graph.startedAt ?? null, endedAt: graph.finishedAt ?? null, rc: 0,
+      result: { cardId: card.id, transport: 'host-graph-run', graphRunId: graph.runId,
+        graphStatePath: graph.statePath, sourceHash: graph.sourceHash ?? null, recipePath } };
+  };
+}

package/src/task-agent/map-reduce.ts

@@ -0,0 +1,158 @@
+/**
+ * MAPREDUCE-FANOUT backend. Inventory and card execution are ports so the CLI can
+ * bind the existing checklist/draft readers and tasks hand Pod launcher separately.
+ * A run snapshots its inventory before any card starts; one terminal row belongs
+ * to each item. This module never changes a checklist or closes a PR.
+ */
+import { randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+import {
+  appendMapRunRow, createMapRun, readMapRun, reduceMapRun,
+  type MapRecipe, type MapRowKind, type MapRunRow, type MapRunStart,
+} from './map-run-ledger.js';
+
+export type MapSource = 'landed-but-yellow' | 'drafts';
+export interface MapItem { id: string }
+export interface MapInventory<T extends MapItem> {
+  items: readonly T[];
+  complete: boolean;
+  snapshotTime: string;
+  snapshotRef: string;
+  recipeSha: string;
+  mainSha: string;
+  checklistSnapshotPath: string | null;
+  requestedPool: string;
+  selectedPool: string | null;
+  imageCommit: string | null;
+  /** A failed inventory is recorded as a suppressed HOLD row. */
+  reason?: string;
+}
+export interface MapCard {
+  id: string;
+  itemId: string;
+  mapRunId: string;
+  recipe: MapRecipe;
+  text: string;
+}
+export interface MapContext {
+  mapRunId: string;
+  recipe: MapRecipe;
+  source: MapSource;
+  dryRun: boolean;
+}
+export interface MapPorts<T extends MapItem> {
+  inventory: (recipe: MapRecipe, source: MapSource, limit: number | undefined) => Promise<MapInventory<T>>;
+  /** Pure card authoring. Do not persist or launch here. */
+  buildCard: (item: T, context: MapContext) => MapCard;
+  /** Production adapter must launch through tasks hand and wait for its terminal recipe result. */
+  launchCard: (card: MapCard, item: T, context: MapContext) => Promise<MapRunRow>;
+  /** Optional pure preview; default dry-run yields a HOLD without invoking launchCard. */
+  previewCard?: (card: MapCard, item: T, context: MapContext) => MapRunRow | Promise<MapRunRow>;
+  log?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface MapRequest {
+  recipe: MapRecipe;
+  source: MapSource;
+  limit?: number;
+  concurrency?: number;
+  dryRun?: boolean;
+  root?: string;
+  mapRunId?: string;
+}
+export interface MapResult { mapRunId: string; expected: number; observed: number; dryRun: boolean }
+
+const validPairs: Readonly<Record<MapRecipe, MapSource>> = {
+  'green-close': 'landed-but-yellow', 'draft-close': 'drafts',
+};
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$/;
+
+function checkPositive(value: number | undefined, label: string): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) throw new Error(`map ${label} must be a positive integer`);
+}
+function hold(context: MapContext, itemId: string | null, reason: string, suppressed = false): MapRunRow {
+  return { event: 'row', mapRunId: context.mapRunId, itemId, recipe: context.recipe,
+    kind: 'hold', verdict: 'hold', reason, evidence: [], ...(suppressed ? { rowsSuppressed: true, pr: null } : {}) };
+}
+function record(log: MapPorts<MapItem>['log'], event: string, data: Record<string, unknown>): void {
+  try { (log ?? ((name, fields) => debug.log('task-agent.map-reduce', name, fields)))(event, data); }
+  catch { /* diagnostics must not turn a completed item into a failed one */ }
+}
+
+/** Bounded workers, with no unbounded Promise.all fanout. Default is a read-only preview. */
+export async function mapInventory<T extends MapItem>(request: MapRequest, ports: MapPorts<T>): Promise<MapResult> {
+  if (validPairs[request.recipe] !== request.source) throw new Error('map recipe/source mismatch');
+  checkPositive(request.limit, 'limit');
+  checkPositive(request.concurrency, 'concurrency');
+  const concurrency = request.concurrency ?? 2;
+  const dryRun = request.dryRun !== false;
+  const mapRunId = request.mapRunId ?? `map-${randomUUID()}`;
+  if (!idPattern.test(mapRunId)) throw new Error('map invalid run id');
+  const context: MapContext = { mapRunId, recipe: request.recipe, source: request.source, dryRun };
+  const inventory = await ports.inventory(request.recipe, request.source, request.limit);
+  // A limit is a selection boundary, not permission to silently truncate a partial inventory.
+  const items = inventory.complete ? inventory.items.slice(0, request.limit) : [];
+  const start: MapRunStart = { event: 'start', mapRunId, recipe: request.recipe,
+    recipeSha: inventory.recipeSha, snapshotTime: inventory.snapshotTime, snapshotRef: inventory.snapshotRef,
+    mainSha: inventory.mainSha, checklistSnapshotPath: inventory.checklistSnapshotPath,
+    inventoryComplete: inventory.complete, itemIds: items.map((item) => item.id),
+    requestedPool: inventory.requestedPool, selectedPool: inventory.selectedPool,
+    imageCommit: inventory.imageCommit, dryRun };
+  createMapRun(start, request.root);
+  record(ports.log, 'start', { mapRunId, recipe: request.recipe, source: request.source, count: items.length, concurrency, dryRun });
+  if (!inventory.complete) {
+    appendMapRunRow(hold(context, null, inventory.reason || 'inventory-incomplete', true), request.root);
+    record(ports.log, 'inventory-hold', { mapRunId, reason: inventory.reason ?? 'inventory-incomplete' });
+    return { mapRunId, expected: 0, observed: 1, dryRun };
+  }
+  let next = 0;
+  let observed = 0;
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      const item = items[next++]!;
+      let row: MapRunRow;
+      try {
+        const card = ports.buildCard(item, context);
+        if (!card || !idPattern.test(card.id) || card.itemId !== item.id || card.mapRunId !== mapRunId
+          || card.recipe !== request.recipe || !card.text.trim()) throw new Error('card identity mismatch');
+        row = dryRun
+          ? ports.previewCard ? await ports.previewCard(card, item, context) : hold(context, item.id, 'dry-run-preview')
+          : await ports.launchCard(card, item, context);
+        if (row.mapRunId !== mapRunId || row.itemId !== item.id || row.recipe !== request.recipe)
+          throw new Error('result identity mismatch');
+        row = { ...row, result: { ...row.result, cardId: card.id } };
+      } catch (error) {
+        row = hold(context, item.id, `map-item-failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      // The ledger validates recipe-specific evidence and rejects duplicate/unknown rows.
+      // An invalid result is a hard error; never launder it into a successful map run.
+      appendMapRunRow(row, request.root);
+      observed++;
+      record(ports.log, 'item', { mapRunId, itemId: item.id, kind: row.kind, reason: row.reason });
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+  record(ports.log, 'finished', { mapRunId, expected: items.length, observed });
+  return { mapRunId, expected: items.length, observed, dryRun };
+}
+
+export interface MapReduceTable { mapRunId: string; markdown: string; writes: 0 }
+const countKinds: readonly MapRowKind[] = ['green-candidate', 'mock-pr', 'implementation-remains', 'harvest', 'close-candidate', 'hold'];
+function cell(value: unknown): string { return String(value ?? '').replaceAll('|', '\\|').replaceAll(/\r?\n/g, ' '); }
+
+/** Read-only aggregation. Applying green/close candidates belongs to a separate guarded reducer. */
+export function renderMapReduceTable(mapRunId: string, root?: string): MapReduceTable {
+  const { start, rows } = readMapRun(mapRunId, root);
+  const summary = reduceMapRun(mapRunId, root);
+  const lines = [
+    `# Map run ${cell(mapRunId)}`,
+    '',
+    `Recipe: ${start.recipe} · snapshot: ${cell(start.snapshotRef)} · dry-run: ${start.dryRun} · verdict: ${summary.verdict} (${summary.reason})`,
+    `Expected: ${summary.expected} · observed: ${summary.observed} · writes: 0`,
+    `Counts: ${countKinds.map((kind) => `${kind} ${summary.counts[kind]}`).join(' · ')}`,
+    '',
+    '| Item | Card | Result | PR | Reason |',
+    '| --- | --- | --- | --- | --- |',
+    ...rows.map((row) => `| ${cell(row.itemId ?? 'inventory')} | ${cell(row.result?.cardId)} | ${row.kind} | ${cell(row.pr)} | ${cell(row.reason)} |`),
+  ];
+  return { mapRunId, markdown: `${lines.join('\n')}\n`, writes: 0 };
+}

package/src/task-agent/map-run-ledger.ts

@@ -0,0 +1,226 @@
+/**
+ * MAPREDUCE-FANOUT: one immutable inventory snapshot, followed by one result per item.
+ * The reducer is read-only. A partial inventory or missing/duplicate result is a hold,
+ * never evidence for a checklist change or a draft close.
+ */
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+
+export type MapRecipe = 'green-close' | 'draft-close';
+export type MapRowKind = 'green-candidate' | 'mock-pr' | 'implementation-remains'
+  | 'harvest' | 'close-candidate' | 'hold';
+export type MapEvidenceVerdict = 'pass' | 'fail' | 'hold' | 'unmeasured';
+
+export interface MapRunStart {
+  event: 'start';
+  mapRunId: string;
+  recipe: MapRecipe;
+  recipeSha: string;
+  snapshotTime: string;
+  snapshotRef: string;
+  /** Exact origin/main captured with the inventory, independent of the image or recipe commit. */
+  mainSha: string;
+  /** The checklist snapshot artifact used by green-close; draft-close records null. */
+  checklistSnapshotPath: string | null;
+  inventoryComplete: boolean;
+  /** Stable identities from the complete inventory; item display titles are never keys. */
+  itemIds: string[];
+  requestedPool: string;
+  selectedPool: string | null;
+  imageCommit: string | null;
+  dryRun: boolean;
+}
+
+export interface MapRunRow {
+  event: 'row';
+  mapRunId: string;
+  itemId: string | null;
+  recipe: MapRecipe;
+  kind: MapRowKind;
+  verdict: MapRowKind;
+  reason: string;
+  evidence: string[];
+  e1?: { verdict: MapEvidenceVerdict; mergeSha?: string; mainAncestor?: boolean };
+  e2?: { verdict: MapEvidenceVerdict; command?: string; exitCode?: number };
+  e2Source?: 'completion-boundary' | 'prior-evidence' | 'missing';
+  e3?: { verdict: MapEvidenceVerdict; reason: string };
+  /** Only an inventory-wide failure uses this form; it suppresses all item rows and requires pr:null. */
+  rowsSuppressed?: boolean;
+  pr?: number | null;
+  prUrl?: string | null;
+  headOid?: string | null;
+  podJob?: string | null;
+  podUid?: string | null;
+  startedAt?: string | null;
+  endedAt?: string | null;
+  rc?: number | null;
+  result?: Record<string, unknown>;
+}
+
+export interface MapRunRead {
+  start: MapRunStart;
+  rows: MapRunRow[];
+}
+
+export interface MapRunReduce {
+  mapRunId: string;
+  verdict: 'complete' | 'hold';
+  reason: string;
+  expected: number;
+  observed: number;
+  counts: Record<MapRowKind, number>;
+  /** A dry-run has no write authority, even when every item is a candidate. */
+  writes: 0;
+}
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$/;
+const SHA = /^[0-9a-f]{40}$/;
+const KINDS = new Set<MapRowKind>(['green-candidate', 'mock-pr', 'implementation-remains', 'harvest', 'close-candidate', 'hold']);
+const RECIPE_KINDS: Record<MapRecipe, ReadonlySet<MapRowKind>> = {
+  'green-close': new Set(['green-candidate', 'mock-pr', 'implementation-remains', 'hold']),
+  'draft-close': new Set(['harvest', 'close-candidate', 'hold']),
+};
+
+function checkId(value: string, label: string): void {
+  if (!ID.test(value)) throw new Error(`map-run invalid ${label}: ${value}`);
+}
+
+export function mapRunLedgerPath(mapRunId: string, root = effectiveInstanceRoot()): string {
+  checkId(mapRunId, 'id');
+  return join(root, 'map-runs', `${mapRunId}.jsonl`);
+}
+
+function validateStart(start: MapRunStart): void {
+  checkId(start.mapRunId, 'id');
+  if (start.recipe !== 'green-close' && start.recipe !== 'draft-close') throw new Error('map-run unknown recipe');
+  if (!SHA.test(start.recipeSha)) throw new Error('map-run recipe SHA missing');
+  if (!start.snapshotTime || !start.snapshotRef) throw new Error('map-run snapshot identity missing');
+  if (!SHA.test(start.mainSha) || !('checklistSnapshotPath' in start)
+    || (start.recipe === 'green-close' && (!start.checklistSnapshotPath || !isAbsolute(start.checklistSnapshotPath)))
+    || (start.recipe === 'draft-close' && start.checklistSnapshotPath !== null)) {
+    throw new Error('map-run main or checklist snapshot provenance missing');
+  }
+  if (!Array.isArray(start.itemIds) || start.itemIds.some((id) => typeof id !== 'string' || !ID.test(id))
+    || new Set(start.itemIds).size !== start.itemIds.length) throw new Error('map-run item identities missing or duplicate');
+  if (typeof start.inventoryComplete !== 'boolean' || typeof start.dryRun !== 'boolean') throw new Error('map-run completeness or dry-run missing');
+  if (!start.inventoryComplete && start.itemIds.length) throw new Error('map-run partial inventory cannot name items');
+  if (!start.requestedPool || !('selectedPool' in start) || !('imageCommit' in start)) throw new Error('map-run pool or image provenance missing');
+}
+
+function validateRow(row: MapRunRow, start: MapRunStart): void {
+  if (row.mapRunId !== start.mapRunId || row.recipe !== start.recipe || !KINDS.has(row.kind) || row.verdict !== row.kind
+    || !Array.isArray(row.evidence)
+    || row.evidence.some((value) => typeof value !== 'string') || typeof row.reason !== 'string') {
+    throw new Error('map-run row contract mismatch');
+  }
+  if (!RECIPE_KINDS[start.recipe].has(row.kind)) throw new Error('map-run kind outside recipe');
+  if (row.rowsSuppressed) {
+    if (start.inventoryComplete || row.itemId !== null || row.pr !== null || row.kind !== 'hold') {
+      throw new Error('map-run suppressed row must hold an incomplete inventory without a PR');
+    }
+  } else if (!start.inventoryComplete) {
+    throw new Error('map-run incomplete inventory suppresses item rows');
+  } else if (!row.itemId || !start.itemIds.includes(row.itemId)) {
+    throw new Error(`map-run unknown item: ${row.itemId}`);
+  }
+  if (row.kind === 'hold' && !row.reason.trim()) throw new Error('map-run hold needs a reason');
+  if (row.kind !== 'hold' && row.evidence.length === 0) throw new Error('map-run candidate needs evidence');
+  if (row.kind === 'green-candidate'
+    && (row.e1?.verdict !== 'pass' || row.e2?.verdict !== 'pass' || row.e3?.verdict !== 'pass'
+      || !SHA.test(row.e1.mergeSha ?? '') || row.e1.mainAncestor !== true
+      || !row.e3.reason.trim()
+      || typeof row.pr !== 'number' || !Number.isSafeInteger(row.pr) || row.pr <= 0
+      || !row.prUrl || !row.e2Source || row.e2Source === 'missing'
+      || !row.e2.command?.trim() || row.e2.exitCode !== 0)) {
+    throw new Error('map-run green candidate needs E1/E2/E3 and PR proof');
+  }
+  if ((row.kind === 'harvest' || row.kind === 'close-candidate')
+    && (typeof row.pr !== 'number' || !Number.isSafeInteger(row.pr) || row.pr <= 0 || !SHA.test(row.headOid ?? ''))) {
+    throw new Error('map-run draft decision needs exact PR head');
+  }
+  if (row.rc != null && row.rc !== 0 && row.kind !== 'hold') throw new Error('map-run failed Pod cannot yield a candidate');
+  for (const field of ['podJob', 'podUid', 'startedAt', 'endedAt'] as const) {
+    const value = row[field];
+    if (value != null && (typeof value !== 'string' || !value.trim())) throw new Error(`map-run invalid ${field}`);
+  }
+  if (row.result != null && (typeof row.result !== 'object' || Array.isArray(row.result))) {
+    throw new Error('map-run invalid result');
+  }
+}
+
+/** Exclusive create prevents a retry from silently replacing the original inventory. */
+export function createMapRun(start: MapRunStart, root?: string): string {
+  validateStart(start);
+  const path = mapRunLedgerPath(start.mapRunId, root);
+  mkdirSync(dirname(path), { recursive: true });
+  const fd = openSync(path, 'wx', 0o600);
+  try { writeSync(fd, `${JSON.stringify(start)}\n`); }
+  finally { closeSync(fd); }
+  return path;
+}
+
+export function readMapRun(mapRunId: string, root?: string): MapRunRead {
+  const path = mapRunLedgerPath(mapRunId, root);
+  if (!existsSync(path)) throw new Error(`map-run missing: ${mapRunId}`);
+  const raw = readFileSync(path, 'utf8');
+  if (!raw.endsWith('\n')) throw new Error('map-run truncated JSONL tail');
+  const lines = raw.trimEnd().split('\n');
+  let start: MapRunStart;
+  try { start = JSON.parse(lines[0]!) as MapRunStart; }
+  catch { throw new Error('map-run invalid start JSON'); }
+  if (start.event !== 'start' || start.mapRunId !== mapRunId) throw new Error('map-run invalid start');
+  validateStart(start);
+  const rows: MapRunRow[] = [];
+  const seen = new Set<string>();
+  for (const line of lines.slice(1)) {
+    let row: MapRunRow;
+    try { row = JSON.parse(line) as MapRunRow; }
+    catch { throw new Error('map-run invalid row JSON'); }
+    if (row.event !== 'row') throw new Error('map-run unexpected event');
+    validateRow(row, start);
+    const key = row.rowsSuppressed ? '__inventory_hold__' : row.itemId!;
+    if (seen.has(key)) throw new Error(`map-run duplicate row: ${key}`);
+    seen.add(key);
+    rows.push(row);
+  }
+  if (rows.some((row) => row.rowsSuppressed) && rows.length !== 1) throw new Error('map-run suppressed inventory has item rows');
+  return { start, rows };
+}
+
+/** The lock protects the read-before-append duplicate check across concurrent Pod completions. */
+export function appendMapRunRow(row: MapRunRow, root?: string): void {
+  const path = mapRunLedgerPath(row.mapRunId, root);
+  withFileLockSync(`${path}.lock`, () => {
+    const current = readMapRun(row.mapRunId, root);
+    validateRow(row, current.start);
+    const key = row.rowsSuppressed ? '__inventory_hold__' : row.itemId!;
+    if (current.rows.some((existing) => (existing.rowsSuppressed ? '__inventory_hold__' : existing.itemId) === key)) {
+      throw new Error(`map-run duplicate row: ${key}`);
+    }
+    if (row.rowsSuppressed && current.rows.length) throw new Error('map-run inventory hold cannot follow item rows');
+    if (current.rows.some((existing) => existing.rowsSuppressed)) throw new Error('map-run inventory hold suppresses item rows');
+    appendFileSync(path, `${JSON.stringify(row)}\n`);
+  });
+}
+
+/** No consumer of this result can write: incomplete evidence remains an explicit hold. */
+export function reduceMapRun(mapRunId: string, root?: string): MapRunReduce {
+  const { start, rows } = readMapRun(mapRunId, root);
+  const counts: Record<MapRowKind, number> = {
+    'green-candidate': 0, 'mock-pr': 0, 'implementation-remains': 0,
+    harvest: 0, 'close-candidate': 0, hold: 0,
+  };
+  for (const row of rows) counts[row.kind]++;
+  const accounted = start.inventoryComplete && rows.length === start.itemIds.length
+    && rows.every((row) => !row.rowsSuppressed);
+  const complete = accounted && start.itemIds.length > 0 && counts.hold === 0;
+  return {
+    mapRunId, verdict: complete ? 'complete' : 'hold',
+    reason: !start.inventoryComplete ? 'inventory-incomplete' : start.itemIds.length === 0 ? 'empty-inventory'
+      : !accounted ? 'results-missing'
+      : counts.hold ? 'item-hold' : 'all-items-accounted',
+    expected: start.itemIds.length, observed: rows.length, counts, writes: 0,
+  };
+}

package/src/task-agent/mission.ts

@@ -261,6 +261,13 @@ export async function collectPieceEvidence(pieces: readonly TaskCard[], read: Pi
   for (const piece of pieces) {
     const ref = pieceRef(piece);
     if (ref === undefined) { out[piece.id] = 'no-ref'; continue; }
+    // A verified component train landing closes the component PR; the integration PR is merged.
+    // rejudge-on-head writes this receipt only after verifiedTrainLanding checks the train ledger.
+    if (typeof ref === 'number' && piece.status === 'done' && piece.trainLanding?.componentPr === ref
+      && Number.isSafeInteger(piece.trainLanding.integrationPr) && /^[a-f0-9]{40}$/i.test(piece.trainLanding.mergeSha)) {
+      out[piece.id] = 'merged';
+      continue;
+    }
     let state: 'merged' | 'waiting' | 'blocked';
     try { state = await read(ref); } catch { state = 'waiting'; }
     out[piece.id] = state === 'merged' ? 'merged' : state === 'blocked' ? 'closed' : 'pending';
@@ -343,6 +350,21 @@ export async function advanceMission(missionId: string, opts: AdvanceMissionOpti
   }
 }
 
+/** A confirmed landed piece wakes its own mission. Evidence is read again before any successor launch. */
+export async function advanceLandedPieceMission(pieceId: string, opts: AdvanceMissionOptions = {}): Promise<AdvanceMissionResult | null> {
+  const path = opts.statePath ?? taskAgentStatePath();
+  const piece = readTaskCard(pieceId, path);
+  const missionId = piece?.mission;
+  if (!missionId) return null;
+  const mission = readTaskCard(missionId, path);
+  if (!mission?.pieces?.includes(pieceId) || mission.greenProposal) return null;
+  const launcher = opts.launcher ?? (await import('../cli/tasks-cli.js')).defaultTaskLauncher;
+  const result = await advanceMission(missionId, { ...opts, statePath: path, live: true, launcher });
+  try { debug.log('task-agent', 'mission-auto-advance', { missionId, pieceId, evidence: result.evidence, ready: result.ready,
+    handed: result.handed.map((item) => ({ pieceId: item.pieceId, launched: item.launched, error: item.error ?? null })), green: result.green }); } catch { /* fail-soft */ }
+  return result;
+}
+
 /** `advanceMission` 이 실패했다 — `mission-advance` 관측은 이미 남겼다. */
 export class MissionAdvanceError extends Error {
   constructor(reason: string) {
@@ -403,6 +425,14 @@ async function advanceMissionOnce(missionId: string, opts: AdvanceMissionOptions
       const out = await handTask({
         text: claimed.text, id: pieceId, mission: missionId, after: claimed.after ?? [], landed,
         ...(claimed.seat ? { seat: claimed.seat } : {}), ...(claimed.checklistId ? { checklistId: claimed.checklistId } : {}),
+        ...(claimed.tier ? { tier: claimed.tier } : {}),
+        ...(claimed.tierSplit ? { tierSplit: claimed.tierSplit } : {}),
+        ...(claimed.childLlm ? { childLlm: `${claimed.childLlm.provider}/${claimed.childLlm.model}`,
+          ...(claimed.childLlm.effort ? { childLlmEffort: claimed.childLlm.effort } : {}) } : {}),
+        ...(claimed.parentRoleLlm?.length ? { parentRoleLlm: claimed.parentRoleLlm } : {}),
+        ...(claimed.project?.id ? { project: { id: claimed.project.id, target: claimed.project.target } } : {}),
+        ...(claimed.completion ? { completion: claimed.completion } : {}),
+        ...(claimed.taLand ? { taLand: true } : {}),
         cardFields: { handed: mark, ...(claimed.pr !== undefined ? { pr: claimed.pr } : {}), ...(claimed.goalId !== undefined ? { goalId: claimed.goalId } : {}) },
         live: mode === 'live', statePath: path, ...(opts.launcher ? { launcher: opts.launcher } : {}), ...(opts.now ? { now: opts.now } : {}),
         // claim 을 가진 동안만 쓴다 — 늦게 끝난 shadow 넘김이 live 표지·발사 기록을 덮지 않게.