@lsctech/polaris 0.1.0

package/dist/loop/git-custody.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchCustodyViolation = exports.PROTECTED_BASE_BRANCHES = void 0;
+exports.isProtectedBranch = isProtectedBranch;
+exports.getRefSha = getRefSha;
+exports.isCommitReachableFrom = isCommitReachableFrom;
+exports.assertNotOnBaseBranch = assertNotOnBaseBranch;
+exports.assertDeliveryBranchMatch = assertDeliveryBranchMatch;
+exports.verifyChildCommitCustody = verifyChildCommitCustody;
+exports.buildDeliveryBranchName = buildDeliveryBranchName;
+exports.ensureDeliveryBranch = ensureDeliveryBranch;
+exports.hasNonArtifactSourceChanges = hasNonArtifactSourceChanges;
+exports.patternMatchesPath = patternMatchesPath;
+exports.validateWorkerCommitScope = validateWorkerCommitScope;
+exports.buildCustodyRecord = buildCustodyRecord;
+const node_child_process_1 = require("node:child_process");
+const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
+const node_path_1 = require("node:path");
+exports.PROTECTED_BASE_BRANCHES = new Set([
+    "main",
+    "master",
+    "dev",
+    "develop",
+    "staging",
+    "production",
+    "release",
+]);
+class BranchCustodyViolation extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BranchCustodyViolation";
+    }
+}
+exports.BranchCustodyViolation = BranchCustodyViolation;
+/** Returns true when branchName is a known protected base branch. */
+function isProtectedBranch(branchName) {
+    return exports.PROTECTED_BASE_BRANCHES.has(branchName.toLowerCase());
+}
+/** Returns the SHA for a ref, or null when the ref cannot be resolved. */
+function getRefSha(repoRoot, ref) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", ref], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true when `commit` is an ancestor of (or equal to) `ref`.
+ * Uses `git merge-base --is-ancestor` which exits 0 on success.
+ */
+function isCommitReachableFrom(repoRoot, commit, ref) {
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["merge-base", "--is-ancestor", commit, ref], {
+            cwd: repoRoot,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Throws BranchCustodyViolation when currentBranch is a protected base branch.
+ * Implementation workers must run on a delivery branch, never on main/master/etc.
+ */
+function assertNotOnBaseBranch(currentBranch) {
+    if (isProtectedBranch(currentBranch)) {
+        throw new BranchCustodyViolation(`Branch custody violation: workers must not run on base branch "${currentBranch}". ` +
+            `Create a delivery branch before dispatching implementation workers.`);
+    }
+}
+/**
+ * Throws BranchCustodyViolation when currentBranch differs from the
+ * delivery branch that was recorded for this cluster at first dispatch.
+ */
+function assertDeliveryBranchMatch(currentBranch, deliveryBranch) {
+    if (currentBranch !== deliveryBranch) {
+        throw new BranchCustodyViolation(`Branch custody violation: current branch "${currentBranch}" does not match ` +
+            `recorded delivery branch "${deliveryBranch}". ` +
+            `Switch to the delivery branch before dispatching.`);
+    }
+}
+/**
+ * Verifies that a child commit belongs to the delivery branch and has not yet
+ * been merged into the base branch.
+ *
+ * Returns null on success, or a human-readable error string on failure.
+ */
+function verifyChildCommitCustody(repoRoot, commit, deliveryBranch, baseBranch) {
+    const onDelivery = isCommitReachableFrom(repoRoot, commit, deliveryBranch);
+    if (!onDelivery) {
+        return (`commit ${commit} is not reachable from delivery branch "${deliveryBranch}"`);
+    }
+    const onBase = isCommitReachableFrom(repoRoot, commit, baseBranch);
+    if (onBase) {
+        return (`commit ${commit} is already reachable from base branch "${baseBranch}" ` +
+            `(branch custody violation: implementation committed directly to base)`);
+    }
+    return null;
+}
+/**
+ * Returns the canonical delivery branch name for a cluster.
+ * e.g. "POL-268" → "pol-268-delivery"
+ */
+function buildDeliveryBranchName(clusterId) {
+    return clusterId.toLowerCase().replace(/_/g, "-") + "-delivery";
+}
+/**
+ * Creates and switches to `branchName`, or switches to it if it already exists.
+ * Checks for branch existence explicitly before choosing the git operation so
+ * that errors from unrelated failures are not silently swallowed.
+ * Throws with context when the checkout fails.
+ */
+function ensureDeliveryBranch(repoRoot, branchName) {
+    const branchExists = (() => {
+        try {
+            (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--verify", `refs/heads/${branchName}`], {
+                cwd: repoRoot,
+                stdio: "ignore",
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    const args = branchExists ? ["checkout", branchName] : ["checkout", "-b", branchName];
+    try {
+        (0, node_child_process_1.execFileSync)("git", args, { cwd: repoRoot, stdio: "pipe" });
+    }
+    catch (err) {
+        const stderr = err instanceof Error && "stderr" in err ? String(err.stderr).trim() : "";
+        throw new Error(`ensureDeliveryBranch: git ${args.join(" ")} failed` +
+            (stderr ? `: ${stderr}` : "") +
+            ` (branch="${branchName}", repoRoot="${repoRoot}")`);
+    }
+}
+/**
+ * Returns true when the range baseBranch...deliveryBranch contains at least
+ * one non-artifact source file change (i.e. a real implementation change beyond
+ * Polaris artifacts).
+ *
+ * Pass the explicit delivery branch ref so the comparison is independent of
+ * the current HEAD position.
+ *
+ * Files under .polaris/ and .taskchain_artifacts/ are not counted as
+ * implementation evidence.
+ */
+function hasNonArtifactSourceChanges(repoRoot, baseBranch, clusterId, deliveryBranch) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only", `${baseBranch}...${deliveryBranch}`], { cwd: repoRoot, encoding: "utf-8" }).trim();
+        if (!output)
+            return false;
+        const changedFiles = output.split("\n").filter(Boolean);
+        return changedFiles.some((f) => (0, artifact_policy_js_1.classifyArtifactPath)(f, clusterId) === "non-artifact");
+    }
+    catch (err) {
+        throw new Error(`hasNonArtifactSourceChanges: git diff failed for ${baseBranch}...${deliveryBranch}: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+function normalizeCommitPath(filePath) {
+    return node_path_1.posix.normalize(filePath.replace(/\\/g, "/")).replace(/^\.\//, "");
+}
+function escapeRegExp(value) {
+    return value.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}
+function globPatternToRegExp(pattern) {
+    let re = "^";
+    const normalized = normalizeCommitPath(pattern);
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized[i];
+        if (char === "*") {
+            if (normalized[i + 1] === "*") {
+                re += ".*";
+                i++;
+            }
+            else {
+                re += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            re += "[^/]";
+            continue;
+        }
+        re += escapeRegExp(char);
+    }
+    re += "$";
+    return new RegExp(re);
+}
+function patternMatchesPath(pattern, filePath) {
+    const normalizedPattern = normalizeCommitPath(pattern);
+    const normalizedPath = normalizeCommitPath(filePath);
+    if (/[\\*?\[\]]/.test(normalizedPattern)) {
+        return globPatternToRegExp(normalizedPattern).test(normalizedPath);
+    }
+    if (normalizedPattern.endsWith("/")) {
+        return normalizedPath.startsWith(normalizedPattern);
+    }
+    return normalizedPath === normalizedPattern || normalizedPath.startsWith(`${normalizedPattern}/`);
+}
+function getStagedFiles(repoRoot) {
+    const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR"], { cwd: repoRoot, encoding: "utf-8" }).trim();
+    if (!output) {
+        return [];
+    }
+    return output.split("\n").map((line) => normalizeCommitPath(line)).filter(Boolean);
+}
+function validateWorkerCommitScope(repoRoot, allowedScope, prohibitedWritePaths) {
+    const stagedFiles = getStagedFiles(repoRoot);
+    const violations = [];
+    for (const stagedFile of stagedFiles) {
+        const prohibitedPattern = prohibitedWritePaths.find((pattern) => patternMatchesPath(pattern, stagedFile));
+        if (prohibitedPattern) {
+            violations.push({
+                path: stagedFile,
+                kind: "prohibited",
+                pattern: prohibitedPattern,
+            });
+            continue;
+        }
+        const allowedPattern = allowedScope.find((pattern) => patternMatchesPath(pattern, stagedFile));
+        if (!allowedPattern) {
+            violations.push({
+                path: stagedFile,
+                kind: "out-of-scope",
+                pattern: allowedScope.length > 0 ? allowedScope[0] : "",
+            });
+        }
+    }
+    return { staged_files: stagedFiles, violations };
+}
+/**
+ * Builds a custody record from the current repo state.
+ * base_sha captures the tip of baseBranch at the moment custody is established.
+ */
+function buildCustodyRecord(repoRoot, currentBranch, baseBranch = "main") {
+    const baseSha = getRefSha(repoRoot, baseBranch) ?? getRefSha(repoRoot, "HEAD") ?? "unknown";
+    return {
+        base_branch: baseBranch,
+        base_sha: baseSha,
+        delivery_branch: currentBranch,
+    };
+}

package/dist/loop/impl-packet-input.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImplPacketInput = resolveImplPacketInput;
+function toStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function resolveImplPacketInput(state, childId) {
+    const childMeta = state.open_children_meta?.[childId];
+    const title = childMeta?.["title"];
+    const keyRequirements = toStringArray(childMeta?.["key_requirements"]);
+    const allowedScope = toStringArray(childMeta?.["allowed_scope"]);
+    const validationCommands = toStringArray(childMeta?.["validation_commands"]);
+    if (allowedScope.length === 0) {
+        throw new Error(`cannot dispatch child ${childId}: impl packet generation refused because allowed_scope is empty`);
+    }
+    if (keyRequirements.length === 0) {
+        throw new Error(`cannot dispatch child ${childId}: impl packet generation refused because key_requirements is empty (would produce placeholder goal)`);
+    }
+    const validationWaiver = childMeta?.["validation_waiver"];
+    const hasValidationWaiver = typeof validationWaiver === "string" && validationWaiver.trim().length > 0;
+    if (validationCommands.length === 0 && !hasValidationWaiver) {
+        throw new Error(`cannot dispatch child ${childId}: impl packet generation refused because validation_commands is empty and no validation_waiver is set`);
+    }
+    return {
+        issueContext: {
+            id: childId,
+            title: typeof title === "string" && title.trim().length > 0 ? title : childId,
+            key_requirements: keyRequirements,
+        },
+        allowedScope,
+        validationCommands,
+    };
+}

package/dist/loop/index.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoopCommand = createLoopCommand;
+const commander_1 = require("commander");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const continue_js_1 = require("./continue.js");
+const resume_js_1 = require("./resume.js");
+const status_js_1 = require("./status.js");
+const abort_js_1 = require("./abort.js");
+const dispatch_js_1 = require("./dispatch.js");
+const parent_js_1 = require("./parent.js");
+const run_bootstrap_js_1 = require("./run-bootstrap.js");
+const run_preflight_js_1 = require("./run-preflight.js");
+const evidence_backfill_js_1 = require("./evidence-backfill.js");
+const wait_js_1 = require("./wait.js");
+function defaultStateFile(repoRoot, stateFile) {
+    if (stateFile) {
+        return stateFile;
+    }
+    const newPath = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+    const legacyPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
+    // If the new path exists, use it
+    if ((0, node_fs_1.existsSync)(newPath)) {
+        return newPath;
+    }
+    // If the legacy path exists, use it
+    if ((0, node_fs_1.existsSync)(legacyPath)) {
+        return legacyPath;
+    }
+    // Neither exists, return the new path so callers can create it
+    return newPath;
+}
+function failMissingSubcommand(command, commandName) {
+    const unknownSubcommand = command.args[0];
+    const message = unknownSubcommand
+        ? `error: unknown command '${unknownSubcommand}' for '${commandName}'. Run '${commandName} --help'.`
+        : `error: missing command for '${commandName}'. Run '${commandName} --help'.`;
+    command.error(message, {
+        code: "commander.missingCommand",
+        exitCode: 1,
+    });
+}
+function createLoopCommand(handlers = {}) {
+    const continueHandler = handlers.runLoopContinue ?? continue_js_1.runLoopContinue;
+    const resumeHandler = handlers.runLoopResume ?? resume_js_1.runLoopResume;
+    const statusHandler = handlers.runLoopStatus ?? status_js_1.runLoopStatus;
+    const abortHandler = handlers.runLoopAbort ?? abort_js_1.runLoopAbort;
+    const dispatchHandler = handlers.runLoopDispatch ?? dispatch_js_1.runLoopDispatch;
+    const parentHandler = handlers.runParentLoop ?? parent_js_1.runParentLoop;
+    const bootstrapHandler = handlers.runLoopBootstrapInit ?? run_bootstrap_js_1.runLoopBootstrapInit;
+    const repoRootDefault = handlers.repoRoot ?? process.cwd();
+    const loop = new commander_1.Command("loop")
+        .description("Polaris loop commands: status is safe/read-only; continue is mutating")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    loop.action(() => failMissingSubcommand(loop, "polaris loop"));
+    loop
+        .command("run")
+        .description("mutating: run the automated parent loop for a cluster")
+        .argument("<cluster-id>", "Parent cluster ID")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Path to current-state.json")
+        .option("--adapter <mode>", "Execution adapter: agent-subtask, terminal-cli, ci, ssh, remote-worker, cross-agent")
+        .option("--provider <name>", "AI provider for worker dispatch (e.g. claude, openai, gemini)")
+        .option("--dry-run", "Log dispatches without executing workers")
+        .option("--allow-analyze-children", "Allow analyze-type children to be dispatched (overrides budget.allow_analyze_children)")
+        .action(async (clusterId, options) => {
+        const repoRoot = options.repoRoot;
+        const stateFile = defaultStateFile(repoRoot, options.stateFile);
+        await (0, run_preflight_js_1.ensureClusterRunState)({
+            clusterId,
+            stateFile,
+            repoRoot,
+            bootstrapHandler,
+        });
+        const result = await parentHandler({
+            stateFile,
+            repoRoot,
+            adapter: options.adapter,
+            provider: options.provider,
+            dryRun: options.dryRun,
+            allowAnalyzeChildren: options.allowAnalyzeChildren,
+        });
+        const summary = [
+            `Polaris parent loop halted: ${result.haltReason}`,
+            `Cluster: ${clusterId}`,
+            `Children dispatched: ${result.childrenDispatched}`,
+            result.haltingChild ? `Halting child: ${result.haltingChild}` : undefined,
+            result.message,
+        ].filter((line) => Boolean(line)).join("\n");
+        if (result.haltReason === "cluster-complete") {
+            process.stdout.write(`${summary}
+`);
+            return;
+        }
+        process.stderr.write(`${summary}
+`);
+        process.exit(1);
+    });
+    loop
+        .command("continue")
+        .description("mutating: checkpoint state and generate next-session bootstrap packet; not a smoke test")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Path to current-state.json")
+        .option("--adapter <mode>", "Execution adapter: agent-subtask, terminal-cli, ci, ssh, remote-worker, cross-agent")
+        .option("--provider <provider>", "AI provider for the next worker session (e.g. claude, openai, gemini)")
+        .option("--allow-analyze-children", "Allow analyze-type children to be dispatched (overrides budget.allow_analyze_children)")
+        .action((options) => {
+        const repoRoot = options.repoRoot;
+        const stateFile = defaultStateFile(repoRoot, options.stateFile);
+        continueHandler({ stateFile, repoRoot, adapter: options.adapter, provider: options.provider, allowAnalyzeChildren: options.allowAnalyzeChildren });
+    });
+    loop
+        .command("dispatch")
+        .description("mutating: claim the next open child and emit a compiled WorkerPacket")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--child <id>", "Open child issue ID to dispatch instead of the first open child")
+        .option("--result-file <path>", "Path to write the sealed result file")
+        .action((options) => {
+        dispatchHandler({
+            repoRoot: options.repoRoot,
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+            childId: options.child,
+            resultFile: options.resultFile,
+        });
+    });
+    loop
+        .command("resume [run_id]")
+        .description("mutating: resume from a bootstrap packet after branch/state integrity checks")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .action((runId, options) => {
+        resumeHandler({
+            runId,
+            repoRoot: options.repoRoot,
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+        });
+    });
+    loop
+        .command("status")
+        .description("safe/read-only: print current loop run state summary")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--json", "Emit JSON output instead of human-readable text")
+        .action((options) => {
+        statusHandler({
+            repoRoot: options.repoRoot,
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+            json: options.json,
+        });
+    });
+    loop
+        .command("abort [reason]")
+        .description("mutating: record a blocker, set status to blocked, and halt cleanly")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--child <id>", "Child issue ID the blocker is associated with")
+        .action((reason, options) => {
+        if (!reason) {
+            process.stderr.write("Error: reason is required\n");
+            process.exit(1);
+        }
+        abortHandler({
+            reason,
+            childId: options.child,
+            repoRoot: options.repoRoot,
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+        });
+    });
+    loop
+        .command("bootstrap")
+        .description("mutating: initialize a new run — the ONLY valid way to create run state. " +
+        "Parent sessions may not hand-create current-state.json; this command issues " +
+        "a bootstrap seal that dispatch and run commands verify before proceeding.")
+        .requiredOption("--cluster-id <id>", "Parent cluster issue ID (e.g. POL-100)")
+        .requiredOption("--children <csv>", "Comma-separated ordered list of child issue IDs to execute (e.g. POL-101,POL-102)")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to write current-state.json")
+        .option("--run-id <id>", "Override auto-generated run ID")
+        .option("--session-type <type>", "Session type: analyze | implement (default: implement)", "implement")
+        .option("--max-children <n>", "Max children per dispatch session (default: 1)", "1")
+        .option("--branch <name>", "Git branch for this run")
+        .option("--artifact-dir <path>", "Override artifact directory")
+        .option("--overwrite", "Archive existing state file and start fresh instead of failing")
+        .action((options) => {
+        const openChildren = options.children
+            .split(",")
+            .map((c) => c.trim())
+            .filter(Boolean);
+        const parsedMaxChildren = parseInt(options.maxChildren, 10);
+        const maxChildrenPerSession = Number.isInteger(parsedMaxChildren) && parsedMaxChildren > 0
+            ? parsedMaxChildren
+            : 1;
+        const bootstrapOptions = {
+            clusterId: options.clusterId,
+            runId: options.runId,
+            openChildren,
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+            repoRoot: options.repoRoot,
+            branch: options.branch,
+            sessionType: options.sessionType === "analyze" ? "analyze" : "implement",
+            maxChildrenPerSession,
+            artifactDir: options.artifactDir,
+            overwrite: options.overwrite,
+        };
+        bootstrapHandler(bootstrapOptions);
+    });
+    loop
+        .command("wait")
+        .description("safe/read-only: block until the active child's result file appears (replaces polling loop status)")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--child <id>", "Child ID to wait for (default: active_child from state)")
+        .option("--timeout <ms>", "Timeout in milliseconds (default: 1800000 = 30 min)", "1800000")
+        .option("--poll-interval <ms>", "Poll interval in milliseconds (default: 5000)", "5000")
+        .action((options) => {
+        const timeoutMs = parseInt(options.timeout, 10);
+        const pollIntervalMs = parseInt(options.pollInterval, 10);
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+            process.stderr.write(`Error: --timeout must be a positive integer, got "${options.timeout}"\n`);
+            process.exit(1);
+        }
+        if (!Number.isInteger(pollIntervalMs) || pollIntervalMs <= 0) {
+            process.stderr.write(`Error: --poll-interval must be a positive integer, got "${options.pollInterval}"\n`);
+            process.exit(1);
+        }
+        (0, wait_js_1.runLoopWait)({
+            stateFile: defaultStateFile(options.repoRoot, options.stateFile),
+            repoRoot: options.repoRoot,
+            childId: options.child,
+            timeoutMs,
+            pollIntervalMs,
+        });
+    });
+    loop
+        .command("backfill-evidence")
+        .description("mutating: backfill cluster-state commits/validation from sealed result files for completed children. " +
+        "Rejects placeholder commits. Does not weaken finalize.")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Override path to current-state.json")
+        .option("--dry-run", "Report what would be written without mutating cluster-state.json")
+        .action((options) => {
+        const repoRoot = options.repoRoot;
+        const stateFile = defaultStateFile(repoRoot, options.stateFile);
+        const report = (0, evidence_backfill_js_1.backfillClusterStateEvidence)({ repoRoot, stateFile, dryRun: options.dryRun });
+        const backfilledIds = report.backfilled.map((b) => b.childId);
+        const skippedLines = report.skipped.map((s) => `  SKIP ${s.childId}: ${s.reason}`);
+        if (backfilledIds.length > 0) {
+            process.stdout.write(`Backfilled ${backfilledIds.length} children: ${backfilledIds.join(", ")}\n`);
+            for (const b of report.backfilled) {
+                process.stdout.write(`  OK   ${b.childId}: commit=${b.commit}\n`);
+            }
+        }
+        else {
+            process.stdout.write("No children backfilled.\n");
+        }
+        if (skippedLines.length > 0) {
+            process.stdout.write(skippedLines.join("\n") + "\n");
+        }
+        if (options.dryRun) {
+            process.stdout.write("(dry-run: cluster-state.json not written)\n");
+        }
+        if (report.skipped.length > 0 && backfilledIds.length === 0) {
+            process.exit(1);
+        }
+    });
+    return loop;
+}

package/dist/loop/ledger.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LedgerWriter = exports.DEFAULT_LEDGER_PATH = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.DEFAULT_LEDGER_PATH = ".polaris/runs/ledger.jsonl";
+const TERMINAL_OPEN_RUN_STATUSES = new Set(["complete", "finalized", "canceled"]);
+class LedgerWriter {
+    ledgerPath;
+    constructor(ledgerPath = exports.DEFAULT_LEDGER_PATH) {
+        this.ledgerPath = ledgerPath;
+    }
+    append(event) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.ledgerPath), { recursive: true });
+        (0, node_fs_1.appendFileSync)(this.ledgerPath, `${JSON.stringify(event)}\n`, { encoding: "utf-8", flag: "a" });
+    }
+    readAll() {
+        if (!(0, node_fs_1.existsSync)(this.ledgerPath)) {
+            return [];
+        }
+        const content = (0, node_fs_1.readFileSync)(this.ledgerPath, "utf-8").trim();
+        if (content.length === 0) {
+            return [];
+        }
+        const lines = content.split("\n");
+        const events = [];
+        for (let i = 0; i < lines.length; i++) {
+            try {
+                events.push(JSON.parse(lines[i]));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`Warning: skipping malformed ledger line ${i + 1}: ${msg}\nContent: ${lines[i]}`);
+            }
+        }
+        return events;
+    }
+    queryByIssue(issueId) {
+        return this.readAll().filter((event) => event.cluster_id === issueId);
+    }
+    queryOpenRuns() {
+        const latestByRun = new Map();
+        for (const event of this.readAll()) {
+            latestByRun.set(event.run_id, event);
+        }
+        return Array.from(latestByRun.values()).filter((event) => !TERMINAL_OPEN_RUN_STATUSES.has(event.status));
+    }
+}
+exports.LedgerWriter = LedgerWriter;