toolroll 0.9.58 → 0.9.59

package/dist/builder.js

@@ -857,9 +857,11 @@ export async function build(store, request) {
             // still-blocked history) is left alone rather than having a
             // revision 1 invented underneath it.
             if (planDocument !== null && store.latestPlanRevision(taskRef) === null) {
+                // Revision 1 for a task planned once; past every earlier generation's revisions for one planned again (v119).
+                planRevisionNumber = store.nextPlanRevisionNumber(taskRef);
                 planRevisionId = store.insertPlanRevision({
                     taskRef,
-                    revision: 1,
+                    revision: planRevisionNumber,
                     artifact: planArtifact.id,
                     parentHash: null,
                     reason: "the plan the operator approved",
@@ -1803,7 +1805,7 @@ function settleRevisionProposal(captured, binding) {
     if (latest !== null && latest.status === "blocked") {
         return broke("the agent proposed a plan revision, but one is already awaiting your approval on this task");
     }
-    const revisionNumber = (latest?.revision ?? 0) + 1;
+    const revisionNumber = store.nextPlanRevisionNumber(taskRef);
     // Stored re-serialized from the validated shape, never the agent's raw
     // bytes: what a later brief quotes and hash-verifies is exactly what this
     // parser admitted.

package/dist/chat-channel.d.ts

@@ -81,6 +81,7 @@ export declare function confirmedLink(store: Store, outcome: DoorOutcome, propos
 export declare function proposalPreview(store: Store, proposal: LeadProposal, repos: readonly string[], channel?: ChatChannelName | null): {
     text: string;
     buttons: boolean;
+    closed?: true;
 };
 /** The card after it resolves, from the recorded outcome — the same words every surface shows. */
 export declare function proposalOutcomeText(proposal: LeadProposal): string;

package/dist/chat-channel.js

@@ -1,5 +1,6 @@
 /** Shared membership-chat identity, proposal previews and result links. Transport adapters never grant authority. */
 import { FLOW_HREF } from "./flow-engine.js";
+import { closedQuestionWords } from "./decision.js";
 import { createHash } from "node:crypto";
 import { sharedActionPayload, sharedActionNeedsReview, sharedActionReviewPath, sharedActionAllowsChallenge, CHAT_ACTIONS, } from "./chat-actions.js";
 import { isDirectChatProvider, subscriptionCredentialKey } from "./converse.js";
@@ -366,6 +367,8 @@ export function proposalPreview(store, proposal, repos, channel = null) {
         case "answer": {
             const id = typeof payload["decision"] === "number" ? payload["decision"] : null;
             const decision = id === null ? null : store.getDecision(id);
+            if (decision?.supersededReason != null)
+                return { text: closedQuestionWords(decision.supersededReason), buttons: false, closed: true };
             const pick = t("option", 64);
             const irreversible = payload["reversible"] === false;
             const body = decision === null

package/dist/chat-delivery.js

@@ -600,6 +600,8 @@ export function applyChatAction(options, event, binding, repos) {
         const phase = action.phase;
         if (proposal.state !== "pending")
             content = { text: proposalOutcomeText(proposal), edit: event.ts };
+        else if (preview.closed)
+            content = { text: preview.text, edit: event.ts };
         else if (!preview.buttons ||
             preview.text.length > (options.maxProposal ?? 10_000))
             content = { ...content, text: "Review this action in Toolroll." };

package/dist/contract-changes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The mechanical difference between two sets of contract terms — a task's goal, exclusions, touches and acceptance
+ * rubric. Pure and import-light, so both the planner's source (planner-source.ts) and scope filing (scope.ts, which
+ * restarts planning when the terms truly change) read the same comparison.
+ */
+import type { AcceptanceCriterion, EvidenceKind } from "./scope.js";
+/** The four contract fields a planner may propose to amend. */
+export type ContractTerms = {
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: AcceptanceCriterion[];
+};
+export type ContractChange = {
+    field: "goal";
+    kind: "changed";
+    before: string;
+    after: string;
+} | {
+    field: "outOfScope";
+    kind: "added" | "removed" | "changed";
+    before: string | null;
+    after: string | null;
+} | {
+    field: "touches";
+    kind: "added" | "removed";
+    path: string;
+} | {
+    field: "acceptance";
+    kind: "added" | "removed" | "changed";
+    id: string;
+    before: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    after: {
+        statement: string;
+        evidence: EvidenceKind[];
+        how: string | null;
+    } | null;
+    /** For `changed`: which parts moved. `how` is advisory and unsigned,
+     * but a planner rewriting it is still a change the operator sees. */
+    moved: ("statement" | "evidence" | "how")[];
+};
+/**
+ * Every addition, change, and removal between the filed contract and a
+ * proposed one. Whitespace at the ends and touch/evidence order do not
+ * count (the scope digest ignores them too); everything else does,
+ * including the advisory `how`, because the operator wrote it.
+ */
+export declare function contractChangesOf(filed: ContractTerms, proposed: ContractTerms): ContractChange[];

package/dist/contract-changes.js

@@ -0,0 +1,61 @@
+const trimmed = (text) => {
+    if (text === null)
+        return null;
+    const t = text.trim();
+    return t === "" ? null : t;
+};
+/**
+ * Every addition, change, and removal between the filed contract and a
+ * proposed one. Whitespace at the ends and touch/evidence order do not
+ * count (the scope digest ignores them too); everything else does,
+ * including the advisory `how`, because the operator wrote it.
+ */
+export function contractChangesOf(filed, proposed) {
+    const changes = [];
+    if (filed.goal.trim() !== proposed.goal.trim()) {
+        changes.push({ field: "goal", kind: "changed", before: filed.goal, after: proposed.goal });
+    }
+    const filedOut = trimmed(filed.outOfScope);
+    const proposedOut = trimmed(proposed.outOfScope);
+    if (filedOut !== proposedOut) {
+        changes.push({
+            field: "outOfScope",
+            kind: filedOut === null ? "added" : proposedOut === null ? "removed" : "changed",
+            before: filed.outOfScope,
+            after: proposed.outOfScope,
+        });
+    }
+    const filedTouches = new Set(filed.touches.map(one => one.trim()).filter(one => one !== ""));
+    const proposedTouches = new Set(proposed.touches.map(one => one.trim()).filter(one => one !== ""));
+    for (const path of filedTouches)
+        if (!proposedTouches.has(path))
+            changes.push({ field: "touches", kind: "removed", path });
+    for (const path of proposedTouches)
+        if (!filedTouches.has(path))
+            changes.push({ field: "touches", kind: "added", path });
+    const criterionOf = (one) => ({ statement: one.statement, evidence: [...one.evidence].sort(), how: one.how });
+    const filedById = new Map(filed.acceptance.map(one => [one.id, one]));
+    const proposedById = new Map(proposed.acceptance.map(one => [one.id, one]));
+    for (const [id, before] of filedById) {
+        const after = proposedById.get(id);
+        if (after === undefined) {
+            changes.push({ field: "acceptance", kind: "removed", id, before: criterionOf(before), after: null, moved: [] });
+            continue;
+        }
+        const moved = [];
+        if (before.statement.trim() !== after.statement.trim())
+            moved.push("statement");
+        if ([...before.evidence].sort().join(",") !== [...after.evidence].sort().join(","))
+            moved.push("evidence");
+        if (trimmed(before.how) !== trimmed(after.how))
+            moved.push("how");
+        if (moved.length > 0) {
+            changes.push({ field: "acceptance", kind: "changed", id, before: criterionOf(before), after: criterionOf(after), moved });
+        }
+    }
+    for (const [id, after] of proposedById) {
+        if (!filedById.has(id))
+            changes.push({ field: "acceptance", kind: "added", id, before: null, after: criterionOf(after), moved: [] });
+    }
+    return changes;
+}

package/dist/decision.d.ts

@@ -43,6 +43,10 @@ export declare const LIMITS: {
 };
 /** Bytes an operator's note may occupy — the UTF-8 backstop under LIMITS.note. */
 export declare const NOTE_BYTE_CAP: 16000;
+/** Why a question closed without an answer (v119), in plain words. */
+export declare function closedQuestionReason(reason: "scope-changed" | "cancelled"): string;
+/** The same, said once on one line wherever its answer would show. */
+export declare function closedQuestionWords(reason: "scope-changed" | "cancelled"): string;
 /**
  * The one validator every note passes — before a draft persists AND inside
  * the answer CAS, which stays the final gate. Trims, then refuses empty,

package/dist/decision.js

@@ -25,6 +25,14 @@ export const LIMITS = {
 };
 /** Bytes an operator's note may occupy — the UTF-8 backstop under LIMITS.note. */
 export const NOTE_BYTE_CAP = TEXT_LIMITS.noteBytes;
+/** Why a question closed without an answer (v119), in plain words. */
+export function closedQuestionReason(reason) {
+    return reason === "scope-changed" ? "The scope changed, so planning started again." : "The task was cancelled.";
+}
+/** The same, said once on one line wherever its answer would show. */
+export function closedQuestionWords(reason) {
+    return `Closed without an answer. ${closedQuestionReason(reason)}`;
+}
 /**
  * Unicode that reorders or breaks lines invisibly: bidi controls and the
  * line/paragraph separators. A note carrying these can spoof what a

package/dist/deploy-lock.d.ts

@@ -0,0 +1,8 @@
+/** Separate from orders.db: no live writer is reserved while deployment drains or backs up.
+ * SQLite owns the OS lock until close/process death, including SIGKILL. Never unlink this file:
+ * replacing its inode would let two contenders hold different locks for the same journal. */
+export type DeploymentLock = {
+    assertHeld(journalFile: string): void;
+    release(): void;
+};
+export declare function acquireDeploymentLock(journalFile: string, waitMs?: number): DeploymentLock;

package/dist/deploy-lock.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import { closeSync, constants, lstatSync, openSync, realpathSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+const canonical = (file) => join(realpathSync(dirname(file)), basename(file));
+export function acquireDeploymentLock(journalFile, waitMs = 5000) {
+    if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 5000)
+        throw Error("Invalid deployment lock wait.");
+    const journal = canonical(journalFile), file = `${journal}.lock.sqlite`;
+    // Only create a missing file. On POSIX, closing ANY independently opened descriptor
+    // for an existing inode can drop this process's fcntl lock, even another connection's.
+    // Let SQLite manage all descriptors for an existing coordination file.
+    try {
+        const fd = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+        closeSync(fd);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    if (!lstatSync(file).isFile())
+        throw Error(`Unexpected deployment lock: ${file}`);
+    // Lazy, as elsewhere in the CLI: merely importing the help must not load SQLite.
+    const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+    const db = new DatabaseSync(file);
+    try {
+        db.exec(`PRAGMA busy_timeout=${waitMs}; BEGIN EXCLUSIVE`);
+    }
+    catch (cause) {
+        db.close();
+        throw new Error(`Deployment is busy or its lock is unavailable: ${journal}. Let it finish, then retry.`, { cause });
+    }
+    let held = true;
+    return {
+        assertHeld(expected) {
+            if (!held || canonical(expected) !== journal)
+                throw Error("The deployment journal lock is not held.");
+        },
+        release() {
+            if (!held)
+                return;
+            db.close();
+            held = false;
+        },
+    };
+}

package/dist/dispatch.js

@@ -319,7 +319,7 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
         // this is where the task page says so.
         const sourceProblem = plannerSourceProblemOf(store, taskId);
         if (sourceProblem !== null)
-            return answer("planner-source", "waiting", "The filed request cannot be planned as filed", sourceProblem, { action: "write-scope", role });
+            return answer("planner-source", "waiting", sourceProblem.title, sourceProblem.detail, { action: "write-scope", role });
         return answer("planning-ready", "retrying", "Planner ready", "An eligible worker can draft the scope on the next pass.", { role });
     }
     if (role === "scout")

package/dist/lead-cli.js

@@ -1,4 +1,5 @@
 import { configureLeadFollow, leadFollowStatus } from './lead-follow.js';
+import { closedQuestionWords } from "./decision.js";
 /**
  * `toolroll chat` (mate arc §6): the same thread the console shows,
  * driven from a terminal. The password is typed once — it mints the lead
@@ -45,6 +46,8 @@ export function answerContextLines(store, payload) {
     const decision = id === null ? null : store.getDecision(id);
     if (decision === null)
         return ["     (the decision is gone)"];
+    if (decision.supersededReason !== null)
+        return [`     ${decision.question}`, `     ${closedQuestionWords(decision.supersededReason)}`];
     const pick = typeof payload["option"] === "string" ? payload["option"] : "";
     return [
         `     ${decision.question}${decision.state !== "open" ? ` [${decision.state}]` : ""}`,

package/dist/lead-doors.js

@@ -14,6 +14,7 @@ import { executeSharedAction, sharedActionPayload, sharedActionAllowsChallenge,
  * scope was rewritten, the decision answered) is a refusal, never a
  * silent re-read.
  */
+import { closedQuestionWords } from "./decision.js";
 import { isCheckLevel, setTaskCheckLevel } from "./check-levels.js";
 import { leadTurnKeepsProposals, verifiedAuthor } from "./store.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
@@ -317,6 +318,8 @@ function executeProposal(store, actor, kind, payload, now, options) {
             return refuse("stale", "that option no longer exists on the decision");
         // The proposal contract is "open": a decision past its deadline — swept
         // or not — is not answered through a card (v3 review, finding 7).
+        if (decision.supersededReason !== null)
+            return refuse("stale", closedQuestionWords(decision.supersededReason));
         if (decision.state === "answered")
             return refuse("already-answered", "already answered — somebody got there first");
         if (decision.state !== "open" || (decision.deadline !== null && Date.parse(decision.deadline) <= now.getTime())) {

package/dist/lead-tools.js

@@ -284,12 +284,13 @@ export function decisionOver(store, repos, decisionId, now) {
         return null;
     // "Open" is derived, not stored (v3 review, finding 7): a decision past
     // its deadline is expired here whether or not the sweep has run.
-    const state = decision.state === "open" && decision.deadline !== null && Date.parse(decision.deadline) <= now.getTime() ? "expired" : decision.state;
+    const state = decision.supersededReason !== null ? "closed" : decision.state === "open" && decision.deadline !== null && Date.parse(decision.deadline) <= now.getTime() ? "expired" : decision.state;
     return {
         repoIndex,
         decision: decision.id,
         task: ref.externalId,
         state,
+        ...(decision.supersededReason === null ? {} : { closedBecause: decision.supersededReason }),
         question: decision.question,
         options: decision.options.map(one => ({ id: one.id, label: one.label, reversible: one.reversible, consequence: one.consequence })),
         ageHours: Math.max(0, Math.round((now.getTime() - Date.parse(decision.createdAt)) / 3_600_000)),

package/dist/needs-you.js

@@ -20,7 +20,9 @@ export const NEEDS = {
     hold: { sentence: () => "A hold is keeping this task from starting. Review it to release it.", action: { code: "inspect-hold", label: "Review hold" } },
     "choose-project": { sentence: () => "Choose a project so a builder can start.", action: { code: "place-task", label: "Choose a project" } },
     "define-task": { sentence: () => "Say what the task should do so it can be planned.", action: { code: "write-scope", label: "Define the task" } },
-    "fix-request": { sentence: () => "The request can't be planned as written. Edit it so the planner can start.", action: { code: "write-scope", label: "Edit the request" } },
+    "fix-request": { sentence: () => "The request can't be planned as written. Edit it so the planner can start.", action: { code: "write-scope", label: "Edit the request" },
+        // Its own size and limit say exactly what to shorten.
+        useReason: reason => /the planner can carry at most/.test(reason) },
     "choose-agent": { sentence: () => "Choose an agent to build this.", action: { code: "select-agent", label: "Choose an agent" } },
     "fix-dependency": { sentence: () => "A task this one waits on didn't finish. Fix or remove it so this one can start.", action: { code: "repair-dependency", label: "Fix the required task" },
         useReason: reason => /didn't finish|did not finish|before it finished/i.test(reason), withReason: reason => `${reason.replace(/[.\s]*$/, ".")} Fix or remove it so this one can start.` },

package/dist/operate.js

@@ -106,7 +106,7 @@ import { spawn as spawnChild } from "node:child_process";
 // Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
 import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
 import { auditCommand } from "./audit-cli.js";
-import { hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
+import { closedQuestionWords, hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
 import { readVerifiedArtifact, readVerifiedReport, storeEvidence } from "./evidence.js";
 import { contractChangesOf, decodePlanContractRecord, describeContractChanges, encodePlannerSource, plannerSourceOf } from "./planner-source.js";
 /**
@@ -3721,7 +3721,7 @@ async function decideCommand(positional, flags, context) {
             write(envelopeJson({ ok: true, command: "decide", decision, taskId, evidence }));
             return EXIT.ok;
         }
-        write(`${taskId} — ${decision.state.toUpperCase()}${decision.deadline === null ? "" : ` · deadline ${decision.deadline}`}`);
+        write(`${taskId} — ${decision.supersededReason !== null ? "CLOSED" : decision.state.toUpperCase()}${decision.deadline === null ? "" : ` · deadline ${decision.deadline}`}`);
         write("");
         write(`  ${decision.recap}`);
         write("");
@@ -3739,7 +3739,9 @@ async function decideCommand(positional, flags, context) {
         }
         if (decision.state === "answered") {
             write("");
-            write(`  answered: ${decision.choice} by ${decision.answeredBy} at ${decision.answeredAt}${decision.note === null ? "" : ` — ${decision.note}`}`);
+            write(decision.supersededReason !== null
+                ? `  ${closedQuestionWords(decision.supersededReason)} (${decision.answeredAt})`
+                : `  answered: ${decision.choice} by ${decision.answeredBy} at ${decision.answeredAt}${decision.note === null ? "" : ` — ${decision.note}`}`);
         }
         if (evidence.length > 0) {
             write("");
@@ -3747,8 +3749,10 @@ async function decideCommand(positional, flags, context) {
                 write(`  evidence  ${artifact.kind.padEnd(14)} ${artifact.key}${artifact.truncated ? "  (truncated)" : ""}`);
             }
         }
-        write("");
-        write(`  → toolroll decide ${id} --choose <option> --as <you> --token <t>`);
+        if (decision.state !== "answered") {
+            write("");
+            write(`  → toolroll decide ${id} --choose <option> --as <you> --token <t>`);
+        }
         return EXIT.ok;
     }
     const acting = await askCredentials(flags, context);
@@ -3767,9 +3771,11 @@ async function decideCommand(positional, flags, context) {
             ? `"${choice}" is not one of this decision's options — \`toolroll decide ${id}\` shows them`
             : answered.reason === "already-answered"
                 ? `decision ${id} was already answered differently — "decided" is not negotiable; park a new task if the answer must change`
-                : answered.reason === "bad-note"
-                    ? "the note is too long or carries control characters"
-                    : `no decision ${id}`;
+                : answered.reason === "closed"
+                    ? `decision ${id}: ${closedQuestionWords(store.getDecision(id)?.supersededReason ?? "cancelled")} Nothing to answer.`
+                    : answered.reason === "bad-note"
+                        ? "the note is too long or carries control characters"
+                        : `no decision ${id}`;
         return fail(write, json, "decide", answered.reason, why, EXIT.refused);
     }
     return succeed(write, json, "decide", { decision: answered.decision, duplicate: answered.duplicate === true }, () => answered.duplicate === true
@@ -9707,6 +9713,7 @@ async function scopeTask(positional, flags, context) {
     // the mode seal record as a single operation —
     // a replayed key returns the FIRST answer whole instead of re-sealing
     // whatever scope happens to be current.
+    const generationBefore = store.lookupRef(id)?.planningGeneration ?? 0;
     const filed = store.replay(mutationFrom(flags, now), "task-scope-filed", () => store.transact(() => {
         const coverage = actor !== null
             ? modeFilingCoverage(store, store.refFor(BUILT_IN, id).repo, actor, now)
@@ -9763,8 +9770,12 @@ async function scopeTask(positional, flags, context) {
             ...describeScope(scope),
         ]);
     }
-    return succeed(write, json, "task scope", { scope }, () => [
-        `Scope written for ${id}. Nothing will build it until somebody approves it.`,
+    // A changed scope on a planning task plans again (v119): say so once, instead of leaving the old plan implied.
+    const replanned = (store.lookupRef(id)?.planningGeneration ?? 0) > generationBefore;
+    return succeed(write, json, "task scope", { scope, ...(replanned ? { planningRestarted: true } : {}) }, () => [
+        replanned
+            ? `Scope written for ${id}. The scope changed, so planning starts again; nothing builds until somebody approves the new plan.`
+            : `Scope written for ${id}. Nothing will build it until somebody approves it.`,
         ...describeScope(scope),
         "",
         `  toolroll task approve ${id} --yes`,

package/dist/password-bearer.d.ts

@@ -7,11 +7,11 @@
 import type { ServerResponse } from "node:http";
 /** The one replacement every machine-credential refusal names. */
 export declare const TOKEN_REPLACEMENT = "Create an API token with `toolroll tokens create`";
-/** The first release that refuses a password on a request: one release after this one (0.9.58) deprecated it. */
-export declare const PASSWORD_BEARER_REFUSED_FROM = "0.9.59";
-export declare const PASSWORD_BEARER_WARNING = "Signing in with a password on each request is deprecated and stops working in Toolroll 0.9.59. Create an API token with `toolroll tokens create` and send it as the bearer instead.";
+/** The first release that refuses a password on a request; 0.9.58 deprecated it with a warning. */
+export declare const PASSWORD_BEARER_REFUSED_FROM = "0.10.0";
+export declare const PASSWORD_BEARER_WARNING = "Signing in with a password on each request is deprecated and stops working in Toolroll 0.10.0. Create an API token with `toolroll tokens create` and send it as the bearer instead.";
 /** What the CLI says on stderr when a saved connection signs in with a password instead of an API token. */
-export declare const PASSWORD_PROFILE_WARNING = "Warning: this connection signs in with your password on each request, which is deprecated and stops working in Toolroll 0.9.59. Create an API token with `toolroll tokens create`, then connect again with --token-stdin.";
+export declare const PASSWORD_PROFILE_WARNING = "Warning: this connection signs in with your password on each request, which is deprecated and stops working in Toolroll 0.10.0. Create an API token with `toolroll tokens create`, then connect again with --token-stdin.";
 export declare const PASSWORD_BEARER_REFUSED = "Toolroll no longer accepts a password on a request. Create an API token with `toolroll tokens create` and send it as the bearer instead.";
 /** Whether an Authorization header is a password bearer: a name and a secret, never an API token. */
 export declare function isPasswordBearer(authorization: string | undefined): boolean;

package/dist/password-bearer.js

@@ -1,8 +1,8 @@
 import { PACKAGE_VERSION } from "./version.js";
 /** The one replacement every machine-credential refusal names. */
 export const TOKEN_REPLACEMENT = "Create an API token with `toolroll tokens create`";
-/** The first release that refuses a password on a request: one release after this one (0.9.58) deprecated it. */
-export const PASSWORD_BEARER_REFUSED_FROM = "0.9.59";
+/** The first release that refuses a password on a request; 0.9.58 deprecated it with a warning. */
+export const PASSWORD_BEARER_REFUSED_FROM = "0.10.0";
 export const PASSWORD_BEARER_WARNING = `Signing in with a password on each request is deprecated and stops working in Toolroll ${PASSWORD_BEARER_REFUSED_FROM}. ${TOKEN_REPLACEMENT} and send it as the bearer instead.`;
 /** What the CLI says on stderr when a saved connection signs in with a password instead of an API token. */
 export const PASSWORD_PROFILE_WARNING = `Warning: this connection signs in with your password on each request, which is deprecated and stops working in Toolroll ${PASSWORD_BEARER_REFUSED_FROM}. ${TOKEN_REPLACEMENT}, then connect again with --token-stdin.`;

package/dist/planner-source.d.ts

@@ -36,9 +36,10 @@
  * transactions of its own: the fenced finalizers in claim.ts seal.
  */
 import type { Store } from "./store.js";
-import type { AcceptanceCriterion, EvidenceKind, Scope } from "./scope.js";
+import type { Scope } from "./scope.js";
 import type { QualityMode } from "./quality.js";
 import type { RiskLevel } from "./phase-routing.js";
+import { type ContractChange, type ContractTerms } from "./contract-changes.js";
 export declare const PLANNER_SOURCE_VERSION = 1;
 export declare const PLANNER_SOURCE_LIMITS: {
     /** The whole recorded source before lossless prompt fencing. Equal to
@@ -49,13 +50,9 @@ export declare const PLANNER_SOURCE_LIMITS: {
     readonly amendment: 1000;
     /** Earlier answers quoted into the brief. */
     readonly answers: 5;
-};
-/** The four contract fields a planner may propose to amend. */
-export type ContractTerms = {
-    goal: string;
-    outOfScope: string | null;
-    touches: string[];
-    acceptance: AcceptanceCriterion[];
+    /** Terms that exceed the entire handoff cap cannot fit regardless of the plan's size. Do not reserve a maximum-
+     * sized plan here: a shorter document can carry larger valid terms. The final payload still enforces its byte cap. */
+    readonly handoffTerms: number;
 };
 export type PlannerContractScope = ContractTerms & {
     /** The filed row's digest — the exact bytes the terms carry today. */
@@ -154,7 +151,7 @@ export type PlannerSourceResult = {
     bytes: number;
 } | {
     ok: false;
-    reason: "no-task" | "revision-brief" | "oversized";
+    reason: "no-task" | "revision-brief" | "oversized" | "too-long";
     message: string;
 };
 /**
@@ -168,55 +165,28 @@ export declare function plannerSourceOf(store: Store, root: string, taskId: stri
 /**
  * The dispatch diagnosis's read of the same gate, from the store alone:
  * why the next pass would refuse to plan this task before spending — the
- * revision brief unreadable, or the filed request over the byte cap. The
- * size is a floor (the brief's stored bytes, before JSON quoting), so a
- * "yes" here is certain and the dispatch refusal itself stays the exact
- * word. Null when nothing here stands in the way.
+ * revision brief unreadable, the filed request over the byte cap, or terms
+ * the planner's handoff cannot carry. The size is a floor (the brief's
+ * stored bytes, before JSON quoting), so a "yes" here is certain and the
+ * dispatch refusal itself stays the exact word. Null when nothing here
+ * stands in the way.
+ */
+export declare function plannerSourceProblemOf(store: Store, taskId: string): {
+    title: string;
+    detail: string;
+} | null;
+/**
+ * Whether the planner can hand the filed terms back (contracts/plan.ts): it must reproduce the goal, exclusions,
+ * touches and criteria in its handoff, so terms its handoff cannot carry would end every attempt as a malformed plan.
+ * This names the problem before any workspace, run or provider spend instead: the actual size, the limit, and what to
+ * shorten. Null when the terms fit.
  */
-export declare function plannerSourceProblemOf(store: Store, taskId: string): string | null;
+export declare function plannerHandoffProblemOf(terms: ContractTerms): string | null;
 /** The exact bytes recorded as evidence; prompt fencing preserves the JSON value. */
 export declare function encodePlannerSource(source: PlannerSource): Buffer;
 /** Read a recorded source back; null when the bytes are not one. */
 export declare function decodePlannerSource(content: Buffer): PlannerSource | null;
-export type ContractChange = {
-    field: "goal";
-    kind: "changed";
-    before: string;
-    after: string;
-} | {
-    field: "outOfScope";
-    kind: "added" | "removed" | "changed";
-    before: string | null;
-    after: string | null;
-} | {
-    field: "touches";
-    kind: "added" | "removed";
-    path: string;
-} | {
-    field: "acceptance";
-    kind: "added" | "removed" | "changed";
-    id: string;
-    before: {
-        statement: string;
-        evidence: EvidenceKind[];
-        how: string | null;
-    } | null;
-    after: {
-        statement: string;
-        evidence: EvidenceKind[];
-        how: string | null;
-    } | null;
-    /** For `changed`: which parts moved. `how` is advisory and unsigned,
-     * but a planner rewriting it is still a change the operator sees. */
-    moved: ("statement" | "evidence" | "how")[];
-};
-/**
- * Every addition, change, and removal between the filed contract and a
- * proposed one. Whitespace at the ends and touch/evidence order do not
- * count (the scope digest ignores them too); everything else does,
- * including the advisory `how`, because the operator wrote it.
- */
-export declare function contractChangesOf(filed: ContractTerms, proposed: ContractTerms): ContractChange[];
+export { contractChangesOf, type ContractChange, type ContractTerms } from "./contract-changes.js";
 /** One line per change, for terminals, notifications, and validation messages. */
 export declare function describeContractChanges(changes: readonly ContractChange[]): string[];
 /**