toolroll 0.9.34 → 0.9.37

package/dist/contracts/gateway-tools.d.ts

@@ -0,0 +1,374 @@
+/**
+ * The MCP gateway's tools (docs/plans/zod-revamp.md, item 5; docs/mcp-gateway-spec.md): one input schema per tool and
+ * one output schema for what each returns. The input schema is the `inputSchema` tools/list advertises and the check
+ * a call is read with before its handler runs (mcp.ts): a call it refuses is a JSON-RPC InvalidParams error naming each
+ * path, never a tool refusal. The assignment tools' schemas are also what `toolroll assignment` reads its flags with
+ * (assignment-adapters.ts), so the CLI and the gateway take exactly the same arguments.
+ *
+ * A coordinator names a project by its path and a task by `ref`; the lead's tools (lead-tools.ts) say r1 and `task`.
+ * Output schemas describe a result's top level: checked in tests, logged when a result disagrees, never a refusal.
+ */
+import { z } from "zod";
+/** The assignment tools, by the operation `toolroll assignment` names them. */
+export declare const ASSIGNMENT_INPUTS: {
+    readonly show: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly updates: z.ZodObject<{
+        after: z.ZodOptional<z.ZodInt>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly claim: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly check: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    readonly brief: z.ZodObject<{
+        repo: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly inbox: z.ZodObject<{
+        consumer: z.ZodString;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly ack: z.ZodObject<{
+        consumer: z.ZodString;
+        batchId: z.ZodString;
+    }, z.core.$strict>;
+};
+export type AssignmentOperation = keyof typeof ASSIGNMENT_INPUTS;
+export type AssignmentInput<O extends AssignmentOperation> = z.infer<(typeof ASSIGNMENT_INPUTS)[O]>;
+export declare const GATEWAY_TOOL_INPUTS: {
+    readonly get_project_context: z.ZodObject<{
+        repo: z.ZodString;
+        query: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            impact: "impact";
+            search: "search";
+        }>>;
+    }, z.core.$strict>;
+    readonly get_assignment: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly list_assignment_updates: z.ZodObject<{
+        after: z.ZodOptional<z.ZodInt>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly claim_assignment: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly acknowledge_assignment: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    readonly get_assignment_brief: z.ZodObject<{
+        repo: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly get_assignment_inbox: z.ZodObject<{
+        consumer: z.ZodString;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly acknowledge_assignment_delivery: z.ZodObject<{
+        consumer: z.ZodString;
+        batchId: z.ZodString;
+    }, z.core.$strict>;
+    readonly status: z.ZodObject<{}, z.core.$strict>;
+    readonly list_tasks: z.ZodObject<{
+        state: z.ZodOptional<z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+        }>>;
+        repo: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodInt>;
+        limit: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly get_task: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly list_repos: z.ZodObject<{}, z.core.$strict>;
+    readonly recap: z.ZodObject<{
+        since: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly list_decisions: z.ZodObject<{}, z.core.$strict>;
+    readonly queue: z.ZodObject<{
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    readonly get_decision: z.ZodObject<{
+        decision: z.ZodInt;
+    }, z.core.$strict>;
+    readonly propose_next: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly propose_reserve: z.ZodObject<{
+        ref: z.ZodString;
+        worker: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    readonly propose_hold: z.ZodObject<{
+        ref: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    readonly propose_unhold: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    readonly propose_scope: z.ZodObject<{
+        ref: z.ZodString;
+        goal: z.ZodString;
+        not: z.ZodOptional<z.ZodString>;
+        touches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    readonly propose_cancel: z.ZodObject<{
+        ref: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    readonly propose_answer: z.ZodObject<{
+        decision: z.ZodInt;
+        option: z.ZodString;
+        rationale: z.ZodString;
+    }, z.core.$strict>;
+    readonly get_contract: z.ZodObject<{}, z.core.$strict>;
+    readonly file_proposal: z.ZodObject<{
+        repo: z.ZodString;
+        title: z.ZodString;
+        intent: z.ZodOptional<z.ZodString>;
+        idempotency_key: z.ZodString;
+        deliverable: z.ZodOptional<z.ZodEnum<{
+            branch: "branch";
+            report: "report";
+        }>>;
+    }, z.core.$strict>;
+};
+export type GatewayToolName = keyof typeof GATEWAY_TOOL_INPUTS;
+export type GatewayToolInput<N extends GatewayToolName> = z.infer<(typeof GATEWAY_TOOL_INPUTS)[N]>;
+export declare const GATEWAY_TOOL_OUTPUTS: {
+    readonly get_project_context: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        readOnly: z.ZodBoolean;
+        query: z.ZodString;
+        mode: z.ZodEnum<{
+            impact: "impact";
+            search: "search";
+        }>;
+        asOf: z.ZodString;
+        excerpts: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$loose>;
+    readonly get_assignment: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        rootId: z.ZodString;
+        activeTaskId: z.ZodString;
+        title: z.ZodString;
+        state: z.ZodString;
+        detail: z.ZodString;
+        attention: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    readonly list_assignment_updates: z.ZodObject<{
+        events: z.ZodArray<z.ZodUnknown>;
+        nextCursor: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly claim_assignment: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        rootId: z.ZodString;
+        activeTaskId: z.ZodString;
+        title: z.ZodString;
+        state: z.ZodString;
+        detail: z.ZodString;
+        attention: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    readonly acknowledge_assignment: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        rootId: z.ZodString;
+        activeTaskId: z.ZodString;
+        title: z.ZodString;
+        state: z.ZodString;
+        detail: z.ZodString;
+        attention: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    readonly get_assignment_brief: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        asOf: z.ZodString;
+        readOnly: z.ZodLiteral<true>;
+        assignments: z.ZodArray<z.ZodUnknown>;
+        projects: z.ZodArray<z.ZodUnknown>;
+        omissions: z.ZodObject<{}, z.core.$loose>;
+    }, z.core.$loose>;
+    readonly get_assignment_inbox: z.ZodObject<{
+        batch: z.ZodObject<{
+            id: z.ZodNullable<z.ZodString>;
+            consumer: z.ZodString;
+            events: z.ZodArray<z.ZodUnknown>;
+            hasMore: z.ZodBoolean;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+    readonly acknowledge_assignment_delivery: z.ZodObject<{
+        alreadyAcknowledged: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly status: z.ZodObject<{
+        waitsOnYou: z.ZodNumber;
+        waits: z.ZodObject<{
+            approvals: z.ZodNumber;
+            questions: z.ZodNumber;
+            incidents: z.ZodNumber;
+            picks: z.ZodNumber;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+    readonly list_tasks: z.ZodObject<{
+        tasks: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$loose>;
+    readonly get_task: z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$loose>;
+    readonly list_repos: z.ZodObject<{
+        repos: z.ZodArray<z.ZodObject<{
+            repo: z.ZodString;
+            mode: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    readonly recap: z.ZodObject<{
+        since: z.ZodNullable<z.ZodString>;
+        repos: z.ZodArray<z.ZodUnknown>;
+        waitsOnYou: z.ZodObject<{
+            decisions: z.ZodArray<z.ZodUnknown>;
+            incidents: z.ZodNumber;
+            scopesAwaitingApproval: z.ZodArray<z.ZodUnknown>;
+        }, z.core.$loose>;
+        running: z.ZodArray<z.ZodUnknown>;
+        truncated: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly list_decisions: z.ZodObject<{
+        decisions: z.ZodArray<z.ZodObject<{
+            decision: z.ZodNumber;
+            task: z.ZodString;
+            question: z.ZodString;
+            options: z.ZodArray<z.ZodUnknown>;
+            ageHours: z.ZodNumber;
+        }, z.core.$loose>>;
+        truncated: z.ZodBoolean;
+    }, z.core.$loose>;
+    readonly queue: z.ZodObject<{
+        columns: z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            tasks: z.ZodArray<z.ZodUnknown>;
+        }, z.core.$loose>>;
+        repo: z.ZodString;
+    }, z.core.$loose>;
+    readonly get_decision: z.ZodObject<{
+        repo: z.ZodString;
+        decision: z.ZodNumber;
+        task: z.ZodString;
+        state: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            reversible: z.ZodBoolean;
+            consequence: z.ZodString;
+        }, z.core.$loose>>;
+        ageHours: z.ZodNumber;
+    }, z.core.$loose>;
+    readonly propose_next: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_reserve: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_hold: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_unhold: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_scope: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_cancel: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly propose_answer: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            cancel: "cancel";
+            hold: "hold";
+            next: "next";
+            reserve: "reserve";
+            scope: "scope";
+            unhold: "unhold";
+        }>;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
+    readonly get_contract: z.ZodObject<{
+        contract: z.ZodString;
+    }, z.core.$loose>;
+    readonly file_proposal: z.ZodObject<{
+        ref: z.ZodString;
+        replayed: z.ZodBoolean;
+        admission: z.ZodString;
+    }, z.core.$loose>;
+};
+export type GatewayToolOutput<N extends GatewayToolName> = z.infer<(typeof GATEWAY_TOOL_OUTPUTS)[N]>;

package/dist/contracts/gateway-tools.js

@@ -0,0 +1,94 @@
+/**
+ * The MCP gateway's tools (docs/plans/zod-revamp.md, item 5; docs/mcp-gateway-spec.md): one input schema per tool and
+ * one output schema for what each returns. The input schema is the `inputSchema` tools/list advertises and the check
+ * a call is read with before its handler runs (mcp.ts): a call it refuses is a JSON-RPC InvalidParams error naming each
+ * path, never a tool refusal. The assignment tools' schemas are also what `toolroll assignment` reads its flags with
+ * (assignment-adapters.ts), so the CLI and the gateway take exactly the same arguments.
+ *
+ * A coordinator names a project by its path and a task by `ref`; the lead's tools (lead-tools.ts) say r1 and `task`.
+ * Output schemas describe a result's top level: checked in tests, logged when a result disagrees, never a refusal.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { catchUpOutput, decisionOutput, decisionsOutput, LISTED_TASK_STATES, queueColumnsOutput, recapOutput, repositoryContextOutput, scopeText, touches } from "./lead-tools.js";
+const text = (key) => z.string().max(TEXT_LIMITS[key]);
+const ref = z.string().min(1).max(TEXT_LIMITS.taskRef);
+const projectPath = text("projectPath").min(1);
+const gatewayRepo = text("gatewayRepo").min(1);
+const consumer = z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]{0,63}$/, { error: "must be a stable consumer name: lowercase letters, digits and hyphens" });
+const limit = (most) => z.int().min(1).max(most);
+/** The assignment tools, by the operation `toolroll assignment` names them. */
+export const ASSIGNMENT_INPUTS = {
+    show: z.strictObject({ ref }),
+    updates: z.strictObject({ after: z.int().min(0).optional(), limit: limit(100).optional() }),
+    claim: z.strictObject({ ref }),
+    check: z.strictObject({ ref, digest: z.string().min(64).max(64).regex(/^[a-f0-9]{64}$/, { error: "must be the exact 64-character receipt digest from assignment show" }) }),
+    brief: z.strictObject({ repo: projectPath.optional(), limit: limit(25).optional() }),
+    inbox: z.strictObject({ consumer, limit: limit(100).optional() }),
+    ack: z.strictObject({ consumer, batchId: z.string().min(32).max(32).regex(/^[a-f0-9]{32}$/, { error: "must be the exact batchId from assignment inbox" }) }),
+};
+export const GATEWAY_TOOL_INPUTS = {
+    get_project_context: z.strictObject({ repo: projectPath, query: text("contextQuery").min(1), mode: z.enum(["search", "impact"]).optional() }),
+    get_assignment: ASSIGNMENT_INPUTS.show,
+    list_assignment_updates: ASSIGNMENT_INPUTS.updates,
+    claim_assignment: ASSIGNMENT_INPUTS.claim,
+    acknowledge_assignment: ASSIGNMENT_INPUTS.check,
+    get_assignment_brief: ASSIGNMENT_INPUTS.brief,
+    get_assignment_inbox: ASSIGNMENT_INPUTS.inbox,
+    acknowledge_assignment_delivery: ASSIGNMENT_INPUTS.ack,
+    status: z.strictObject({}),
+    list_tasks: z.strictObject({ state: z.enum(LISTED_TASK_STATES).optional(), repo: text("gatewayRepo").optional(), cursor: z.int().min(0).optional(), limit: limit(50).optional() }),
+    get_task: z.strictObject({ ref }),
+    list_repos: z.strictObject({}),
+    recap: z.strictObject({ since: text("recapSince").optional() }),
+    list_decisions: z.strictObject({}),
+    queue: z.strictObject({ repo: gatewayRepo }),
+    get_decision: z.strictObject({ decision: z.int().min(1) }),
+    propose_next: z.strictObject({ ref }),
+    propose_reserve: z.strictObject({ ref, worker: text("workerName").nullable() }),
+    propose_hold: z.strictObject({ ref, reason: text("proposalReason") }),
+    propose_unhold: z.strictObject({ ref }),
+    propose_scope: z.strictObject({ ref, goal: scopeText, not: scopeText.optional(), touches: touches.optional() }),
+    propose_cancel: z.strictObject({ ref, reason: text("proposalReason") }),
+    propose_answer: z.strictObject({ decision: z.int().min(1), option: text("answerOption").min(1), rationale: text("answerRationale") }),
+    get_contract: z.strictObject({}),
+    file_proposal: z.strictObject({
+        repo: gatewayRepo, title: text("taskTitle").min(1), intent: scopeText.optional(), idempotency_key: text("idempotencyKey").min(8),
+        deliverable: z.enum(["branch", "report"]).optional(),
+    }),
+};
+// ------------------------------------------------------------- outputs
+const str = z.string();
+const int = z.number().int();
+const list = z.array(z.unknown());
+const rows = (shape) => z.array(z.looseObject(shape));
+const proposed = z.looseObject({ proposal: int, kind: z.enum(["next", "reserve", "hold", "unhold", "scope", "cancel", "answer"]), awaiting: str });
+/** One assignment (assignment.ts `AssignmentSnapshot`). */
+const assignmentOutput = z.looseObject({ version: z.literal(1), rootId: str, activeTaskId: str, title: str, state: str, detail: str, attention: z.array(str) });
+export const GATEWAY_TOOL_OUTPUTS = {
+    get_project_context: repositoryContextOutput,
+    get_assignment: assignmentOutput,
+    list_assignment_updates: z.looseObject({ events: list, nextCursor: int, hasMore: z.boolean() }),
+    claim_assignment: assignmentOutput,
+    acknowledge_assignment: assignmentOutput,
+    get_assignment_brief: catchUpOutput,
+    get_assignment_inbox: z.looseObject({ batch: z.looseObject({ id: str.nullable(), consumer: str, events: list, hasMore: z.boolean() }) }),
+    acknowledge_assignment_delivery: z.looseObject({ alreadyAcknowledged: z.boolean() }),
+    status: z.looseObject({ waitsOnYou: int, waits: z.looseObject({ approvals: int, questions: int, incidents: int, picks: int }) }),
+    list_tasks: z.looseObject({ tasks: list }),
+    get_task: z.looseObject({ ref: str }),
+    list_repos: z.looseObject({ repos: rows({ repo: str, mode: str }) }),
+    recap: recapOutput,
+    list_decisions: decisionsOutput,
+    queue: z.looseObject({ repo: str, ...queueColumnsOutput }),
+    get_decision: decisionOutput,
+    propose_next: proposed,
+    propose_reserve: proposed,
+    propose_hold: proposed,
+    propose_unhold: proposed,
+    propose_scope: proposed,
+    propose_cancel: proposed,
+    propose_answer: proposed,
+    get_contract: z.looseObject({ contract: str }),
+    file_proposal: z.looseObject({ ref: str, replayed: z.boolean(), admission: str }),
+};

package/dist/contracts/handoff.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The handoff artifact (`handoff.json`, M6.10): one schema for the machine's own statement of where a finished run
+ * left the world — workspace identity, exact base and head, which answered decisions the brief carried, the agent's
+ * conclusion and lists, and a freshness stamp a successor proves against the branch. `storeHandoffArtifact` writes it
+ * and every reader reads it through `readHandoffArtifact`.
+ *
+ * The agent's own terminal handoff (`STANDING-ORDERS-DONE-*`, `parseHandoff` in decision.ts) is a different contract;
+ * this file records what the machine made of it.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const ROUTE_PHASES: readonly ["plan", "build", "repair", "review"];
+export declare const ROUTE_CHOICES: readonly ["recommended", "override", "pinned", "legacy", "fallback"];
+/** The sealed route leg the run ran as (v47); absent on handoffs written before routes existed. */
+export declare const handoffRouteSchema: z.ZodObject<{
+    digest: z.ZodString;
+    phase: z.ZodEnum<{
+        build: "build";
+        plan: "plan";
+        repair: "repair";
+        review: "review";
+    }>;
+    provider: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    chosen: z.ZodEnum<{
+        fallback: "fallback";
+        legacy: "legacy";
+        override: "override";
+        pinned: "pinned";
+        recommended: "recommended";
+    }>;
+}, z.core.$strict>;
+export declare const HANDOFF_VERSION = 1;
+export declare const handoffSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    taskId: z.ZodString;
+    runId: z.ZodInt;
+    provider: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodObject<{
+        digest: z.ZodString;
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodNullable<z.ZodString>;
+        chosen: z.ZodEnum<{
+            fallback: "fallback";
+            legacy: "legacy";
+            override: "override";
+            pinned: "pinned";
+            recommended: "recommended";
+        }>;
+    }, z.core.$strict>>;
+    sessionId: z.ZodNullable<z.ZodString>;
+    branch: z.ZodString;
+    worktree: z.ZodString;
+    base: z.ZodString;
+    head: z.ZodString;
+    outcome: z.ZodEnum<{
+        built: "built";
+        "no-change": "no-change";
+    }>;
+    committed: z.ZodBoolean;
+    decisionsIncorporated: z.ZodArray<z.ZodInt>;
+    conclusion: z.ZodString;
+    changes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    verification: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    followUps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freshness: z.ZodObject<{
+        stampedAt: z.ZodString;
+        currentAsOf: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type HandoffArtifact = z.infer<typeof handoffSchema>;
+/**
+ * A handoff written before handoffs carried `version` (every handoff through 0.9.34, stamped `schema: 1`), as
+ * version 1. The shape is the same; readers then read only the fields they knew and ignored any others, so this keeps
+ * exactly the known fields. Anything not stamped `schema: 1` is left as it is, for the schema to refuse by path.
+ */
+export declare function upgradeSchemaOneHandoff(body: Record<string, unknown>): Record<string, unknown>;
+export declare const HANDOFF_UPGRADES: {
+    readonly 0: typeof upgradeSchemaOneHandoff;
+};
+/** Read a handoff artifact: version 1 as itself, a `schema: 1` one upgraded, a newer one refused plainly. */
+export declare function readHandoffArtifact(input: unknown): ContractResult<HandoffArtifact>;
+/** Read a stored handoff's bytes: JSON first, then the schema. */
+export declare function parseHandoffArtifact(raw: string): ContractResult<HandoffArtifact>;

package/dist/contracts/handoff.js

@@ -0,0 +1,82 @@
+/**
+ * The handoff artifact (`handoff.json`, M6.10): one schema for the machine's own statement of where a finished run
+ * left the world — workspace identity, exact base and head, which answered decisions the brief carried, the agent's
+ * conclusion and lists, and a freshness stamp a successor proves against the branch. `storeHandoffArtifact` writes it
+ * and every reader reads it through `readHandoffArtifact`.
+ *
+ * The agent's own terminal handoff (`STANDING-ORDERS-DONE-*`, `parseHandoff` in decision.ts) is a different contract;
+ * this file records what the machine made of it.
+ */
+import { z } from "zod";
+import { readVersioned, versioned } from "./contract.js";
+export const ROUTE_PHASES = ["plan", "build", "repair", "review"];
+export const ROUTE_CHOICES = ["recommended", "override", "pinned", "legacy", "fallback"];
+/** The sealed route leg the run ran as (v47); absent on handoffs written before routes existed. */
+export const handoffRouteSchema = z.strictObject({
+    digest: z.string(),
+    phase: z.enum(ROUTE_PHASES),
+    provider: z.string(),
+    model: z.string().nullable(),
+    chosen: z.enum(ROUTE_CHOICES),
+});
+export const HANDOFF_VERSION = 1;
+export const handoffSchema = versioned(HANDOFF_VERSION, {
+    taskId: z.string(),
+    runId: z.int(),
+    provider: z.string(),
+    /** v47: the exact model that ran. Absent on handoffs written before routes existed. */
+    model: z.string().optional(),
+    route: handoffRouteSchema.optional(),
+    sessionId: z.string().nullable(),
+    branch: z.string(),
+    worktree: z.string(),
+    base: z.string(),
+    head: z.string(),
+    outcome: z.enum(["built", "no-change"]),
+    committed: z.boolean(),
+    /** Decision ids whose answers were in this run's brief — causality, not time. */
+    decisionsIncorporated: z.array(z.int()),
+    /** The agent's conclusion — agent-reported, and labeled so by its position here. */
+    conclusion: z.string(),
+    /** The agent's structured lists; absent on handoffs written before they existed, read as none. */
+    changes: z.array(z.string()).optional(),
+    verification: z.array(z.string()).optional(),
+    followUps: z.array(z.string()).optional(),
+    freshness: z.strictObject({
+        stampedAt: z.string(),
+        /** A successor proves this against the branch before trusting anything above. */
+        currentAsOf: z.string(),
+    }),
+});
+const HANDOFF_FIELDS = Object.keys(handoffSchema.shape).filter(field => field !== "version");
+/**
+ * A handoff written before handoffs carried `version` (every handoff through 0.9.34, stamped `schema: 1`), as
+ * version 1. The shape is the same; readers then read only the fields they knew and ignored any others, so this keeps
+ * exactly the known fields. Anything not stamped `schema: 1` is left as it is, for the schema to refuse by path.
+ */
+export function upgradeSchemaOneHandoff(body) {
+    if (body["schema"] !== 1)
+        return body;
+    const out = { version: HANDOFF_VERSION };
+    for (const field of HANDOFF_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    return out;
+}
+export const HANDOFF_UPGRADES = { 0: upgradeSchemaOneHandoff };
+/** Read a handoff artifact: version 1 as itself, a `schema: 1` one upgraded, a newer one refused plainly. */
+export function readHandoffArtifact(input) {
+    return readVersioned(handoffSchema, input, HANDOFF_UPGRADES);
+}
+/** Read a stored handoff's bytes: JSON first, then the schema. */
+export function parseHandoffArtifact(raw) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    return readHandoffArtifact(body);
+}