toolroll 0.9.57 → 0.9.59

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

@@ -96,7 +96,8 @@ import { deleteProject, holdingsWords, projectHoldings, projectRunning } from ".
 import { pushPass } from "./push.js";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync } from "node:fs";
 import { BRANCH_PREFIX, envTwins, envValue, existingOrFirst, taskBranches } from "./names.js";
-import { claimActor, currentActor, parseLeadToken, withActor } from "./actor.js";
+import { claimActor, currentActor, withActor } from "./actor.js";
+import { parseLeadToken } from "./api-tokens.js";
 import { CLI_PASSWORD_SOURCE, withPasswordSource } from "./sign-in-guard.js";
 import { admissionRecorded, admitProject, commandLineActor } from "./project-admission.js";
 import { leadClaim, leadSay, noteLeadWork } from "./lead-voice.js";
@@ -105,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";
 /**
@@ -3720,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("");
@@ -3738,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("");
@@ -3746,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);
@@ -3766,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
@@ -9706,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)
@@ -9762,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

@@ -0,0 +1,27 @@
+/**
+ * D7: a password on each request (`Authorization: Bearer <name>:<password>`) is deprecated. This release still
+ * accepts it everywhere it was accepted, with the same per-address tries, locks and budgets, but every answer carries
+ * a deprecation warning, and every refusal of such a request names the replacement: an API token. From
+ * PASSWORD_BEARER_REFUSED_FROM on, the server refuses it before checking the password.
+ */
+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; 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.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;
+/** Whether this build still accepts a password bearer: only a release before PASSWORD_BEARER_REFUSED_FROM does. */
+export declare function passwordBearerAccepted(version?: string): boolean;
+/** A refusal's words for this request: unchanged, or with the replacement when it came with a password bearer. */
+export declare function withReplacement(authorization: string | undefined, message: string): string;
+/**
+ * The refusal boundary for one password-bearer request, whichever adapter answers it: the deprecation is announced in
+ * headers (RFC 9745 Deprecation, and a Warning naming the replacement), and any refusal's words, plain text or a JSON
+ * `message`, gain the replacement. Successful answers are left byte for byte.
+ */
+export declare function announcePasswordBearer(response: ServerResponse): void;

package/dist/password-bearer.js

@@ -0,0 +1,59 @@
+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; 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.`;
+export const PASSWORD_BEARER_REFUSED = `Toolroll no longer accepts a password on a request. ${TOKEN_REPLACEMENT} 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 function isPasswordBearer(authorization) {
+    return authorization !== undefined && /^Bearer (.+):(.+)$/.test(authorization) && !/^Bearer so_/.test(authorization);
+}
+const parts = (version) => (/^(\d+)\.(\d+)\.(\d+)/.exec(version) ?? [0, 0, 0, 0]).slice(1).map(Number);
+/** Whether this build still accepts a password bearer: only a release before PASSWORD_BEARER_REFUSED_FROM does. */
+export function passwordBearerAccepted(version = PACKAGE_VERSION) {
+    const have = parts(version), limit = parts(PASSWORD_BEARER_REFUSED_FROM);
+    for (let index = 0; index < 3; index++)
+        if (have[index] !== limit[index])
+            return have[index] < limit[index];
+    return false;
+}
+/** A refusal's words for this request: unchanged, or with the replacement when it came with a password bearer. */
+export function withReplacement(authorization, message) {
+    return !isPasswordBearer(authorization) || message.includes("toolroll tokens create") ? message : `${message} ${PASSWORD_BEARER_WARNING}`;
+}
+/**
+ * The refusal boundary for one password-bearer request, whichever adapter answers it: the deprecation is announced in
+ * headers (RFC 9745 Deprecation, and a Warning naming the replacement), and any refusal's words, plain text or a JSON
+ * `message`, gain the replacement. Successful answers are left byte for byte.
+ */
+export function announcePasswordBearer(response) {
+    response.setHeader("Deprecation", "true");
+    response.setHeader("Warning", `299 toolroll "${PASSWORD_BEARER_WARNING.replace(/"/g, "'")}"`);
+    const end = response.end.bind(response);
+    response.end = ((...args) => {
+        const [chunk] = args;
+        if (response.statusCode >= 400 && typeof chunk === "string" && !chunk.includes("toolroll tokens create"))
+            args[0] = annotated(chunk);
+        return end(...args);
+    });
+}
+function annotated(body) {
+    if (/^\s*\{/.test(body)) {
+        try {
+            const value = JSON.parse(body);
+            if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                const row = value;
+                if (typeof row["message"] === "string")
+                    return JSON.stringify({ ...row, message: `${row["message"]} ${PASSWORD_BEARER_WARNING}` });
+                if (typeof row["error_description"] === "string")
+                    return JSON.stringify({ ...row, error_description: `${row["error_description"]} ${PASSWORD_BEARER_WARNING}` });
+            }
+        }
+        catch { /* not JSON after all: plain text below */ }
+        return body;
+    }
+    return body.trimStart().startsWith("<") ? body : `${body.replace(/\s+$/, "")}\n${PASSWORD_BEARER_WARNING}`;
+}

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[];
 /**

package/dist/planner-source.js

@@ -38,6 +38,8 @@
 import { createHash } from "node:crypto";
 import { EVIDENCE_CAPS, readVerifiedArtifact } from "./evidence.js";
 import { TEXT_LIMITS } from "./text-limits.js";
+import { PLAN_TOUCHES } from "./contracts/plan.js";
+import { contractChangesOf } from "./contract-changes.js";
 export const PLANNER_SOURCE_VERSION = 1;
 export const PLANNER_SOURCE_LIMITS = {
     /** The whole recorded source before lossless prompt fencing. Equal to
@@ -48,6 +50,9 @@ export const PLANNER_SOURCE_LIMITS = {
     amendment: TEXT_LIMITS.planAmendment,
     /** Earlier answers quoted into the brief. */
     answers: 5,
+    /** 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. */
+    handoffTerms: TEXT_LIMITS.planPayloadBytes,
 };
 /** Stable JSON for hashing and equality only — no filling, no trimming. */
 export function canonicalContractJson(value) {
@@ -192,26 +197,55 @@ export function plannerSourceOf(store, root, taskId, answers) {
                 `(scope ${scopeBytes}, revision brief ${briefBytes}); nothing is trimmed silently — shorten the scope or brief, then plan again`,
         };
     }
+    const handoff = source.contract.scope === null ? null : plannerHandoffProblemOf(source.contract.scope);
+    if (handoff !== null)
+        return { ok: false, reason: "too-long", message: handoff };
     return { ok: true, source, bytes };
 }
 /**
  * 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 function plannerSourceProblemOf(store, taskId) {
+    const filed = (detail) => ({ title: "The filed request cannot be planned as filed", detail });
     if (store.answeredDecisionsFor(taskId, PLANNER_SOURCE_LIMITS.answers + 1).length > PLANNER_SOURCE_LIMITS.answers)
-        return `more than ${PLANNER_SOURCE_LIMITS.answers} answered decisions exceed the planner history bound; file a follow-up task with the consolidated decisions`;
+        return filed(`more than ${PLANNER_SOURCE_LIMITS.answers} answered decisions exceed the planner history bound; file a follow-up task with the consolidated decisions`);
     const contract = plannerContractOf(store, taskId);
     if (!contract.ok)
-        return contract.message;
+        return filed(contract.message);
     const briefBytes = contract.contract.revision === null ? 0 : (store.getArtifact(contract.contract.revision.briefArtifact)?.bytesStored ?? 0);
     const floor = Buffer.byteLength(JSON.stringify(contract.contract, null, 2), "utf8") + briefBytes;
     if (floor > PLANNER_SOURCE_LIMITS.bytes) {
-        return `the filed request is at least ${floor} bytes — over the ${PLANNER_SOURCE_LIMITS.bytes}-byte planner source cap; shorten the scope or brief before planning`;
+        return filed(`the filed request is at least ${floor} bytes — over the ${PLANNER_SOURCE_LIMITS.bytes}-byte planner source cap; shorten the scope or brief before planning`);
+    }
+    const handoff = contract.contract.scope === null ? null : plannerHandoffProblemOf(contract.contract.scope);
+    return handoff === null ? null : { title: "Scope too long to plan", detail: handoff };
+}
+/**
+ * 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 function plannerHandoffProblemOf(terms) {
+    const n = (value) => value.toLocaleString("en-US");
+    for (const [label, is, text] of [["goal", "is", terms.goal], ["exclusions", "are", terms.outOfScope ?? ""]]) {
+        if (text.length > TEXT_LIMITS.goal)
+            return `The ${label} ${is} ${n(text.length)} characters; the planner can carry at most ${n(TEXT_LIMITS.goal)}. Shorten the ${label} and planning starts again.`;
+    }
+    if (terms.touches.length > PLAN_TOUCHES)
+        return `The scope lists ${n(terms.touches.length)} paths; the planner can carry at most ${PLAN_TOUCHES}. List fewer paths and planning starts again.`;
+    const path = terms.touches.find(one => one.length > TEXT_LIMITS.planTouch);
+    if (path !== undefined)
+        return `A path is ${n(path.length)} characters; the planner can carry at most ${n(TEXT_LIMITS.planTouch)}. Shorten it and planning starts again.`;
+    const bytes = Buffer.byteLength(JSON.stringify({ goal: terms.goal, outOfScope: terms.outOfScope, touches: terms.touches, acceptance: terms.acceptance }), "utf8");
+    if (bytes > PLANNER_SOURCE_LIMITS.handoffTerms) {
+        return `The goal, exclusions, paths and criteria are ${n(bytes)} bytes together; the planner can carry at most ${n(PLANNER_SOURCE_LIMITS.handoffTerms)} bytes in its whole handoff. Shorten the scope and planning starts again.`;
     }
     return null;
 }
@@ -257,67 +291,8 @@ export function decodePlannerSource(content) {
         return null;
     }
 }
-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;
-}
+// ---- amendments -----------------------------------------------------------
+export { contractChangesOf } from "./contract-changes.js";
 const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
 /** One line per change, for terminals, notifications, and validation messages. */
 export function describeContractChanges(changes) {

package/dist/release-gate.d.ts

@@ -1,8 +1,7 @@
 /**
  * `toolroll release --release-gate <id>`: lift one update pause that a browser deployment (scripts/deploy-browser.mjs)
- * left behind when it stopped before the swap and its own recovery could not tell. The typical case is a deployment
- * killed between installing the pause and journaling that it had: the journal still says `preparing`, so
- * `--phase recover` leaves the pause alone, and new work stays paused.
+ * left behind when it stopped before the swap and its own exit recovery never ran. The typical case is a deployment
+ * killed outright (SIGKILL, a crash or power loss) while paused: nothing lifted the pause, and new work stays paused.
  *
  * The id alone proves nothing, and neither does the journal's phase. The pause is lifted only when every piece of
  * evidence agrees that the service was never swapped:

package/dist/release-gate.js

@@ -1,8 +1,7 @@
 /**
  * `toolroll release --release-gate <id>`: lift one update pause that a browser deployment (scripts/deploy-browser.mjs)
- * left behind when it stopped before the swap and its own recovery could not tell. The typical case is a deployment
- * killed between installing the pause and journaling that it had: the journal still says `preparing`, so
- * `--phase recover` leaves the pause alone, and new work stays paused.
+ * left behind when it stopped before the swap and its own exit recovery never ran. The typical case is a deployment
+ * killed outright (SIGKILL, a crash or power loss) while paused: nothing lifted the pause, and new work stays paused.
  *
  * The id alone proves nothing, and neither does the journal's phase. The pause is lifted only when every piece of
  * evidence agrees that the service was never swapped:
@@ -23,6 +22,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { durableJson } from "./desktop-update.js";
 import { removeUpdateGate, updateGateOwned } from "./desktop-update-gate.js";
+import { acquireDeploymentLock } from "./deploy-lock.js";
 /** The journal phases a deployment passes before it stops the old service (deploy-phases.mjs). */
 export const BEFORE_SWAP = Object.freeze(["preparing", "admission-paused", "frozen", "backup-verified", "rehearsed"]);
 /** Journal fields that only the swap and later phases write. */
@@ -129,22 +129,50 @@ export function proveBeforeSwap(id, world) {
 }
 /** Prove, then (with `yes`) lift exactly that pause and journal the release in the deployment's own journal. */
 export function releaseGate(id, world, yes) {
-    const proved = proveBeforeSwap(id, world);
-    if (!proved.ok)
-        return proved;
+    // Discovery is not authority to remove anything. Dry-run remains read-only, even for legacy stages.
+    const discovered = proveBeforeSwap(id, world);
+    if (!discovered.ok)
+        return discovered;
     if (!yes)
-        return { ok: true, released: false, id, stage: proved.stage, proof: proved.proof };
-    const db = world.open();
-    // removeUpdateGate checks the owner again inside its own write: a pause that changed hands is not touched.
+        return { ok: true, released: false, id, stage: discovered.stage, proof: discovered.proof };
+    const journalFile = join(discovered.stage, "deployment.json");
+    let lock;
     try {
-        removeUpdateGate(db, id);
+        lock = acquireDeploymentLock(journalFile);
+    }
+    catch (error) {
+        return refuse("deploying", error.message);
+    }
+    try {
+        const proved = proveBeforeSwap(id, world);
+        if (!proved.ok)
+            return proved;
+        if (proved.stage !== discovered.stage)
+            return refuse("conflict", "The deployment stage changed during release.");
+        const db = world.open();
+        try {
+            // Repeat the entire proof at the mutation boundary, under the same exclusion as deploy/resume/recover.
+            const fresh = proveBeforeSwap(id, world);
+            if (!fresh.ok)
+                return fresh;
+            if (fresh.stage !== proved.stage || JSON.stringify(fresh.journal) !== JSON.stringify(proved.journal) ||
+                JSON.stringify(JSON.parse(readFileSync(journalFile, "utf8"))) !== JSON.stringify(fresh.journal)) {
+                return refuse("conflict", "The deployment journal changed during release.");
+            }
+            lock.assertHeld(journalFile);
+            // The owner is checked again within removeUpdateGate's short write transaction.
+            removeUpdateGate(db, id);
+            durableJson(journalFile, {
+                ...fresh.journal, phase: "released", updatedAt: world.now().toISOString(),
+                releasedBeforeSwap: { at: world.now().toISOString(), by: "toolroll release --release-gate", from: fresh.journal.phase, proof: fresh.proof },
+            });
+            return { ok: true, released: true, id, stage: fresh.stage, proof: fresh.proof };
+        }
+        finally {
+            db.close();
+        }
     }
     finally {
-        db.close();
+        lock.release();
     }
-    durableJson(join(proved.stage, "deployment.json"), {
-        ...proved.journal, phase: "released", updatedAt: world.now().toISOString(),
-        releasedBeforeSwap: { at: world.now().toISOString(), by: "toolroll release --release-gate", from: proved.journal.phase, proof: proved.proof },
-    });
-    return { ok: true, released: true, id, stage: proved.stage, proof: proved.proof };
 }

package/dist/remote-command.js

@@ -34,8 +34,6 @@ export const REMOTE_PATH_ARGUMENTS = [
     ...['link', 'unlink'].map(invocation => ({ invocation, argument: { flag: '--to' }, policy: 'refuse' })),
     ...['repos add', 'repos remove', 'pulls', 'graph', ''].map(invocation => ({ invocation, argument: { position: 0, name: 'path', rest: true }, policy: 'refuse' })),
     { invocation: 'project use', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
-    // These local HTTP clients read prompts themselves; they do not consume runOperateAs's files map.
-    ...['session start', 'session send'].map(invocation => ({ invocation, argument: { flag: '--file' }, policy: 'refuse' })),
 ];
 /**
  * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a

package/dist/remote-exec.d.ts

@@ -1,4 +1,5 @@
 import { type TeamCliOptions } from './team-cli.js';
+import { type CliRequest } from './cli-http.js';
 import { type RemoteCommandLookup } from './remote-command.js';
 export { contractRow, STEP_UP_MESSAGE, type RemoteMode } from './remote-command.js';
 export type RemoteExecOptions = TeamCliOptions & {
@@ -9,6 +10,24 @@ export type RemoteExecOptions = TeamCliOptions & {
     /** Injected by tests: the contract row lookup (default: COMMAND_GUIDE's `remote` field). */
     modeOf?: RemoteCommandLookup;
 };
+type Answer = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type Outcome = {
+    kind: 'answer';
+    answer: Answer;
+} | {
+    kind: 'refused';
+    status: number;
+    code: string;
+    message: string;
+} | {
+    kind: 'unconfirmed';
+};
+/** One request, never retried. */
+export declare function postCli(origin: string, token: string, request: CliRequest, options: RemoteExecOptions): Promise<Outcome>;
 /**
  * null: run locally with argv unchanged. `{ local }`: run locally with this argv (`--local` removed).
  * A number: the command ran remotely (or was refused before sending) and this is its exit code.