@fiale-plus/pi-rogue 0.2.1 → 0.2.3

package/node_modules/@fiale-plus/pi-rogue-router/src/outcomes.ts

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hashText } from "./hash.js";
+import { readCheckpointJsonl } from "./decision.js";
+import { readRouteEvents, type RouteEvent } from "./ledger.js";
+import type { RouterCheckpoint, TaskStatus, TaskType } from "./types.js";
+
+export const ROUTER_OUTCOME_SCHEMA = "pi-router.outcome.v1" as const;
+
+export interface RouterOutcome {
+  schema: typeof ROUTER_OUTCOME_SCHEMA;
+  outcomeId: string;
+  recordedAt: string;
+  sessionId: string;
+  checkpointId?: string;
+  routeEventId?: string;
+  taskType: TaskType;
+  taskStatus: TaskStatus;
+  testsPassedAfter: boolean | null;
+  verifierImproved: boolean | null;
+  acceptedDiff: boolean | null;
+  userInterrupted: boolean;
+  userOverrodeDecision: boolean;
+  finalFilesTouched: number;
+  finalDiffLines: number;
+  wallTimeMs: number | null;
+  cloudCostUsd: number | null;
+  frontierCalls: number;
+  localTurns: number;
+  reworkTurns: number;
+  evidence: {
+    source: "inferred" | "manual";
+    rawSessionRef?: RouterCheckpoint["rawSessionRef"];
+    routeEventId?: string;
+    notesHash?: string;
+  };
+}
+
+export interface OutcomeWriteSummary {
+  schema: "pi-router.outcomes-summary.v1";
+  output: string;
+  outcomes: number;
+  inferred: number;
+}
+
+function roundStatus(event: RouteEvent, checkpoint?: RouterCheckpoint): TaskStatus {
+  if (event.decision.action === "stop_and_ask_user") return "unknown";
+  if (checkpoint?.features.verifierUsed && checkpoint.features.progressScore >= 0.75) return "partial";
+  return "unknown";
+}
+
+function taskTypeFromCheckpoint(checkpoint?: RouterCheckpoint): TaskType {
+  const phase = checkpoint?.phase ?? "unknown";
+  return phase === "implementation" || phase === "debug" || phase === "review" || phase === "research" || phase === "ops" || phase === "planning"
+    ? phase
+    : "unknown";
+}
+
+function isFrontierModel(model?: string): boolean {
+  return Boolean(model && /(gpt-5|gpt-4|claude|gemini|opus|sonnet)/i.test(model));
+}
+
+function isLocalModel(model?: string): boolean {
+  return Boolean(model && /(qwen|llama|mlx|ollama|local)/i.test(model));
+}
+
+export function buildUnknownOutcome(event: RouteEvent, checkpoint?: RouterCheckpoint, recordedAt = new Date().toISOString()): RouterOutcome {
+  const model = event.runtime.activeModel;
+  return {
+    schema: ROUTER_OUTCOME_SCHEMA,
+    outcomeId: hashText("outcome", event.eventId, checkpoint?.rawSessionRef.contentHash ?? event.rawSessionRef.contentHash),
+    recordedAt,
+    sessionId: event.sessionId,
+    checkpointId: event.checkpointId,
+    routeEventId: event.eventId,
+    taskType: taskTypeFromCheckpoint(checkpoint),
+    taskStatus: roundStatus(event, checkpoint),
+    testsPassedAfter: null,
+    verifierImproved: null,
+    acceptedDiff: null,
+    userInterrupted: event.decision.action === "stop_and_ask_user",
+    userOverrodeDecision: Boolean(event.observed.overriddenBy),
+    finalFilesTouched: checkpoint ? ((checkpoint.features.diffFilesChanged ?? 0) > 0 ? (checkpoint.features.diffFilesChanged ?? 0) : checkpoint.features.filesTouched) : 0,
+    finalDiffLines: checkpoint?.features.diffLines ?? 0,
+    wallTimeMs: null,
+    cloudCostUsd: null,
+    frontierCalls: isFrontierModel(model) ? 1 : 0,
+    localTurns: isLocalModel(model) ? 1 : 0,
+    reworkTurns: checkpoint?.features.sameErrorRepeatedCount && checkpoint.features.sameErrorRepeatedCount > 1 ? checkpoint.features.sameErrorRepeatedCount - 1 : 0,
+    evidence: {
+      source: "inferred",
+      rawSessionRef: checkpoint?.rawSessionRef ?? event.rawSessionRef,
+      routeEventId: event.eventId,
+    },
+  };
+}
+
+export function inferOutcomes(events: RouteEvent[], checkpoints: RouterCheckpoint[], recordedAt = new Date().toISOString()): RouterOutcome[] {
+  const byCheckpoint = new Map(checkpoints.map((checkpoint) => [checkpoint.checkpointId, checkpoint]));
+  return events.map((event) => buildUnknownOutcome(event, byCheckpoint.get(event.checkpointId), recordedAt));
+}
+
+export function readOutcomes(path?: string): RouterOutcome[] {
+  if (!path) return [];
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) throw new Error(`outcomes file not found: ${path}`);
+  return readFileSync(resolved, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .flatMap((line) => {
+      try { return [JSON.parse(line) as RouterOutcome]; } catch { return []; }
+    });
+}
+
+export function writeOutcomesJsonl(outcomes: RouterOutcome[], path: string): void {
+  const resolved = resolve(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, outcomes.map((outcome) => JSON.stringify(outcome)).join("\n") + (outcomes.length ? "\n" : ""));
+}
+
+export function writeInferredOutcomes(options: { checkpointPath: string; eventsPath: string; outputPath: string }): OutcomeWriteSummary {
+  if (!existsSync(resolve(options.eventsPath))) throw new Error(`required route events file not found: ${options.eventsPath}`);
+  const checkpoints = readCheckpointJsonl(options.checkpointPath);
+  const events = readRouteEvents(options.eventsPath);
+  const outcomes = inferOutcomes(events, checkpoints);
+  writeOutcomesJsonl(outcomes, options.outputPath);
+  return { schema: "pi-router.outcomes-summary.v1", output: resolve(options.outputPath), outcomes: outcomes.length, inferred: outcomes.length };
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/progress.ts

@@ -0,0 +1,93 @@
+import { hashText } from "./hash.js";
+import type { RawPiSessionEvent } from "./session-reader.js";
+import type { ProgressSignals } from "./types.js";
+
+const FILE_PATH_RE = /(?:^|\s)([\w./-]+\.(?:ts|tsx|js|jsx|json|md|yaml|yml|py|rs|go|css|scss|html|sh))(?:\s|$|:)/g;
+
+export function touchedFileHashesFromEvent(event: RawPiSessionEvent): string[] {
+  const files = new Set<string>();
+  const rawMessage = event.raw.message;
+  if (!rawMessage || typeof rawMessage !== "object") return [];
+  const content = (rawMessage as { content?: unknown }).content;
+  if (!Array.isArray(content)) return [];
+  for (const item of content) {
+    if (!item || typeof item !== "object") continue;
+    const record = item as Record<string, unknown>;
+    const args = record.arguments;
+    const command = args && typeof args === "object" ? (args as Record<string, unknown>).command : undefined;
+    if (typeof command !== "string") continue;
+    for (const match of command.matchAll(FILE_PATH_RE)) files.add(match[1]);
+  }
+  return [...files].sort().map((file) => hashText(file));
+}
+
+export function touchedFileHashes(events: RawPiSessionEvent[]): string[] {
+  const files = new Set<string>();
+  for (const event of events) {
+    for (const fileHash of touchedFileHashesFromEvent(event)) files.add(fileHash);
+  }
+  return [...files].sort();
+}
+
+function consecutiveRepeatCount<T>(items: T[], valueOf: (item: T) => string | undefined): number {
+  let last: string | undefined;
+  let count = 0;
+  for (let index = items.length - 1; index >= 0; index--) {
+    const value = valueOf(items[index]);
+    if (!value) continue;
+    if (last === undefined) {
+      last = value;
+      count = 1;
+      continue;
+    }
+    if (value !== last) break;
+    count++;
+  }
+  return count;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+export function computeProgressSignals(events: RawPiSessionEvent[]): ProgressSignals {
+  const commandEvents = events.flatMap((event) => event.commandEvents);
+  const toolResults = events.flatMap((event) => event.toolResult ? [event.toolResult] : []);
+  const errorResults = toolResults.filter((result) => result.isError && result.errorHash);
+  const sameCommandRepeatedCount = consecutiveRepeatCount(commandEvents, (event) => event.normalizedCommandHash);
+  const sameErrorRepeatedCount = consecutiveRepeatCount(errorResults, (event) => event.errorHash);
+  const verifierUsed = commandEvents.some((event) => event.isVerifier);
+  const recentCommands = commandEvents.slice(-10);
+  const uniqueRecentCommands = new Set(recentCommands.map((event) => event.normalizedCommandHash).filter(Boolean));
+  const fileHashes = touchedFileHashes(events);
+
+  const commandRepeatPressure = clamp01((sameCommandRepeatedCount - 1) / 3);
+  const errorRepeatPressure = clamp01((sameErrorRepeatedCount - 1) / 3);
+  const toolThrashScore = recentCommands.length === 0 ? 0 : clamp01(1 - uniqueRecentCommands.size / recentCommands.length);
+  const noVerifierUsed = fileHashes.length > 0 && commandEvents.length >= 4 && !verifierUsed;
+  const noVerifierPressure = noVerifierUsed ? 0.2 : 0;
+  const loopScore = clamp01(commandRepeatPressure * 0.35 + errorRepeatPressure * 0.4 + toolThrashScore * 0.2 + noVerifierPressure);
+  const progressScore = clamp01(1 - loopScore - (noVerifierUsed ? 0.1 : 0));
+  const lastError = errorResults.at(-1)?.errorHash;
+  const previousError = errorResults.at(-2)?.errorHash;
+
+  return {
+    sameCommandRepeatedCount,
+    sameErrorRepeatedCount,
+    errorChanged: Boolean(lastError && previousError && lastError !== previousError),
+    testsImproved: null,
+    filesTouched: fileHashes.length,
+    diffLines: 0,
+    diffFilesChanged: 0,
+    diffLinesAdded: 0,
+    diffLinesDeleted: 0,
+    diffChurnScore: 0,
+    toolThrashScore,
+    goalDriftScore: 0,
+    loopScore,
+    progressScore,
+    verifierUsed,
+    noVerifierUsed,
+    toolCallsLast10Turns: recentCommands.length,
+  };
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/session-reader.ts

@@ -0,0 +1,217 @@
+import { basename, resolve } from "node:path";
+import { createReadStream, readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { hashMaybe, hashText, normalizeText } from "./hash.js";
+import type { SessionCommandEvent, SessionEventPointer, SessionRole, SessionToolResultEvent } from "./types.js";
+
+export interface RawPiSessionEvent {
+  index: number;
+  byteStart: number;
+  byteEnd: number;
+  raw: Record<string, unknown>;
+  rawLineHash: string;
+  pointer: SessionEventPointer;
+  role: SessionRole;
+  textHash?: string;
+  normalizedTextHash?: string;
+  commandEvents: SessionCommandEvent[];
+  toolResult?: SessionToolResultEvent;
+  provider?: string;
+  model?: string;
+  usage?: Record<string, unknown>;
+}
+
+export interface PiSession {
+  id: string;
+  path: string;
+  cwd?: string;
+  events: RawPiSessionEvent[];
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function roleOf(raw: Record<string, unknown>): SessionRole {
+  const message = asRecord(raw.message);
+  const role = String(message?.role ?? "");
+  if (role === "user" || role === "assistant" || role === "toolResult" || role === "system") return role;
+  return "unknown";
+}
+
+function textFromContent(content: unknown): string {
+  const parts: string[] = [];
+  for (const item of asArray(content)) {
+    const record = asRecord(item);
+    if (!record) continue;
+    if (typeof record.text === "string") parts.push(record.text);
+  }
+  return parts.join("\n");
+}
+
+function commandFromToolCallArgs(args: unknown): string | undefined {
+  if (typeof args === "string") return args;
+  const record = asRecord(args);
+  const command = record?.command;
+  return typeof command === "string" ? command : undefined;
+}
+
+function isVerifierCommand(command: string): boolean {
+  return /\b(npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|check|lint|build)\b|\b(vitest|pytest|cargo\s+test|go\s+test|make\s+test|tsc\b)/i.test(command);
+}
+
+function normalizedErrorFingerprint(text: string): string {
+  return String(text ?? "")
+    .toLowerCase()
+    .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/g, " <uuid> ")
+    .replace(/0x[0-9a-f]+/g, " <addr> ")
+    .replace(/\b\d{4}-\d{2}-\d{2}t\d{2}:\d{2}:\d{2}(?:\.\d+)?z?\b/g, " <timestamp> ")
+    .replace(/\b[\w./-]+\.(?:test\.)?(?:ts|tsx|js|jsx|json|md|yaml|yml|py|rs|go|css|scss|html|sh)(?::\d+)*(?:\b|$)/g, " <file> ")
+    .replace(/(?:file:\/\/)?(?:\/[\w .-]+)+/g, " <path> ")
+    .replace(/\bline\s+\d+\b/g, " line <n> ")
+    .replace(/\bcolumn\s+\d+\b/g, " column <n> ")
+    .replace(/\b\d+ms\b/g, " <duration> ")
+    .replace(/\bport\s+\d+\b/g, " port <n> ")
+    .replace(/\b\d+\b/g, " <n> ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function exitCodeFromText(text: string): number | undefined {
+  const match = text.match(/\b(?:exit(?:ed)?(?: with)? code|code)\s+([1-9]\d*)\b/i);
+  return match ? Number(match[1]) : undefined;
+}
+
+function failingTestHashFromText(text: string): string | undefined {
+  const match = text.match(/(?:FAIL|FAILED)\s+([^\n\r]+)/i) ?? text.match(/(?:test|it)\(["']([^"']+)["']/i);
+  return match?.[1] ? hashText(normalizeText(match[1])) : undefined;
+}
+
+function commandEventsFromMessage(eventIndex: number, raw: Record<string, unknown>): SessionCommandEvent[] {
+  const message = asRecord(raw.message);
+  if (message?.role !== "assistant") return [];
+
+  return asArray(message.content).flatMap((item) => {
+    const record = asRecord(item);
+    if (!record || record.type !== "toolCall") return [];
+    const toolName = typeof record.name === "string" ? record.name : "unknown";
+    const command = toolName === "bash" ? commandFromToolCallArgs(record.arguments) : undefined;
+    return [{
+      eventIndex,
+      toolCallId: typeof record.id === "string" ? record.id : undefined,
+      toolName,
+      commandHash: command ? hashText(command) : undefined,
+      normalizedCommandHash: command ? hashMaybe(command) : undefined,
+      isVerifier: command ? isVerifierCommand(command) : false,
+    } satisfies SessionCommandEvent];
+  });
+}
+
+function toolResultFromMessage(eventIndex: number, raw: Record<string, unknown>): SessionToolResultEvent | undefined {
+  const message = asRecord(raw.message);
+  if (message?.role !== "toolResult") return undefined;
+  const text = textFromContent(message.content);
+  const isError = Boolean(message.isError) || /\b(error|failed|failure|traceback|exception|not found|enoent|command exited with code [1-9])\b/i.test(text);
+  const fingerprint = isError && text ? normalizedErrorFingerprint(text) : "";
+  return {
+    eventIndex,
+    toolCallId: typeof message.toolCallId === "string" ? message.toolCallId : undefined,
+    toolName: typeof message.toolName === "string" ? message.toolName : undefined,
+    isError,
+    outputHash: text ? hashText(text) : undefined,
+    normalizedOutputHash: text ? hashMaybe(text) : undefined,
+    errorHash: isError && text ? hashMaybe(text) : undefined,
+    errorFingerprintHash: fingerprint ? hashText(fingerprint) : undefined,
+    exitCode: text ? exitCodeFromText(text) : undefined,
+    failingTestHash: text ? failingTestHashFromText(text) : undefined,
+  };
+}
+
+function textHashes(raw: Record<string, unknown>): { textHash?: string; normalizedTextHash?: string } {
+  const message = asRecord(raw.message);
+  if (!message) return {};
+  const text = textFromContent(message.content);
+  if (!text) return {};
+  return { textHash: hashText(text), normalizedTextHash: hashText(normalizeText(text)) };
+}
+
+function modelFrom(raw: Record<string, unknown>): { provider?: string; model?: string; usage?: Record<string, unknown> } {
+  const message = asRecord(raw.message);
+  return {
+    provider: typeof raw.provider === "string" ? raw.provider : typeof message?.provider === "string" ? message.provider : undefined,
+    model: typeof raw.modelId === "string" ? raw.modelId : typeof message?.model === "string" ? message.model : undefined,
+    usage: asRecord(message?.usage),
+  };
+}
+
+export function sessionIdFromPath(path: string): string {
+  return basename(path).replace(/\.jsonl$/i, "");
+}
+
+export function parsePiSessionLine(line: string, index: number, byteStart: number, byteEnd: number): RawPiSessionEvent {
+  const raw = JSON.parse(line) as Record<string, unknown>;
+  const role = roleOf(raw);
+  const model = modelFrom(raw);
+  return {
+    index,
+    byteStart,
+    byteEnd,
+    raw,
+    rawLineHash: hashText(line),
+    pointer: {
+      index,
+      byteStart,
+      byteEnd,
+      id: typeof raw.id === "string" ? raw.id : undefined,
+      timestamp: typeof raw.timestamp === "string" ? raw.timestamp : undefined,
+      type: typeof raw.type === "string" ? raw.type : "unknown",
+      role,
+    },
+    role,
+    ...textHashes(raw),
+    commandEvents: commandEventsFromMessage(index, raw),
+    toolResult: toolResultFromMessage(index, raw),
+    ...model,
+  };
+}
+
+export async function* streamPiSessionEvents(path: string): AsyncGenerator<RawPiSessionEvent> {
+  const input = createReadStream(resolve(path), { encoding: "utf8" });
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  let index = 0;
+  let byteStart = 0;
+  for await (const line of lines) {
+    const byteEnd = byteStart + Buffer.byteLength(`${line}\n`);
+    if (line.trim()) {
+      yield parsePiSessionLine(line, index, byteStart, byteEnd);
+      index++;
+    }
+    byteStart = byteEnd;
+  }
+}
+
+export function readPiSession(path: string): PiSession {
+  const resolved = resolve(path);
+  const rawBuffer = readFileSync(resolved);
+  const text = rawBuffer.toString("utf8");
+  const events: RawPiSessionEvent[] = [];
+  let byteStart = 0;
+  let cwd: string | undefined;
+
+  for (const line of text.split(/(?<=\n)/)) {
+    const withoutNewline = line.endsWith("\n") ? line.slice(0, -1) : line;
+    const byteEnd = byteStart + Buffer.byteLength(line);
+    if (withoutNewline.trim()) {
+      const event = parsePiSessionLine(withoutNewline, events.length, byteStart, byteEnd);
+      if (event.raw.type === "session" && typeof event.raw.cwd === "string") cwd = event.raw.cwd;
+      events.push(event);
+    }
+    byteStart = byteEnd;
+  }
+
+  return { id: sessionIdFromPath(resolved), path: resolved, cwd, events };
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/subagents.ts

@@ -0,0 +1,178 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hashText } from "./hash.js";
+import type {
+  ContextPolicy,
+  RouterCheckpoint,
+  SubagentReturnContract,
+  SubagentRole,
+  SubagentToolPolicy,
+} from "./types.js";
+
+export const SUBAGENT_DECISION_SCHEMA = "pi-router.subagent-decision.v1" as const;
+export const SUBAGENT_LEDGER_EVENT_SCHEMA = "pi-router.subagent-ledger-event.v1" as const;
+export const EVIDENCE_SUMMARY_SCHEMA = "pi-router.evidence-summary.v1" as const;
+
+export interface EvidenceSummaryItem {
+  kind: "file" | "command" | "session" | "manual";
+  ref: string;
+  reason: string;
+  outputFingerprint?: string;
+}
+
+export interface EvidenceSummaryContract {
+  schema: typeof EVIDENCE_SUMMARY_SCHEMA;
+  status: "success" | "partial" | "failed";
+  confidence: number;
+  recommendedNextAction: string;
+  evidence: EvidenceSummaryItem[];
+  findings: string[];
+  risks: string[];
+  minimalPayloadForParent: string;
+  rawTraceRef?: {
+    childSessionId?: string;
+    path?: string;
+    fromEvent?: number;
+    toEvent?: number;
+  };
+}
+
+export interface SubagentRouteDecision {
+  schema: typeof SUBAGENT_DECISION_SCHEMA;
+  parentCheckpointId: string;
+  action: "spawn_subagent";
+  subagentRole: SubagentRole;
+  targetModel: string;
+  toolPolicy: SubagentToolPolicy;
+  contextPolicy: ContextPolicy | "goal_only" | "focused_files" | "repo_card_plus_goal";
+  returnContract: SubagentReturnContract;
+  maxSteps: number;
+  maxTokens: number | null;
+  confidence: number;
+  reason: string;
+}
+
+export interface SubagentLedgerEvent {
+  schema: typeof SUBAGENT_LEDGER_EVENT_SCHEMA;
+  eventId: string;
+  recordedAt: string;
+  parentSessionId: string;
+  childSessionId: string;
+  parentCheckpointId: string;
+  subagentRole: SubagentRole;
+  model: string;
+  toolPolicy: SubagentToolPolicy;
+  contextPolicy: SubagentRouteDecision["contextPolicy"];
+  inputSummaryHash: string;
+  outputSummaryHash: string;
+  acceptedIntoParent: boolean | null;
+  useful: boolean | null;
+  causedRework: boolean | null;
+  returnContract: SubagentReturnContract;
+}
+
+function clampConfidence(value: number): number {
+  return Math.max(0, Math.min(1, Number(value.toFixed(3))));
+}
+
+export function recommendSubagentDecision(
+  checkpoint: RouterCheckpoint,
+  profile: Partial<Record<SubagentRole | "worker" | "smart" | "reviewer", string>>,
+): SubagentRouteDecision | null {
+  if (checkpoint.phase === "research" || (checkpoint.phase === "unknown" && checkpoint.features.toolCallsLast10Turns === 0)) {
+    return buildSubagentDecision(checkpoint, {
+      subagentRole: "explore",
+      targetModel: profile.explore ?? profile.worker ?? "unknown",
+      toolPolicy: "read_only",
+      contextPolicy: "goal_only",
+      confidence: 0.68,
+      reason: "repo area or question appears exploratory; a read-only fresh-context scout can reduce main-context pollution",
+    });
+  }
+  if (checkpoint.phase === "debug" && checkpoint.features.sameErrorRepeatedCount >= 2) {
+    return buildSubagentDecision(checkpoint, {
+      subagentRole: "debug_diagnose",
+      targetModel: profile.debug_diagnose ?? profile.smart ?? "unknown",
+      toolPolicy: "read_only",
+      contextPolicy: "focused_error_and_diff",
+      confidence: clampConfidence(0.72 + Math.min(checkpoint.features.sameErrorRepeatedCount, 4) * 0.04),
+      reason: "repeated failure fingerprint; ask a focused diagnostic subagent for evidence-backed root cause",
+    });
+  }
+  if (checkpoint.phase === "review" && checkpoint.features.diffLines >= 250) {
+    return buildSubagentDecision(checkpoint, {
+      subagentRole: "review",
+      targetModel: profile.review ?? profile.reviewer ?? profile.smart ?? "unknown",
+      toolPolicy: "read_only",
+      contextPolicy: "diff_only",
+      confidence: 0.74,
+      reason: "large review diff; spawn read-only reviewer with diff-only context and evidence contract",
+    });
+  }
+  if (checkpoint.features.noVerifierUsed) {
+    return buildSubagentDecision(checkpoint, {
+      subagentRole: "verify",
+      targetModel: profile.verify ?? profile.worker ?? "unknown",
+      toolPolicy: "test_only",
+      contextPolicy: "focused_files",
+      confidence: 0.7,
+      reason: "implementation/debug work changed files without verifier; run bounded verification outside main context",
+    });
+  }
+  return null;
+}
+
+export function buildSubagentDecision(
+  checkpoint: RouterCheckpoint,
+  options: Omit<SubagentRouteDecision, "schema" | "parentCheckpointId" | "action" | "returnContract" | "maxSteps" | "maxTokens"> & Partial<Pick<SubagentRouteDecision, "maxSteps" | "maxTokens" | "returnContract">>,
+): SubagentRouteDecision {
+  return {
+    schema: SUBAGENT_DECISION_SCHEMA,
+    parentCheckpointId: checkpoint.checkpointId,
+    action: "spawn_subagent",
+    subagentRole: options.subagentRole,
+    targetModel: options.targetModel,
+    toolPolicy: options.toolPolicy,
+    contextPolicy: options.contextPolicy,
+    returnContract: options.returnContract ?? "evidence_summary_v1",
+    maxSteps: options.maxSteps ?? 8,
+    maxTokens: options.maxTokens ?? null,
+    confidence: clampConfidence(options.confidence),
+    reason: options.reason,
+  };
+}
+
+export function buildSubagentLedgerEvent(options: Omit<SubagentLedgerEvent, "schema" | "eventId" | "recordedAt"> & { recordedAt?: string }): SubagentLedgerEvent {
+  const recordedAt = options.recordedAt ?? new Date().toISOString();
+  return {
+    schema: SUBAGENT_LEDGER_EVENT_SCHEMA,
+    eventId: hashText("subagent", options.parentSessionId, options.childSessionId, options.parentCheckpointId, options.subagentRole, options.outputSummaryHash),
+    recordedAt,
+    parentSessionId: options.parentSessionId,
+    childSessionId: options.childSessionId,
+    parentCheckpointId: options.parentCheckpointId,
+    subagentRole: options.subagentRole,
+    model: options.model,
+    toolPolicy: options.toolPolicy,
+    contextPolicy: options.contextPolicy,
+    inputSummaryHash: options.inputSummaryHash,
+    outputSummaryHash: options.outputSummaryHash,
+    acceptedIntoParent: options.acceptedIntoParent,
+    useful: options.useful,
+    causedRework: options.causedRework,
+    returnContract: options.returnContract,
+  };
+}
+
+export function appendSubagentLedgerEvent(path: string, event: SubagentLedgerEvent): void {
+  const resolved = resolve(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${JSON.stringify(event)}\n`, { flag: "a" });
+}
+
+export function readSubagentLedgerEvents(path: string): SubagentLedgerEvent[] {
+  return readFileSync(resolve(path), "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as SubagentLedgerEvent);
+}