@kisev/skills-opencode 1.1.1 → 2.0.0

package/dist/routing.js

@@ -1,15 +1,38 @@
 import { createHash } from "node:crypto";
-export const CATEGORIES = ["exploration", "architecture", "implementation", "review", "documentation", "quick"];
+import { validateAgentReport } from "./contracts.js";
+export const CATEGORIES = ["exploration", "architecture", "implementation", "review"];
 const MATRIX = {
     schema_version: 1,
     categories: {
-        exploration: { profiles: ["mapper", "architect"], capabilities: ["read", "search"], tools: ["read", "glob", "grep"], cost: "low", latency: "fast" },
-        architecture: { profiles: ["architect", "mapper"], capabilities: ["read", "architecture"], tools: ["read", "glob", "grep"], cost: "medium", latency: "standard" },
-        implementation: { profiles: ["worker"], capabilities: ["read", "write", "verify"], tools: ["read", "edit", "bash"], cost: "medium", latency: "standard" },
-        review: { profiles: ["review", "critic"], capabilities: ["read", "review"], tools: ["read", "glob", "grep"], cost: "medium", latency: "standard" },
-        documentation: { profiles: ["worker", "review"], capabilities: ["read", "write", "documentation"], tools: ["read", "edit"], cost: "low", latency: "standard" },
-        quick: { profiles: ["mapper", "worker"], capabilities: ["read"], tools: ["read"], cost: "low", latency: "fast" }
-    }
+        exploration: {
+            profiles: ["mapper", "architect"],
+            capabilities: ["read", "search"],
+            tools: ["read", "glob", "grep"],
+            cost: "low",
+            latency: "fast",
+        },
+        architecture: {
+            profiles: ["architect", "mapper"],
+            capabilities: ["read", "architecture"],
+            tools: ["read", "glob", "grep"],
+            cost: "medium",
+            latency: "standard",
+        },
+        implementation: {
+            profiles: ["worker"],
+            capabilities: ["read", "write", "verify"],
+            tools: ["read", "edit", "bash"],
+            cost: "medium",
+            latency: "standard",
+        },
+        review: {
+            profiles: ["review", "critic"],
+            capabilities: ["read", "review"],
+            tools: ["read", "glob", "grep"],
+            cost: "medium",
+            latency: "standard",
+        },
+    },
 };
 function stable(value) {
     if (value === null || typeof value !== "object")
@@ -17,11 +40,66 @@ function stable(value) {
     if (Array.isArray(value))
         return `[${value.map(stable).join(",")}]`;
     const object = value;
-    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stable(object[key])}`).join(",")}}`;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stable(object[key])}`)
+        .join(",")}}`;
 }
 function digest(value) {
     return createHash("sha256").update(stable(value), "utf8").digest("hex");
 }
+export function validateRoutingReceipt(value, context) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("routing receipt is not an object");
+    const decision = value;
+    if ("destination" in decision) {
+        const receipt = value;
+        if (receipt.schema_version !== 1 ||
+            !CATEGORIES.includes(receipt.destination) ||
+            !receipt.agent ||
+            !receipt.nonce ||
+            !/^[a-f0-9]{64}$/.test(receipt.host_inventory_revision) ||
+            !/^[a-f0-9]{64}$/.test(receipt.receipt_digest) ||
+            !Number.isFinite(Date.parse(receipt.expires_at)) ||
+            (receipt.card_revision !== null &&
+                (!Number.isInteger(receipt.card_revision) || receipt.card_revision < 1)))
+            throw new Error("routing receipt is malformed");
+        if (Date.parse(receipt.expires_at) < Date.now())
+            throw new Error("routing receipt has expired");
+        const { receipt_digest: _receiptDigest, ...receiptBase } = receipt;
+        if (digest(receiptBase) !== receipt.receipt_digest)
+            throw new Error("routing receipt integrity is invalid");
+        if (context?.category !== undefined && receipt.destination !== context.category)
+            throw new Error("routing receipt destination does not match");
+        if (context?.task !== undefined && receipt.task_digest !== digest(context.task))
+            throw new Error("routing receipt task does not match");
+        if (context?.requirements !== undefined &&
+            receipt.requirements_digest !== digest(context.requirements))
+            throw new Error("routing receipt requirements do not match");
+        if (context?.card !== undefined && receipt.card_digest !== digest(context.card))
+            throw new Error("routing receipt card does not match");
+        return receipt;
+    }
+    if (decision.schema_version !== 1 ||
+        decision.status !== "selected" ||
+        !decision.agent ||
+        !CATEGORIES.includes(decision.category))
+        throw new Error("routing receipt is not selected");
+    if (!decision.matrix_revision ||
+        !decision.decision_digest ||
+        !/^[a-f0-9]{64}$/.test(decision.decision_digest))
+        throw new Error("routing receipt is incomplete");
+    const { decision_digest: _digest, ...base } = decision;
+    if (digest(base) !== decision.decision_digest)
+        throw new Error("routing receipt digest is forged or stale");
+    if (decision.matrix_revision !== digest(MATRIX))
+        throw new Error("routing receipt matrix is stale");
+    if (context?.category !== undefined && decision.category !== context.category)
+        throw new Error("routing receipt category does not match");
+    if (context?.task !== undefined && decision.task_digest !== digest(context.task))
+        throw new Error("routing receipt task does not match");
+    return decision;
+}
 function missing(required, actual) {
     const values = new Set(actual ?? []);
     return required.some((item) => !values.has(item));
@@ -32,10 +110,20 @@ function exceeds(value, limit, order) {
 export function resolveRouting(input) {
     const category = MATRIX.categories[input.category];
     const revision = digest(MATRIX);
+    const hostInventoryRevision = input.inventory_revision ?? digest(input.agents);
     const inventory = new Map(input.agents.map((agent) => [agent.agent, agent]));
     const alternatives = [];
     const eligible = [];
-    for (const profile of category.profiles) {
+    const dynamicCritics = input.category === "review"
+        ? input.agents
+            .map(({ agent }) => agent)
+            .filter((agent) => /^critic-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent))
+            .sort()
+        : [];
+    const profiles = input.trusted_override && input.override && !category.profiles.includes(input.override)
+        ? [...category.profiles, ...dynamicCritics, input.override]
+        : [...category.profiles, ...dynamicCritics];
+    for (const profile of profiles) {
         const agent = inventory.get(profile);
         const reasons = [];
         if (!agent)
@@ -57,34 +145,398 @@ export function resolveRouting(input) {
         else if (agent)
             eligible.push(agent);
     }
-    const selected = input.override ? eligible.find((agent) => agent.agent === input.override) : eligible[0];
+    if (input.override &&
+        !input.trusted_override &&
+        !category.profiles.includes(input.override))
+        throw new Error("Unknown or user-owned profile requires a trusted override");
+    const selected = input.override
+        ? eligible.find((agent) => agent.agent === input.override)
+        : eligible[0];
+    const card = input.execution_card === undefined ? undefined : validateExecutionCard(input.execution_card);
+    if (card && !card.valid)
+        throw new Error(`Invalid execution card: ${card.failedField}`);
     const base = selected
-        ? { schema_version: 1, status: "selected", category: input.category, agent: selected.agent, reason_codes: [input.override ? "explicit_override" : selected.agent === category.profiles[0] ? "primary_available" : "fallback_selected", "capabilities_match"], alternatives, matrix_revision: revision }
-        : { schema_version: 1, status: "escalate", category: input.category, reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"], alternatives, matrix_revision: revision };
+        ? {
+            schema_version: 1,
+            status: "selected",
+            category: input.category,
+            agent: selected.agent,
+            reason_codes: [
+                input.override
+                    ? "explicit_override"
+                    : selected.agent === category.profiles[0]
+                        ? "primary_available"
+                        : "fallback_selected",
+                "capabilities_match",
+            ],
+            alternatives,
+            matrix_revision: revision,
+            host_inventory_revision: hostInventoryRevision,
+            task_digest: digest(input.task ?? ""),
+            requirements_digest: digest(input.requirements),
+            ...(card?.valid
+                ? {
+                    execution_card_digest: digest(card.card),
+                    execution_card_revision: card.card.revision,
+                }
+                : {}),
+        }
+        : {
+            schema_version: 1,
+            status: "escalate",
+            category: input.category,
+            reason_codes: [input.override ? "override_unavailable" : "no_eligible_profile"],
+            alternatives,
+            matrix_revision: revision,
+            host_inventory_revision: hostInventoryRevision,
+            task_digest: digest(input.task ?? ""),
+            requirements_digest: digest(input.requirements),
+            ...(card?.valid
+                ? {
+                    execution_card_digest: digest(card.card),
+                    execution_card_revision: card.card.revision,
+                }
+                : {}),
+        };
     return { ...base, decision_digest: digest(base) };
 }
+function isNonEmptyStringArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((item) => typeof item === "string" && item.length > 0));
+}
+export function validateExecutionCard(card) {
+    if (!card || typeof card !== "object" || Array.isArray(card)) {
+        return { valid: false, failedField: "root" };
+    }
+    const c = card;
+    const expectedFields = [
+        "schema_version",
+        "status",
+        "card_id",
+        "revision",
+        "objective",
+        "evidence",
+        "changed_behavior",
+        "risks",
+        "write_set",
+        "control_markers",
+        "decisions",
+        "steps",
+        "acceptance_criteria",
+        "checks",
+        "operations",
+        "confirmations",
+        "boundaries",
+    ];
+    if (Object.keys(c).sort().join(",") !== expectedFields.slice().sort().join(","))
+        return { valid: false, failedField: "schema" };
+    if (c.schema_version !== 1)
+        return { valid: false, failedField: "schema_version" };
+    if (c.status !== "READY")
+        return { valid: false, failedField: "status" };
+    if (typeof c.card_id !== "string" || !c.card_id)
+        return { valid: false, failedField: "card_id" };
+    if (typeof c.revision !== "number" || !Number.isInteger(c.revision) || c.revision < 1)
+        return { valid: false, failedField: "revision" };
+    if (typeof c.objective !== "string" || !c.objective)
+        return { valid: false, failedField: "objective" };
+    if (!isNonEmptyStringArray(c.evidence))
+        return { valid: false, failedField: "evidence" };
+    if (!isNonEmptyStringArray(c.changed_behavior))
+        return { valid: false, failedField: "changed_behavior" };
+    if (!isNonEmptyStringArray(c.risks))
+        return { valid: false, failedField: "risks" };
+    if (!isNonEmptyStringArray(c.write_set))
+        return { valid: false, failedField: "write_set" };
+    if (new Set(c.write_set).size !== c.write_set.length)
+        return { valid: false, failedField: "write_set" };
+    if (!Array.isArray(c.control_markers) || c.control_markers.length === 0)
+        return { valid: false, failedField: "control_markers" };
+    for (const marker of c.control_markers) {
+        if (!marker || typeof marker !== "object" || Array.isArray(marker))
+            return { valid: false, failedField: "control_markers" };
+        const m = marker;
+        if (typeof m.path !== "string" || !m.path)
+            return { valid: false, failedField: "control_markers" };
+        const hasExpected = typeof m.expected === "string" && m.expected.length > 0;
+        const hasExpectedAbsent = m.expected_absent === true;
+        if (hasExpected === hasExpectedAbsent)
+            return { valid: false, failedField: "control_markers" };
+        if (Object.keys(m).some((k) => k !== "path" && k !== "expected" && k !== "expected_absent"))
+            return { valid: false, failedField: "control_markers" };
+    }
+    if (!isNonEmptyStringArray(c.decisions))
+        return { valid: false, failedField: "decisions" };
+    if (!Array.isArray(c.steps) || c.steps.length === 0)
+        return { valid: false, failedField: "steps" };
+    for (const step of c.steps) {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            return { valid: false, failedField: "steps" };
+        const s = step;
+        if (typeof s.path !== "string" || !s.path)
+            return { valid: false, failedField: "steps" };
+        if (typeof s.operation !== "string" || !s.operation)
+            return { valid: false, failedField: "steps" };
+        if (Object.keys(s).some((k) => k !== "path" && k !== "operation"))
+            return { valid: false, failedField: "steps" };
+    }
+    if (!isNonEmptyStringArray(c.acceptance_criteria))
+        return { valid: false, failedField: "acceptance_criteria" };
+    if (!isNonEmptyStringArray(c.checks))
+        return { valid: false, failedField: "checks" };
+    if (!Array.isArray(c.operations) || c.operations.length === 0)
+        return { valid: false, failedField: "operations" };
+    const operationKinds = new Set([
+        "write",
+        "check",
+        "commit",
+        "rebase",
+        "push",
+        "merge",
+        "tag",
+        "release",
+    ]);
+    for (const operation of c.operations) {
+        if (!operation || typeof operation !== "object" || Array.isArray(operation))
+            return { valid: false, failedField: "operations" };
+        const item = operation;
+        if (typeof item.kind !== "string" ||
+            !operationKinds.has(item.kind) ||
+            typeof item.command !== "string" ||
+            !item.command)
+            return { valid: false, failedField: "operations" };
+        if (item.path !== undefined && (typeof item.path !== "string" || !item.path))
+            return { valid: false, failedField: "operations" };
+        if (item.confirmation_ref !== undefined &&
+            (typeof item.confirmation_ref !== "string" || !item.confirmation_ref))
+            return { valid: false, failedField: "operations" };
+        if (Object.keys(item).some((key) => !["kind", "command", "path", "confirmation_ref"].includes(key)))
+            return { valid: false, failedField: "operations" };
+        if ((item.kind === "write" || item.kind === "check") && typeof item.path !== "string")
+            return { valid: false, failedField: "operations" };
+    }
+    const operationSet = new Set(c.operations.map(({ kind }) => kind));
+    for (const required of ["commit", "rebase", "push", "merge", "tag", "release"])
+        if (!operationSet.has(required))
+            return { valid: false, failedField: "operations" };
+    if (!c.confirmations || typeof c.confirmations !== "object" || Array.isArray(c.confirmations))
+        return { valid: false, failedField: "confirmations" };
+    const confirmations = c.confirmations;
+    if (typeof confirmations.execution !== "string" || !confirmations.execution)
+        return { valid: false, failedField: "confirmations" };
+    if (operationSet.has("push") ||
+        operationSet.has("merge") ||
+        operationSet.has("tag") ||
+        operationSet.has("release"))
+        if (typeof confirmations.publication !== "string" || !confirmations.publication)
+            return { valid: false, failedField: "confirmations" };
+    if (operationSet.has("rebase"))
+        if (typeof confirmations.history_rewrite !== "string" || !confirmations.history_rewrite)
+            return { valid: false, failedField: "confirmations" };
+    if (Object.keys(confirmations).some((key) => !["execution", "publication", "history_rewrite"].includes(key)))
+        return { valid: false, failedField: "confirmations" };
+    if (!c.boundaries || typeof c.boundaries !== "object" || Array.isArray(c.boundaries))
+        return { valid: false, failedField: "boundaries" };
+    const b = c.boundaries;
+    if (!isNonEmptyStringArray(b.forbidden_paths) || typeof b.scope !== "string" || !b.scope)
+        return { valid: false, failedField: "boundaries" };
+    if (Object.keys(b).some((k) => k !== "forbidden_paths" && k !== "scope"))
+        return { valid: false, failedField: "boundaries" };
+    const writeSet = c.write_set;
+    const forbiddenPaths = b.forbidden_paths;
+    const safePath = (path) => !path.startsWith("/") &&
+        !path.includes("\\") &&
+        !path.split("/").some((part) => !part || part === "." || part === "..");
+    if (![...writeSet, ...forbiddenPaths].every(safePath))
+        return { valid: false, failedField: "boundaries" };
+    const stepPaths = c.steps.map((s) => s.path);
+    const markerPaths = c.control_markers.map((m) => m.path);
+    const referenced = new Set([...stepPaths, ...markerPaths]);
+    if (![...referenced].every((p) => writeSet.includes(p)))
+        return { valid: false, failedField: "steps" };
+    const overlaps = (left, right) => left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+    if (writeSet.some((p) => forbiddenPaths.some((forbidden) => overlaps(p, forbidden))))
+        return { valid: false, failedField: "boundaries" };
+    if (!writeSet.every((path) => stepPaths.includes(path)))
+        return { valid: false, failedField: "steps" };
+    const operations = c.operations;
+    if (!writeSet.every((path) => operations.some((operation) => operation.kind === "write" && operation.path === path) &&
+        operations.some((operation) => operation.kind === "check" && operation.path === path)))
+        return { valid: false, failedField: "operations" };
+    for (const operation of operations) {
+        if (["commit", "rebase", "push", "merge", "tag", "release"].includes(operation.kind) &&
+            !operation.confirmation_ref)
+            return { valid: false, failedField: "operations" };
+        if (operation.kind === "rebase" && operation.confirmation_ref !== confirmations.history_rewrite)
+            return { valid: false, failedField: "confirmations" };
+        if (["push", "merge", "tag", "release"].includes(operation.kind) &&
+            operation.confirmation_ref !== confirmations.publication)
+            return { valid: false, failedField: "confirmations" };
+    }
+    return { valid: true, card: c };
+}
+export class ExecutionCardLifecycle {
+    #status = "READY";
+    #cardID;
+    #revision;
+    constructor(card) {
+        const result = validateExecutionCard(card);
+        if (!result.valid)
+            throw new Error(`Invalid execution card: ${result.failedField}`);
+        this.#cardID = result.card.card_id;
+        this.#revision = result.card.revision;
+    }
+    get status() {
+        return this.#status;
+    }
+    get card_id() {
+        return this.#cardID;
+    }
+    get revision() {
+        return this.#revision;
+    }
+    transition(status, identity) {
+        if (identity.card_id !== this.#cardID || identity.revision !== this.#revision)
+            throw new Error("Execution card identity is stale");
+        const allowed = {
+            READY: ["RUNNING", "CANCELLED"],
+            RUNNING: ["COMPLETED", "BLOCKED", "FAILED", "REJECTED_PLAN", "CANCELLED"],
+            COMPLETED: ["APPROVED", "CHANGES_REQUIRED"],
+            BLOCKED: [],
+            FAILED: [],
+            REJECTED_PLAN: [],
+            APPROVED: [],
+            CHANGES_REQUIRED: [],
+            CANCELLED: [],
+        };
+        if (!allowed[this.#status].includes(status))
+            throw new Error(`Invalid execution-card transition: ${this.#status} -> ${status}`);
+        this.#status = status;
+        return this.#status;
+    }
+}
 export class RoutingGate {
     #receipts = new Map();
+    #active = new Map();
+    #ttlMs = 10 * 60 * 1000;
     preview(input) {
         return resolveRouting(input);
     }
     dispatch(input, provided) {
         const decision = resolveRouting(input);
-        if (!provided || typeof provided !== "object" || provided.decision_digest !== decision.decision_digest || provided.matrix_revision !== decision.matrix_revision)
+        if (!provided || typeof provided !== "object" || stable(provided) !== stable(decision))
             throw new Error("Routing decision is stale; request a new preview");
         if (decision.status !== "selected" || !decision.agent)
             throw new Error("Routing escalated; no agent was dispatched");
         return decision;
     }
-    grant(sessionID, decision) {
-        this.#receipts.set(sessionID, decision);
+    grant(sessionID, decision, context) {
+        const now = Date.now();
+        const taskDigest = context?.task === undefined ? decision.task_digest : digest(context.task);
+        const requirementsDigest = context?.requirements === undefined
+            ? decision.requirements_digest
+            : digest(context.requirements);
+        const cardDigest = context?.card === undefined ? decision.execution_card_digest : digest(context.card);
+        const receiptBase = {
+            schema_version: 1,
+            task_digest: taskDigest,
+            requirements_digest: requirementsDigest,
+            destination: decision.category,
+            agent: decision.agent,
+            card_digest: cardDigest ?? null,
+            card_revision: decision.execution_card_revision ?? null,
+            host_inventory_revision: decision.host_inventory_revision,
+            expires_at: new Date(now + this.#ttlMs).toISOString(),
+            nonce: createHash("sha256")
+                .update(`${sessionID}:${now}:${decision.decision_digest}`)
+                .digest("hex"),
+        };
+        const receipt = { ...receiptBase, receipt_digest: digest(receiptBase) };
+        this.#receipts.set(sessionID, {
+            decision,
+            taskDigest,
+            requirementsDigest,
+            cardDigest,
+            expiresAt: Date.parse(receipt.expires_at),
+        });
+        return receipt;
     }
-    consume(sessionID, agent) {
+    cancel(sessionID) {
+        this.#receipts.delete(sessionID);
+        this.#active.delete(sessionID);
+    }
+    consume(sessionID, agent, context) {
         const receipt = this.#receipts.get(sessionID);
         if (!receipt)
             throw new Error("Native Task requires an active routing receipt; use the route tool");
-        if (receipt.agent !== agent)
+        if (receipt.decision.agent !== agent)
             throw new Error("Native Task agent does not match the active routing receipt");
+        if (Date.now() > receipt.expiresAt)
+            throw new Error("Routing receipt has expired; request a new preview");
+        if (context) {
+            const taskDigest = digest(context.task ?? "");
+            if (taskDigest !== receipt.taskDigest)
+                throw new Error("Routing receipt task does not match the active routing receipt");
+            const requirementsDigest = digest(context.requirements ?? []);
+            if (requirementsDigest !== receipt.requirementsDigest)
+                throw new Error("Routing receipt requirements do not match the active routing receipt");
+            const cardDigest = context.card !== undefined ? digest(context.card) : undefined;
+            if (cardDigest !== receipt.cardDigest)
+                throw new Error("Routing receipt execution card does not match the active routing receipt");
+        }
         this.#receipts.delete(sessionID);
+        const validatedCard = context?.card === undefined ? undefined : validateExecutionCard(context.card);
+        const card = validatedCard?.valid ? validatedCard.card : undefined;
+        const lifecycle = card ? new ExecutionCardLifecycle(card) : undefined;
+        if (lifecycle)
+            lifecycle.transition("RUNNING", { card_id: card.card_id, revision: card.revision });
+        this.#active.set(sessionID, { agent, card, lifecycle, expiresAt: receipt.expiresAt });
+    }
+    complete(sessionID, agent, output) {
+        const active = this.#active.get(sessionID);
+        if (!active || active.agent !== agent)
+            throw new Error("Task result has no matching active routing receipt");
+        if (Date.now() > active.expiresAt)
+            throw new Error("Task result routing receipt has expired");
+        const report = output && typeof output === "object" ? output : undefined;
+        const value = report?.[agent === "architect" ? "execution_card" : `${agent}_report`] ?? report?.report;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Task result is missing a structured agent report");
+        const result = value;
+        validateAgentReport(agent, report, active.card);
+        if (active.card &&
+            (result.card_id !== active.card.card_id || result.revision !== active.card.revision))
+            throw new Error("Task result does not match the active execution card");
+        const status = result.status;
+        const allowed = agent === "worker"
+            ? ["COMPLETED", "BLOCKED", "FAILED", "REJECTED_PLAN"]
+            : agent === "critic"
+                ? ["APPROVED", "CHANGES_REQUIRED"]
+                : undefined;
+        if (allowed && (typeof status !== "string" || !allowed.includes(status)))
+            throw new Error("Task result has an invalid machine transition");
+        if (active.lifecycle && status === "COMPLETED")
+            active.lifecycle.transition("COMPLETED", {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        if (active.lifecycle &&
+            (status === "BLOCKED" || status === "FAILED" || status === "REJECTED_PLAN"))
+            active.lifecycle.transition(status, {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        if (active.lifecycle && (status === "APPROVED" || status === "CHANGES_REQUIRED")) {
+            active.lifecycle.transition("COMPLETED", {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+            active.lifecycle.transition(status, {
+                card_id: active.card.card_id,
+                revision: active.card.revision,
+            });
+        }
+        this.#active.delete(sessionID);
     }
 }

package/dist/runtime/state.d.ts

@@ -4,4 +4,5 @@ export declare function readState<T>(path: string, boundary: string): Promise<T
 export declare function listState(boundary: string, suffix?: string): Promise<string[]>;
 export declare function writeState(path: string, boundary: string, value: unknown): Promise<void>;
 export declare function appendState(path: string, boundary: string, value: unknown): Promise<void>;
+export declare function withStateLock<T>(boundary: string, callback: () => Promise<T>): Promise<T>;
 export declare function digest(value: unknown): string;

package/dist/runtime/state.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, mkdir, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { appendPrivate, writeAtomic } from "../lifecycle.js";
+import { appendPrivate, withLifecycleLock, writeAtomic } from "../lifecycle.js";
 function home(value = process.env.HOME ?? homedir()) {
     if (!isAbsolute(value) || value.split(sep).includes(".."))
         throw new Error("HOME must be an absolute safe path");
@@ -94,14 +94,21 @@ export async function listState(boundary, suffix = ".json") {
 export async function writeState(path, boundary, value) {
     if (!inside(boundary, path))
         throw new Error("state path escapes its boundary");
-    await safeDirectory(dirname(path), boundary, true);
-    await writeAtomic(path, Buffer.from(`${JSON.stringify(value)}\n`), 0o600);
+    await withLifecycleLock(boundary, async () => {
+        await safeDirectory(dirname(path), boundary, true);
+        await writeAtomic(path, Buffer.from(`${JSON.stringify(value)}\n`), 0o600);
+    });
 }
 export async function appendState(path, boundary, value) {
     if (!inside(boundary, path))
         throw new Error("state path escapes its boundary");
-    await safeDirectory(dirname(path), boundary, true);
-    await appendPrivate(path, value);
+    await withLifecycleLock(boundary, async () => {
+        await safeDirectory(dirname(path), boundary, true);
+        await appendPrivate(path, value);
+    });
+}
+export async function withStateLock(boundary, callback) {
+    return withLifecycleLock(boundary, callback);
 }
 export function digest(value) {
     return createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex");

package/dist/runtime/worktree.d.ts

@@ -0,0 +1,33 @@
+export type WorktreeStatus = "managed" | "missing" | "blocked" | "unknown";
+export type WorktreeRecord = {
+    schema_version: 1;
+    workspace_id: string;
+    project: string;
+    path: string;
+    branch: string;
+    start_ref: string;
+    repository_fingerprint: string;
+    marker: string;
+    status: WorktreeStatus;
+    created_at: string;
+    updated_at: string;
+};
+export declare function worktreePlan(project: string, workspaceID?: `${string}-${string}-${string}-${string}-${string}`): Promise<Record<string, unknown>>;
+export declare function worktreeCreate(input: {
+    project: string;
+    workspace_id: string;
+    path?: string;
+    branch?: string;
+    start_ref?: string;
+}): Promise<WorktreeRecord>;
+export declare function worktreeStatus(project: string, workspaceID: string): Promise<WorktreeRecord | undefined>;
+export declare function worktreeList(project: string): Promise<WorktreeRecord[]>;
+export declare function worktreeRelease(project: string, workspaceID: string): Promise<{
+    status: "released" | "blocked";
+    workspace_id: string;
+    reason?: string;
+}>;
+export declare function worktreeRecover(project: string): Promise<{
+    recovered: number;
+    blocked: number;
+}>;