legacymaxxing 0.1.0

package/dist/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Typed error: a stable string `code` (asserted in tests) plus a numeric
+ * `exitCode` (what the OS sees). Conversion to a process exit happens ONLY at the
+ * top-level catch in cli.ts. Reserved exit codes:
+ *   1 runtime · 2 invalid usage/preconditions · 3 dirty worktree ·
+ *   4 provider auth/config · 5 provider quota · 6 validation/gate failed ·
+ *   7 lock conflict / external-CLI failure · 8 malformed model output.
+ */
+export class ToolError extends Error {
+    exitCode;
+    code;
+    constructor(message, exitCode = 1, code = "runtime") {
+        super(message);
+        this.name = "ToolError";
+        this.exitCode = exitCode;
+        this.code = code;
+    }
+}
+export function errMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/fs.d.ts

@@ -0,0 +1,8 @@
+import type { ZodType } from "zod";
+export declare function ensureDir(dir: string): Promise<void>;
+/** Atomic write: tmp file + rename, so a crash never leaves a half-written record. */
+export declare function writeJson(path: string, value: unknown): Promise<void>;
+/** Read + schema-validate. Corrupt JSON and schema mismatch BOTH surface as a typed error. */
+export declare function readJson<T>(path: string, schema: ZodType<T>): Promise<T>;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function isDirectory(path: string): Promise<boolean>;

package/dist/fs.js

@@ -0,0 +1,47 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { ToolError } from "./errors.js";
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+/** Atomic write: tmp file + rename, so a crash never leaves a half-written record. */
+export async function writeJson(path, value) {
+    await ensureDir(dirname(path));
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await rename(tmp, path);
+}
+/** Read + schema-validate. Corrupt JSON and schema mismatch BOTH surface as a typed error. */
+export async function readJson(path, schema) {
+    const raw = await readFile(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ToolError(`corrupt state: ${path}`, 1, "malformed-state");
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw new ToolError(`invalid state: ${path}`, 1, "malformed-state");
+    }
+    return result.data;
+}
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,9 @@
+export declare function isGitRepo(root: string): Promise<boolean>;
+export declare function headSha(root: string): Promise<string | null>;
+/**
+ * Paths with uncommitted changes, excluding any under `excludePrefixes` (our own
+ * state dir and the analysis dir, which the agent legitimately writes).
+ */
+export declare function worktreeDirtyPaths(root: string, excludePrefixes: string[]): Promise<string[]>;
+/** Mutating phases require a clean git worktree so a bad rewrite is recoverable. */
+export declare function assertCleanWorktree(root: string, excludePrefixes: string[]): Promise<void>;

package/dist/git.js

@@ -0,0 +1,60 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ToolError } from "./errors.js";
+const exec = promisify(execFile);
+export async function isGitRepo(root) {
+    try {
+        await exec("git", ["-C", root, "rev-parse", "--is-inside-work-tree"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function headSha(root) {
+    try {
+        const { stdout } = await exec("git", ["-C", root, "rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Paths with uncommitted changes, excluding any under `excludePrefixes` (our own
+ * state dir and the analysis dir, which the agent legitimately writes).
+ */
+export async function worktreeDirtyPaths(root, excludePrefixes) {
+    let stdout = "";
+    try {
+        ({ stdout } = await exec("git", ["-C", root, "status", "--porcelain"]));
+    }
+    catch {
+        return [];
+    }
+    const dirty = [];
+    for (const line of stdout.split("\n")) {
+        if (line.length < 4)
+            continue;
+        let path = line.slice(3).trim();
+        const arrow = path.indexOf(" -> ");
+        if (arrow !== -1)
+            path = path.slice(arrow + 4);
+        if (path.length === 0)
+            continue;
+        if (excludePrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)))
+            continue;
+        dirty.push(path);
+    }
+    return dirty;
+}
+/** Mutating phases require a clean git worktree so a bad rewrite is recoverable. */
+export async function assertCleanWorktree(root, excludePrefixes) {
+    if (!(await isGitRepo(root))) {
+        throw new ToolError("mutating phase requires a git repository", 3, "dirty-worktree");
+    }
+    const dirty = await worktreeDirtyPaths(root, excludePrefixes);
+    if (dirty.length > 0) {
+        throw new ToolError(`dirty worktree: ${dirty.slice(0, 5).join(", ")}${dirty.length > 5 ? ", ..." : ""}`, 3, "dirty-worktree");
+    }
+}

package/dist/phases.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The modernization phase state-machine. PHASE_NAMES is a topological order:
+ * `next`/`loop` walk it left to right. Each phase declares its dependencies, its
+ * gate, whether it mutates, and the artifacts the agent is expected to write.
+ *
+ * Adding breadth (a new phase) is a single entry here plus a prompt brief; the
+ * command core never changes.
+ */
+export declare const PHASE_NAMES: readonly ["assess", "map", "extract", "brief", "transform", "reimagine", "harden"];
+export type PhaseName = (typeof PHASE_NAMES)[number];
+export type ArtifactKind = "md" | "mermaid" | "json" | "html" | "dir" | "patch";
+export type ArtifactSpec = {
+    /** Path relative to --root. `module` is only consulted by module-scoped phases. */
+    path: (system: string, module: string | null) => string;
+    kind: ArtifactKind;
+    required: boolean;
+};
+export type PhaseSpec = {
+    name: PhaseName;
+    /** Writes code/files outside analysis state → guarded behind --apply + clean worktree. */
+    mutating: boolean;
+    /** Produces, then waits for a human `gate` decision before it counts as done. */
+    gated: boolean;
+    /** Phases that must be done (validated or gate-approved) before this can run. */
+    dependsOn: PhaseName[];
+    /** Gated phases whose decision must be `approve` before this can run. */
+    requiresApprovedGate: PhaseName[];
+    needsModule: boolean;
+    needsVision: boolean;
+    artifacts: ArtifactSpec[];
+};
+export declare const PHASES: Record<PhaseName, PhaseSpec>;
+export declare function isPhaseName(value: string): value is PhaseName;

package/dist/phases.js

@@ -0,0 +1,112 @@
+/**
+ * The modernization phase state-machine. PHASE_NAMES is a topological order:
+ * `next`/`loop` walk it left to right. Each phase declares its dependencies, its
+ * gate, whether it mutates, and the artifacts the agent is expected to write.
+ *
+ * Adding breadth (a new phase) is a single entry here plus a prompt brief; the
+ * command core never changes.
+ */
+export const PHASE_NAMES = [
+    "assess",
+    "map",
+    "extract",
+    "brief",
+    "transform",
+    "reimagine",
+    "harden",
+];
+const analysis = (file) => (system) => `analysis/${system}/${file}`;
+export const PHASES = {
+    assess: {
+        name: "assess",
+        mutating: false,
+        gated: false,
+        dependsOn: [],
+        requiresApprovedGate: [],
+        needsModule: false,
+        needsVision: false,
+        artifacts: [
+            { path: analysis("ASSESSMENT.md"), kind: "md", required: true },
+            { path: analysis("ARCHITECTURE.mmd"), kind: "mermaid", required: true },
+        ],
+    },
+    map: {
+        name: "map",
+        mutating: false,
+        gated: false,
+        dependsOn: ["assess"],
+        requiresApprovedGate: [],
+        needsModule: false,
+        needsVision: false,
+        artifacts: [
+            { path: analysis("topology.json"), kind: "json", required: true },
+            { path: analysis("TOPOLOGY.html"), kind: "html", required: true },
+            { path: analysis("call-graph.mmd"), kind: "mermaid", required: false },
+        ],
+    },
+    extract: {
+        name: "extract",
+        mutating: false,
+        gated: false,
+        dependsOn: ["assess"],
+        requiresApprovedGate: [],
+        needsModule: false,
+        needsVision: false,
+        artifacts: [
+            { path: analysis("BUSINESS_RULES.md"), kind: "md", required: true },
+            { path: analysis("DATA_OBJECTS.md"), kind: "md", required: false },
+        ],
+    },
+    brief: {
+        name: "brief",
+        mutating: false,
+        gated: true,
+        dependsOn: ["assess", "map", "extract"],
+        requiresApprovedGate: [],
+        needsModule: false,
+        needsVision: false,
+        artifacts: [{ path: analysis("MODERNIZATION_BRIEF.md"), kind: "md", required: true }],
+    },
+    transform: {
+        name: "transform",
+        mutating: true,
+        gated: false,
+        dependsOn: ["brief"],
+        requiresApprovedGate: ["brief"],
+        needsModule: true,
+        needsVision: false,
+        artifacts: [
+            { path: (s, m) => `modernized/${s}/${m ?? "module"}`, kind: "dir", required: true },
+            { path: analysis("TRANSFORMATION_NOTES.md"), kind: "md", required: true },
+        ],
+    },
+    reimagine: {
+        name: "reimagine",
+        mutating: true,
+        gated: false,
+        dependsOn: ["brief"],
+        requiresApprovedGate: ["brief"],
+        needsModule: false,
+        needsVision: true,
+        artifacts: [
+            { path: (s) => `modernized/${s}-reimagined`, kind: "dir", required: true },
+            { path: analysis("AI_NATIVE_SPEC.md"), kind: "md", required: true },
+        ],
+    },
+    harden: {
+        name: "harden",
+        mutating: false,
+        gated: false,
+        dependsOn: ["assess"],
+        requiresApprovedGate: [],
+        needsModule: false,
+        needsVision: false,
+        artifacts: [
+            { path: analysis("SECURITY_FINDINGS.md"), kind: "md", required: true },
+            { path: analysis("security_remediation.patch"), kind: "patch", required: false },
+        ],
+    },
+};
+export function isPhaseName(value) {
+    return PHASE_NAMES.includes(value);
+}

package/dist/prompts.d.ts

@@ -0,0 +1,11 @@
+import { type PhaseName } from "./phases.js";
+import type { StackSeed } from "./detectors/types.js";
+export type PromptContext = {
+    system: string;
+    legacyPath: string;
+    seeds: StackSeed[];
+    module: string | null;
+    vision: string | null;
+};
+/** Deterministic prompt assembly. No model call happens here. */
+export declare function buildPrompt(ctx: PromptContext, phase: PhaseName): string;

package/dist/prompts.js

@@ -0,0 +1,38 @@
+import { PHASES } from "./phases.js";
+const PHASE_BRIEF = {
+    assess: "Inventory the legacy system: languages, size, build system, integrations, technical debt, security posture, and documentation gaps.",
+    map: "Build dependency and topology maps: call graph, data lineage, entry points, dead-end candidates, and the critical-path business flow.",
+    extract: "Mine embedded business rules into Given/When/Then rule cards, each with file:line citations and a confidence rating.",
+    brief: "Synthesize the discovery artifacts into an approval-gated modernization brief: target architecture, phased plan with entry/exit criteria, behavior contract, validation strategy, and open questions.",
+    transform: "Surgically rewrite ONE module (strangler-fig) with characterization tests proving behavior equivalence. Touch only the target module.",
+    reimagine: "Greenfield rebuild from the extracted intent (NOT a structural port), with executable acceptance tests and a knowledge handoff.",
+    harden: "Security-harden the LEGACY system in place-of-record only: OWASP/CWE scan, CVEs, secrets, injection. Produce a reviewable patch — DO NOT apply it.",
+};
+/** Deterministic prompt assembly. No model call happens here. */
+export function buildPrompt(ctx, phase) {
+    const spec = PHASES[phase];
+    const artifactLines = spec.artifacts.map((artifact) => `- ${artifact.path(ctx.system, ctx.module)} (${artifact.kind}${artifact.required ? ", required" : ", optional"})`);
+    const seedLines = ctx.seeds.length > 0
+        ? ctx.seeds.map((seed) => `- ${seed.language}: ${seed.files} files`).join("\n")
+        : "- (no known languages detected by the deterministic scan)";
+    const sections = [
+        `# legacymaxxing phase: ${phase}`,
+        "",
+        PHASE_BRIEF[phase],
+        "",
+        "## Legacy system",
+        `Name: ${ctx.system}`,
+        `Read-only source root: ${ctx.legacyPath}`,
+        "Do NOT modify any file under the legacy source root.",
+        "",
+        "## Detected stacks (deterministic pre-scan)",
+        seedLines,
+        "",
+    ];
+    if (ctx.module)
+        sections.push("## Target module", ctx.module, "");
+    if (ctx.vision)
+        sections.push("## Target vision", ctx.vision, "");
+    sections.push("## Write exactly these artifacts", ...artifactLines, "", "## Final output", "After writing the artifacts, emit as the FINAL line a single JSON object (and nothing after it):", '{"summary": string, "artifacts": [{"path": string, "kind": "md|mermaid|json|html|dir|patch"}], "notes": string | null}');
+    return sections.join("\n");
+}

package/dist/provider.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { PhaseName } from "./phases.js";
+import { type PhaseOutput } from "./types.js";
+export type ProviderOptions = {
+    model: string | null;
+    noInput: boolean;
+};
+export type RunPhaseArgs = {
+    root: string;
+    system: string;
+    phase: PhaseName;
+    prompt: string;
+    mutating: boolean;
+    module: string | null;
+    vision: string | null;
+    options: ProviderOptions;
+};
+export type Provider = {
+    name: string;
+    /** Verify the provider CLI is present + authed. Returns a human-readable detail. */
+    check(root: string): Promise<string>;
+    /** Run one phase. Returns raw `unknown` — parsed only at the boundary below. */
+    runPhase(args: RunPhaseArgs): Promise<unknown>;
+};
+export declare function formatZodError(error: z.ZodError): string;
+/** THE single boundary. All model output is `unknown` until it passes here. */
+export declare function parseOrThrow<T>(schema: z.ZodType<T>, input: unknown, label: string): T;
+/**
+ * Partition a phase output: a fundamentally wrong container throws
+ * malformed-output (8); individual bad artifact items are dropped, not fatal.
+ */
+export declare function partitionArtifacts(raw: unknown, label: string): {
+    output: PhaseOutput;
+    dropped: number;
+};
+export declare function providerByName(name: string): Provider;

package/dist/provider.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { ToolError } from "./errors.js";
+import { phaseOutputArtifactSchema } from "./types.js";
+import { codexProvider } from "./providers/codex.js";
+import { mockProvider } from "./providers/mock.js";
+export function formatZodError(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+        .join("; ");
+}
+/** THE single boundary. All model output is `unknown` until it passes here. */
+export function parseOrThrow(schema, input, label) {
+    const result = schema.safeParse(input);
+    if (result.success)
+        return result.data;
+    throw new ToolError(`${label}: ${formatZodError(result.error)}`, 8, "malformed-output");
+}
+const containerSchema = z.object({
+    summary: z.string(),
+    artifacts: z.array(z.unknown()),
+    notes: z.string().nullable(),
+});
+/**
+ * Partition a phase output: a fundamentally wrong container throws
+ * malformed-output (8); individual bad artifact items are dropped, not fatal.
+ */
+export function partitionArtifacts(raw, label) {
+    const container = parseOrThrow(containerSchema, raw, label);
+    const kept = [];
+    let dropped = 0;
+    for (const item of container.artifacts) {
+        const result = phaseOutputArtifactSchema.safeParse(item);
+        if (result.success)
+            kept.push(result.data);
+        else
+            dropped += 1;
+    }
+    return {
+        output: { summary: container.summary, artifacts: kept, notes: container.notes },
+        dropped,
+    };
+}
+export function providerByName(name) {
+    switch (name) {
+        case "codex":
+            return codexProvider;
+        case "mock":
+            return mockProvider;
+        default:
+            throw new ToolError(`unsupported provider: ${name}`, 2, "unsupported-provider");
+    }
+}

package/dist/providers/codex.d.ts

@@ -0,0 +1,11 @@
+import type { Provider } from "../provider.js";
+/**
+ * The first real provider: shells out to the `codex` CLI. Read-only sandbox by
+ * default; only mutating phases get `workspace-write`. Auth/quota are detected
+ * from output and mapped to exit codes 4/5.
+ *
+ * NOTE: this path is not exercised in CI (the `mock` provider covers the
+ * pipeline). The exact `codex exec` flags may need tuning against your installed
+ * codex version — see README.
+ */
+export declare const codexProvider: Provider;

package/dist/providers/codex.js

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ToolError, errMessage } from "../errors.js";
+const exec = promisify(execFile);
+/**
+ * The first real provider: shells out to the `codex` CLI. Read-only sandbox by
+ * default; only mutating phases get `workspace-write`. Auth/quota are detected
+ * from output and mapped to exit codes 4/5.
+ *
+ * NOTE: this path is not exercised in CI (the `mock` provider covers the
+ * pipeline). The exact `codex exec` flags may need tuning against your installed
+ * codex version — see README.
+ */
+export const codexProvider = {
+    name: "codex",
+    check: async (root) => {
+        try {
+            const { stdout } = await exec("codex", ["--version"], { cwd: root });
+            return stdout.trim() || "codex available";
+        }
+        catch (error) {
+            throw new ToolError(`codex CLI not found or not runnable: ${errMessage(error)}`, 4, "provider-auth");
+        }
+    },
+    runPhase: async (args) => {
+        const sandbox = args.mutating ? "workspace-write" : "read-only";
+        const cmdArgs = ["exec", "--json", "--sandbox", sandbox];
+        if (args.options.model)
+            cmdArgs.push("--model", args.options.model);
+        cmdArgs.push(args.prompt);
+        let stdout = "";
+        try {
+            ({ stdout } = await exec("codex", cmdArgs, {
+                cwd: args.root,
+                maxBuffer: 64 * 1024 * 1024,
+            }));
+        }
+        catch (error) {
+            const text = errMessage(error);
+            if (/auth|login|unauthor/iu.test(text)) {
+                throw new ToolError(`codex auth failure: ${text}`, 4, "provider-auth");
+            }
+            if (/quota|rate.?limit|\b429\b/iu.test(text)) {
+                throw new ToolError(`codex quota/rate-limit: ${text}`, 5, "provider-quota");
+            }
+            throw new ToolError(`codex invocation failed: ${text}`, 7, "external-cli");
+        }
+        return extractManifest(stdout);
+    },
+};
+/** Find the last line that parses as a JSON object — the phase output manifest. */
+function extractManifest(stdout) {
+    const trimmed = stdout.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // fall through to line scan
+    }
+    const lines = trimmed.split("\n");
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (!line || !line.startsWith("{"))
+            continue;
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            // keep scanning earlier lines
+        }
+    }
+    throw new ToolError("codex produced no parseable JSON manifest", 8, "malformed-output");
+}

package/dist/providers/mock.d.ts

@@ -0,0 +1,8 @@
+import type { Provider } from "../provider.js";
+/**
+ * Deterministic, network-free provider. It "does the agent's work" by writing a
+ * minimal-but-valid artifact for every expected output of the phase, then
+ * returning a well-formed manifest — so the whole pipeline (assemble → run →
+ * boundary parse → validate → record) is testable end to end.
+ */
+export declare const mockProvider: Provider;

package/dist/providers/mock.js

@@ -0,0 +1,52 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { PHASES } from "../phases.js";
+/**
+ * Deterministic, network-free provider. It "does the agent's work" by writing a
+ * minimal-but-valid artifact for every expected output of the phase, then
+ * returning a well-formed manifest — so the whole pipeline (assemble → run →
+ * boundary parse → validate → record) is testable end to end.
+ */
+export const mockProvider = {
+    name: "mock",
+    check: async () => "mock provider ready",
+    runPhase: async (args) => {
+        const spec = PHASES[args.phase];
+        const artifacts = [];
+        for (const artifact of spec.artifacts) {
+            const rel = artifact.path(args.system, args.module);
+            await writeArtifact(args.root, rel, artifact.kind, args);
+            artifacts.push({ path: rel, kind: artifact.kind });
+        }
+        return {
+            summary: `mock ${args.phase} for ${args.system}`,
+            artifacts,
+            notes: null,
+        };
+    },
+};
+async function writeArtifact(root, rel, kind, args) {
+    const abs = join(root, rel);
+    if (kind === "dir") {
+        await mkdir(abs, { recursive: true });
+        await writeFile(join(abs, "README.md"), `# ${args.system} (mock ${args.phase})\n`, "utf8");
+        await writeFile(join(abs, "acceptance.test.txt"), "mock characterization test\n", "utf8");
+        return;
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, bodyFor(kind, args), "utf8");
+}
+function bodyFor(kind, args) {
+    switch (kind) {
+        case "json":
+            return `${JSON.stringify({ system: args.system, phase: args.phase, mock: true }, null, 2)}\n`;
+        case "mermaid":
+            return "graph TD;\n  Legacy-->Modern;\n";
+        case "html":
+            return `<!doctype html><title>${args.system} ${args.phase}</title><body>mock</body>\n`;
+        case "patch":
+            return "--- a/legacy\n+++ b/legacy\n@@ -0,0 +1 @@\n+mock remediation (review before applying)\n";
+        default:
+            return `# ${args.system} — ${args.phase}\n\nGenerated by the mock provider.\n`;
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,16 @@
+export type StatePaths = {
+    stateDir: string;
+    config: string;
+    project: string;
+    phases: string;
+    runs: string;
+    locks: string;
+};
+export declare function statePaths(stateDir: string): StatePaths;
+export declare function phaseRecordPath(stateDir: string, system: string, phase: string): string;
+export declare function runRecordPath(stateDir: string, runId: string): string;
+export declare function lockPath(stateDir: string, system: string, phase: string): string;
+/** Exclusive-create lock; EEXIST → lock-conflict (7). Enables future --jobs N. */
+export declare function claim(path: string, runId: string): Promise<void>;
+export declare function release(path: string): Promise<void>;
+export declare function listLocks(stateDir: string): Promise<string[]>;

package/dist/state.js

@@ -0,0 +1,54 @@
+import { open, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ToolError } from "./errors.js";
+import { ensureDir } from "./fs.js";
+export function statePaths(stateDir) {
+    return {
+        stateDir,
+        config: join(stateDir, "config.json"),
+        project: join(stateDir, "project.json"),
+        phases: join(stateDir, "phases"),
+        runs: join(stateDir, "runs"),
+        locks: join(stateDir, "locks"),
+    };
+}
+export function phaseRecordPath(stateDir, system, phase) {
+    return join(stateDir, "phases", system, `${phase}.json`);
+}
+export function runRecordPath(stateDir, runId) {
+    return join(stateDir, "runs", `${runId}.json`);
+}
+export function lockPath(stateDir, system, phase) {
+    return join(stateDir, "locks", `${system}-${phase}.json`);
+}
+/** Exclusive-create lock; EEXIST → lock-conflict (7). Enables future --jobs N. */
+export async function claim(path, runId) {
+    await ensureDir(dirname(path));
+    try {
+        const fd = await open(path, "wx");
+        await fd.writeFile(JSON.stringify({
+            lockedByRunId: runId,
+            lockedAt: new Date().toISOString(),
+            pid: process.pid,
+        }));
+        await fd.close();
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new ToolError(`phase locked: ${path}`, 7, "lock-conflict");
+        }
+        throw error;
+    }
+}
+export async function release(path) {
+    await rm(path, { force: true });
+}
+export async function listLocks(stateDir) {
+    try {
+        const entries = await readdir(join(stateDir, "locks"));
+        return entries.filter((name) => name.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+}