@wildorder/nightshift 0.15.0 → 0.17.0

package/dist/causal-analysis.js

@@ -0,0 +1,733 @@
+import { z } from "zod";
+import { invokeAgent, resolveReviewerAgent, tail, } from "./agent-runner.js";
+import { resolveSummary, summaryContract } from "./agent-summary.js";
+import { NOOP_PERMITS_CONTEXT } from "./permits.js";
+import { clippedInputPoint, createBriefBuilder, promptComponentSizePoints, } from "./prompt-telemetry.js";
+import { NOOP_RUN_RECORDER } from "./run-analytics.js";
+import { aggregateRunAnalytics } from "./run-analytics-report.js";
+/**
+ * WS-05: an optional, independent, read-only causal-analysis pass, spawned
+ * through the existing `reviewerAgent`, that traces measured run costs
+ * (WS-04's `RunAnalyticsSummary`) toward planner-actionable causes — every
+ * step cited against retained evidence the run actually observed, and an
+ * unresolved result whenever the evidence runs out. Structured after
+ * `whole-program-review.ts`: a brief builder, a total non-throwing response
+ * parser, a deterministic evidence gate, a fail-open runner, and a pure
+ * renderer. Nothing here computes a duration, grades the run, or mutates
+ * anything — it consumes WS-04's numbers and cites them by handle.
+ */
+// ---------------------------------------------------------------------------
+// Shared formatting (duplicated from run-analytics-report.ts — that module is
+// WS-04's, not this workstream's, and importing its private, unexported
+// helpers is not an option; the same duplication precedent already exists
+// between whole-program-review.ts and run-program.ts for TEST_CRITIQUE_DIFF_LIMIT).
+// ---------------------------------------------------------------------------
+function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        ms = 0;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const totalSeconds = ms / 1000;
+    if (totalSeconds < 60)
+        return `${totalSeconds.toFixed(1)}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = Math.round(totalSeconds - minutes * 60);
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+/** Combines every workstream's spec content into one labelled block, ready for the caller to clip like the diff and program narrative. Pure. */
+export function combineWorkstreamSpecs(specs) {
+    if (specs.length === 0)
+        return "";
+    return specs
+        .map((entry) => `#### ${entry.id} ${entry.name} (\`${entry.taskFile}\`)\n\n` +
+        (entry.spec && entry.spec.trim() !== ""
+            ? entry.spec.trim()
+            : "(this workstream's spec file could not be read)"))
+        .join("\n\n");
+}
+/** span, point, evidence, and ledger-event handles are concrete observations; bucket/workstream/verify-command are category labels — context, never support on their own (D2). */
+export function isConcreteHandleKind(kind) {
+    return kind === "span" || kind === "point" || kind === "evidence" || kind === "ledger-event";
+}
+function spanDescription(span) {
+    const duration = span.endOffsetMs === undefined
+        ? "open (no recorded end)"
+        : formatDuration(span.endOffsetMs - span.startOffsetMs);
+    const parts = [`stage=${span.stage}`, `bucket=${span.bucket}`, `duration=${duration}`];
+    const dims = span.dimensions;
+    if (dims.workstream !== undefined)
+        parts.push(`workstream=${dims.workstream}`);
+    if (dims.role !== undefined)
+        parts.push(`role=${dims.role}`);
+    if (dims.attemptSeat !== undefined)
+        parts.push(`attemptSeat=${dims.attemptSeat}`);
+    if (dims.attemptIndex !== undefined)
+        parts.push(`attemptIndex=${dims.attemptIndex}`);
+    if (dims.attemptReason !== undefined)
+        parts.push(`attemptReason=${dims.attemptReason}`);
+    if (dims.verifyCommand !== undefined)
+        parts.push(`verifyCommand=${dims.verifyCommand}`);
+    if (dims.outcome !== undefined)
+        parts.push(`outcome=${dims.outcome}`);
+    return parts.join(", ");
+}
+function pointDescription(point) {
+    const parts = [`kind=${point.kind}`];
+    if (point.label !== undefined)
+        parts.push(`label=${point.label}`);
+    if (point.value !== undefined)
+        parts.push(`value=${point.value}${point.unit ? point.unit : ""}`);
+    if (point.detail !== undefined)
+        parts.push(`detail=${point.detail}`);
+    parts.push(`coverage=${point.coverage}`);
+    return parts.join(", ");
+}
+/**
+ * Builds the citable-handle registry from what this run actually observed
+ * (D2): every span and point id in `snapshot`, every `EvidenceReference.ref`
+ * carried on them, every ledger event id, and — only when the run actually
+ * has a span under them — bucket, workstream, and verify-command category
+ * labels sourced from `summary`'s own already-observed groupings. Pure,
+ * deterministic; never a static vocabulary dump.
+ */
+export function buildHandleRegistry(snapshot, summary, ledger) {
+    const registry = new Map();
+    for (const span of snapshot.spans) {
+        registry.set(span.id, { kind: "span", value: spanDescription(span) });
+        for (const ref of span.dimensions.evidence ?? []) {
+            registry.set(ref.ref, {
+                kind: "evidence",
+                value: `${ref.kind} evidence (local)${ref.note ? ` — ${ref.note}` : ""}`,
+            });
+        }
+    }
+    for (const point of snapshot.points) {
+        registry.set(point.id, { kind: "point", value: pointDescription(point) });
+        for (const ref of point.evidence ?? []) {
+            registry.set(ref.ref, {
+                kind: "evidence",
+                value: `${ref.kind} evidence (local)${ref.note ? ` — ${ref.note}` : ""}`,
+            });
+        }
+    }
+    for (const decision of ledger.decisions) {
+        registry.set(decision.id, {
+            kind: "ledger-event",
+            value: `decision "${decision.decision.title}" (${decision.status})`,
+        });
+    }
+    for (const findingRecord of ledger.findings) {
+        registry.set(findingRecord.id, {
+            kind: "ledger-event",
+            value: `finding "${findingRecord.subject}" (${findingRecord.severity}, ${findingRecord.status})`,
+        });
+    }
+    for (const denial of ledger.denials) {
+        registry.set(denial.id, {
+            kind: "ledger-event",
+            value: `denied command \`${denial.command}\` (${denial.source}) in ${denial.workstream}/${denial.attempt}`,
+        });
+    }
+    for (const bucket of summary.buckets) {
+        if (bucket.spanCount === 0)
+            continue;
+        registry.set(bucket.bucket, {
+            kind: "bucket",
+            value: `${formatDuration(bucket.durationMs)} across ${plural(bucket.spanCount, "span")}`,
+        });
+    }
+    for (const workstream of summary.rankings.byWorkstream) {
+        registry.set(workstream.key, {
+            kind: "workstream",
+            value: `${formatDuration(workstream.durationMs)} across ${plural(workstream.count, "span")}`,
+        });
+    }
+    for (const command of summary.rankings.byVerifyCommand) {
+        registry.set(command.command, {
+            kind: "verify-command",
+            value: `${formatDuration(command.totalMs)} across ${plural(command.invocations, "invocation")}`,
+        });
+    }
+    return registry;
+}
+function registryLines(registry, kind) {
+    return [...registry.entries()]
+        .filter(([, entry]) => entry.kind === kind)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([handle, entry]) => `- \`${handle}\`: ${entry.value}`);
+}
+const causalStepSchema = z.object({
+    claim: z.string().min(1),
+    cites: z.array(z.string()).default([]),
+    from: z.string().optional(),
+    to: z.string().optional(),
+});
+const planningConstraintSchema = z.object({
+    constraint: z.string().min(1),
+    cites: z.array(z.string()).default([]),
+});
+const INTERPRETATION_PATTERN = /```interpretation[^\S\r\n]*\r?\n([\s\S]*?)```/gu;
+const CONSTRAINTS_PATTERN = /```constraints[^\S\r\n]*\r?\n([\s\S]*?)```/gu;
+const UNRESOLVED_PATTERN = /```unresolved[^\S\r\n]*\r?\n([\s\S]*?)```/gu;
+/** The last non-empty fenced block's body, or undefined when none appeared — the same echo guard used throughout (extractSummary, parseSnapshotHalf). */
+function lastNonEmptyBlock(output, pattern) {
+    const bodies = [...output.matchAll(pattern)]
+        .map((match) => match[1]?.trim() ?? "")
+        .filter((body) => body !== "");
+    return bodies.length > 0 ? bodies[bodies.length - 1] : undefined;
+}
+function parseJsonArray(body, schema, label, errors) {
+    if (body === undefined)
+        return [];
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch (error) {
+        errors.push(`${label} block is not valid JSON: ${error.message}`);
+        return [];
+    }
+    if (!Array.isArray(json)) {
+        errors.push(`${label} block is not a JSON array`);
+        return [];
+    }
+    const out = [];
+    json.forEach((element, index) => {
+        const result = schema.safeParse(element);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; ");
+            errors.push(`${label}[${index}] has the wrong shape: ${issues}`);
+            return;
+        }
+        out.push(result.data);
+    });
+    return out;
+}
+function parseUnresolved(body) {
+    if (body === undefined)
+        return [];
+    try {
+        const json = JSON.parse(body);
+        if (Array.isArray(json)) {
+            return json
+                .filter((item) => typeof item === "string" && item.trim() !== "")
+                .map((item) => item.trim());
+        }
+    }
+    catch {
+        // Not JSON — treat the block as bulleted prose below.
+    }
+    return body
+        .split(/\r?\n/u)
+        .map((line) => line.replace(/^[-*]\s*/u, "").trim())
+        .filter((line) => line !== "");
+}
+/** Parses the analyzer's three-layer reply. Total: a missing block is empty, malformed JSON is a recorded error and an empty layer, and a reply with none of the three blocks is `blockless` — the analyzer-error path (§3.4). */
+export function parseCausalAnalysis(output) {
+    const errors = [];
+    const interpretationBody = lastNonEmptyBlock(output, INTERPRETATION_PATTERN);
+    const constraintsBody = lastNonEmptyBlock(output, CONSTRAINTS_PATTERN);
+    const unresolvedBody = lastNonEmptyBlock(output, UNRESOLVED_PATTERN);
+    const interpretation = parseJsonArray(interpretationBody, causalStepSchema, "interpretation", errors).map((step) => ({
+        claim: step.claim,
+        cites: step.cites,
+        ...(step.from === undefined ? {} : { from: step.from }),
+        ...(step.to === undefined ? {} : { to: step.to }),
+    }));
+    const constraints = parseJsonArray(constraintsBody, planningConstraintSchema, "constraints", errors).map((constraint) => ({ constraint: constraint.constraint, cites: constraint.cites }));
+    const unresolved = parseUnresolved(unresolvedBody);
+    return {
+        interpretation,
+        constraints,
+        unresolved,
+        errors,
+        blockless: interpretationBody === undefined && constraintsBody === undefined && unresolvedBody === undefined,
+    };
+}
+function validateCites(cites, registry) {
+    const resolved = [];
+    const unresolvedCites = [];
+    for (const cite of cites) {
+        const entry = registry.get(cite);
+        if (entry === undefined) {
+            unresolvedCites.push(cite);
+            continue;
+        }
+        resolved.push({ handle: cite, kind: entry.kind, value: entry.value });
+    }
+    const supported = resolved.some((citation) => isConcreteHandleKind(citation.kind));
+    return { resolved, unresolvedCites, supported };
+}
+/** The deterministic gate: proves every rendered causal step cites at least one concrete observation the run actually retained, and no cited handle is fabricated. Never judges whether a resolving citation logically supports its claim (D2) — that is left to the human. Pure. */
+export function validateCausalEvidence(reply, registry) {
+    const supportedSteps = [];
+    const unsupportedSteps = [];
+    for (const step of reply.interpretation) {
+        const validation = validateCites(step.cites, registry);
+        const claim = { source: step, ...validation };
+        (validation.supported ? supportedSteps : unsupportedSteps).push(claim);
+    }
+    const supportedConstraints = [];
+    const unsupportedConstraints = [];
+    for (const constraint of reply.constraints) {
+        const validation = validateCites(constraint.cites, registry);
+        const claim = { source: constraint, ...validation };
+        (validation.supported ? supportedConstraints : unsupportedConstraints).push(claim);
+    }
+    return { supportedSteps, unsupportedSteps, supportedConstraints, unsupportedConstraints };
+}
+// ---------------------------------------------------------------------------
+// Observed-measurements: rendered deterministically from `RunAnalyticsSummary`
+// (D4) — shared, byte-for-byte, between the analyzer's brief and the report's
+// own observed layer. The analyzer never authors a number that reaches
+// either.
+// ---------------------------------------------------------------------------
+function observedMeasurementLines(summary) {
+    const lines = [];
+    lines.push(`- Total elapsed: ${formatDuration(summary.totalElapsedMs)}.`);
+    lines.push("- By bucket:");
+    for (const bucket of summary.buckets) {
+        if (bucket.spanCount === 0)
+            continue;
+        lines.push(`  - \`${bucket.bucket}\`: ${formatDuration(bucket.durationMs)} (${bucket.percent.toFixed(1)}%, ${plural(bucket.spanCount, "span")})`);
+    }
+    const topStage = summary.rankings.byStage[0];
+    if (topStage) {
+        lines.push(`- Largest stage: \`${topStage.key}\` — ${formatDuration(topStage.durationMs)} across ${plural(topStage.count, "span")}.`);
+    }
+    const topWorkstream = summary.rankings.byWorkstream[0];
+    if (topWorkstream) {
+        lines.push(`- Largest workstream: \`${topWorkstream.key}\` — ${formatDuration(topWorkstream.durationMs)}.`);
+    }
+    const attempt = summary.rankings.largestAgentAttempt;
+    if (attempt) {
+        lines.push(`- Largest single agent attempt: \`${attempt.stage}\`` +
+            (attempt.workstream ? ` (${attempt.workstream}` : " (") +
+            `${attempt.attemptSeat ? `, ${attempt.attemptSeat}` : ""}` +
+            `${attempt.attemptIndex !== undefined ? ` #${attempt.attemptIndex}` : ""}) — ${formatDuration(attempt.durationMs)}.`);
+    }
+    const topCommand = summary.rankings.byVerifyCommand[0];
+    if (topCommand) {
+        lines.push(`- Largest verification command: \`${topCommand.command}\` — ${formatDuration(topCommand.totalMs)} across ${plural(topCommand.invocations, "invocation")}.`);
+    }
+    lines.push(`- Attempts by disposition: ${summary.dispositions.map((d) => `${d.outcome} ${plural(d.count, "attempt")} (${formatDuration(d.durationMs)})`).join(", ")}.`);
+    lines.push(`- Agent rerun time: ${formatDuration(summary.rerun.agent.totalMs)}` +
+        (summary.rerun.agent.byReason.length > 0
+            ? `, by trigger: ${summary.rerun.agent.byReason.map((r) => `${r.key} ${plural(r.count, "attempt")} (${formatDuration(r.durationMs)})`).join(", ")}`
+            : "") +
+        ".");
+    lines.push(`- Verification rerun time: ${formatDuration(summary.rerun.verification.totalMs)}` +
+        (summary.rerun.verification.byPhase.length > 0
+            ? `, by phase: ${summary.rerun.verification.byPhase.map((p) => `${p.key} ${plural(p.count, "invocation")} (${formatDuration(p.durationMs)})`).join(", ")}`
+            : "") +
+        ".");
+    lines.push(`- Observability coverage: ${summary.coverage.counts.observed} observed, ${summary.coverage.counts.estimated} estimated, ` +
+        `${summary.coverage.counts.unavailable} unavailable, ${summary.coverage.counts.incomplete} incomplete` +
+        (summary.coverage.unavailableRoles.length > 0
+            ? ` (unavailable roles: ${summary.coverage.unavailableRoles.join(", ")} — unmeasured, not zero)`
+            : "") +
+        ".");
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// The brief (§3.3)
+// ---------------------------------------------------------------------------
+function successCriteriaLines(manifest) {
+    if (manifest.successCriteria.length === 0)
+        return ["None recorded in the manifest."];
+    return manifest.successCriteria.map((criterion) => `- **${criterion.id}**: ${criterion.description}`);
+}
+function rosterLines(manifest) {
+    return manifest.workstreams.map((workstream) => `- ${workstream.id} ${workstream.name} (spec: \`${workstream.taskFile}\`): ` +
+        `${workstream.scope?.summary ?? workstream.name}`);
+}
+function ledgerLines(ledger) {
+    if (ledger.decisions.length === 0 && ledger.findings.length === 0 && ledger.denials.length === 0) {
+        return ["No decisions, findings, or denials were journaled this run."];
+    }
+    const lines = [];
+    if (ledger.decisions.length > 0) {
+        lines.push("Decisions:");
+        for (const decision of ledger.decisions) {
+            lines.push(`- \`${decision.id}\` **${decision.decision.title}** (${decision.status}): ${decision.decision.rationale}`);
+        }
+    }
+    if (ledger.findings.length > 0) {
+        lines.push("", "Findings:");
+        for (const findingRecord of ledger.findings) {
+            lines.push(`- \`${findingRecord.id}\` **${findingRecord.subject}** (${findingRecord.severity}, ${findingRecord.status}): ${findingRecord.message}`);
+        }
+    }
+    if (ledger.denials.length > 0) {
+        lines.push("", "Denied commands:");
+        for (const denial of ledger.denials) {
+            lines.push(`- \`${denial.id}\` \`${denial.command}\` (${denial.source}) in ${denial.workstream}/${denial.attempt}`);
+        }
+    }
+    return lines;
+}
+function timelineLines(workstreams) {
+    if (workstreams.length === 0)
+        return ["No workstream results were recorded."];
+    const lines = [];
+    for (const workstream of workstreams) {
+        lines.push(`- **${workstream.id} ${workstream.name}** — ${workstream.status}${workstream.reason ? `: ${workstream.reason}` : ""}`);
+        for (const diagnosis of workstream.failureDiagnoses ?? []) {
+            lines.push(`  - after the ${diagnosis.attempt} attempt, the reviewer diagnosed: ${diagnosis.verdict}`);
+        }
+        if (workstream.testCritique) {
+            const tc = workstream.testCritique;
+            lines.push(`  - test critique: ${tc.stopReason} after ${plural(tc.roundsRun, "round")}` +
+                (tc.openSubjects.length > 0 ? `; still open: ${tc.openSubjects.join(", ")}` : "") +
+                (tc.resolvedSubjects.length > 0 ? `; fixed: ${tc.resolvedSubjects.join(", ")}` : ""));
+        }
+    }
+    return lines;
+}
+const CAUSAL_ANALYSIS_CLIP_LIMIT = 60_000;
+function clipForCausalAnalysis(text, label) {
+    if (text.length <= CAUSAL_ANALYSIS_CLIP_LIMIT)
+        return { text, clipped: false };
+    return {
+        text: `${text.slice(0, CAUSAL_ANALYSIS_CLIP_LIMIT)}\n… (${label} clipped at ` +
+            `${CAUSAL_ANALYSIS_CLIP_LIMIT} characters — the analyzer saw a partial ${label})`,
+        clipped: true,
+    };
+}
+const CAUSAL_CONTRACT = `
+## Causal analysis (how to report your read)
+
+End your reply with three fenced blocks, in this exact order:
+\`\`\`interpretation\`\`\`, \`\`\`constraints\`\`\`, \`\`\`unresolved\`\`\`. There is
+deliberately no \`observed\` block — the observed measurements above are
+rendered by software from the run's own analytics; restating their values is
+not your job, and nothing you write there would reach the report.
+
+\`\`\`interpretation
+[
+  {
+    "claim": "<a sentence tracing a measured cost toward a planner-actionable cause>",
+    "cites": ["<handle>", "<handle>"],
+    "from": "<optional handle — the measured cost this step starts from>",
+    "to": "<optional handle — the cause this step points toward>"
+  }
+]
+\`\`\`
+
+Every \`cites\` entry must be an exact handle string copied from one of the
+sections above (a span id, a point id, a ledger event id, or an evidence
+ref — plus, for context only, a bucket name, workstream id, or
+verify-command name). A step is only ever shown as a cause when at least one
+of its citations is a concrete handle — a span, a point, a ledger event, or
+an evidence ref. Citing only a bucket/workstream/verify-command name, citing
+nothing, or citing a handle that does not appear above is checked
+mechanically and never rendered as a fact. Fabricating a handle is pointless:
+it will not resolve.
+
+\`\`\`constraints
+[
+  { "constraint": "<a rule a future plan should carry forward>", "cites": ["<handle>"] }
+]
+\`\`\`
+
+Gated the same way as interpretation steps.
+
+\`\`\`unresolved
+[
+  "<a plain-language question naming the missing or conflicting evidence>"
+]
+\`\`\`
+
+Where two evidence items disagree, where telemetry is unavailable, or where
+closing a chain would require a guess, put the question here instead of
+picking a side in \`interpretation\`. An empty array in any block is a fine
+answer — this is a second opinion, not an obligation to manufacture a cause.
+`.trim();
+/** The ```interpretation/```constraints/```unresolved block-format instructions. */
+export function causalAnalysisContract() {
+    return CAUSAL_CONTRACT;
+}
+/**
+ * Assembles the analyzer's read-only brief (§3.3): framing, the
+ * software-rendered observed measurements, the citable span/point/evidence/
+ * ledger handles (drawn straight from `registry`, so what is shown is
+ * exactly what is citable), the plan, the ledger, the verification/retry
+ * timeline, the clipped final diff, and the response contract. Pure;
+ * returns the per-component byte sizes for SC-07 prompt telemetry.
+ */
+export function causalAnalysisBrief(input) {
+    const builder = createBriefBuilder();
+    builder.push("framing", `# Causal analysis: ${input.manifest.program.name} (${input.programId})`, "", "The run for this program is finished. You are an optional, independent,", "read-only second opinion — not a re-measurement. Every number below is", "already final; your job is to interpret it with cited evidence, or say", "plainly where you cannot.", "", "Build a causal chain only as far as retained evidence carries it. Where", "telemetry is unavailable, where two evidence items conflict, or where", "closing the chain would require a guess, record an unresolved question", "instead of picking a side or inventing a cause — an unresolved result is", "the correct answer here, not a failure.", "", "This analysis runs before the run report is assembled, so it reasons", "over a snapshot taken just before you were spawned: your own cost is", "not in any of the figures below.", "");
+    builder.push("observed-measurements", "## Observed measurements", "", ...observedMeasurementLines(input.summary), "", "Cite these by the exact handle shown — do not restate their values.", "");
+    const spanLines = registryLines(input.registry, "span");
+    const pointLines = registryLines(input.registry, "point");
+    builder.push("span-point-handles", "## Span and point handles", "", spanLines.length === 0 ? "No spans were recorded." : spanLines.join("\n"), "", pointLines.length === 0 ? "No points were recorded." : pointLines.join("\n"), "");
+    const evidenceLines = registryLines(input.registry, "evidence");
+    builder.push("evidence-index", "## Retained evidence index", "", evidenceLines.length === 0
+        ? "No local evidence references were recorded for this run."
+        : evidenceLines.join("\n"), "", "Every reference above resolves only on the machine that ran this build.", "");
+    builder.push("plan", "## Program plan", "", "### Program narrative", "", input.programNarrative && input.programNarrative.trim() !== ""
+        ? input.programNarrative.trim()
+        : "(the program document could not be read; only the manifest's success criteria and roster below are available)", "", "### Success criteria", "", ...successCriteriaLines(input.manifest), "", "### Workstream roster", "", "Each entry names its spec file by path; the full text of every spec is", "reproduced below. Trust the repository's spec file and the diff below", "over this narrative and roster where they disagree.", "", ...rosterLines(input.manifest), "");
+    builder.push("workstream-specs", "### Workstream specifications", "", input.workstreamSpecsText.trim() === ""
+        ? "(no workstream spec content was available)"
+        : input.workstreamSpecsText, "");
+    builder.push("ledger", "## Decision ledger", "", ...ledgerLines(input.ledger), "");
+    builder.push("timeline", "## Verification/retry timeline", "", ...timelineLines(input.workstreams), "");
+    builder.push("diff", "## Final diff", "", input.baseCommit ? `Base commit: ${input.baseCommit}` : "(no base commit)", "", "```diff", input.diff.trim() === "" ? "(no diff available)" : input.diff, "```", "");
+    builder.push("contract", CAUSAL_CONTRACT, "", summaryContract());
+    return { brief: builder.join(), components: builder.components() };
+}
+/** The outcome recorded when no reviewerAgent is configured. */
+export function causalAnalysisReviewerAbsent() {
+    return {
+        ran: false,
+        status: "no-reviewer",
+        reason: "causal analysis is disabled — no reviewerAgent is configured, and the pass was " +
+            "not substituted with the implementer or skipped silently.",
+        unresolvedQuestions: [],
+        parseErrors: [],
+        inputClipped: false,
+    };
+}
+function noAnalyticsOutcome() {
+    return {
+        ran: false,
+        status: "no-analytics",
+        reason: "causal analysis found no analytics to interpret — the run recorder produced no " +
+            "usable snapshot at the point this stage ran.",
+        unresolvedQuestions: [],
+        parseErrors: [],
+        inputClipped: false,
+    };
+}
+function analyzerErrorOutcome(reason, inputClipped, note) {
+    return {
+        ran: false,
+        status: "analyzer-error",
+        reason,
+        unresolvedQuestions: [],
+        parseErrors: [],
+        inputClipped,
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * Runs the pass once: resolve reviewer → build brief → spawn → parse →
+ * validate → outcome. Never throws — every failure becomes a status and a
+ * `reason` sentence on the returned outcome (§3.5).
+ */
+export async function runCausalAnalysis(options) {
+    const reviewerAgent = resolveReviewerAgent(options.config);
+    if (!reviewerAgent)
+        return causalAnalysisReviewerAbsent();
+    if (options.snapshot === undefined)
+        return noAnalyticsOutcome();
+    let summary;
+    try {
+        summary = aggregateRunAnalytics(options.snapshot);
+    }
+    catch {
+        return noAnalyticsOutcome();
+    }
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
+    const log = options.log ?? ((_line) => { });
+    const permits = options.permits ?? NOOP_PERMITS_CONTEXT;
+    const registry = buildHandleRegistry(options.snapshot, summary, options.ledger);
+    const diffClip = clipForCausalAnalysis(options.diff, "diff");
+    recorder.point(clippedInputPoint("causal-analysis-diff", options.diff, diffClip.text, { role: "reviewerAgent" }));
+    const narrativeClip = clipForCausalAnalysis(options.programNarrative ?? "", "program narrative");
+    recorder.point(clippedInputPoint("causal-analysis-plan", options.programNarrative ?? "", narrativeClip.text, {
+        role: "reviewerAgent",
+    }));
+    const specsText = combineWorkstreamSpecs(options.workstreamSpecs ?? []);
+    const specsClip = clipForCausalAnalysis(specsText, "workstream specs");
+    recorder.point(clippedInputPoint("causal-analysis-specs", specsText, specsClip.text, { role: "reviewerAgent" }));
+    const inputClipped = diffClip.clipped || narrativeClip.clipped || specsClip.clipped;
+    const { brief, components } = causalAnalysisBrief({
+        manifest: options.manifest,
+        programId: options.programId,
+        summary,
+        registry,
+        ledger: options.ledger,
+        workstreams: options.workstreams,
+        diff: diffClip.text,
+        workstreamSpecsText: specsClip.text,
+        ...(options.baseCommit === undefined ? {} : { baseCommit: options.baseCommit }),
+        ...(options.programNarrative === undefined ? {} : { programNarrative: narrativeClip.text }),
+    });
+    for (const point of promptComponentSizePoints(components, { role: "reviewerAgent" })) {
+        recorder.point(point);
+    }
+    log(`causal analysis: briefing reviewer (${brief.length} bytes)`);
+    const observe = {
+        root: options.root,
+        programId: options.programId,
+        label: "causal-analyzer",
+        log,
+    };
+    let invocation;
+    try {
+        invocation = await invokeAgent(options.agentRunner, reviewerAgent, brief, options.root, permits, "reviewerAgent", observe, recorder, { stage: "causal-analysis" });
+    }
+    catch (error) {
+        return analyzerErrorOutcome(`the causal analyzer invocation threw: ${error.message}`, inputClipped);
+    }
+    const agentSummary = resolveSummary(invocation.output);
+    if (invocation.exitCode !== 0) {
+        return analyzerErrorOutcome(`the causal analyzer exited with code ${invocation.exitCode}: ${tail(invocation.output)}`, inputClipped, agentSummary.text);
+    }
+    const reply = parseCausalAnalysis(invocation.output);
+    if (reply.blockless) {
+        return analyzerErrorOutcome(`the causal analyzer's reply carried no interpretation, constraints, or unresolved ` +
+            `block: ${tail(invocation.output)}`, inputClipped, agentSummary.text);
+    }
+    const validated = validateCausalEvidence(reply, registry);
+    const status = validated.supportedSteps.length > 0 ? "analyzed" : "unresolved";
+    return {
+        ran: true,
+        status,
+        ...(status === "unresolved"
+            ? {
+                reason: "the analyzer ran, but no claim it made cited retained evidence the gate could " +
+                    "confirm — this is a valid answer when the evidence does not support a cause.",
+            }
+            : {}),
+        validated,
+        unresolvedQuestions: reply.unresolved,
+        parseErrors: reply.errors,
+        inputClipped,
+        note: agentSummary.text,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering (§3.6)
+// ---------------------------------------------------------------------------
+function renderClaimLines(claim, text) {
+    const lines = [`- ${text}`];
+    if (claim.resolved.length > 0) {
+        lines.push(`  Cites: ${claim.resolved.map((citation) => `\`${citation.handle}\` [${citation.kind}] — ${citation.value}`).join("; ")}.`);
+    }
+    if (claim.unresolvedCites.length > 0) {
+        lines.push(`  Unresolved citations (not shown as evidence): ${claim.unresolvedCites.map((c) => `\`${c}\``).join(", ")}.`);
+    }
+    return lines;
+}
+/**
+ * A human-facing render of one completed (or absent) causal analysis, for
+ * the run report. Markdown lines, no heading — the caller splices them
+ * under its own `## Why the time went there` heading, immediately after
+ * WS-04's own section. Total, never-throwing.
+ */
+export function renderCausalAnalysis(outcome, summary) {
+    if (outcome.status === "no-reviewer") {
+        return [
+            "**Causal analysis:** disabled — no reviewer is configured, and the pass was not",
+            "substituted with the implementer or skipped silently.",
+        ];
+    }
+    if (outcome.status === "no-analytics") {
+        return ["**Causal analysis:** no analytics were available to interpret.", outcome.reason ?? ""];
+    }
+    if (outcome.status === "analyzer-error") {
+        const lines = ["**Causal analysis:** the analyzer did not produce a readable reply.", outcome.reason ?? ""];
+        if (outcome.note !== undefined)
+            lines.push(`Analyzer's note: ${outcome.note}`);
+        return lines;
+    }
+    const lines = [
+        "This section traces measured run costs toward planner-actionable causes,",
+        "using an independent, read-only pass over the numbers above. Boundary:",
+        "it analyzes the run from start to the moment this analysis began — its",
+        "own cost is in the deterministic buckets above, but not in the figures",
+        "it cites below.",
+        "",
+        "### Observed measurements",
+        "",
+        ...observedMeasurementLines(summary),
+        "",
+        "### Interpretation",
+        "",
+    ];
+    const validated = outcome.validated;
+    if (outcome.status === "unresolved" || validated === undefined || validated.supportedSteps.length === 0) {
+        lines.push("No evidence-backed causal step could be established this run.", "");
+    }
+    else {
+        for (const step of validated.supportedSteps) {
+            lines.push(...renderClaimLines(step, step.source.claim));
+        }
+        lines.push("");
+    }
+    lines.push("### Reusable planning constraints", "");
+    if (validated === undefined || validated.supportedConstraints.length === 0) {
+        lines.push("None with resolving evidence.", "");
+    }
+    else {
+        for (const constraint of validated.supportedConstraints) {
+            lines.push(...renderClaimLines(constraint, constraint.source.constraint));
+        }
+        lines.push("");
+    }
+    lines.push("### Unresolved questions", "");
+    if (outcome.unresolvedQuestions.length === 0) {
+        lines.push("None recorded.", "");
+    }
+    else {
+        for (const question of outcome.unresolvedQuestions)
+            lines.push(`- ${question}`);
+        lines.push("");
+    }
+    const unsupportedSteps = validated?.unsupportedSteps ?? [];
+    const unsupportedConstraints = validated?.unsupportedConstraints ?? [];
+    if (unsupportedSteps.length > 0 || unsupportedConstraints.length > 0) {
+        lines.push("Claims the analyzer made without retained evidence (reported for transparency,", "never treated as findings):", "");
+        for (const step of unsupportedSteps)
+            lines.push(`- ${step.source.claim}`);
+        for (const constraint of unsupportedConstraints)
+            lines.push(`- ${constraint.source.constraint}`);
+        lines.push("");
+    }
+    if (outcome.parseErrors.length > 0) {
+        lines.push(`Parse errors: ${outcome.parseErrors.join("; ")}`, "");
+    }
+    if (outcome.inputClipped) {
+        lines.push("Input was clipped for length before the analyzer saw it.", "");
+    }
+    if (outcome.note !== undefined) {
+        lines.push(`Analyzer's note: ${outcome.note}`, "");
+    }
+    return lines;
+}
+/**
+ * The run's own fail-open isolation boundary for the causal-analysis section
+ * (mirrors `renderAnalyticsSection` in run-analytics-report.ts): always
+ * returns a `## Why the time went there` section, never throws. `artifact`
+ * accepts a thunk so an evaluation failure of `recorder.snapshot()` itself
+ * stays inside this function's own try/catch rather than escaping before it
+ * is reached.
+ */
+export function renderCausalAnalysisSection(outcome, artifact, deps = {}) {
+    const aggregate = deps.aggregate ?? aggregateRunAnalytics;
+    const heading = ["## Why the time went there", ""];
+    try {
+        const resolved = typeof artifact === "function" ? artifact() : artifact;
+        if (resolved === undefined) {
+            return [
+                ...heading,
+                "Causal analysis unavailable — no analytics snapshot was available when the report was rendered.",
+                "",
+            ];
+        }
+        return [...heading, ...renderCausalAnalysis(outcome, aggregate(resolved)), ""];
+    }
+    catch (error) {
+        return [...heading, `Causal analysis unavailable — ${error.message}.`, ""];
+    }
+}
+//# sourceMappingURL=causal-analysis.js.map