@fiale-plus/pi-rogue 0.2.0 → 0.2.2

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/advisor-checkins.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { sessionKey } from "./internal.js";
 
 type AdvisorConfig = Record<string, unknown> & { checkins?: "mid-hour" | "off"; checkinStartedAt?: number };
 type AdvisorState = Record<string, unknown> & {
@@ -34,6 +35,15 @@ const ADVISOR_DIR = join(homedir(), ".pi", "agent", "pi-rogue", "advisor");
 const ADVISOR_CONFIG_PATH = join(homedir(), ".pi", "agent", "pi-rogue", "advisor", "config.json");
 const ADVISOR_STATE_PATH = join(ADVISOR_DIR, "state.json");
 
+function safeSessionKey(key: string): string {
+  const safe = String(key || "session").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return safe || "session";
+}
+
+export function advisorSessionStatePath(ctx: any): string {
+  return join(ADVISOR_DIR, "sessions", safeSessionKey(sessionKey(ctx)), "state.json");
+}
+
 function readJson<T>(file: string): T {
   if (!existsSync(file)) return {} as T;
   try {
@@ -63,9 +73,14 @@ export function setAdvisorCheckinsEnabled(enabled: boolean, configPath = ADVISOR
 }
 
 export function resetAdvisorSessionContext(
-  configPath = ADVISOR_CONFIG_PATH,
-  statePath = ADVISOR_STATE_PATH,
+  ctxOrConfigPath?: any,
+  configPathOrStatePath = ADVISOR_STATE_PATH,
+  explicitStatePath?: string,
 ): { config: AdvisorConfig; state: AdvisorState } {
+  const configPath = typeof ctxOrConfigPath === "string" ? ctxOrConfigPath : ADVISOR_CONFIG_PATH;
+  const statePath = typeof ctxOrConfigPath === "string"
+    ? configPathOrStatePath
+    : explicitStatePath || (ctxOrConfigPath ? advisorSessionStatePath(ctxOrConfigPath) : ADVISOR_STATE_PATH);
   const currentConfig = cleanAdvisorConfig(readJson<AdvisorConfig>(configPath));
   const nextConfig: AdvisorConfig = {
     ...currentConfig,

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/goal.ts

@@ -54,7 +54,7 @@ export function setGoal(ctx: any, goal: string, options: { restartDuplicate?: bo
   }
   clearLoop(ctx, { clearResearch: true, preserveCheckins: true });
   writeText(sessionFile(FEATURE, ctx, CURRENT_FILE), note ? `${note}\n` : "");
-  resetAdvisorSessionContext();
+  resetAdvisorSessionContext(ctx);
   if (note) {
     setAdvisorCheckinsEnabled(true);
   }
@@ -68,7 +68,7 @@ export function setGoal(ctx: any, goal: string, options: { restartDuplicate?: bo
 
 export function clearGoal(ctx: any): void {
   writeText(sessionFile(FEATURE, ctx, CURRENT_FILE), "");
-  resetAdvisorSessionContext();
+  resetAdvisorSessionContext(ctx);
 }
 
 function goalBlock(goal: string): string {

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/internal.ts

@@ -77,10 +77,19 @@ export function featureDir(feature: string): string {
   return dir;
 }
 
+function safeSessionKey(key: string): string {
+  const safe = String(key || "session").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return safe || "session";
+}
+
 export function sessionKey(ctx: any): string {
   const sessionFile = ctx?.sessionManager?.getSessionFile?.();
-  if (!sessionFile) return "session";
-  return basename(String(sessionFile)).replace(/\.[^.]+$/, "");
+  if (typeof sessionFile === "string" && sessionFile.length > 0) {
+    return safeSessionKey(basename(String(sessionFile)).replace(/\.[^.]+$/, ""));
+  }
+  const sessionId = ctx?.session?.id || process.env.PI_ROGUE_SESSION_ID;
+  if (typeof sessionId === "string" && sessionId.length > 0) return safeSessionKey(sessionId);
+  return "session";
 }
 
 export function sessionDir(feature: string, ctx: any): string {

package/node_modules/@fiale-plus/pi-rogue-router/README.md

@@ -0,0 +1,32 @@
+# Pi-Rogue Router
+
+Local-only offline trajectory router experiments for Pi-Rogue.
+
+This package intentionally does **not** change live advisor or orchestration behavior. It reads existing Pi session JSONL files, derives compact checkpoints, and computes cheap progress/loop signals without copying raw transcript content into derived artifacts.
+
+```bash
+npm run router:rebuild -- --session ~/.pi/agent/sessions/.../session.jsonl --output .pi/router/checkpoints.jsonl
+npm run router:rebuild -- --session-dir ~/.pi/agent/sessions/... --output .pi/router/checkpoints.jsonl
+npm run router:rebuild -- --session ./current-session.jsonl --workspace-diff --output .pi/router/checkpoints-with-live-diff.jsonl
+npm run router:decide -- --checkpoint-file .pi/router/checkpoints.jsonl --ledger .pi/router/events.jsonl
+npm run router:cards -- --events .pi/router/events.jsonl --output .pi/router/model-cards.jsonl
+npm run router:outcomes -- --checkpoint-file .pi/router/checkpoints.jsonl --events .pi/router/events.jsonl --output .pi/router/outcomes.jsonl
+npm run router:teacher-requests -- --checkpoint-file .pi/router/checkpoints.jsonl --output .pi/router/teacher-requests.jsonl --teacher openai-codex/gpt-5.5
+npm run router:reflect -- --checkpoint-file .pi/router/checkpoints.jsonl --labels .pi/router/labels/teacher-labels.jsonl --reflection .pi/router/reflections/session.md --teacher local-rule
+npm run router:dataset -- --checkpoint-file .pi/router/checkpoints.jsonl --events .pi/router/events.jsonl --outcomes .pi/router/outcomes.jsonl --labels .pi/router/labels/teacher-labels.jsonl --output .pi/router/training.jsonl
+npm run router:shadow -- --checkpoint-file .pi/router/checkpoints.jsonl --ledger .pi/router/events.jsonl --output .pi/router/shadow-report.json
+
+# Live observe-only extension commands:
+# /router on|off|status|profile|profiles|models|configure|cycle
+# ctrl+alt+p cycles router profiles (Ctrl-P is reserved by Pi model cycling).
+```
+
+## V1 telemetry notes
+
+Router v1 is still observe-only. It adds outcome skeletons, stronger diff/error fingerprints, teacher-label request export, binary gate dataset export, and subagent-aware telemetry schemas. It does not switch models, spawn agents, or promote policies automatically.
+
+- Diff telemetry stores counts and hashes from `git diff`, not raw patches. Offline rebuilds remain deterministic by default; use `--workspace-diff` only with one current live session/worktree snapshot.
+- Error fingerprints normalize paths, line numbers, timestamps, UUIDs, ports, and object ids before hashing.
+- `router:teacher-requests` writes local JSONL requests for an explicit teacher model; imported teacher decisions are still required before labels become training truth.
+- `router:dataset` excludes `local-rule` labels by default so a future model does not merely imitate the current rules.
+- Subagent route/ledger schemas describe parent-child evidence flow, but live autonomous spawning remains out of scope.

package/node_modules/@fiale-plus/pi-rogue-router/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fiale-plus/pi-rogue-router",
+  "version": "0.1.0",
+  "description": "Local-only offline trajectory router experiments for Pi-Rogue.",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "check": "tsc -p ../../tsconfig.json --noEmit",
+    "test": "cd ../.. && vitest run packages/router/src/*.test.ts"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./extension": "./src/extension.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ]
+}

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

@@ -0,0 +1,84 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { buildCheckpoints, rebuildCheckpointsFromSession, streamCheckpointsFromSessionPath, writeCheckpointsJsonl } from "./checkpoints.js";
+import { readPiSession } from "./session-reader.js";
+
+function writeFixture(lines: Array<Record<string, unknown>>): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-router-"));
+  const path = join(dir, "2026-06-12T00-00-00Z_fixture.jsonl");
+  writeFileSync(path, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
+  return path;
+}
+
+function fixtureSession(): string {
+  return writeFixture([
+    { type: "session", version: 1, id: "session-1", timestamp: "2026-06-12T00:00:00.000Z", cwd: "/repo/example" },
+    { type: "model_change", id: "m1", timestamp: "2026-06-12T00:00:01.000Z", provider: "local", modelId: "qwen-local" },
+    { type: "message", id: "u1", timestamp: "2026-06-12T00:00:02.000Z", message: { role: "user", content: [{ type: "text", text: "please fix the failing tests" }] } },
+    { type: "message", id: "a1", timestamp: "2026-06-12T00:00:03.000Z", message: { role: "assistant", provider: "local", model: "qwen-local", usage: { inputTokens: 1234 }, content: [{ type: "toolCall", id: "call-1", name: "bash", arguments: { command: "npm test -- --runInBand src/foo.test.ts" } }] } },
+    { type: "message", id: "t1", timestamp: "2026-06-12T00:00:04.000Z", message: { role: "toolResult", toolCallId: "call-1", toolName: "bash", isError: true, content: [{ type: "text", text: "FAIL src/foo.test.ts\nError: boom" }] } },
+    { type: "message", id: "a2", timestamp: "2026-06-12T00:00:05.000Z", message: { role: "assistant", provider: "local", model: "qwen-local", content: [{ type: "toolCall", id: "call-2", name: "bash", arguments: { command: "npm test -- --runInBand src/foo.test.ts" } }] } },
+    { type: "message", id: "t2", timestamp: "2026-06-12T00:00:06.000Z", message: { role: "toolResult", toolCallId: "call-2", toolName: "bash", isError: true, content: [{ type: "text", text: "FAIL src/foo.test.ts\nError: boom" }] } },
+  ]);
+}
+
+describe("trajectory router checkpoint rebuild", () => {
+  it("reads Pi session JSONL and extracts command/tool metadata", () => {
+    const session = readPiSession(fixtureSession());
+
+    expect(session.id).toBe("2026-06-12T00-00-00Z_fixture");
+    expect(session.cwd).toBe("/repo/example");
+    expect(session.events).toHaveLength(7);
+    expect(session.events[3].commandEvents[0]).toMatchObject({ toolName: "bash", isVerifier: true });
+    expect(session.events[4].toolResult).toMatchObject({ toolName: "bash", isError: true });
+  });
+
+  it("builds compact derived checkpoints without raw transcript content", () => {
+    const checkpoints = rebuildCheckpointsFromSession(fixtureSession());
+    const last = checkpoints.at(-1);
+
+    expect(last?.schema).toBe("pi-router.checkpoint.v1");
+    expect(last?.rawSessionRef).toMatchObject({ schema: "pi-router.raw-session-ref.v1", fromEvent: 0, toEvent: 6 });
+    expect(last?.activeModel).toBe("qwen-local");
+    expect(last?.provider).toBe("local");
+    expect(last?.phase).toBe("debug");
+    expect(last?.features.contextTokensApprox).toBe(1234);
+    expect(last?.features.sameCommandRepeatedCount).toBe(2);
+    expect(last?.features.sameErrorRepeatedCount).toBe(2);
+    expect(last?.features.verifierUsed).toBe(true);
+    expect(last?.features.loopScore).toBeGreaterThan(0);
+    expect(last?.recent.lastCommandHash).toBeTruthy();
+    expect(last?.recent.lastErrorHash).toBeTruthy();
+    expect(last?.recent.touchedFileHashes).toHaveLength(1);
+
+    const serialized = JSON.stringify(last);
+    expect(serialized).not.toContain("please fix the failing tests");
+    expect(serialized).not.toContain("npm test");
+    expect(serialized).not.toContain("Error: boom");
+    expect(serialized).not.toContain("src/foo.test.ts");
+  });
+
+  it("streams checkpoints equivalent to the sync fixture API", async () => {
+    const path = fixtureSession();
+    const sync = rebuildCheckpointsFromSession(path).map((checkpoint) => checkpoint.checkpointId);
+    const streamed: string[] = [];
+
+    for await (const checkpoint of streamCheckpointsFromSessionPath(path)) streamed.push(checkpoint.checkpointId);
+
+    expect(streamed).toEqual(sync);
+  });
+
+  it("writes checkpoints as JSONL", () => {
+    const session = readPiSession(fixtureSession());
+    const checkpoints = buildCheckpoints(session);
+    const output = join(mkdtempSync(join(tmpdir(), "pi-router-out-")), "checkpoints.jsonl");
+
+    writeCheckpointsJsonl(checkpoints, output);
+
+    const lines = readFileSync(output, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(checkpoints.length);
+    expect(JSON.parse(lines.at(-1) || "{}").checkpointId).toBe(checkpoints.at(-1)?.checkpointId);
+  });
+});

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

@@ -0,0 +1,355 @@
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hashMaybe, hashText, normalizeText } from "./hash.js";
+import { diffChurnScore, EMPTY_DIFF_STATS, readGitDiffStats } from "./git-features.js";
+import { touchedFileHashesFromEvent } from "./progress.js";
+import { readPiSession, sessionIdFromPath, streamPiSessionEvents, type PiSession, type RawPiSessionEvent } from "./session-reader.js";
+import { RAW_SESSION_REF_SCHEMA, ROUTER_CHECKPOINT_SCHEMA, type ProgressSignals, type RawSessionRef, type RouterCheckpoint, type SessionCommandEvent, type SessionToolResultEvent } from "./types.js";
+
+function textFromEvent(event: RawPiSessionEvent): string {
+  const message = event.raw.message;
+  if (!message || typeof message !== "object") return "";
+  const content = (message as { content?: unknown }).content;
+  if (!Array.isArray(content)) return "";
+  return content.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const text = (item as Record<string, unknown>).text;
+    return typeof text === "string" ? [text] : [];
+  }).join("\n");
+}
+
+function phaseFromText(text: string): RouterCheckpoint["phase"] {
+  const normalized = normalizeText(text);
+  if (/\b(debug|bug|error|fail(?:ed|ing|ure)?|broken|crash|traceback|stack)\b/.test(normalized)) return "debug";
+  if (/\b(review|diff|pr|pull request|audit|looks good)\b/.test(normalized)) return "review";
+  if (/\b(research|docs?|look up|what is|compare|benchmark)\b/.test(normalized)) return "research";
+  if (/\b(install|config|configure|status|logs?|deploy|environment|shell)\b/.test(normalized)) return "ops";
+  if (/\b(plan|design|architecture|strategy|scope)\b/.test(normalized)) return "planning";
+  if (/\b(implement|build|add|edit|refactor|fix|write|change)\b/.test(normalized)) return "implementation";
+  return "unknown";
+}
+
+function contextTokensFromUsage(usage: Record<string, unknown> | undefined): number | null {
+  if (!usage) return null;
+  const candidates = ["inputTokens", "input_tokens", "promptTokens", "prompt_tokens", "totalTokens", "total_tokens"];
+  for (const key of candidates) {
+    const value = usage[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return null;
+}
+
+interface SessionContext {
+  id: string;
+  path: string;
+  cwd?: string;
+}
+
+function rawSessionRef(session: SessionContext, refEvents: RawPiSessionEvent[], last: RawPiSessionEvent | undefined): RawSessionRef {
+  const first = refEvents[0];
+  const fromByte = first?.byteStart ?? 0;
+  const toByte = last?.byteEnd ?? 0;
+  return {
+    schema: RAW_SESSION_REF_SCHEMA,
+    path: session.path,
+    fromEvent: first?.index ?? 0,
+    toEvent: last?.index ?? 0,
+    fromByte,
+    toByte,
+    contentHash: hashText(...refEvents.map((event) => event.rawLineHash)),
+  };
+}
+
+function repoHashFromCwd(cwd?: string): string | undefined {
+  return cwd ? hashText(resolve(cwd)) : undefined;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+const RAW_REF_EVENT_WINDOW = 30;
+
+interface BuildState {
+  activeModel?: string;
+  provider?: string;
+  contextTokensApprox: number | null;
+  lastUserGoalHash?: string;
+  phase: RouterCheckpoint["phase"];
+  lastCommandHash?: string;
+  sameCommandRepeatedCount: number;
+  lastErrorHash?: string;
+  previousErrorHash?: string;
+  lastErrorFingerprintHash?: string;
+  previousErrorFingerprintHash?: string;
+  sameErrorRepeatedCount: number;
+  verifierUsed: boolean;
+  commandCount: number;
+  recentCommands: string[];
+  touchedFileHashes: Set<string>;
+  diffStats: import("./types.js").DiffStats;
+}
+
+function updateCommandState(state: BuildState, command: SessionCommandEvent): void {
+  if (command.normalizedCommandHash) {
+    if (state.lastCommandHash === command.normalizedCommandHash) state.sameCommandRepeatedCount++;
+    else state.sameCommandRepeatedCount = 1;
+    state.lastCommandHash = command.normalizedCommandHash;
+    state.recentCommands.push(command.normalizedCommandHash);
+    state.recentCommands = state.recentCommands.slice(-10);
+  }
+  state.commandCount++;
+  state.verifierUsed = state.verifierUsed || command.isVerifier;
+}
+
+function updateToolResultState(state: BuildState, result: SessionToolResultEvent): void {
+  const errorKey = result.errorFingerprintHash ?? result.errorHash;
+  if (!errorKey) return;
+  state.previousErrorHash = state.lastErrorHash;
+  state.previousErrorFingerprintHash = state.lastErrorFingerprintHash;
+  if ((state.lastErrorFingerprintHash ?? state.lastErrorHash) === errorKey) state.sameErrorRepeatedCount++;
+  else state.sameErrorRepeatedCount = 1;
+  state.lastErrorHash = result.errorHash;
+  state.lastErrorFingerprintHash = result.errorFingerprintHash;
+}
+
+function signalsFromState(state: BuildState): ProgressSignals {
+  const uniqueRecentCommands = new Set(state.recentCommands);
+  const commandRepeatPressure = clamp01((state.sameCommandRepeatedCount - 1) / 3);
+  const errorRepeatPressure = clamp01((state.sameErrorRepeatedCount - 1) / 3);
+  const toolThrashScore = state.recentCommands.length === 0 ? 0 : clamp01(1 - uniqueRecentCommands.size / state.recentCommands.length);
+  const changedFiles = state.touchedFileHashes.size + state.diffStats.filesChanged;
+  const phaseWantsVerifier = state.phase === "implementation" || state.phase === "debug" || state.phase === "review";
+  const noVerifierUsed = phaseWantsVerifier && changedFiles > 0 && state.commandCount >= 4 && !state.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));
+  return {
+    sameCommandRepeatedCount: state.sameCommandRepeatedCount,
+    sameErrorRepeatedCount: state.sameErrorRepeatedCount,
+    errorChanged: Boolean(
+      (state.lastErrorFingerprintHash ?? state.lastErrorHash)
+      && (state.previousErrorFingerprintHash ?? state.previousErrorHash)
+      && (state.lastErrorFingerprintHash ?? state.lastErrorHash) !== (state.previousErrorFingerprintHash ?? state.previousErrorHash),
+    ),
+    testsImproved: null,
+    filesTouched: state.touchedFileHashes.size,
+    diffLines: state.diffStats.totalLines,
+    diffFilesChanged: state.diffStats.filesChanged,
+    diffLinesAdded: state.diffStats.linesAdded,
+    diffLinesDeleted: state.diffStats.linesDeleted,
+    diffChurnScore: diffChurnScore(state.diffStats),
+    toolThrashScore,
+    goalDriftScore: 0,
+    loopScore,
+    progressScore,
+    verifierUsed: state.verifierUsed,
+    noVerifierUsed,
+    toolCallsLast10Turns: state.recentCommands.length,
+  };
+}
+
+function checkpointFromState(session: SessionContext, event: RawPiSessionEvent, refEvents: RawPiSessionEvent[], state: BuildState): RouterCheckpoint {
+  const signals = signalsFromState(state);
+  return {
+    schema: ROUTER_CHECKPOINT_SCHEMA,
+    sessionId: session.id,
+    checkpointId: `${session.id}:event-${event.index}`,
+    createdAt: new Date().toISOString(),
+    rawSessionRef: rawSessionRef(session, refEvents, event),
+    harness: "pi",
+    repoHash: repoHashFromCwd(session.cwd),
+    goalHash: state.lastUserGoalHash,
+    phase: state.phase,
+    activeModel: state.activeModel,
+    provider: state.provider,
+    features: {
+      ...signals,
+      turnIndex: event.index,
+      contextTokensApprox: state.contextTokensApprox,
+      gitDirty: null,
+    },
+    recent: {
+      lastUserGoalHash: state.lastUserGoalHash,
+      lastCommandHash: state.lastCommandHash,
+      lastErrorHash: state.lastErrorHash,
+      lastErrorFingerprintHash: state.lastErrorFingerprintHash,
+      touchedFileHashes: [...state.touchedFileHashes].sort(),
+      diffFileHashes: state.diffStats.fileHashes,
+    },
+    sourceEvent: event.pointer,
+  };
+}
+
+function initialBuildState(): BuildState {
+  return {
+    contextTokensApprox: null,
+    phase: "unknown",
+    sameCommandRepeatedCount: 0,
+    sameErrorRepeatedCount: 0,
+    verifierUsed: false,
+    commandCount: 0,
+    recentCommands: [],
+    touchedFileHashes: new Set(),
+    diffStats: EMPTY_DIFF_STATS,
+  };
+}
+
+function updateStateFromEvent(state: BuildState, event: RawPiSessionEvent): void {
+  state.activeModel = event.model ?? state.activeModel;
+  state.provider = event.provider ?? state.provider;
+  state.contextTokensApprox = contextTokensFromUsage(event.usage) ?? state.contextTokensApprox;
+
+  if (event.role === "user") {
+    const text = textFromEvent(event);
+    state.lastUserGoalHash = hashMaybe(text);
+    state.phase = phaseFromText(text);
+  }
+  for (const fileHash of touchedFileHashesFromEvent(event)) state.touchedFileHashes.add(fileHash);
+  for (const command of event.commandEvents) updateCommandState(state, command);
+  if (event.toolResult) updateToolResultState(state, event.toolResult);
+}
+
+function isCheckpointEvent(event: RawPiSessionEvent): boolean {
+  return event.role === "user" || event.role === "assistant" || event.role === "toolResult";
+}
+
+function pushRefWindow(refEvents: RawPiSessionEvent[], event: RawPiSessionEvent): void {
+  refEvents.push(event);
+  if (refEvents.length > RAW_REF_EVENT_WINDOW) refEvents.shift();
+}
+
+export function* iterateCheckpoints(session: PiSession): Generator<RouterCheckpoint> {
+  const state = initialBuildState();
+  const refEvents: RawPiSessionEvent[] = [];
+  for (const event of session.events) {
+    pushRefWindow(refEvents, event);
+    updateStateFromEvent(state, event);
+    if (!isCheckpointEvent(event)) continue;
+    yield checkpointFromState(session, event, refEvents, state);
+  }
+}
+
+export async function* streamCheckpointsFromSessionPath(sessionPath: string): AsyncGenerator<RouterCheckpoint> {
+  const session: SessionContext = { id: sessionIdFromPath(resolve(sessionPath)), path: resolve(sessionPath) };
+  const state = initialBuildState();
+  const refEvents: RawPiSessionEvent[] = [];
+  for await (const event of streamPiSessionEvents(session.path)) {
+    if (event.raw.type === "session" && typeof event.raw.cwd === "string") session.cwd = event.raw.cwd;
+    pushRefWindow(refEvents, event);
+    updateStateFromEvent(state, event);
+    if (!isCheckpointEvent(event)) continue;
+    yield checkpointFromState(session, event, refEvents, state);
+  }
+}
+
+function clampFeature(value: number): number {
+  return Math.max(0, Math.min(1, Number(value.toFixed(3))));
+}
+
+export function checkpointWithDiffStats(checkpoint: RouterCheckpoint, cwd?: string, excludePaths: string[] = []): RouterCheckpoint {
+  const stats = readGitDiffStats(cwd, { excludePaths });
+  if (stats.filesChanged === 0) return checkpoint;
+  const phaseWantsVerifier = checkpoint.phase === "implementation" || checkpoint.phase === "debug" || checkpoint.phase === "review";
+  const noVerifierUsed = checkpoint.features.noVerifierUsed
+    || (phaseWantsVerifier && !checkpoint.features.verifierUsed && checkpoint.features.toolCallsLast10Turns >= 4);
+  const loopScore = noVerifierUsed && !checkpoint.features.noVerifierUsed
+    ? clampFeature(checkpoint.features.loopScore + 0.2)
+    : checkpoint.features.loopScore;
+  const progressScore = noVerifierUsed && !checkpoint.features.noVerifierUsed
+    ? clampFeature(checkpoint.features.progressScore - 0.1)
+    : checkpoint.features.progressScore;
+  return {
+    ...checkpoint,
+    features: {
+      ...checkpoint.features,
+      diffLines: stats.totalLines,
+      diffFilesChanged: stats.filesChanged,
+      diffLinesAdded: stats.linesAdded,
+      diffLinesDeleted: stats.linesDeleted,
+      diffChurnScore: diffChurnScore(stats),
+      noVerifierUsed,
+      loopScore,
+      progressScore,
+    },
+    recent: { ...checkpoint.recent, diffFileHashes: stats.fileHashes },
+  };
+}
+
+function applyWorkspaceDiffToLatest(checkpoints: RouterCheckpoint[], cwd?: string, excludePaths: string[] = []): RouterCheckpoint[] {
+  if (checkpoints.length === 0) return checkpoints;
+  const next = [...checkpoints];
+  next[next.length - 1] = checkpointWithDiffStats(next[next.length - 1], cwd, excludePaths);
+  return next;
+}
+
+export function buildCheckpoints(session: PiSession): RouterCheckpoint[] {
+  return [...iterateCheckpoints(session)];
+}
+
+export function rebuildCheckpointsFromSession(sessionPath: string): RouterCheckpoint[] {
+  return buildCheckpoints(readPiSession(sessionPath));
+}
+
+export function writeCheckpointsJsonl(checkpoints: RouterCheckpoint[], outputPath: string): void {
+  const resolved = resolve(outputPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  const fd = openSync(resolved, "w");
+  try {
+    for (const checkpoint of checkpoints) writeSync(fd, `${JSON.stringify(checkpoint)}\n`);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export interface SessionCheckpointWriteSummary {
+  sessions: string[];
+  output: string;
+  checkpoints: number;
+  firstCheckpointId?: string;
+  lastCheckpointId?: string;
+}
+
+export async function writeSessionCheckpointsJsonl(sessionPaths: string[], outputPath: string, options: { workspaceDiff?: boolean } = {}): Promise<SessionCheckpointWriteSummary> {
+  if (options.workspaceDiff && sessionPaths.length !== 1) {
+    throw new Error("--workspace-diff can only be used with exactly one current session");
+  }
+
+  const resolved = resolve(outputPath);
+  // Compute live workspace diff before opening/truncating the output so the output artifact cannot count itself.
+  const workspaceDiffCheckpoints = options.workspaceDiff
+    ? (() => {
+      const session = readPiSession(sessionPaths[0]);
+      const routerDir = session.cwd ? resolve(session.cwd, ".pi", "router") : undefined;
+      const routerArtifacts = routerDir ? [resolve(routerDir, "config.json"), resolve(routerDir, "state.json"), resolve(routerDir, "events.jsonl")] : [];
+      return applyWorkspaceDiffToLatest(buildCheckpoints(session), session.cwd, [session.path, resolved, ...routerArtifacts]);
+    })()
+    : null;
+  mkdirSync(dirname(resolved), { recursive: true });
+  const fd = openSync(resolved, "w");
+  let checkpoints = 0;
+  let firstCheckpointId: string | undefined;
+  let lastCheckpointId: string | undefined;
+  try {
+    if (workspaceDiffCheckpoints) {
+      for (const checkpoint of workspaceDiffCheckpoints) {
+        firstCheckpointId ??= checkpoint.checkpointId;
+        lastCheckpointId = checkpoint.checkpointId;
+        checkpoints++;
+        writeSync(fd, `${JSON.stringify(checkpoint)}\n`);
+      }
+    } else {
+      for (const sessionPath of sessionPaths) {
+        for await (const checkpoint of streamCheckpointsFromSessionPath(sessionPath)) {
+          firstCheckpointId ??= checkpoint.checkpointId;
+          lastCheckpointId = checkpoint.checkpointId;
+          checkpoints++;
+          writeSync(fd, `${JSON.stringify(checkpoint)}\n`);
+        }
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+  return { sessions: sessionPaths, output: resolved, checkpoints, firstCheckpointId, lastCheckpointId };
+}