@velum-labs/routekit-harness-core 0.9.0

package/dist/test/harness-core.test.js

@@ -0,0 +1,259 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { z } from "zod";
+import { DriverRegistry, EventLog, HarnessError, PendingRequests, asHarnessError, createCachedHarnessDriver, createStreamJsonStepEmitter, createTrackedTmpDir, decideApproval, parseStreamJsonTrajectory, probeCliVersion, readCachedStatus, releaseTrackedTmpDir, resolveDriverEnv, statusSkipReason, streamJsonResultContentText, sweepTrackedTmpDirs, writeCachedStatus } from "../index.js";
+import { createMockDriver, driverContractSuite } from "../testing/index.js";
+// The mock driver is the reference implementation: it must pass the same
+// contract suite every real driver is held against.
+driverContractSuite({
+    name: "mock driver",
+    createInstance: async () => {
+        const driver = createMockDriver();
+        return driver.createInstance(driver.configSchema.parse({}));
+    },
+    startOptions: () => ({ cwd: process.cwd() }),
+    supportsResume: true
+});
+test("shared stream JSON primitives normalize incremental and buffered events", () => {
+    const stepsForEvent = (event) => event.type === "message" && typeof event.text === "string"
+        ? [{ kind: "message", text: event.text }]
+        : [];
+    const resultStep = (result) => ({ kind: "result", text: result });
+    const emitted = [];
+    const emit = createStreamJsonStepEmitter({ stepsForEvent, resultStep, onStep: (step) => emitted.push(step) });
+    emit('{"type":"message","text":"hello"}');
+    emit('{"type":"result","result":"done"}');
+    assert.deepEqual(emitted, [
+        { index: 0, kind: "message", text: "hello" },
+        { index: 1, kind: "result", text: "done" }
+    ]);
+    const parsed = parseStreamJsonTrajectory({
+        stdout: '{"type":"message","text":"hello"}\n' +
+            '{"type":"result","result":"done","is_error":false}\n',
+        stepsForEvent,
+        resultStep
+    });
+    assert.equal(parsed.finalOutput, "done");
+    assert.equal(parsed.sawResult, true);
+    assert.equal(parsed.isError, false);
+    assert.equal(streamJsonResultContentText([{ type: "text", text: "a" }, { type: "text", text: "b" }]), "ab");
+});
+test("registry decodes config exactly once and classifies failures", async () => {
+    const registry = new DriverRegistry().register(createMockDriver());
+    const instance = await registry.createInstance("generic", { replies: ["hi"] });
+    assert.equal(instance.kind, "generic");
+    await instance.dispose();
+    await assert.rejects(registry.createInstance("generic", { replies: "not-an-array" }), (error) => error.code === "invalid_config");
+    await assert.rejects(registry.createInstance("codex", {}), (error) => error.code === "invalid_config");
+    assert.throws(() => registry.register(createMockDriver()), /already registered/);
+});
+test("error taxonomy derives retryability and category", () => {
+    const timeout = new HarnessError("timeout", "deadline exceeded");
+    assert.equal(timeout.retryable, true);
+    assert.equal(timeout.category, "transient");
+    const auth = new HarnessError("not_authenticated", "run codex login");
+    assert.equal(auth.retryable, false);
+    assert.equal(auth.category, "auth_permanent");
+    const quota = new HarnessError("provider_error", "out of credits", {
+        category: "quota_exhausted"
+    });
+    assert.equal(quota.retryable, true);
+    const enoent = asHarnessError(Object.assign(new Error("spawn codex ENOENT"), { code: "ENOENT" }));
+    assert.equal(enoent.code, "not_installed");
+});
+test("approvals: policy verdicts and teardown settlement", async () => {
+    assert.equal(decideApproval({ autoApprove: "all" }, "exec_command_approval"), "accept");
+    assert.equal(decideApproval({ autoApprove: "all" }, "tool_user_input"), undefined);
+    assert.equal(decideApproval({ autoApprove: "edits" }, "file_change_approval"), "accept");
+    assert.equal(decideApproval({ autoApprove: "edits" }, "exec_command_approval"), undefined);
+    assert.equal(decideApproval({ autoApprove: "none" }, "file_change_approval"), undefined);
+    const pending = new PendingRequests();
+    const first = pending.open({ requestType: "exec_command_approval", detail: "rm -rf" });
+    const second = pending.open({ requestType: "tool_user_input" });
+    assert.equal(pending.resolve(first.requestId, "decline"), true);
+    assert.equal(await first.decision, "decline");
+    assert.equal(pending.resolve(first.requestId, "accept"), false);
+    assert.equal(pending.settleAll("cancel"), 1);
+    assert.equal(await second.decision, "cancel");
+});
+test("status cache round-trips and rejects identity mismatches", () => {
+    const dir = mkdtempSync(join(tmpdir(), "harness-status-"));
+    try {
+        const status = {
+            kind: "codex",
+            installed: true,
+            command: "codex",
+            version: "0.99.0",
+            auth: { status: "authenticated" },
+            checkedAt: new Date().toISOString()
+        };
+        writeCachedStatus(status, dir);
+        assert.deepEqual(readCachedStatus("codex", dir), status);
+        // The payload's kind, not the filename, is the routing key.
+        assert.equal(readCachedStatus("cursor", dir), undefined);
+        assert.equal(statusSkipReason(status), undefined);
+        assert.match(statusSkipReason({ ...status, auth: { status: "unauthenticated" } }) ?? "", /not logged in/);
+        assert.match(statusSkipReason({ ...status, installed: false }) ?? "", /not installed/);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("driver env resolution honors an explicit context without merging", () => {
+    const env = { PATH: "/custom/bin", ROUTEKIT_TEST_TOKEN: "secret" };
+    assert.equal(resolveDriverEnv({ env }), env);
+    assert.equal(resolveDriverEnv(undefined), process.env);
+});
+test("CLI version probing normalizes success and failures", async () => {
+    const probed = await probeCliVersion({
+        kind: "generic",
+        command: process.execPath,
+        cliName: "node",
+        args: ["-e", 'process.stdout.write("tool 1.2.3\\n")'],
+        env: {},
+        auth: { status: "unknown" },
+        notInstalledMessage: "node missing"
+    });
+    assert.equal(probed.installed, true);
+    assert.equal(probed.version, "1.2.3");
+    const failed = await probeCliVersion({
+        kind: "generic",
+        command: process.execPath,
+        cliName: "node",
+        args: ["-e", 'process.stderr.write("bad version probe\\n"); process.exit(7)'],
+        env: {},
+        auth: { status: "authenticated" },
+        failureAuth: { status: "unauthenticated" },
+        notInstalledMessage: "node missing"
+    });
+    assert.equal(failed.installed, false);
+    assert.equal(failed.auth.status, "unauthenticated");
+    assert.equal(failed.probeError, "bad version probe");
+    const missing = await probeCliVersion({
+        kind: "generic",
+        command: join(tmpdir(), `missing-cli-${process.pid}`),
+        cliName: "missing",
+        env: {},
+        auth: { status: "authenticated" },
+        notInstalledAuth: { status: "unknown" },
+        notInstalledMessage: "missing CLI is not installed"
+    });
+    assert.equal(missing.installed, false);
+    assert.equal(missing.auth.status, "unknown");
+    assert.equal(missing.probeError, "missing CLI is not installed");
+});
+test("cached driver construction reuses status written by probe", async () => {
+    const cacheDir = mkdtempSync(join(tmpdir(), "harness-driver-cache-"));
+    let probeCount = 0;
+    const status = {
+        kind: "generic",
+        installed: true,
+        command: "tool",
+        version: "1.0.0",
+        auth: { status: "authenticated" },
+        checkedAt: new Date().toISOString()
+    };
+    const instance = {
+        kind: "generic",
+        status: () => status,
+        startSession: async () => {
+            throw new Error("not used");
+        },
+        dispose: async () => { }
+    };
+    let instanceStatus;
+    const driver = createCachedHarnessDriver({
+        kind: "generic",
+        configSchema: z.object({ command: z.string().default("tool") }),
+        probeConfig: () => ({ command: "tool" }),
+        probeStatus: async () => {
+            probeCount += 1;
+            return status;
+        },
+        createInstance: (_config, _context, cachedStatus) => {
+            instanceStatus = cachedStatus;
+            return instance;
+        }
+    });
+    try {
+        await driver.probe({ statusCacheDir: cacheDir });
+        const created = await driver.createInstance(driver.configSchema.parse({}), { statusCacheDir: cacheDir });
+        assert.equal(created, instance);
+        assert.deepEqual(instanceStatus, status);
+        assert.equal(probeCount, 1);
+    }
+    finally {
+        rmSync(cacheDir, { recursive: true, force: true });
+    }
+});
+test("mock session surfaces approvals under autoApprove none and resolves them", async () => {
+    const driver = createMockDriver();
+    const instance = await driver.createInstance(driver.configSchema.parse({ approvalDetail: "npm test", replies: ["done"] }));
+    const session = await instance.startSession({
+        cwd: process.cwd(),
+        approvalPolicy: { autoApprove: "none" }
+    });
+    const events = [];
+    for await (const event of session.sendTurn({ prompt: "run tests" })) {
+        events.push(event);
+        if (event.type === "request.opened") {
+            await session.respondToRequest(event.requestId, "accept");
+        }
+    }
+    const types = events.map((event) => event.type);
+    assert.deepEqual(types, [
+        "turn.started",
+        "request.opened",
+        "request.resolved",
+        "content.delta",
+        "turn.completed"
+    ]);
+    await instance.dispose();
+});
+test("EventLog writes NDJSON per session and summarizes raw payloads", () => {
+    const dir = mkdtempSync(join(tmpdir(), "harness-log-"));
+    try {
+        const log = new EventLog({ dir });
+        log.write({
+            kind: "codex",
+            sessionId: "sess/1",
+            at: new Date().toISOString(),
+            type: "content.delta",
+            stream: "assistant_text",
+            text: "hi",
+            raw: { source: "codex.exec.json", method: "item.completed", payload: { a: 1, b: 2 } }
+        });
+        const contents = readFileSync(join(dir, "sess_1.ndjson"), "utf8").trim();
+        const parsed = JSON.parse(contents);
+        assert.equal(parsed.type, "content.delta");
+        // The raw payload is summarized to a shape, never written whole.
+        assert.equal(parsed.raw.source, "codex.exec.json");
+        assert.equal(parsed.raw.payload.fields, 2);
+        assert.ok(parsed.raw.payload.bytes > 0);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("tracked temp dirs are swept after a simulated crash", () => {
+    const manifestDir = mkdtempSync(join(tmpdir(), "harness-manifest-"));
+    const manifest = join(manifestDir, "tmp-manifest.json");
+    try {
+        const leaked = createTrackedTmpDir("harness-sweep-", manifest);
+        const kept = createTrackedTmpDir("harness-sweep-", manifest);
+        // A clean release drops one entry; the other is "leaked" by a crash.
+        releaseTrackedTmpDir(kept, manifest);
+        assert.equal(existsSync(kept), false);
+        assert.equal(existsSync(leaked), true);
+        const swept = sweepTrackedTmpDirs(manifest);
+        assert.deepEqual(swept, [leaked]);
+        assert.equal(existsSync(leaked), false);
+        assert.deepEqual(sweepTrackedTmpDirs(manifest), []);
+    }
+    finally {
+        rmSync(manifestDir, { recursive: true, force: true });
+    }
+});

package/dist/testing/contract-suite.d.ts

@@ -0,0 +1,22 @@
+import type { HarnessInstance, StartSessionOptions } from "../contract.js";
+export type DriverContractSuiteInput = {
+    /** Suite label, e.g. "codex driver". */
+    name: string;
+    /** Fresh instance per test; disposed by the suite. */
+    createInstance: () => Promise<HarnessInstance>;
+    /** Session options valid for this driver (cwd usually a temp repo). */
+    startOptions: () => StartSessionOptions;
+    prompt?: string;
+    /** Set when the driver supports native resume; enables the resume test. */
+    supportsResume?: boolean;
+    /** Upper bound for a scripted turn to settle (default 30s). */
+    turnTimeoutMs?: number;
+    /** Skip reason (e.g. CLI not installed locally); tests report skipped, never silently pass. */
+    skip?: string | false;
+};
+/**
+ * The invariants every harness driver must satisfy, executed as node:test
+ * tests. Drivers register their own scripted fixtures (fake CLI binaries or
+ * scripted transports) and hand the suite a fresh instance per test.
+ */
+export declare function driverContractSuite(input: DriverContractSuiteInput): void;

package/dist/testing/contract-suite.js

@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+async function collect(events, timeoutMs) {
+    const out = [];
+    const deadline = new Error(`turn did not settle within ${timeoutMs}ms`);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(deadline), timeoutMs);
+    });
+    try {
+        const iterator = events[Symbol.asyncIterator]();
+        for (;;) {
+            const next = await Promise.race([iterator.next(), timeout]);
+            if (next.done === true)
+                break;
+            out.push(next.value);
+        }
+        return out;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * The invariants every harness driver must satisfy, executed as node:test
+ * tests. Drivers register their own scripted fixtures (fake CLI binaries or
+ * scripted transports) and hand the suite a fresh instance per test.
+ */
+export function driverContractSuite(input) {
+    const timeoutMs = input.turnTimeoutMs ?? 30_000;
+    const prompt = input.prompt ?? "Reply with OK.";
+    const skip = input.skip ?? false;
+    test(`${input.name}: a scripted turn completes with canonical events`, { skip }, async () => {
+        const instance = await input.createInstance();
+        try {
+            const session = await instance.startSession(input.startOptions());
+            const events = await collect(session.sendTurn({ prompt }), timeoutMs);
+            const types = events.map((event) => event.type);
+            assert.ok(types.includes("turn.started"), `turn.started missing in ${types.join(",")}`);
+            const completed = events.find((event) => event.type === "turn.completed");
+            assert.ok(completed, `turn.completed missing in ${types.join(",")}`);
+            assert.equal(completed.endReason, "completed");
+            assert.ok(events.every((event) => event.sessionId === session.sessionId), "every event carries the session id");
+            await session.stop();
+        }
+        finally {
+            await instance.dispose();
+        }
+    });
+    test(`${input.name}: an aborted turn settles as aborted, never hangs`, { skip }, async () => {
+        const instance = await input.createInstance();
+        try {
+            const session = await instance.startSession(input.startOptions());
+            const events = await collect(session.sendTurn({ prompt, signal: AbortSignal.abort(new Error("straggler_abandoned")) }), timeoutMs);
+            const terminal = events.at(-1);
+            assert.ok(terminal, "an aborted turn still yields events");
+            assert.ok((terminal.type === "turn.completed" &&
+                (terminal.endReason === "aborted" || terminal.endReason === "interrupted")) ||
+                terminal.type === "turn.failed", `terminal event must record the abort, got ${terminal.type}`);
+            await session.stop();
+        }
+        finally {
+            await instance.dispose();
+        }
+    });
+    test(`${input.name}: stop settles pending approvals (nothing hangs)`, { skip }, async () => {
+        const instance = await input.createInstance();
+        try {
+            const session = await instance.startSession(input.startOptions());
+            // Consume the stream concurrently; stop() must let it terminate even
+            // if the driver opened approvals that were never answered.
+            const collecting = collect(session.sendTurn({ prompt }), timeoutMs);
+            await session.stop();
+            await collecting.catch(() => undefined);
+        }
+        finally {
+            await instance.dispose();
+        }
+    });
+    if (input.supportsResume === true) {
+        test(`${input.name}: resume cursor round-trips into a new session`, { skip }, async () => {
+            const instance = await input.createInstance();
+            try {
+                const first = await instance.startSession(input.startOptions());
+                await collect(first.sendTurn({ prompt }), timeoutMs);
+                const cursor = first.resumeCursor();
+                assert.ok(cursor, "driver advertises resume but produced no cursor");
+                await first.stop();
+                const resumed = await instance.startSession({ ...input.startOptions(), resume: cursor });
+                assert.equal(resumed.sessionId, first.sessionId, "resume restores the session identity");
+                await resumed.stop();
+            }
+            finally {
+                await instance.dispose();
+            }
+        });
+    }
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { createMockDriver, mockDriverConfigSchema } from "./mock-driver.js";
+export type { MockDriverConfig } from "./mock-driver.js";
+export { driverContractSuite } from "./contract-suite.js";
+export type { DriverContractSuiteInput } from "./contract-suite.js";

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+export { createMockDriver, mockDriverConfigSchema } from "./mock-driver.js";
+export { driverContractSuite } from "./contract-suite.js";

package/dist/testing/mock-driver.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { HarnessDriver } from "../contract.js";
+export declare const mockDriverConfigSchema: z.ZodObject<{
+    replies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    approvalDetail: z.ZodOptional<z.ZodString>;
+    installed: z.ZodDefault<z.ZodBoolean>;
+    authenticated: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type MockDriverConfig = z.infer<typeof mockDriverConfigSchema>;
+/**
+ * A fully in-memory driver implementing the whole contract: scripted replies,
+ * approvals, resume cursors, abort handling. The fixture for registry and
+ * consumer tests, and the reference implementation drivers are held against.
+ */
+export declare function createMockDriver(): HarnessDriver<MockDriverConfig>;

package/dist/testing/mock-driver.js

@@ -0,0 +1,154 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { HarnessError } from "../errors.js";
+import { DEFAULT_AUTOMATION_APPROVAL_POLICY, PendingRequests, decideApproval } from "../approvals.js";
+export const mockDriverConfigSchema = z.object({
+    /** Scripted assistant replies, consumed one per turn (last one repeats). */
+    replies: z.array(z.string()).default(["mock reply"]),
+    /** When set, every `sendTurn` opens one approval of this detail first. */
+    approvalDetail: z.string().optional(),
+    installed: z.boolean().default(true),
+    authenticated: z.boolean().default(true)
+});
+function nowIso() {
+    return new Date().toISOString();
+}
+function statusFor(config) {
+    return {
+        kind: "generic",
+        installed: config.installed,
+        ...(config.installed ? { command: "mock-cli", version: "1.0.0" } : {}),
+        auth: { status: config.authenticated ? "authenticated" : "unauthenticated" },
+        checkedAt: nowIso()
+    };
+}
+class MockSession {
+    sessionId;
+    #config;
+    #pending = new PendingRequests();
+    #approvalPolicy;
+    #turnCount;
+    #stopped = false;
+    constructor(config, options) {
+        this.#config = config;
+        this.#approvalPolicy = options.approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY;
+        if (options.resume !== undefined) {
+            const data = options.resume.data;
+            this.sessionId = data.sessionId ?? randomUUID();
+            this.#turnCount = data.turnCount ?? 0;
+        }
+        else {
+            this.sessionId = randomUUID();
+            this.#turnCount = 0;
+        }
+    }
+    async *sendTurn(input) {
+        if (this.#stopped) {
+            throw new HarnessError("session_closed", "mock session is stopped");
+        }
+        const base = { kind: "generic", sessionId: this.sessionId, at: nowIso() };
+        const turnId = `turn_${this.#turnCount + 1}`;
+        yield { ...base, type: "turn.started", turnId };
+        if (input.signal?.aborted === true) {
+            yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
+            return;
+        }
+        if (this.#config.approvalDetail !== undefined) {
+            const auto = decideApproval(this.#approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY, "exec_command_approval");
+            if (auto === undefined) {
+                const request = this.#pending.open({
+                    requestType: "exec_command_approval",
+                    detail: this.#config.approvalDetail
+                });
+                yield {
+                    ...base,
+                    type: "request.opened",
+                    turnId,
+                    requestId: request.requestId,
+                    requestType: request.requestType,
+                    ...(request.detail !== undefined ? { detail: request.detail } : {})
+                };
+                const decision = await Promise.race([
+                    request.decision,
+                    abortAsDecision(input.signal)
+                ]);
+                yield { ...base, type: "request.resolved", turnId, requestId: request.requestId, decision };
+                if (decision === "decline" || decision === "cancel") {
+                    yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
+                    return;
+                }
+            }
+        }
+        const reply = this.#config.replies[Math.min(this.#turnCount, this.#config.replies.length - 1)] ??
+            "mock reply";
+        this.#turnCount += 1;
+        yield { ...base, type: "content.delta", turnId, stream: "assistant_text", text: reply };
+        yield { ...base, type: "turn.completed", turnId, endReason: "completed" };
+    }
+    async respondToRequest(requestId, decision) {
+        if (!this.#pending.resolve(requestId, decision)) {
+            throw new HarnessError("protocol_parse", `unknown pending request ${requestId}`);
+        }
+    }
+    async interrupt() {
+        this.#pending.settleAll("cancel");
+    }
+    resumeCursor() {
+        return {
+            version: 1,
+            kind: "generic",
+            data: { sessionId: this.sessionId, turnCount: this.#turnCount }
+        };
+    }
+    async stop() {
+        this.#stopped = true;
+        this.#pending.settleAll("cancel");
+    }
+}
+class MockInstance {
+    kind = "generic";
+    #config;
+    #sessions = new Set();
+    constructor(config) {
+        this.#config = config;
+    }
+    status() {
+        return statusFor(this.#config);
+    }
+    async startSession(options) {
+        if (!this.#config.installed) {
+            throw new HarnessError("not_installed", "mock CLI is not installed");
+        }
+        if (!this.#config.authenticated) {
+            throw new HarnessError("not_authenticated", "mock CLI is not logged in");
+        }
+        const session = new MockSession(this.#config, options);
+        this.#sessions.add(session);
+        return session;
+    }
+    async dispose() {
+        for (const session of this.#sessions)
+            await session.stop();
+        this.#sessions.clear();
+    }
+}
+function abortAsDecision(signal) {
+    if (signal === undefined)
+        return new Promise(() => undefined);
+    if (signal.aborted)
+        return Promise.resolve("cancel");
+    return new Promise((resolve) => signal.addEventListener("abort", () => resolve("cancel"), { once: true }));
+}
+/**
+ * A fully in-memory driver implementing the whole contract: scripted replies,
+ * approvals, resume cursors, abort handling. The fixture for registry and
+ * consumer tests, and the reference implementation drivers are held against.
+ */
+export function createMockDriver() {
+    return {
+        kind: "generic",
+        configSchema: mockDriverConfigSchema,
+        probe: async (_context) => statusFor(mockDriverConfigSchema.parse({})),
+        createInstance: async (config, _context) => new MockInstance(config)
+    };
+}

package/dist/tmp-sweep.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A crash-safe registry of temp directories a harness created (ephemeral CLI
+ * homes, worktrees). Each is recorded before use and removed on normal
+ * cleanup; anything still recorded at the next process start is swept, so a
+ * crash between creation and cleanup cannot leak dirs (or credentials) in
+ * /tmp forever.
+ */
+export declare const DEFAULT_TMP_MANIFEST: string;
+/** Create a tracked temp dir under `tmpdir()`, recorded in the manifest. */
+export declare function createTrackedTmpDir(prefix: string, manifestPath?: string): string;
+/** Remove a tracked temp dir and drop it from the manifest. */
+export declare function releaseTrackedTmpDir(dir: string, manifestPath?: string): void;
+/**
+ * Remove every temp dir still recorded in the manifest (leaked by a prior
+ * crash) and clear it. Returns the paths swept. Call once at CLI start.
+ */
+export declare function sweepTrackedTmpDirs(manifestPath?: string): string[];

package/dist/tmp-sweep.js

@@ -0,0 +1,61 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * A crash-safe registry of temp directories a harness created (ephemeral CLI
+ * homes, worktrees). Each is recorded before use and removed on normal
+ * cleanup; anything still recorded at the next process start is swept, so a
+ * crash between creation and cleanup cannot leak dirs (or credentials) in
+ * /tmp forever.
+ */
+export const DEFAULT_TMP_MANIFEST = join(homedir(), ".routekit", "tmp-manifest.json");
+function readManifest(manifestPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeManifest(manifestPath, entries) {
+    try {
+        mkdirSync(dirname(manifestPath), { recursive: true });
+        writeFileSync(manifestPath, `${JSON.stringify({ entries }, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort: a manifest write failure must not break the run.
+    }
+}
+/** Create a tracked temp dir under `tmpdir()`, recorded in the manifest. */
+export function createTrackedTmpDir(prefix, manifestPath = DEFAULT_TMP_MANIFEST) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    const entries = readManifest(manifestPath);
+    entries.push({ path: dir, createdAt: new Date().toISOString() });
+    writeManifest(manifestPath, entries);
+    return dir;
+}
+/** Remove a tracked temp dir and drop it from the manifest. */
+export function releaseTrackedTmpDir(dir, manifestPath = DEFAULT_TMP_MANIFEST) {
+    rmSync(dir, { recursive: true, force: true });
+    writeManifest(manifestPath, readManifest(manifestPath).filter((entry) => entry.path !== dir));
+}
+/**
+ * Remove every temp dir still recorded in the manifest (leaked by a prior
+ * crash) and clear it. Returns the paths swept. Call once at CLI start.
+ */
+export function sweepTrackedTmpDirs(manifestPath = DEFAULT_TMP_MANIFEST) {
+    const entries = readManifest(manifestPath);
+    const swept = [];
+    for (const entry of entries) {
+        try {
+            rmSync(entry.path, { recursive: true, force: true });
+            swept.push(entry.path);
+        }
+        catch {
+            // Leave un-sweepable paths for a later attempt.
+        }
+    }
+    writeManifest(manifestPath, []);
+    return swept;
+}