tickmarkr 1.69.0 → 1.70.0

package/dist/cli/commands/report.js

@@ -1,8 +1,11 @@
+import { writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { ttyVisual } from "../../adapters/model-lints.js";
 import { addUsage } from "../../adapters/types.js";
 import { dim, rule, title } from "../../brand.js";
 import { loadConfig } from "../../config/config.js";
+import { buildProofBundle } from "../../report/bundle.js";
+import { compareRuns } from "../../report/compare.js";
 import { estimateCosts } from "../../report/cost.js";
 import { cellsOf, cellSummary } from "../../route/profile.js";
 import { Journal, loadRoutingProfile } from "../../run/journal.js";
@@ -316,17 +319,49 @@ const stylizeReport = (out) => {
 export async function report(argv, cwd = process.cwd()) {
     const { values, positionals } = parseArgs({
         args: argv,
-        options: { md: { type: "boolean" } },
+        options: {
+            md: { type: "boolean" },
+            // v1.70 T3: baseline run id for cost/gate/duration delta + environment comparability guard
+            compare: { type: "string" },
+            // v1.70 T4: write a portable, schema-versioned proof packet (local file only — no network)
+            bundle: { type: "string" },
+        },
         allowPositionals: true,
     });
     const runId = positionals[0] ?? Journal.latestRunId(cwd, { withJournal: true });
     if (!runId)
-        throw new Error("no runs found — usage: tickmarkr report <run-id> [--md]");
+        throw new Error("no runs found — usage: tickmarkr report <run-id> [--md] [--compare <baseline-run-id>] [--bundle <path>]");
     const j = Journal.open(cwd, runId);
     const events = j.read();
+    const rows = j.readTelemetry();
+    const cfg = loadConfig(cwd);
+    let bundleNote = "";
+    if (values.bundle) {
+        // Local-only write of the pure proof packet — no network path exists in buildProofBundle.
+        const packet = buildProofBundle(runId, events);
+        writeFileSync(values.bundle, JSON.stringify(packet, null, 2) + "\n");
+        bundleNote = `wrote proof bundle → ${values.bundle}\n`;
+    }
+    let comparison = "";
+    if (values.compare) {
+        const baselineRunId = values.compare;
+        const baseline = Journal.open(cwd, baselineRunId);
+        const outcome = compareRuns({
+            runId,
+            baselineRunId,
+            events,
+            baselineEvents: baseline.read(),
+            rows,
+            baselineRows: baseline.readTelemetry(),
+            cost: cfg.cost,
+        });
+        // Fail closed: missing run-start yields a clear reason, never a partial table.
+        if (!outcome.ok)
+            throw new Error(outcome.reason);
+        comparison = "\n" + outcome.text;
+    }
     if (values.md) {
-        const rows = j.readTelemetry();
-        return renderMarkdownRecord(runId, events, estimateCosts(rows, loadConfig(cwd).cost), rows);
+        return bundleNote + renderMarkdownRecord(runId, events, estimateCosts(rows, cfg.cost), rows) + comparison;
     }
-    return stylizeReport(textReport(runId, events, j.readTelemetry(), cwd));
+    return bundleNote + stylizeReport(textReport(runId, events, rows, cwd)) + comparison;
 }

package/dist/gates/acceptance.d.ts

@@ -2,13 +2,17 @@ import { type WorkerAdapter } from "../adapters/types.js";
 import { type Task } from "../graph/schema.js";
 import { type LlmVia } from "./llm.js";
 import type { GateResult } from "./types.js";
+export interface EvidenceCitation {
+    path: string;
+    line: number;
+}
 export interface JudgeVerdict {
     pass: boolean;
     criteria: Array<{
         criterion: string;
         met: boolean;
         reason: string;
-        evidence: string;
+        evidence: string | EvidenceCitation;
     }>;
 }
 export declare function judgeCriterionId(index: number): string;

package/dist/gates/acceptance.js

@@ -7,13 +7,14 @@ import { checkDiffCap, fetchTaskDiff } from "./review.js";
 import { COMPLETION_FAKING_CHECKLIST, extractVerdictJson, generateVerdictNonce, runLlm, verdictNonceLine } from "./llm.js";
 // Fable F4: acceptance judge shares review's 900s timeout — 300s default killed frontier judges on cap-sized diffs.
 const JUDGE_TIMEOUT_MS = 900_000;
+const CitationSchema = z.object({ path: z.string(), line: z.number().int() });
 const JudgeVerdictRowSchema = z.object({
     criterion: z.string(),
     met: z.boolean(),
     reason: z.string(),
-    // v1.64: a verbatim quote from the judged diff grounding the ruling — required; a verdict
-    // omitting it is malformed and fails closed like any other shape violation.
-    evidence: z.string(),
+    // Required, either form: a row omitting evidence is malformed and fails closed like any other shape
+    // violation. Object → structured citation; string → legacy quote.
+    evidence: z.union([CitationSchema, z.string()]),
 });
 const JudgeVerdictSchema = z.object({
     pass: z.boolean(),
@@ -103,6 +104,64 @@ function tail(out, n = 8) {
         return "";
     return "\n" + t.split("\n").slice(-n).join("\n");
 }
+// v1.70: the new-file line numbers each hunk actually ADDS, per changed path — parsed from the
+// unified-diff hunk headers so a citation is validated against real changed locations, not a substring
+// of the whole diff text (which also matches unchanged context lines and the diff's own +++/@@ headers).
+// Only `+` lines are changed locations; context lines advance the new-file counter but are not changes.
+// ponytail: assumes git's default a/ b/ prefixes (fetchTaskDiff uses plain `git diff`); revisit if a
+// caller passes a --no-prefix diff.
+function changedLinesByFile(diff) {
+    const byFile = new Map();
+    let path = null;
+    let newLine = 0;
+    let inHunk = false;
+    for (const raw of diff.split("\n")) {
+        if (raw.startsWith("diff --git")) {
+            inHunk = false;
+            path = null;
+            continue;
+        }
+        if (!inHunk && raw.startsWith("--- "))
+            continue;
+        if (!inHunk && raw.startsWith("+++ ")) {
+            const p = raw.slice(4).trim();
+            path = p === "/dev/null" ? null : p.replace(/^[ab]\//, "");
+            continue;
+        }
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+        if (hunk) {
+            newLine = Number(hunk[1]);
+            inHunk = true;
+            continue;
+        }
+        if (!inHunk || path === null)
+            continue;
+        const c = raw[0];
+        if (c === "+") {
+            let set = byFile.get(path);
+            if (!set) {
+                set = new Set();
+                byFile.set(path, set);
+            }
+            set.add(newLine);
+            newLine++;
+        }
+        else if (c === " ") {
+            newLine++;
+        }
+        else if (c !== "-") {
+            inHunk = false; // "\ No newline", a trailing blank, or the next section — hunk body ended
+        }
+    }
+    return byFile;
+}
+// A citation is valid evidence iff the diff adds the cited line of the cited file. A legacy free-text
+// quote (string) keeps v1.64's substring check — non-empty and present somewhere in the diff.
+function citesChangedLocation(evidence, changed, diff) {
+    if (typeof evidence === "string")
+        return evidence.trim().length > 0 && diff.includes(evidence);
+    return changed.get(evidence.path)?.has(evidence.line) ?? false;
+}
 export async function acceptanceGate(task, worktree, baseRef, judge, via, opts = {}) {
     // 1. deterministic oracles — exit code decides, fail-closed, zero LLM calls (spec §2, T2).
     //    A failure returns here, before any runLlm() call: a judge can never override it.
@@ -176,9 +235,9 @@ ${diff}
 ${verdictNonceLine(nonce)}
 
 Respond with ONLY this JSON (no prose before or after):
-{"nonce": "${nonce}", "pass": true|false, "criteria": [{"criterion": "c1", "met": true|false, "reason": "...", "evidence": "..."}]}
+{"nonce": "${nonce}", "pass": true|false, "criteria": [{"criterion": "c1", "met": true|false, "reason": "...", "evidence": {"path": "path/to/file", "line": 42}}]}
 Each criteria[].criterion MUST be the stable id from the rubric (c1, c2, ...) exactly once.
-Each criteria[].evidence MUST be a short verbatim quote copied from the diff above that grounds the ruling; a quote not found in the diff voids the whole verdict.
+Each criteria[].evidence MUST be a structured citation {"path", "line"} pointing at a line the diff above actually adds or changes (the new-file line number); a citation to an unchanged or nonexistent location voids the whole verdict.
 `;
     const raw = await runLlm(judge.adapter, judge.model, prompt, worktree, via, JUDGE_TIMEOUT_MS);
     const extracted = extractVerdictJson(raw, nonce);
@@ -191,13 +250,16 @@ Each criteria[].evidence MUST be a short verbatim quote copied from the diff abo
             meta: { unparseable: true, judge: channelKey({ adapter: judge.adapter.id, model: judge.model }) } };
     }
     const { verdict: v, inconsistencies } = checkJudgeVerdict(extracted, expectedIds);
-    // v1.64: quoted evidence must appear verbatim in `diff` — the exact string embedded in the prompt
-    // above, never the worktree or any other artifact. A quote the diff doesn't contain is a
-    // hallucinated verdict: treated as unparseable so GATE-09 retries the judge on a failover channel.
-    const fabricated = v.criteria.filter((row) => !row.evidence.trim() || !diff.includes(row.evidence));
+    // v1.70: each citation must point at a line the diff actually changed — validated against the hunks
+    // of `diff` (the exact string embedded in the prompt above), never the worktree or any other artifact.
+    // A citation to an untouched file or a line outside every changed hunk is a hallucinated verdict:
+    // treated as unparseable so GATE-09 retries the judge on a failover channel. (A legacy free-text quote
+    // still validates by substring, for the fake seam and pre-v1.70 fixtures.)
+    const changed = changedLinesByFile(diff);
+    const fabricated = v.criteria.filter((row) => !citesChangedLocation(row.evidence, changed, diff));
     if (fabricated.length) {
         return { gate: "acceptance", pass: false,
-            details: warn + detBlock + `judge verdict quotes evidence absent from the judged diff (${fabricated.map((row) => row.criterion).join(", ")}) — treating as unparseable, failing closed`,
+            details: warn + detBlock + `judge verdict cites evidence absent from the judged diff (${fabricated.map((row) => row.criterion).join(", ")}) — treating as unparseable, failing closed`,
             meta: { unparseable: true, judge: channelKey({ adapter: judge.adapter.id, model: judge.model }) } };
     }
     const pass = v.pass === true && inconsistencies.length === 0 && v.criteria.every((row) => row.met);

package/dist/gates/review.d.ts

@@ -3,9 +3,17 @@ import { type TickmarkrConfig } from "../config/config.js";
 import { type Task } from "../graph/schema.js";
 import { type GateVia } from "./llm.js";
 import type { GateResult } from "./types.js";
+export type ReviewSeverity = "material" | "minor";
+export interface ReviewFinding {
+    note: string;
+    severity: ReviewSeverity;
+    defer?: boolean;
+    rationale?: string;
+}
 export interface ReviewVerdict {
-    approve: boolean;
-    issues: string[];
+    approve?: boolean;
+    issues?: string[];
+    findings?: ReviewFinding[];
 }
 export declare function fetchTaskDiff(worktree: string, baseRef: string): Promise<{
     full: string;

package/dist/gates/review.js

@@ -5,6 +5,63 @@ import { getAdapter } from "../adapters/registry.js";
 import { shOk } from "../run/git.js";
 import { marginalCostRank } from "../route/router.js";
 import { COMPLETION_FAKING_CHECKLIST, extractVerdictJson, generateVerdictNonce, runLlm, verdictNonceLine } from "./llm.js";
+// legacy flat `issues` shape — every issue blocks; the approve flag must agree with the list.
+function classifyReviewIssues(approve, issues) {
+    const inconsistencies = [];
+    issues.forEach((issue, i) => {
+        if (typeof issue !== "string")
+            inconsistencies.push(`review verdict inconsistent: issues[${i}] must be a string`);
+    });
+    if (approve && issues.length) {
+        inconsistencies.push("review verdict inconsistent: approve=true requires issues to be empty");
+    }
+    else if (!approve && !issues.length) {
+        inconsistencies.push("review verdict inconsistent: approve=false requires at least one issue");
+    }
+    const pass = approve === true && inconsistencies.length === 0;
+    const lines = issues.map((issue) => `- ${typeof issue === "string" ? issue : JSON.stringify(issue)}`);
+    lines.push(...inconsistencies);
+    return { pass, headline: pass ? "approved" : approve ? "approval rejected" : "requested changes", lines };
+}
+// v1.70 T5: classified findings — only material (non-deferred) findings block approval. Deferred
+// findings carry their rationale into the details (never dropped). Malformed rows fail closed like any
+// other shape violation, so a garbage "findings" array can never fake an approval.
+function classifyReviewFindings(findings) {
+    const inconsistencies = [];
+    const lines = [];
+    let material = 0;
+    let deferred = 0;
+    findings.forEach((f, i) => {
+        if (!f || typeof f !== "object") {
+            inconsistencies.push(`review finding inconsistent: findings[${i}] must be an object`);
+            return;
+        }
+        const { note, severity, defer, rationale } = f;
+        if (typeof note !== "string")
+            inconsistencies.push(`review finding inconsistent: findings[${i}].note must be a string`);
+        if (severity !== "material" && severity !== "minor")
+            inconsistencies.push(`review finding inconsistent: findings[${i}].severity must be "material" or "minor"`);
+        if (defer !== undefined && typeof defer !== "boolean")
+            inconsistencies.push(`review finding inconsistent: findings[${i}].defer must be a boolean`);
+        const isDeferred = defer === true;
+        if (isDeferred && (typeof rationale !== "string" || !rationale.trim())) {
+            inconsistencies.push(`review finding inconsistent: deferred findings[${i}] requires a rationale`);
+        }
+        if (severity === "material" && !isDeferred)
+            material++;
+        if (isDeferred)
+            deferred++;
+        const label = isDeferred ? `deferred/${severity ?? "?"}` : String(severity ?? "?");
+        const why = isDeferred && typeof rationale === "string" ? ` — rationale: ${rationale}` : "";
+        lines.push(`- [${label}] ${typeof note === "string" ? note : JSON.stringify(note)}${why}`);
+    });
+    const pass = material === 0 && inconsistencies.length === 0;
+    lines.push(...inconsistencies);
+    const headline = pass
+        ? deferred ? `approved (${deferred} deferred)` : "approved"
+        : `requested changes (${material} material)`;
+    return { pass, headline, lines };
+}
 // OBS-48: cap on zero-context diff bytes (git diff -U0), not context-padded full diff — scattered
 // one-line hunks no longer trip at ~370 diff-bytes per changed line. Full diff still goes to the judge.
 const DIFF_CAP_REMEDY = "split the task, or raise gates.diffCap";
@@ -95,8 +152,14 @@ ${diff}
 
 ${verdictNonceLine(nonce)}
 
+Classify every concern as "material" (a correctness, security, or acceptance-criteria defect that must
+block the merge) or "minor" (style, naming, or preference that should not block). ONLY material findings
+block approval. For a minor concern you have decided not to block on, set "defer": true and give a
+one-line "rationale" — it is recorded in the review, never dropped.
+
 Respond with ONLY this JSON:
-{"nonce": "${nonce}", "approve": true|false, "issues": ["..."]}
+{"nonce": "${nonce}", "approve": true|false, "findings": [{"note": "...", "severity": "material"|"minor", "defer": false, "rationale": ""}]}
+Approve iff no material finding remains; an empty findings list is a clean approval.
 `;
     const raw = await runLlm(getAdapter(reviewer.adapter, adapters), reviewer.model, prompt, worktree, via ? { driver: via.driver, keep: via.keep, onSlot: via.onSlot, name: via.nameFor("review", reviewer.adapter), label: via.labelFor("review") } : undefined, 
     // frontier reviewers routinely need >5min on a configured-cap-sized diff, and `claude -p` buffers all
@@ -106,7 +169,9 @@ Respond with ONLY this JSON:
     // second knob-turner appears.
     900_000);
     const v = extractVerdictJson(raw, nonce);
-    if (!v || typeof v.approve !== "boolean" || !Array.isArray(v.issues)) {
+    const findings = v && Array.isArray(v.findings) ? v.findings : null;
+    // findings decides the verdict on its own; the legacy path still needs approve + issues to parse.
+    if (!v || (findings === null && (typeof v.approve !== "boolean" || !Array.isArray(v.issues)))) {
         return {
             gate: "review",
             pass: false,
@@ -114,25 +179,13 @@ Respond with ONLY this JSON:
             meta: { reviewer: channelKey(reviewer) },
         };
     }
-    const issues = v.issues;
-    const inconsistencies = [];
-    issues.forEach((issue, i) => {
-        if (typeof issue !== "string")
-            inconsistencies.push(`review verdict inconsistent: issues[${i}] must be a string`);
-    });
-    if (v.approve && issues.length) {
-        inconsistencies.push("review verdict inconsistent: approve=true requires issues to be empty");
-    }
-    else if (!v.approve && !issues.length) {
-        inconsistencies.push("review verdict inconsistent: approve=false requires at least one issue");
-    }
-    const pass = v.approve === true && inconsistencies.length === 0;
-    const lines = issues.map((issue) => `- ${typeof issue === "string" ? issue : JSON.stringify(issue)}`);
-    lines.push(...inconsistencies);
+    const decided = findings !== null
+        ? classifyReviewFindings(findings)
+        : classifyReviewIssues(v.approve, v.issues);
     return {
         gate: "review",
-        pass,
-        details: `reviewer ${reviewer.adapter}:${reviewer.model} (${reviewer.vendor}): ${pass ? "approved" : v.approve ? "approval rejected" : "requested changes"}${lines.length ? "\n" + lines.join("\n") : ""}`,
+        pass: decided.pass,
+        details: `reviewer ${reviewer.adapter}:${reviewer.model} (${reviewer.vendor}): ${decided.headline}${decided.lines.length ? "\n" + decided.lines.join("\n") : ""}`,
         meta: { reviewer: channelKey(reviewer) },
     };
 }

package/dist/report/bundle.d.ts

@@ -0,0 +1,45 @@
+import type { EvidenceCitation } from "../gates/acceptance.js";
+import type { RunEnvironment } from "../run/environment.js";
+import type { JournalEvent } from "../run/journal.js";
+export declare const BUNDLE_SCHEMA_VERSION = 1;
+export declare const KNOWN_LIMITS: readonly string[];
+export type BundleEvidence = string | EvidenceCitation;
+export interface BundleJudgeCriterion {
+    criterion: string;
+    met: boolean;
+    reason: string;
+    evidence: BundleEvidence;
+}
+export interface BundleGateResult {
+    gate: string;
+    pass: boolean;
+    details: string;
+}
+export interface BundleTask {
+    taskId: string;
+    outcome: "done" | "failed" | "human" | "not-recorded";
+    gates: BundleGateResult[];
+    /** Judge criteria with evidence citations, when the journal recorded them structured. */
+    judgeCriteria: BundleJudgeCriterion[];
+}
+export interface BundleContentHashes {
+    /** sha256 of the canonical JSON of the source journal events used to build this packet. */
+    journal: string;
+    /** graphDefinitionHash from run-start when recorded. */
+    graphDefinitionHash?: string;
+}
+export interface ProofBundle {
+    /** Schema version a future reader must check before parsing the rest. */
+    schemaVersion: number;
+    runId: string;
+    environment?: RunEnvironment;
+    contentHashes: BundleContentHashes;
+    tasks: BundleTask[];
+    /** Plain-language known limits — this is not an unconditional proof of correctness. */
+    knownLimits: string[];
+}
+/**
+ * Build a schema-versioned proof packet from a run's journal events.
+ * Pure: no filesystem, no network. Caller writes the result.
+ */
+export declare function buildProofBundle(runId: string, events: JournalEvent[]): ProofBundle;

package/dist/report/bundle.js

@@ -0,0 +1,158 @@
+// v1.70 T4: pure proof-packet builder for `tickmarkr report --bundle <path>`.
+// One portable, schema-versioned snapshot of a run — task outcomes, judge evidence
+// citations, environment identity, content hashes — secrets redacted via the shared
+// redactSecrets seam. No I/O and no network: the caller (report CLI) owns the write.
+import { createHash } from "node:crypto";
+import { redactSecrets } from "../run/redact.js";
+import { recordedEnvironment } from "./compare.js";
+// Bump when the packet shape changes in a way a future reader must branch on before parsing.
+export const BUNDLE_SCHEMA_VERSION = 1;
+// Plain-language known limits — the packet is a journal snapshot, not an unconditional proof.
+export const KNOWN_LIMITS = [
+    "This packet is a portable snapshot of journaled run facts, not an independent re-verification of the work or its gates.",
+    "Judge evidence citations are copied from the journal as the judge recorded them; this packet does not re-validate citations against the judged diff.",
+    "Content hashes bind this packet to the journal bytes used to build it; they do not prove the underlying gates, merges, or tip verification were correct.",
+    "Secret-shaped strings are redacted by local pattern matching only; redaction is not a formal security audit.",
+    "Producing this packet never contacts a network and never uploads anything.",
+];
+function contentHash(events) {
+    return createHash("sha256").update(JSON.stringify(events)).digest("hex");
+}
+function graphHash(events) {
+    for (const e of events) {
+        if (e.event !== "run-start")
+            continue;
+        const h = e.data.graphDefinitionHash;
+        return typeof h === "string" ? h : undefined;
+    }
+    return undefined;
+}
+function taskIds(events) {
+    const seen = new Set();
+    const out = [];
+    for (const e of events) {
+        if (!e.taskId || seen.has(e.taskId))
+            continue;
+        seen.add(e.taskId);
+        out.push(e.taskId);
+    }
+    return out;
+}
+function outcomeFor(events, taskId, runEnd) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.taskId !== taskId)
+            continue;
+        if (e.event === "task-done")
+            return "done";
+        if (e.event === "task-failed")
+            return "failed";
+        if (e.event === "task-human")
+            return "human";
+    }
+    if (runEnd) {
+        const d = runEnd.data;
+        if (Array.isArray(d.done) && d.done.includes(taskId))
+            return "done";
+        if (Array.isArray(d.failed) && d.failed.includes(taskId))
+            return "failed";
+        if (Array.isArray(d.human) && d.human.includes(taskId))
+            return "human";
+    }
+    return "not-recorded";
+}
+// Parse a structured evidence citation without rewriting path/line — unaltered copy.
+function parseEvidence(raw) {
+    if (typeof raw === "string")
+        return raw;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    if (typeof o.path === "string" && typeof o.line === "number" && Number.isInteger(o.line)) {
+        return { path: o.path, line: o.line };
+    }
+    return undefined;
+}
+// Structured judge criteria on an acceptance gate-result (when journaled). Evidence is copied
+// unaltered so a future reader can match citations byte-for-byte to what the judge recorded.
+function parseJudgeCriteria(data) {
+    const raw = data.criteria;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const row of raw) {
+        if (!row || typeof row !== "object" || Array.isArray(row))
+            continue;
+        const r = row;
+        if (typeof r.criterion !== "string" || typeof r.met !== "boolean" || typeof r.reason !== "string")
+            continue;
+        const evidence = parseEvidence(r.evidence);
+        if (evidence === undefined)
+            continue;
+        out.push({ criterion: r.criterion, met: r.met, reason: r.reason, evidence });
+    }
+    return out;
+}
+// Deep-walk string leaves through redactSecrets. Numbers/booleans/null stay as-is.
+// Structured evidence citations keep path/line unaltered (redact only free-text string evidence).
+function redactValue(v) {
+    if (typeof v === "string")
+        return redactSecrets(v);
+    if (v === null || typeof v !== "object")
+        return v;
+    if (Array.isArray(v))
+        return v.map(redactValue);
+    const o = v;
+    // Preserve structured {path, line} citations unaltered (criterion "unaltered").
+    if (typeof o.path === "string" && typeof o.line === "number" && Object.keys(o).length === 2) {
+        return { path: o.path, line: o.line };
+    }
+    const out = {};
+    for (const [k, val] of Object.entries(o))
+        out[k] = redactValue(val);
+    return out;
+}
+/**
+ * Build a schema-versioned proof packet from a run's journal events.
+ * Pure: no filesystem, no network. Caller writes the result.
+ */
+export function buildProofBundle(runId, events) {
+    const runEnd = [...events].reverse().find((e) => e.event === "run-end");
+    const environment = recordedEnvironment(events);
+    const journalHash = contentHash(events);
+    const gHash = graphHash(events);
+    const tasks = taskIds(events).map((taskId) => {
+        const gateEvents = events.filter((e) => e.taskId === taskId && e.event === "gate-result");
+        const gates = [];
+        const judgeCriteria = [];
+        for (const g of gateEvents) {
+            const gate = typeof g.data.gate === "string" ? g.data.gate : "unknown";
+            const pass = g.data.pass === true;
+            const details = typeof g.data.details === "string" ? g.data.details : "";
+            gates.push({ gate, pass, details });
+            if (gate === "acceptance") {
+                for (const c of parseJudgeCriteria(g.data))
+                    judgeCriteria.push(c);
+            }
+        }
+        return {
+            taskId,
+            outcome: outcomeFor(events, taskId, runEnd),
+            gates,
+            judgeCriteria,
+        };
+    });
+    const packet = {
+        schemaVersion: BUNDLE_SCHEMA_VERSION,
+        runId,
+        ...(environment ? { environment } : {}),
+        contentHashes: {
+            journal: journalHash,
+            ...(gHash ? { graphDefinitionHash: gHash } : {}),
+        },
+        tasks,
+        knownLimits: [...KNOWN_LIMITS],
+    };
+    // Redact secret-shaped strings anywhere in the packet. Structured {path,line} citations stay intact.
+    return redactValue(packet);
+}

package/dist/report/compare.d.ts

@@ -0,0 +1,64 @@
+import type { RunEnvironment } from "../run/environment.js";
+import type { JournalEvent, TelemetryRow } from "../run/journal.js";
+import { type CostConfig } from "./cost.js";
+export type EnvironmentCompare = {
+    comparable: true;
+    recorded: string;
+} | {
+    comparable: false;
+    reason: "mismatch";
+    recorded: string;
+} | {
+    comparable: false;
+    reason: "unbound";
+};
+export declare function hasRunStart(events: JournalEvent[]): boolean;
+export declare function recordedEnvironment(events: JournalEvent[]): RunEnvironment | undefined;
+export declare function environmentComparable(baselineEnv: RunEnvironment | undefined, currentEnv: RunEnvironment | undefined): EnvironmentCompare;
+export interface RunMetrics {
+    durationMs: number | undefined;
+    gatePass: number;
+    gateFail: number;
+    gateTotal: number;
+    costUsd: number | undefined;
+    tokensTotal: number | undefined;
+}
+export declare function runMetrics(events: JournalEvent[], rows?: TelemetryRow[], cost?: CostConfig): RunMetrics;
+export interface RunDelta {
+    durationMs: number | undefined;
+    gateFail: number;
+    costUsd: number | undefined;
+    tokensTotal: number | undefined;
+}
+export type CompareOutcome = {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    runId: string;
+    baselineRunId: string;
+    comparability: EnvironmentCompare;
+    current: RunMetrics;
+    baseline: RunMetrics;
+    delta: RunDelta;
+    text: string;
+};
+export declare function renderComparison(opts: {
+    runId: string;
+    baselineRunId: string;
+    comparability: EnvironmentCompare;
+    baselineEnv: RunEnvironment | undefined;
+    currentEnv: RunEnvironment | undefined;
+    current: RunMetrics;
+    baseline: RunMetrics;
+    delta: RunDelta;
+}): string;
+export declare function compareRuns(opts: {
+    runId: string;
+    baselineRunId: string;
+    events: JournalEvent[];
+    baselineEvents: JournalEvent[];
+    rows?: TelemetryRow[];
+    baselineRows?: TelemetryRow[];
+    cost?: CostConfig;
+}): CompareOutcome;

package/dist/report/compare.js

@@ -0,0 +1,231 @@
+import { estimateCosts } from "./cost.js";
+export function hasRunStart(events) {
+    return events.some((e) => e.event === "run-start");
+}
+// First run-start's environment, fail-closed on a missing or malformed stamp.
+export function recordedEnvironment(events) {
+    for (const e of events) {
+        if (e.event !== "run-start")
+            continue;
+        const env = e.data.environment;
+        if (!env || typeof env !== "object" || Array.isArray(env))
+            return undefined;
+        const o = env;
+        if (typeof o.tickmarkrVersion !== "string" || typeof o.configHash !== "string")
+            return undefined;
+        if (!o.adapterVersions || typeof o.adapterVersions !== "object" || Array.isArray(o.adapterVersions))
+            return undefined;
+        const adapterVersions = {};
+        for (const [k, v] of Object.entries(o.adapterVersions)) {
+            if (typeof v !== "string")
+                return undefined;
+            adapterVersions[k] = v;
+        }
+        return { tickmarkrVersion: o.tickmarkrVersion, configHash: o.configHash, adapterVersions };
+    }
+    return undefined;
+}
+// Canonical identity string for the `recorded` field — configHash is the axis the acceptance
+// criteria name; full environment equality still decides .comparable.
+function envFingerprint(env) {
+    return env.configHash;
+}
+function envEqual(a, b) {
+    if (a.tickmarkrVersion !== b.tickmarkrVersion || a.configHash !== b.configHash)
+        return false;
+    const ak = Object.keys(a.adapterVersions).sort();
+    const bk = Object.keys(b.adapterVersions).sort();
+    if (ak.length !== bk.length)
+        return false;
+    for (let i = 0; i < ak.length; i++) {
+        if (ak[i] !== bk[i])
+            return false;
+        if (a.adapterVersions[ak[i]] !== b.adapterVersions[bk[i]])
+            return false;
+    }
+    return true;
+}
+// THE environment-identity comparator (criterion: reuses engagementComparable's shape).
+// unbound = either side lacks a usable stamp; mismatch = stamps disagree; comparable = equal.
+export function environmentComparable(baselineEnv, currentEnv) {
+    if (baselineEnv === undefined || currentEnv === undefined)
+        return { comparable: false, reason: "unbound" };
+    const recorded = envFingerprint(baselineEnv);
+    return envEqual(baselineEnv, currentEnv)
+        ? { comparable: true, recorded }
+        : { comparable: false, reason: "mismatch", recorded };
+}
+export function runMetrics(events, rows = [], cost = {}) {
+    const start = events.find((e) => e.event === "run-start");
+    const end = [...events].reverse().find((e) => e.event === "run-end");
+    let durationMs;
+    if (start && end) {
+        const from = Date.parse(start.ts);
+        const to = Date.parse(end.ts);
+        if (Number.isFinite(from) && Number.isFinite(to) && to >= from)
+            durationMs = to - from;
+    }
+    const gates = events.filter((e) => e.event === "gate-result");
+    const gatePass = gates.filter((e) => e.data.pass === true).length;
+    const gateFail = gates.filter((e) => e.data.pass === false).length;
+    let costUsd;
+    let costSum = 0;
+    let hasCost = false;
+    for (const p of estimateCosts(rows, cost)) {
+        if (p.apiUsd !== undefined) {
+            costSum += p.apiUsd;
+            hasCost = true;
+        }
+        else if (p.amortizedUsd) {
+            costSum += (p.amortizedUsd[0] + p.amortizedUsd[1]) / 2;
+            hasCost = true;
+        }
+    }
+    if (hasCost)
+        costUsd = Math.round(costSum * 1e6) / 1e6;
+    let tokensTotal;
+    let tokenSum = 0;
+    let hasTokens = false;
+    for (const r of rows) {
+        if (!r.tokens)
+            continue;
+        hasTokens = true;
+        const t = r.tokens;
+        tokenSum += t.input + t.output + (t.cacheRead ?? 0) + (t.cacheWrite ?? 0) + (t.reasoning ?? 0);
+    }
+    if (hasTokens)
+        tokensTotal = tokenSum;
+    return { durationMs, gatePass, gateFail, gateTotal: gates.length, costUsd, tokensTotal };
+}
+const n = (x) => x.toLocaleString("en-US");
+const EM = "—";
+function fmtDuration(ms) {
+    if (ms === undefined)
+        return EM;
+    const seconds = Math.round(ms / 1_000);
+    const minutes = Math.floor(seconds / 60);
+    return minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
+}
+function fmtSignedDuration(ms) {
+    if (ms === undefined)
+        return EM;
+    if (ms === 0)
+        return "0s";
+    const sign = ms > 0 ? "+" : "-";
+    return `${sign}${fmtDuration(Math.abs(ms))}`;
+}
+function fmtUsd(v) {
+    if (v === undefined)
+        return EM;
+    return `$${v.toFixed(6)}`;
+}
+function fmtSignedUsd(v) {
+    if (v === undefined)
+        return EM;
+    if (v === 0)
+        return "$0.000000";
+    const sign = v > 0 ? "+" : "-";
+    return `${sign}$${Math.abs(v).toFixed(6)}`;
+}
+function fmtInt(v) {
+    if (v === undefined)
+        return EM;
+    return n(v);
+}
+function fmtSignedInt(v) {
+    if (v === undefined)
+        return EM;
+    if (v === 0)
+        return "0";
+    return v > 0 ? `+${n(v)}` : `-${n(Math.abs(v))}`;
+}
+function comparabilityLine(cmp, baselineEnv, currentEnv) {
+    if (cmp.comparable) {
+        return `full comparability (environment identity matches; configHash=${cmp.recorded})`;
+    }
+    if (cmp.reason === "unbound") {
+        return "comparability caveat — one or both runs lack a recorded environment identity; not apples-to-apples";
+    }
+    const base = baselineEnv?.configHash ?? EM;
+    const cur = currentEnv?.configHash ?? EM;
+    return `comparability caveat — environment identity disagrees (baseline configHash=${base} ≠ current configHash=${cur}; recorded baseline ${cmp.recorded}); not apples-to-apples`;
+}
+export function renderComparison(opts) {
+    const { runId, baselineRunId, comparability, baselineEnv, currentEnv, current, baseline, delta } = opts;
+    // Both run ids are always named so the reader knows which is the baseline.
+    const lines = [
+        `## Comparison`,
+        "",
+        `- **run:** ${runId}`,
+        `- **baseline:** ${baselineRunId}`,
+        `- **comparability:** ${comparabilityLine(comparability, baselineEnv, currentEnv)}`,
+        "",
+        "### Delta (current − baseline)",
+        "",
+        `| metric | baseline (${baselineRunId}) | current (${runId}) | delta |`,
+        `| --- | --- | --- | --- |`,
+        `| duration | ${fmtDuration(baseline.durationMs)} | ${fmtDuration(current.durationMs)} | ${fmtSignedDuration(delta.durationMs)} |`,
+        `| gate failures | ${fmtInt(baseline.gateFail)} | ${fmtInt(current.gateFail)} | ${fmtSignedInt(delta.gateFail)} |`,
+        `| gate pass rate | ${baseline.gateTotal ? `${baseline.gatePass}/${baseline.gateTotal}` : EM} | ${current.gateTotal ? `${current.gatePass}/${current.gateTotal}` : EM} | ${EM} |`,
+        `| cost | ${fmtUsd(baseline.costUsd)} | ${fmtUsd(current.costUsd)} | ${fmtSignedUsd(delta.costUsd)} |`,
+        `| tokens | ${fmtInt(baseline.tokensTotal)} | ${fmtInt(current.tokensTotal)} | ${fmtSignedInt(delta.tokensTotal)} |`,
+        "",
+    ];
+    if (!comparability.comparable) {
+        lines.push("_Caveat: deltas are shown for inspection only — environment identity disagrees, so this is not an apples-to-apples table._", "");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+// Fail closed when either journal has no run-start (no partial / fabricated comparison).
+// Mismatch of environment identity still yields a rendered delta, with an explicit caveat.
+export function compareRuns(opts) {
+    if (!hasRunStart(opts.baselineEvents)) {
+        return {
+            ok: false,
+            reason: `baseline run ${opts.baselineRunId} has no recorded run-start event — cannot compare`,
+        };
+    }
+    if (!hasRunStart(opts.events)) {
+        return {
+            ok: false,
+            reason: `run ${opts.runId} has no recorded run-start event — cannot compare`,
+        };
+    }
+    const baselineEnv = recordedEnvironment(opts.baselineEvents);
+    const currentEnv = recordedEnvironment(opts.events);
+    const comparability = environmentComparable(baselineEnv, currentEnv);
+    const baseline = runMetrics(opts.baselineEvents, opts.baselineRows ?? [], opts.cost ?? {});
+    const current = runMetrics(opts.events, opts.rows ?? [], opts.cost ?? {});
+    const delta = {
+        durationMs: current.durationMs !== undefined && baseline.durationMs !== undefined
+            ? current.durationMs - baseline.durationMs
+            : undefined,
+        gateFail: current.gateFail - baseline.gateFail,
+        costUsd: current.costUsd !== undefined && baseline.costUsd !== undefined
+            ? Math.round((current.costUsd - baseline.costUsd) * 1e6) / 1e6
+            : undefined,
+        tokensTotal: current.tokensTotal !== undefined && baseline.tokensTotal !== undefined
+            ? current.tokensTotal - baseline.tokensTotal
+            : undefined,
+    };
+    const text = renderComparison({
+        runId: opts.runId,
+        baselineRunId: opts.baselineRunId,
+        comparability,
+        baselineEnv,
+        currentEnv,
+        current,
+        baseline,
+        delta,
+    });
+    return {
+        ok: true,
+        runId: opts.runId,
+        baselineRunId: opts.baselineRunId,
+        comparability,
+        current,
+        baseline,
+        delta,
+        text,
+    };
+}

package/dist/run/daemon.js

@@ -15,6 +15,7 @@ import { captureBaseline, detectGateCommands, detectVacuousOracles } from "../ga
 import { runGates } from "../gates/run-gates.js";
 import { addEvidence, attributeBlocked, blockedTasks, getTask, graphDefinitionHash, loadGraph, pendingTasks, readyTasks, saveGraph, setStatus } from "../graph/graph.js";
 import { augmentRetryBrief, consult, renderRetryGuidance } from "./consult.js";
+import { runEnvironment } from "./environment.js";
 import { cleanupRunWorktrees, gitHead, linkNodeModules, sh, shGit, WORKTREE_LAYOUT_CONTRACT, worktreePath } from "./git.js";
 import { runInteractiveSeed } from "./interactive-seed.js";
 import { classifyWorkerResultCause, engagementComparable, Journal, loadRoutingProfile, newRunId } from "./journal.js";
@@ -65,6 +66,10 @@ export function formatSummary(s) {
     return `done: ${s.done.length}, failed: ${s.failed.length}, human: ${s.human.length}, blocked: ${s.blocked.length}, pending: ${s.pending.length}\nintegration branch: ${s.branch}${tip}`;
 }
 const MAX_ATTEMPTS = 10; // ponytail: hard cap so a pathological ladder can never loop forever
+// v1.70 T5: request-changes review rounds a single task may draw before it parks for a human decision
+// instead of cycling. Well below MAX_ATTEMPTS so review non-convergence is caught long before the
+// global cap. ponytail: literal constant; lift to cfg.review.roundCap only if a second knob-turner appears.
+const REVIEW_ROUND_CAP = 3;
 const BLOCKED_POLL_MS = 30_000; // between trailer-wait slices, check whether the pane is blocked on a prompt
 const PROVIDER_DEATH_REQUEUE_CAP = 2; // v1.46 T1: requeue same assignment twice, then fall through to the normal ladder
 const PROVIDER_DEATH_BACKOFF_MS = 500; // short backoff before provider-death requeue
@@ -253,7 +258,11 @@ export async function runDaemon(repoRoot, opts = {}) {
             baseRef = await gitHead(repoRoot);
             baseline = await captureBaseline(repoRoot, commands);
             writeFileSync(join(journal.dir, "baseline.json"), JSON.stringify(baseline, null, 2));
-            journal.append("run-start", undefined, { pid: process.pid, baseRef, commands, channels: channels.map(channelKey), branch, graphDefinitionHash: graphDefinitionHash(graph), mode: rm.mode.mode, modeSource: rm.source, ...(prior ? { supersedes: prior.runId } : {}) }); // graphDefinitionHash: T3 engagement identity (status+resume share it); pid: v1.13 (VIS-11) liveness; mode/modeSource: v1.51 T2; supersedes: v1.53 T5
+            // v1.70 T2: environment identity beside the graph/branch identity — running tickmarkr version,
+            // loaded-config hash, and the probed CLI version of each adapter holding a channel in the run,
+            // gathered through the existing probe/config-load paths (no second mechanism).
+            const environment = runEnvironment(cfg, channels, health);
+            journal.append("run-start", undefined, { pid: process.pid, baseRef, commands, channels: channels.map(channelKey), branch, graphDefinitionHash: graphDefinitionHash(graph), mode: rm.mode.mode, modeSource: rm.source, environment, ...(prior ? { supersedes: prior.runId } : {}) }); // graphDefinitionHash: T3 engagement identity (status+resume share it); pid: v1.13 (VIS-11) liveness; mode/modeSource: v1.51 T2; supersedes: v1.53 T5
             runStarted = true;
             // v1.53 T5: mark the prior run AFTER this run's run-start exists, so the prior journal never
             // names a successor that has no journal. Append-only — the prior journal is never rewritten.
@@ -410,6 +419,14 @@ export async function runDaemon(repoRoot, opts = {}) {
             if (rs)
                 journal.append("resume-restore", t.id, { attempts: rs.attempts, tried: [...tried], assignment });
             const badReviewers = []; // v1.1: reviewer channels that produced unparseable output for this task
+            // v1.70 T5 (review-convergence): failed review rounds this task has drawn, counted from the per-task
+            // review history already in the journal — the SAME review gate-result stream onGate reads to grow the
+            // reviewer-exclusion list (badReviewers), never a second parallel counter. request-changes rounds do
+            // not exclude their reviewer (a fix is re-checked by the same seat), so their count lives here in the
+            // shared history rather than in badReviewers' garbage-only exclusion subset.
+            const reviewRoundsDrawn = () => journal.read().filter((e) => e.taskId === t.id && e.event === "gate-result" &&
+                e.data.gate === "review" &&
+                e.data.pass === false).length;
             let feedback = "";
             let ladderIdx = 0;
             let modeFallbackNoted = false; // v1.2: journal the interactive→print fallback once per task, not per attempt
@@ -510,6 +527,15 @@ export async function runDaemon(repoRoot, opts = {}) {
                     await park(t, `attempt cap (${MAX_ATTEMPTS}) reached`, "attempt-cap", assignment, attempt, startMs, gateFails, consults, tokens, metered, retryMode);
                     return;
                 }
+                // v1.70 T5: a task that has already drawn REVIEW_ROUND_CAP request-changes review rounds parks for
+                // a human decision instead of dispatching another round. Condition on the review history (data),
+                // never the code path — and let an operator's approval (the human decision the cap asked for)
+                // release it, mirroring the humanGate guard's condition-on-approval precedent. Rounds only accrue
+                // after attempt 0, so the guard skips the journal read on the happy path.
+                if (attempt > 0 && !approved.has(t.id) && reviewRoundsDrawn() >= REVIEW_ROUND_CAP) {
+                    await park(t, `review round cap (${REVIEW_ROUND_CAP}) reached — request-changes reviews not converging; a human should decide`, "gate-fail", assignment, attempt, startMs, gateFails, consults, tokens, metered, retryMode);
+                    return;
+                }
                 // OBS-57: a demoted channel must not be re-dispatched on consult retry or provider requeue.
                 if (demotedChannels.has(channelKey(assignment))) {
                     const next = nextChannel(assignment, t, cfg, channels, tried, profile, demotedChannels);

package/dist/run/environment.d.ts

@@ -0,0 +1,12 @@
+import type { AuthHealth, BillingChannel } from "../adapters/types.js";
+import type { TickmarkrConfig } from "../config/config.js";
+export interface RunEnvironment {
+    tickmarkrVersion: string;
+    configHash: string;
+    adapterVersions: Record<string, string>;
+}
+export declare const UNKNOWN_ADAPTER_VERSION = "unknown";
+export declare function tickmarkrVersion(): string;
+export declare function configHash(cfg: TickmarkrConfig): string;
+export declare function adapterVersions(channels: BillingChannel[], health: Record<string, AuthHealth>): Record<string, string>;
+export declare function runEnvironment(cfg: TickmarkrConfig, channels: BillingChannel[], health: Record<string, AuthHealth>): RunEnvironment;

package/dist/run/environment.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// An adapter whose version probe failed is recorded, not dropped — "unknown", never a fabricated string.
+export const UNKNOWN_ADAPTER_VERSION = "unknown";
+// Same package.json read as src/cli/commands/version.ts (one resolution pattern, two consumers).
+const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+export function tickmarkrVersion() {
+    const { version: v } = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return v;
+}
+// Key order in a parsed config is an accident of the schema/merge layers, so the hash canonicalizes
+// first: object keys sorted recursively, undefined dropped (JSON semantics), array order preserved.
+function stableStringify(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(v)
+        .filter(([, val]) => val !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${stableStringify(val)}`).join(",")}}`;
+}
+// sha256 truncated to 16 hex — the graphDefinitionHash convention (stable, grep-friendly).
+export function configHash(cfg) {
+    return createHash("sha256").update(stableStringify(cfg)).digest("hex").slice(0, 16);
+}
+// One entry per adapter with a channel in the run (not per channel). The version is whatever the
+// adapter's own probe recorded in health; a missing/undefined probe result becomes "unknown".
+export function adapterVersions(channels, health) {
+    const out = {};
+    for (const c of channels) {
+        if (!(c.adapter in out))
+            out[c.adapter] = health[c.adapter]?.version ?? UNKNOWN_ADAPTER_VERSION;
+    }
+    return out;
+}
+export function runEnvironment(cfg, channels, health) {
+    return { tickmarkrVersion: tickmarkrVersion(), configHash: configHash(cfg), adapterVersions: adapterVersions(channels, health) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.69.0",
+  "version": "1.70.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",