@lsctech/polaris 0.1.0

package/dist/loop/evidence-backfill.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPlaceholderCommit = isPlaceholderCommit;
+exports.backfillClusterStateEvidence = backfillClusterStateEvidence;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const checkpoint_js_1 = require("./checkpoint.js");
+const store_js_1 = require("../cluster-state/store.js");
+// Matches abbreviated/full hex SHAs (>=7 chars), case-insensitive — rejects placeholder strings.
+const HEX_SHA_RE = /^[0-9a-f]{7,}$/i;
+function isPlaceholderCommit(commit) {
+    if (typeof commit !== "string" || commit.trim().length === 0)
+        return true;
+    return !HEX_SHA_RE.test(commit.trim());
+}
+function readJsonFile(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return undefined;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Scan a directory for the first (sorted) file whose name starts with `<childId>-` or equals `<childId>.json`.
+function findFileByChildPrefix(dir, childId) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return undefined;
+    for (const name of (0, node_fs_1.readdirSync)(dir).sort()) {
+        if (name === `${childId}.json` || name.startsWith(`${childId}-`)) {
+            return (0, node_path_1.join)(dir, name);
+        }
+    }
+    return undefined;
+}
+function resolveStatePath(repoRoot, filePath) {
+    if (typeof filePath !== "string" || filePath.trim().length === 0)
+        return undefined;
+    const trimmed = filePath.trim();
+    return (0, node_path_1.isAbsolute)(trimmed) ? trimmed : (0, node_path_1.resolve)(repoRoot, trimmed);
+}
+function hasPassingValidation(value) {
+    if (typeof value === "string") {
+        const n = value.trim().toLowerCase();
+        return n === "passed" || n === "pass" || n === "success" || n === "ok";
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const rec = value;
+    const passed = rec["passed"];
+    if (passed === true)
+        return true;
+    if (Array.isArray(passed) && passed.length > 0)
+        return true;
+    if (typeof passed === "number" && passed > 0)
+        return true;
+    for (const key of ["status", "summary", "validation"]) {
+        const v = rec[key];
+        if (typeof v === "string" && ["passed", "pass", "success", "ok"].includes(v.trim().toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasValidationWaiver(packet) {
+    if (!packet || typeof packet !== "object" || Array.isArray(packet))
+        return false;
+    const pkt = packet;
+    const isTruthy = (v) => {
+        if (typeof v === "string")
+            return v.trim().length > 0;
+        if (typeof v === "boolean")
+            return v;
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return Object.keys(v).length > 0;
+        return false;
+    };
+    if (isTruthy(pkt["validation_waiver"]))
+        return true;
+    const instr = pkt["instructions"];
+    if (instr && typeof instr === "object" && !Array.isArray(instr)) {
+        if (isTruthy(instr["validation_waiver"]))
+            return true;
+    }
+    return false;
+}
+function backfillClusterStateEvidence(options) {
+    const { repoRoot, stateFile, dryRun = false } = options;
+    const state = (0, checkpoint_js_1.readState)(stateFile);
+    const clusterId = state.cluster_id;
+    const resultsDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "results");
+    const packetsDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "packets");
+    const backfilled = [];
+    const skipped = [];
+    for (const childId of state.completed_children) {
+        // Resolve result file — mirrors continue.ts priority:
+        //   1. result_file on child meta (explicit override, e.g. --result-file flag)
+        //   2. dispatch_record.expected_result_path
+        //   3. directory scan by child ID prefix (fallback for older state)
+        let resultFilePath;
+        const childMeta = state.open_children_meta?.[childId];
+        const dispatchRecord = childMeta?.dispatch_record;
+        for (const candidate of [childMeta?.result_file, dispatchRecord?.expected_result_path]) {
+            const abs = resolveStatePath(repoRoot, candidate);
+            if (abs && (0, node_fs_1.existsSync)(abs)) {
+                resultFilePath = abs;
+                break;
+            }
+        }
+        if (!resultFilePath) {
+            resultFilePath = findFileByChildPrefix(resultsDir, childId);
+        }
+        if (!resultFilePath) {
+            skipped.push({ childId, reason: "no result file found" });
+            continue;
+        }
+        const result = readJsonFile(resultFilePath);
+        if (!result || typeof result !== "object" || Array.isArray(result)) {
+            skipped.push({ childId, reason: "result file unreadable or not a JSON object" });
+            continue;
+        }
+        // Guard: result file must belong to this child (prevents mis-routing from prefix scan or wrong pointer).
+        const resultChildId = result["child_id"] ?? result["childId"] ?? result["id"];
+        if (resultChildId !== undefined && resultChildId !== childId) {
+            skipped.push({
+                childId,
+                reason: `result file belongs to ${String(resultChildId)}, not ${childId}`,
+            });
+            continue;
+        }
+        // Guard: result must indicate completion.
+        if (result["status"] !== undefined && result["status"] !== "done") {
+            skipped.push({
+                childId,
+                reason: `result status is not done: ${String(result["status"])}`,
+            });
+            continue;
+        }
+        // Reject placeholder commits.
+        const rawCommit = result["commit"] ?? result["commit_hash"];
+        if (isPlaceholderCommit(rawCommit)) {
+            skipped.push({ childId, reason: `placeholder or missing commit: ${String(rawCommit ?? "(none)")}` });
+            continue;
+        }
+        const commit = rawCommit.trim();
+        // Validate — or check for waiver.
+        let packetFilePath;
+        if (dispatchRecord?.packet_path) {
+            const abs = (0, node_path_1.resolve)(repoRoot, dispatchRecord.packet_path);
+            if ((0, node_fs_1.existsSync)(abs))
+                packetFilePath = abs;
+        }
+        if (!packetFilePath) {
+            packetFilePath = findFileByChildPrefix(packetsDir, childId);
+        }
+        const packet = packetFilePath ? readJsonFile(packetFilePath) : undefined;
+        const validationPassed = hasPassingValidation(result["validation"]);
+        if (!validationPassed && !hasValidationWaiver(packet)) {
+            skipped.push({ childId, reason: "validation not passed and no validation_waiver on packet" });
+            continue;
+        }
+        backfilled.push({
+            childId,
+            resultFile: (0, node_path_1.relative)(repoRoot, resultFilePath),
+            packetFile: packetFilePath ? (0, node_path_1.relative)(repoRoot, packetFilePath) : undefined,
+            commit,
+            validationPassed,
+        });
+    }
+    if (!dryRun && backfilled.length > 0) {
+        applyBackfillToClusterState({ clusterId, repoRoot, backfilled });
+    }
+    return { clusterId, backfilled, skipped };
+}
+function applyBackfillToClusterState(params) {
+    const { clusterId, repoRoot, backfilled } = params;
+    const existing = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
+    if (!existing) {
+        throw new Error(`cluster-state.json not found for ${clusterId} — cannot apply backfill`);
+    }
+    const updated = {
+        ...existing,
+        state_generation: existing.state_generation + 1,
+        commits: { ...existing.commits },
+        result_pointers: { ...existing.result_pointers },
+        packet_pointers: { ...existing.packet_pointers },
+        validation_results: { ...existing.validation_results },
+        claim_metadata: { ...existing.claim_metadata },
+        child_states: existing.child_states.map((cs) => ({ ...cs })),
+    };
+    for (const entry of backfilled) {
+        updated.commits[entry.childId] = entry.commit;
+        updated.result_pointers[entry.childId] = entry.resultFile;
+        if (entry.packetFile) {
+            updated.packet_pointers[entry.childId] = entry.packetFile;
+        }
+        const validationResult = {
+            passed: entry.validationPassed,
+            output: `backfilled from ${entry.resultFile}`,
+        };
+        updated.validation_results[entry.childId] = validationResult;
+        delete updated.claim_metadata[entry.childId];
+        const childState = updated.child_states.find((cs) => cs.id === entry.childId);
+        if (childState) {
+            childState.status = "done";
+            childState.commit = entry.commit;
+        }
+        else {
+            updated.child_states.push({ id: entry.childId, status: "done", commit: entry.commit });
+        }
+    }
+    (0, store_js_1.writeClusterStateSync)(clusterId, updated, repoRoot);
+}

package/dist/loop/execution-adapter.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectExecutionAdapter = selectExecutionAdapter;
+exports.buildCompactBootstrapState = buildCompactBootstrapState;
+exports.buildExecutionAdapterContract = buildExecutionAdapterContract;
+const node_path_1 = require("node:path");
+const FALLBACK_ORDER = [
+    "agent-subtask",
+    "terminal-cli",
+    "ci",
+    "ssh",
+    "remote-worker",
+    "cross-agent",
+];
+function fromConfigured(mode) {
+    switch (mode) {
+        case "agent-subtask":
+            return {
+                mode,
+                autoDispatch: true,
+                providerCoupling: "native-same-agent",
+                priority: 1,
+                warnings: [],
+                reason: "native same-agent subtask adapter configured",
+            };
+        case "terminal-cli":
+            return {
+                mode,
+                autoDispatch: false,
+                providerCoupling: "shell-process",
+                priority: 2,
+                warnings: [],
+                reason: "terminal CLI worker adapter configured",
+            };
+        case "ci":
+            return {
+                mode,
+                autoDispatch: false,
+                providerCoupling: "remote-worker",
+                priority: 3,
+                warnings: [],
+                reason: "CI worker adapter configured",
+            };
+        case "ssh":
+        case "remote-worker":
+            return {
+                mode,
+                autoDispatch: false,
+                providerCoupling: "remote-worker",
+                priority: 3,
+                warnings: [],
+                reason: "remote worker adapter configured",
+            };
+        case "cross-agent":
+            return {
+                mode,
+                autoDispatch: true,
+                providerCoupling: "explicit-cross-agent",
+                priority: 4,
+                warnings: [],
+                reason: "cross-agent fallback explicitly configured",
+            };
+        default:
+            throw new Error(`Unknown ExecutionAdapterMode: ${String(mode)}`);
+    }
+}
+function selectExecutionAdapter(input) {
+    const requested = input.explicitAdapter ?? input.configuredAdapter;
+    const warnings = [];
+    if (requested === "cross-agent" && !input.crossAgentConfigured && !input.tokenBudgetLow) {
+        warnings.push("cross-agent fallback requires explicit configuration or low-token emergency");
+        return {
+            ...fromConfigured("terminal-cli"),
+            warnings,
+            reason: "cross-agent fallback denied; terminal CLI requires explicit external worker handoff",
+        };
+    }
+    if (requested) {
+        return fromConfigured(requested);
+    }
+    if (input.insideAgentSession && input.nativeSubtaskAvailable) {
+        return {
+            mode: "agent-subtask",
+            autoDispatch: true,
+            providerCoupling: "native-same-agent",
+            priority: 1,
+            warnings,
+            reason: "native same-agent subtask dispatch is available",
+        };
+    }
+    if (input.insideAgentSession && !input.nativeSubtaskAvailable) {
+        warnings.push("native subtask dispatch unavailable; parent must not shell out to nested agent CLI by default");
+        return {
+            ...fromConfigured("terminal-cli"),
+            autoDispatch: false,
+            warnings,
+            reason: "fallback requires external terminal worker or explicit adapter configuration",
+        };
+    }
+    return fromConfigured("terminal-cli");
+}
+function buildCompactBootstrapState(input) {
+    // Normalize paths to repo-relative for portability
+    const repoRoot = process.cwd();
+    const relStateFile = input.stateFile.startsWith("/") ? (0, node_path_1.relative)(repoRoot, input.stateFile) : input.stateFile;
+    const relTelemetryFile = input.telemetryFile.startsWith("/") ? (0, node_path_1.relative)(repoRoot, input.telemetryFile) : input.telemetryFile;
+    const result = {
+        run_id: input.runId,
+        cluster_id: input.clusterId,
+        child_id: input.childId,
+        state_file: relStateFile,
+        telemetry_file: relTelemetryFile,
+        current_state_sha: input.currentStateSha,
+        branch: input.branch,
+        compact_mode: input.compactMode ?? "standard",
+        return_summary_contract: [
+            "child_id",
+            "status",
+            "commit_hash",
+            "validation_summary",
+            "next_action",
+        ],
+    };
+    if (input.allowAnalyzeChildren !== undefined) {
+        result.allow_analyze_children = input.allowAnalyzeChildren;
+    }
+    return result;
+}
+function buildExecutionAdapterContract(selection, compactBootstrapState) {
+    return {
+        ...selection,
+        compact_bootstrap_state: compactBootstrapState,
+        dispatch_contract: {
+            one_child_per_worker: true,
+            parent_receives_compact_summary_only: true,
+            child_transcript_retained_by_worker: true,
+            updates_current_state_and_telemetry: true,
+        },
+        fallback_order: FALLBACK_ORDER,
+    };
+}

package/dist/loop/execution-adapter.test.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const execution_adapter_js_1 = require("./execution-adapter.js");
+(0, vitest_1.describe)("selectExecutionAdapter", () => {
+    (0, vitest_1.it)("prefers native same-agent subtask dispatch inside interactive agent sessions", () => {
+        const selected = (0, execution_adapter_js_1.selectExecutionAdapter)({
+            insideAgentSession: true,
+            nativeSubtaskAvailable: true,
+        });
+        (0, vitest_1.expect)(selected.mode).toBe("agent-subtask");
+        (0, vitest_1.expect)(selected.autoDispatch).toBe(true);
+        (0, vitest_1.expect)(selected.providerCoupling).toBe("native-same-agent");
+    });
+    (0, vitest_1.it)("does not cross-call another agent unless explicitly configured", () => {
+        const selected = (0, execution_adapter_js_1.selectExecutionAdapter)({
+            insideAgentSession: true,
+            nativeSubtaskAvailable: false,
+            configuredAdapter: "cross-agent",
+            crossAgentConfigured: false,
+            tokenBudgetLow: false,
+        });
+        (0, vitest_1.expect)(selected.mode).toBe("terminal-cli");
+        (0, vitest_1.expect)(selected.autoDispatch).toBe(false);
+        (0, vitest_1.expect)(selected.warnings).toContain("cross-agent fallback requires explicit configuration or low-token emergency");
+    });
+    (0, vitest_1.it)("allows explicit cross-agent fallback when configured", () => {
+        const selected = (0, execution_adapter_js_1.selectExecutionAdapter)({
+            insideAgentSession: true,
+            nativeSubtaskAvailable: false,
+            configuredAdapter: "cross-agent",
+            crossAgentConfigured: true,
+        });
+        (0, vitest_1.expect)(selected.mode).toBe("cross-agent");
+        (0, vitest_1.expect)(selected.autoDispatch).toBe(true);
+    });
+});
+(0, vitest_1.describe)("buildCompactBootstrapState", () => {
+    (0, vitest_1.it)("contains only compact handoff fields", () => {
+        const compact = (0, execution_adapter_js_1.buildCompactBootstrapState)({
+            runId: "run-001",
+            clusterId: "POL-42",
+            childId: "POL-49",
+            stateFile: ".taskchain_artifacts/polaris-run/current-state.json",
+            telemetryFile: ".taskchain_artifacts/polaris-run/runs/run-001/telemetry.jsonl",
+            currentStateSha: "abc123",
+            branch: "feature/pol-42",
+        });
+        (0, vitest_1.expect)(compact).toEqual({
+            run_id: "run-001",
+            cluster_id: "POL-42",
+            child_id: "POL-49",
+            state_file: ".taskchain_artifacts/polaris-run/current-state.json",
+            telemetry_file: ".taskchain_artifacts/polaris-run/runs/run-001/telemetry.jsonl",
+            current_state_sha: "abc123",
+            branch: "feature/pol-42",
+            return_summary_contract: [
+                "child_id",
+                "status",
+                "commit_hash",
+                "validation_summary",
+                "next_action",
+            ],
+        });
+    });
+});

package/dist/loop/finalize-evidence.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFinalizeEvidenceFailures = formatFinalizeEvidenceFailures;
+exports.verifyCompletedChildFinalizeEvidence = verifyCompletedChildFinalizeEvidence;
+exports.assertFinalizeEvidenceOrThrow = assertFinalizeEvidenceOrThrow;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const checkpoint_js_1 = require("./checkpoint.js");
+const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
+function readJsonFile(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return undefined;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolvePath(repoRoot, pathLike) {
+    if (typeof pathLike !== "string" || pathLike.trim().length === 0)
+        return undefined;
+    return (0, node_path_1.isAbsolute)(pathLike) ? pathLike : (0, node_path_1.resolve)(repoRoot, pathLike);
+}
+function pickCommitHash(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string")
+            continue;
+        const commit = candidate.trim();
+        if (commit.length > 0)
+            return commit;
+    }
+    return undefined;
+}
+function packetFlag(packet, key) {
+    if (!packet || typeof packet !== "object" || Array.isArray(packet))
+        return undefined;
+    const pkt = packet;
+    const fromRoot = pkt[key];
+    if (fromRoot !== undefined)
+        return fromRoot;
+    const instructions = pkt.instructions;
+    if (!instructions || typeof instructions !== "object" || Array.isArray(instructions))
+        return undefined;
+    return instructions[key];
+}
+function hasValidationWaiver(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "boolean")
+        return value;
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return Object.keys(value).length > 0;
+    return false;
+}
+function isArtifactOnlyAllowed(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value.trim().toLowerCase() === "true";
+    return false;
+}
+function hasPassingValidation(value) {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        return normalized === "passed" || normalized === "pass" || normalized === "success" || normalized === "ok";
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    const status = record["status"];
+    if (typeof status === "string" && ["passed", "pass", "success", "ok"].includes(status.trim().toLowerCase())) {
+        return true;
+    }
+    const summary = record["summary"];
+    if (typeof summary === "string" && ["passed", "pass", "success", "ok"].includes(summary.trim().toLowerCase())) {
+        return true;
+    }
+    const validation = record["validation"];
+    if (typeof validation === "string" && ["passed", "pass", "success", "ok"].includes(validation.trim().toLowerCase())) {
+        return true;
+    }
+    const passed = record["passed"];
+    if (passed === true)
+        return true;
+    if (Array.isArray(passed))
+        return passed.length > 0;
+    if (typeof passed === "number")
+        return passed > 0;
+    return false;
+}
+function getCommitFiles(repoRoot, commitHash) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["show", "--pretty=format:", "--name-only", commitHash], { cwd: repoRoot, encoding: "utf-8" });
+        return output.split("\n").map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+function listFailingChildren(failures) {
+    const lines = failures.map((failure) => `- ${failure.childId}: ${failure.reasons.join("; ")}`);
+    return [
+        "finalize aborted: completed children missing implementation evidence:",
+        ...lines,
+    ].join("\n");
+}
+function formatFinalizeEvidenceFailures(failures) {
+    return listFailingChildren(failures);
+}
+function verifyCompletedChildFinalizeEvidence(repoRoot, stateFile) {
+    const state = (0, checkpoint_js_1.readState)(stateFile);
+    const clusterStatePath = (0, node_path_1.resolve)(repoRoot, ".polaris", "clusters", state.cluster_id, "cluster-state.json");
+    const clusterState = (readJsonFile(clusterStatePath) ?? {});
+    const failures = [];
+    for (const childId of state.completed_children) {
+        const reasons = [];
+        const childMeta = state.open_children_meta?.[childId];
+        const dispatchRecord = childMeta?.dispatch_record;
+        const packetPath = resolvePath(repoRoot, dispatchRecord?.packet_path ?? clusterState.packet_pointers?.[childId]);
+        const resultPath = resolvePath(repoRoot, dispatchRecord?.expected_result_path ?? childMeta?.result_file ?? clusterState.result_pointers?.[childId]);
+        const packet = packetPath ? readJsonFile(packetPath) : undefined;
+        const result = (resultPath ? readJsonFile(resultPath) : undefined);
+        const stateResult = state.completed_children_results?.[childId];
+        const commitHash = pickCommitHash(clusterState.commits?.[childId], stateResult?.commit, result?.commit, result?.commit_hash);
+        if (!commitHash) {
+            reasons.push("no commit hash recorded in cluster state or result evidence");
+        }
+        else {
+            const commitFiles = getCommitFiles(repoRoot, commitHash);
+            if (commitFiles === null) {
+                reasons.push(`commit ${commitHash} not found in git history`);
+            }
+            else if (commitFiles.length === 0) {
+                reasons.push(`commit ${commitHash} contains no file changes`);
+            }
+            else {
+                const nonArtifactFiles = commitFiles.filter((file) => (0, artifact_policy_js_1.classifyArtifactPath)(file, state.cluster_id) === "non-artifact");
+                const artifactOnlyAllowed = isArtifactOnlyAllowed(packetFlag(packet, "artifact_only"));
+                if (nonArtifactFiles.length === 0 && !artifactOnlyAllowed) {
+                    reasons.push(`commit ${commitHash} changes only artifacts and packet is missing artifact_only: true`);
+                }
+            }
+        }
+        const validationWaiver = packetFlag(packet, "validation_waiver");
+        const validationPassed = hasPassingValidation(result?.validation)
+            || hasPassingValidation(stateResult?.validation)
+            || hasPassingValidation(clusterState.validation_results?.[childId]);
+        if (!validationPassed && !hasValidationWaiver(validationWaiver)) {
+            reasons.push("validation evidence missing or not passed and no validation_waiver was provided");
+        }
+        if (reasons.length > 0) {
+            failures.push({ childId, reasons });
+        }
+    }
+    return {
+        ok: failures.length === 0,
+        failures,
+    };
+}
+function assertFinalizeEvidenceOrThrow(repoRoot, stateFile) {
+    const report = verifyCompletedChildFinalizeEvidence(repoRoot, stateFile);
+    if (!report.ok) {
+        throw new Error(formatFinalizeEvidenceFailures(report.failures));
+    }
+}