@lsctech/polaris 0.5.7 → 0.5.8

package/dist/cli/autoresearch.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAutoresearchCommand = void 0;
 exports.createSolCommand = createSolCommand;
 const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
 const commander_1 = require("commander");
 const dev_gate_js_1 = require("../autoresearch/dev-gate.js");
 const score_js_1 = require("../autoresearch/score.js");
@@ -12,6 +13,9 @@ const sol_evidence_loader_js_1 = require("../autoresearch/sol-evidence-loader.js
 const sol_scorer_js_1 = require("../autoresearch/sol-scorer.js");
 const sol_history_js_1 = require("../autoresearch/sol-history.js");
 const sol_report_js_1 = require("../autoresearch/sol-report.js");
+const sol_scorecard_calculator_js_1 = require("../autoresearch/sol-scorecard-calculator.js");
+const sol_evaluation_writer_js_1 = require("../autoresearch/sol-evaluation-writer.js");
+const sol_report_renderer_js_1 = require("../autoresearch/sol-report-renderer.js");
 const sol_recommendations_js_1 = require("../autoresearch/sol-recommendations.js");
 function createSolCommand(options) {
     const repoRoot = options.repoRoot;
@@ -74,6 +78,79 @@ function createSolCommand(options) {
             process.exit(1);
         }
     });
+    sol
+        .command("report <run-id>")
+        .description("Generate SOL evaluation artifacts and a human-readable SmartDocs report for a run")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--format <mode>", "Output format: markdown or json", "markdown")
+        .option("--json", "Output raw JSON (same as --format json)")
+        .option("--no-write", "Skip writing artifact files")
+        .action((runId, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        if (cmdOptions.format !== "markdown" && cmdOptions.format !== "json") {
+            process.stderr.write(`sol report error: invalid --format "${cmdOptions.format}" (expected "markdown" or "json")\n`);
+            process.exit(1);
+        }
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        let artifacts;
+        let evidence;
+        try {
+            artifacts = (0, score_js_1.loadRunArtifacts)(root, runId);
+            evidence = (0, sol_evidence_loader_js_1.aggregateSolEvidence)(artifacts);
+        }
+        catch (err) {
+            process.stderr.write(`sol report error: cannot load run artifacts: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const report = (0, sol_scorer_js_1.computeSolScoreReport)(evidence);
+            const scorecards = (0, sol_scorecard_calculator_js_1.computeAllScorecards)(evidence);
+            const qcRecommendations = (0, sol_recommendations_js_1.generateQcRecommendations)(evidence);
+            let evaluationPath;
+            let scorecardPaths;
+            let markdownPath;
+            const evaluationRecord = (0, sol_evaluation_writer_js_1.buildEvaluationRecord)(report);
+            const rendered = (0, sol_report_renderer_js_1.renderSolMarkdown)(evaluationRecord, scorecards, qcRecommendations);
+            if (cmdOptions.write) {
+                // Persist the same evaluationRecord object that was rendered, rather than rebuilding internally
+                const evaluationDir = (0, sol_evaluation_writer_js_1.getSolEvaluationsDir)(root);
+                if (!(0, node_fs_1.existsSync)(evaluationDir))
+                    (0, node_fs_1.mkdirSync)(evaluationDir, { recursive: true });
+                evaluationPath = (0, sol_evaluation_writer_js_1.getEvaluationRecordPath)(root, report.run_id);
+                (0, node_fs_1.writeFileSync)(evaluationPath, JSON.stringify(evaluationRecord, null, 2) + "\n", "utf-8");
+                scorecardPaths = (0, sol_evaluation_writer_js_1.writeScorecardSet)(root, scorecards);
+                markdownPath = (0, sol_evaluation_writer_js_1.writeSolMarkdownReport)(root, runId, rendered.markdown);
+            }
+            const outputFormat = cmdOptions.json || cmdOptions.format === "json" ? "json" : "markdown";
+            if (outputFormat === "json") {
+                const output = JSON.stringify({
+                    run_id: runId,
+                    evaluation: evaluationRecord,
+                    scorecards,
+                    qc_recommendations: qcRecommendations,
+                    artifacts: {
+                        evaluation: evaluationPath,
+                        scorecards: scorecardPaths,
+                        markdown: markdownPath,
+                    },
+                }, null, 2);
+                process.stdout.write(`${output}\n`);
+            }
+            else {
+                process.stdout.write(rendered.markdown);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`sol report error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     sol
         .command("propose <diagnosis-file>")
         .description("File Linear improvement proposals from a diagnosis report (dev-gated — never auto-applied)")

package/dist/cluster-state/store.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordQcRun = exports.initializeClusterState = exports.writeClusterStateSync = exports.writeClusterState = exports.readClusterStateSync = exports.readClusterState = void 0;
 exports.pruneExpiredClaims = pruneExpiredClaims;
+exports.pruneMissingQcRunPointers = pruneMissingQcRunPointers;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const local_graph_1 = require("../tracker/local-graph");
@@ -350,12 +351,25 @@ const recordQcRun = async (clusterId, result, repoRoot) => {
     if (!currentState) {
         throw new Error(`Cluster ${clusterId} state not found; cannot record QC run ${result.qcRunId}.`);
     }
+    const rawArtifactPaths = result.rawArtifactPaths ?? [];
+    const providerAttemptPath = result.providerAttempt?.rawOutputArtifactPath;
+    const auditArtifactPaths = providerAttemptPath
+        ? [...rawArtifactPaths, providerAttemptPath]
+        : rawArtifactPaths;
+    const failedRun = result.status === "failed" || result.status === "blocked" || result.allProvidersFailed === true;
+    let availability = "available";
+    if (failedRun && auditArtifactPaths.some((p) => !(0, fs_1.existsSync)(p))) {
+        availability = "unavailable";
+    }
     const pointer = {
         artifact_path: artifactPath,
         status: result.status,
         provider: result.provider,
         started_at: result.startedAt,
         completed_at: result.completedAt,
+        availability,
+        raw_artifact_paths: rawArtifactPaths.length > 0 ? rawArtifactPaths : undefined,
+        provider_attempt_artifact_path: providerAttemptPath,
     };
     const nextState = {
         ...currentState,
@@ -369,3 +383,45 @@ const recordQcRun = async (clusterId, result, repoRoot) => {
     return { artifactPath, state: nextState };
 };
 exports.recordQcRun = recordQcRun;
+/**
+ * Remove QC run pointers whose primary artifacts are missing and mark
+ * pointers with missing raw audit artifacts as unavailable. Returns a new
+ * state object; callers must persist the result if they want the cleanup to
+ * be durable.
+ */
+function pruneMissingQcRunPointers(state) {
+    const warnings = [];
+    const pruned = [];
+    if (!state.qc_runs) {
+        return { state, pruned, warnings };
+    }
+    const validation = (0, artifacts_js_1.validateQcArtifactPointers)(state.qc_runs);
+    if (validation.ok && validation.unavailable.length === 0) {
+        return { state, pruned, warnings };
+    }
+    const nextQcRuns = {};
+    for (const [runId, pointer] of Object.entries(state.qc_runs)) {
+        if (validation.missing.includes(pointer.artifact_path)) {
+            pruned.push(runId);
+            warnings.push(`QC run ${runId} pointer pruned: artifact missing ${pointer.artifact_path}`);
+            continue;
+        }
+        const updated = { ...pointer };
+        const hasMissingRaw = (pointer.raw_artifact_paths ?? []).some((p) => validation.unavailable.includes(p)) ||
+            (pointer.provider_attempt_artifact_path &&
+                validation.unavailable.includes(pointer.provider_attempt_artifact_path));
+        if (hasMissingRaw && updated.availability === "available") {
+            updated.availability = "unavailable";
+            warnings.push(`QC run ${runId} raw audit artifacts missing; marked unavailable`);
+        }
+        nextQcRuns[runId] = updated;
+    }
+    return {
+        state: {
+            ...state,
+            qc_runs: nextQcRuns,
+        },
+        pruned,
+        warnings,
+    };
+}

package/dist/finalize/artifact-policy.js

@@ -37,6 +37,7 @@ function isPromotedClusterArtifact(relativePath, activeClusterId) {
     const suffix = relativePath.slice(activeClusterPrefix.length);
     return (suffix === "clusters.json"
         || suffix === "cluster-state.json"
+        || suffix === "state.json"
         || suffix.startsWith("packets/")
         || suffix.startsWith("results/")
         || suffix.startsWith("qc/"));
@@ -131,6 +132,7 @@ function getArtifactPromotionPolicy(activeClusterId) {
         promoted: [
             `${activeClusterPrefix}clusters.json`,
             `${activeClusterPrefix}cluster-state.json`,
+            `${activeClusterPrefix}state.json`,
             `${activeClusterPrefix}packets/**`,
             `${activeClusterPrefix}results/**`,
             `${activeClusterPrefix}qc/**`,

package/dist/finalize/github.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPrBody = buildPrBody;
 exports.createDraftPr = createDraftPr;
 const node_child_process_1 = require("node:child_process");
+function buildPrBody(state, branch, authoritativeChildCount) {
+    return [
+        `**Cluster ID:** ${state.cluster_id}`,
+        `**Run ID:** ${state.run_id}`,
+        `**Branch:** ${branch}`,
+        `**Children completed:** ${authoritativeChildCount ?? state.completed_children.length}`,
+        ``,
+        `_Generated by polaris finalize_`,
+    ].join("\n");
+}
 function createDraftPr(options) {
-    const { repoRoot, branch, state, draft } = options;
+    const { repoRoot, branch, state, draft, authoritativeChildCount } = options;
     if (!state.cluster_id) {
         throw new Error(`createDraftPr: state.cluster_id is empty — cannot create PR without a cluster identifier`);
     }
@@ -16,14 +27,7 @@ function createDraftPr(options) {
             `branch/cluster mismatch, aborting PR creation`);
     }
     const title = `polaris finalize: ${state.cluster_id} (${state.run_id})`;
-    const body = [
-        `**Cluster ID:** ${state.cluster_id}`,
-        `**Run ID:** ${state.run_id}`,
-        `**Branch:** ${branch}`,
-        `**Children completed:** ${state.completed_children.length}`,
-        ``,
-        `_Generated by polaris finalize_`,
-    ].join("\n");
+    const body = buildPrBody(state, branch, authoritativeChildCount);
     const args = [
         "pr", "create",
         "--title", title,

package/dist/finalize/index.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateStateFileAuthority = validateStateFileAuthority;
+exports.validateQcRepairLoopGate = validateQcRepairLoopGate;
+exports.warnOnMissingQcArtifacts = warnOnMissingQcArtifacts;
+exports.validateAuthoritativeChildState = validateAuthoritativeChildState;
 exports.runFinalize = runFinalize;
 exports.createFinalizeCommand = createFinalizeCommand;
 const commander_1 = require("commander");
@@ -12,6 +16,7 @@ const checkpoint_js_1 = require("../loop/checkpoint.js");
 const artifact_policy_js_1 = require("./artifact-policy.js");
 const git_custody_js_1 = require("../loop/git-custody.js");
 const store_js_1 = require("../cluster-state/store.js");
+const artifacts_js_1 = require("../qc/artifacts.js");
 const canon_check_js_1 = require("../smartdocs-engine/canon-check.js");
 const _01_map_update_js_1 = require("./steps/01-map-update.js");
 const _02_map_validate_js_1 = require("./steps/02-map-validate.js");
@@ -85,6 +90,60 @@ function validateStateBranchMatchesGitBranch(stateBranch, branch) {
         process.exit(1);
     }
 }
+const CLUSTER_STATE_FILE_PATTERN = /[\\/]\.polaris[\\/]clusters[\\/][^\\/]+[\\/]state\.json$/;
+function isClusterStateSnapshotFile(filePath) {
+    return CLUSTER_STATE_FILE_PATTERN.test(filePath.replace(/\\/g, "/"));
+}
+function computeRunStateFreshness(state) {
+    const s = state;
+    let score = 0;
+    score += (s.completed_children?.length ?? 0) * 10;
+    if (s.status === "complete")
+        score += 50;
+    if (s.pr_url)
+        score += 30;
+    if (s.qc_repair_loop?.terminal_outcome)
+        score += 40;
+    score += (s.dispatch_boundary?.dispatch_epoch ?? 0) * 5;
+    score += (s.context_budget?.children_completed ?? 0) * 2;
+    return score;
+}
+/**
+ * Refuse to use a promoted cluster state snapshot when the authoritative
+ * taskchain current-state.json is newer. Cluster snapshots under
+ * `.polaris/clusters/<id>/state.json` are secondary; the taskchain state
+ * owned by the parent loop is authoritative.
+ */
+function validateStateFileAuthority(stateFile, state, repoRoot) {
+    if (!isClusterStateSnapshotFile(stateFile)) {
+        return;
+    }
+    const taskchainStateFile = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+    if (!(0, node_fs_1.existsSync)(taskchainStateFile)) {
+        return;
+    }
+    let taskchainState;
+    try {
+        taskchainState = (0, checkpoint_js_1.readState)(taskchainStateFile);
+    }
+    catch {
+        return;
+    }
+    if (taskchainState.run_id !== state.run_id ||
+        taskchainState.cluster_id !== state.cluster_id) {
+        return;
+    }
+    const taskchainFreshness = computeRunStateFreshness(taskchainState);
+    const snapshotFreshness = computeRunStateFreshness(state);
+    if (taskchainFreshness > snapshotFreshness) {
+        process.stderr.write(`finalize aborted: cluster state snapshot is stale.\n` +
+            `  Snapshot: ${stateFile}\n` +
+            `  Authoritative taskchain state: ${taskchainStateFile}\n` +
+            `The taskchain current-state.json is newer; use it instead, or ` +
+            `update the cluster snapshot before finalizing.\n`);
+        process.exit(1);
+    }
+}
 /**
  * Check that the Closeout Librarian has run and its result passes the gate.
  * Returns null if finalize may proceed; returns a human-readable blocker string if not.
@@ -183,8 +242,106 @@ function resolveQcTelemetryFile(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
     return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
 }
+// ── QC repair-loop terminal state gate ────────────────────────────────────────
+/**
+ * Trusted QC repair-loop terminal outcomes that allow finalize to proceed.
+ * "pass" = QC rerun passed; "qc-disabled" = QC was off; "no-repairable" = no
+ * findings routable to repair workers (follow-up-only or already resolved).
+ */
+const TRUSTED_QC_REPAIR_OUTCOMES = new Set(["pass", "qc-disabled", "no-repairable"]);
+/**
+ * Validate QC repair-loop terminal state when QC is enabled and repair routing
+ * is active. Returns null when finalize may proceed; returns a human-readable
+ * blocker string otherwise.
+ */
+function validateQcRepairLoopGate(state, config) {
+    // Gate only applies when QC is enabled
+    if (!config.enabled)
+        return null;
+    // Gate only applies when repair routing is active (not "log" or "block")
+    const repairRouting = config.repairRouting ?? "route";
+    if (repairRouting !== "route" && repairRouting !== "follow-up")
+        return null;
+    const repairLoop = state.qc_repair_loop;
+    // No repair-loop state at all — the completed-cluster QC trigger ran but
+    // never entered the repair loop. This is a gap: finalize should not proceed.
+    if (!repairLoop) {
+        return ("QC is enabled with repair routing active, but no qc_repair_loop state " +
+            "was found in the run state. The parent loop must run the QC repair loop " +
+            "before finalize can proceed.");
+    }
+    const outcome = repairLoop.terminal_outcome;
+    if (outcome === null || outcome === undefined) {
+        return ("QC repair loop is still in-flight (terminal_outcome is null). " +
+            "Finalize cannot proceed until the repair loop reaches a terminal state.");
+    }
+    if (TRUSTED_QC_REPAIR_OUTCOMES.has(outcome))
+        return null;
+    return (`QC repair loop terminated with untrusted outcome: "${outcome}". ` +
+        `Only ${Array.from(TRUSTED_QC_REPAIR_OUTCOMES).join(", ")} outcomes allow finalize to proceed. ` +
+        `Resolve the repair loop before re-running finalize.`);
+}
+// ── Authoritative completed-child state cross-check ───────────────────────────
+function warnOnMissingQcArtifacts(clusterState, repoRoot) {
+    if (!clusterState)
+        return;
+    const validation = (0, artifacts_js_1.validateQcArtifactPointers)(clusterState.qc_runs);
+    if (validation.ok)
+        return;
+    for (const missing of validation.missing) {
+        console.warn(`finalize warning: cluster-state QC pointer references missing artifact: ${missing}`);
+    }
+    for (const unavailable of validation.unavailable) {
+        console.warn(`finalize warning: QC audit artifact unavailable: ${unavailable}`);
+    }
+}
+/**
+ * Cross-check completed children in the loop state against the cluster-state
+ * child_states. Returns a diagnostic result — when `ok` is false, finalize
+ * should refuse PR creation.
+ */
+function validateAuthoritativeChildState(state, repoRoot) {
+    const clusterState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+    const stateCount = state.completed_children.length;
+    // No cluster state available — backward-compat: trust the loop state.
+    if (!clusterState) {
+        return { ok: true, authoritativeCount: stateCount, stateCount };
+    }
+    const childStates = clusterState.child_states;
+    // No child_states array in cluster state — backward-compat: trust the loop state.
+    // This covers legacy cluster-state files that don't track individual child lifecycle.
+    if (!childStates || childStates.length === 0) {
+        return { ok: true, authoritativeCount: stateCount, stateCount };
+    }
+    const doneChildren = childStates.filter((c) => c.status === "done" || c.status === "reviewed" || c.status === "finalized");
+    const authoritativeCount = doneChildren.length;
+    // When cluster-state has tracked children but zero are done while loop state
+    // claims completions, the cluster state file is stale or was never updated.
+    if (authoritativeCount === 0 && stateCount > 0) {
+        return {
+            ok: false,
+            authoritativeCount,
+            stateCount,
+            reason: `Stale cluster state: cluster-state.json has 0 done children but ` +
+                `loop state claims ${stateCount} completed. ` +
+                `The cluster state file was never updated by worker completions.`,
+        };
+    }
+    // Significant mismatch: cluster-state has fewer done children than loop state
+    if (authoritativeCount < stateCount) {
+        return {
+            ok: false,
+            authoritativeCount,
+            stateCount,
+            reason: `Completed-child count mismatch: cluster-state has ${authoritativeCount} done ` +
+                `children but loop state has ${stateCount}. ` +
+                `The cluster state may be stale or child completions were not recorded properly.`,
+        };
+    }
+    return { ok: true, authoritativeCount, stateCount };
+}
 async function runQcGate(options) {
-    const { config, state, repoRoot, branch, trigger, prUrl, stepLabel } = options;
+    const { config, state, repoRoot, branch, baseRef, trigger, prUrl, stepLabel } = options;
     const registry = (0, index_js_2.createQcRegistry)(config);
     const result = await (0, index_js_2.runQcAtTrigger)({
         config,
@@ -195,6 +352,7 @@ async function runQcGate(options) {
         runId: state.run_id,
         clusterId: state.cluster_id,
         branch,
+        baseRef,
         telemetryFile: resolveQcTelemetryFile(state, repoRoot),
         state,
     });
@@ -236,6 +394,7 @@ async function runFinalize(options) {
     validateStateFilePath(stateFile);
     validateClusterIdMatchesBranch(state.cluster_id, branch);
     validateStateBranchMatchesGitBranch(state.branch, branch);
+    validateStateFileAuthority(stateFile, state, repoRoot);
     // Step 4: Run configured checks
     const checks = config.finalize?.runChecks ?? [];
     if (checks.length > 0) {
@@ -322,6 +481,7 @@ async function runFinalize(options) {
     // loop.allowBranchDivergence is true (direct-main mode).
     {
         const clusterState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+        warnOnMissingQcArtifacts(clusterState, repoRoot);
         const baseBranch = clusterState?.base_branch;
         const deliveryBranch = clusterState?.delivery_branch;
         const directMainMode = config.loop?.allowBranchDivergence === true;
@@ -389,14 +549,37 @@ async function runFinalize(options) {
     }
     // Step 5.8: Completed-cluster QC trigger (when configured)
     // Runs after all authoritative gates and before final commit/delivery.
+    const clusterStateForQc = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+    const qcBaseRef = clusterStateForQc?.base_branch ??
+        config.finalize?.targetBranch ??
+        "main";
     await runQcGate({
         config: config.qc,
         state,
         repoRoot,
         branch,
+        baseRef: qcBaseRef,
         trigger: "completed-cluster",
         stepLabel: "[5.8/14]",
     });
+    // Step 5.9: QC repair-loop terminal state gate
+    // When QC is enabled and repair routing is active, require a trusted
+    // terminal outcome from the QC repair loop before allowing PR creation.
+    {
+        const repairLoopBlocker = validateQcRepairLoopGate(state, config.qc);
+        if (repairLoopBlocker) {
+            process.stderr.write(`finalize aborted: QC repair-loop gate failed.\n${repairLoopBlocker}\n`);
+            process.exit(1);
+        }
+    }
+    // Step 5.10: Authoritative completed-child state cross-check
+    // Verify that the completed children claimed by the loop state match
+    // the cluster-state child_states. Blocks on stale or inconsistent state.
+    const authChildResult = validateAuthoritativeChildState(state, repoRoot);
+    if (!authChildResult.ok) {
+        process.stderr.write(`finalize aborted: authoritative child state mismatch.\n${authChildResult.reason}\n`);
+        process.exit(1);
+    }
     // Step 6: Tracker Reconciliation
     // LinearAdapter is sync-in only; only McpBridgeAdapter supports full reconciliation.
     const trackerType = config.tracker?.adapter;
@@ -465,7 +648,7 @@ async function runFinalize(options) {
     // Step 10: Create draft PR
     const prDraft = config.finalize?.prDraft ?? true;
     console.log("[10/14] Creating draft PR...");
-    const prUrl = (0, _08_create_pr_js_1.stepCreatePr)(repoRoot, branch, state, prDraft);
+    const prUrl = (0, _08_create_pr_js_1.stepCreatePr)(repoRoot, branch, state, prDraft, authChildResult.authoritativeCount);
     // Step 10.5: PR-required QC trigger (when configured)
     // Providers that require a PR URL run here after the PR is created.
     await runQcGate({
@@ -480,6 +663,17 @@ async function runFinalize(options) {
     // Step 11: Write PR URL to current-state.json
     console.log("[11/14] Writing PR URL to state...");
     state = (0, _09_update_state_js_1.stepUpdateState)(resolvedStateFile, state, prUrl);
+    // Promote the authoritative run state into the cluster snapshot so that
+    // `.polaris/clusters/<id>/state.json` preserves completed children, the
+    // dispatch boundary, QC repair-loop terminal state, and the PR URL.
+    try {
+        const clusterStateSnapshotPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "state.json");
+        (0, checkpoint_js_1.writeStateAtomic)(clusterStateSnapshotPath, state);
+    }
+    catch (snapshotError) {
+        process.stderr.write(`[11/14] WARNING: Failed to write cluster state snapshot: ${snapshotError instanceof Error ? snapshotError.message : String(snapshotError)}\n`);
+        process.stderr.write(`Delivery will proceed, but cluster state snapshot at .polaris/clusters/${state.cluster_id}/state.json may be incomplete.\n`);
+    }
     // Step 12: Append JSONL events
     console.log("[12/14] Appending JSONL events...");
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
@@ -489,7 +683,7 @@ async function runFinalize(options) {
     console.log("[13/14] Updating Linear...");
     const linearEnabled = config.tracker?.linear?.enabled ?? false;
     const lifecyclePolicy = config.tracker?.lifecyclePolicy;
-    await (0, _11_update_linear_js_1.stepUpdateLinear)(state, branch, prUrl, true, linearEnabled, state.cluster_id, lifecyclePolicy);
+    await (0, _11_update_linear_js_1.stepUpdateLinear)(state, branch, prUrl, true, linearEnabled, state.cluster_id, lifecyclePolicy, authChildResult.authoritativeCount);
     // Step 14: Archive run snapshot
     console.log("[14/14] Archiving run snapshot...");
     (0, _12_archive_js_1.stepArchive)(repoRoot, state, resolvedStateFile, reportPath);

package/dist/finalize/linear.js

@@ -97,6 +97,7 @@ async function findReviewState(issueId, apiKey) {
 // Comment body builder
 // ──────────────────────────────────────────────────────────────────────────────
 function buildCommentBody(opts) {
+    const childCount = opts.authoritativeChildCount ?? opts.state.completed_children.length;
     const lines = [
         `**polaris finalize complete** — run \`${opts.state.run_id}\``,
         ``,
@@ -104,7 +105,7 @@ function buildCommentBody(opts) {
         `|---|---|`,
         `| Branch | \`${opts.branch}\` |`,
         `| PR | ${opts.prUrl} |`,
-        `| Children completed | ${opts.state.completed_children.length} |`,
+        `| Children completed | ${childCount} |`,
         `| Map validation | ${opts.validationPassed ? "✓ passed" : "✗ failed"} |`,
     ];
     if (opts.reviewStateMissing) {
@@ -117,8 +118,8 @@ function buildCommentBody(opts) {
 // ──────────────────────────────────────────────────────────────────────────────
 /** Posts a finalize-complete comment without attempting a state transition. */
 async function postLinearComment(options) {
-    const { issueId, state, branch, prUrl, validationPassed, apiKey } = options;
-    const body = buildCommentBody({ state, branch, prUrl, validationPassed, reviewStateMissing: false });
+    const { issueId, state, branch, prUrl, validationPassed, apiKey, authoritativeChildCount } = options;
+    const body = buildCommentBody({ state, branch, prUrl, validationPassed, reviewStateMissing: false, authoritativeChildCount });
     const data = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
       commentCreate(input: { issueId: $issueId, body: $body }) { success }
     }`, { issueId, body }, apiKey);
@@ -140,7 +141,7 @@ async function postLinearComment(options) {
  * state ID. The assertNotDoneState guard enforces this at runtime.
  */
 async function updateLinearIssueAfterFinalize(options) {
-    const { issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy } = options;
+    const { issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy, authoritativeChildCount } = options;
     // Resolve lifecycle transition from policy
     const lifecycleTransition = (0, lifecycle_policy_js_1.resolveLifecycleTransition)("parent-all-children-complete", lifecyclePolicy);
     // If policy says skip, skip the state transition entirely
@@ -152,6 +153,7 @@ async function updateLinearIssueAfterFinalize(options) {
             prUrl,
             validationPassed,
             reviewStateMissing: false,
+            authoritativeChildCount,
         });
         const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
         commentCreate(input: { issueId: $issueId, body: $body }) { success }
@@ -172,6 +174,7 @@ async function updateLinearIssueAfterFinalize(options) {
             prUrl,
             validationPassed,
             reviewStateMissing: false,
+            authoritativeChildCount,
         });
         const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
         commentCreate(input: { issueId: $issueId, body: $body }) { success }
@@ -205,6 +208,7 @@ async function updateLinearIssueAfterFinalize(options) {
         prUrl,
         validationPassed,
         reviewStateMissing: reviewState === null,
+        authoritativeChildCount,
     });
     const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
       commentCreate(input: { issueId: $issueId, body: $body }) { success }

package/dist/finalize/steps/08-create-pr.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stepCreatePr = stepCreatePr;
 const github_js_1 = require("../github.js");
-function stepCreatePr(repoRoot, branch, state, draft) {
-    const prUrl = (0, github_js_1.createDraftPr)({ repoRoot, branch, state, draft });
+function stepCreatePr(repoRoot, branch, state, draft, authoritativeChildCount) {
+    const prUrl = (0, github_js_1.createDraftPr)({ repoRoot, branch, state, draft, authoritativeChildCount });
     console.log(`PR created: ${prUrl}`);
     return prUrl;
 }

package/dist/finalize/steps/11-update-linear.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stepUpdateLinear = stepUpdateLinear;
 const linear_js_1 = require("../linear.js");
-async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEnabled, parentIssueId, lifecyclePolicy) {
+async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEnabled, parentIssueId, lifecyclePolicy, authoritativeChildCount) {
     if (!linearEnabled) {
         console.log("[11/12] Linear integration disabled — skipping.");
         return;
@@ -17,6 +17,6 @@ async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEn
         process.stderr.write("Warning: no Linear parent issue ID — skipping Linear update.\n");
         return;
     }
-    await (0, linear_js_1.updateLinearIssueAfterFinalize)({ issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy });
+    await (0, linear_js_1.updateLinearIssueAfterFinalize)({ issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy, authoritativeChildCount });
     console.log(`Linear parent ${issueId} updated.`);
 }