@bli-cockpit/mcp 0.1.3 → 0.1.4

package/README.md

@@ -34,7 +34,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**39 of 57 Tower verbs have an MCP twin.**
+**56 of 57 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -44,7 +44,9 @@ three tables below.
 | --- | --- | --- |
 | `cockpit brief history` | `brief_history` | `GET /api/jarvis/brief?history=1` |
 | `cockpit brief read` | `brief_read` | `GET /api/jarvis/brief` |
+| `cockpit brief rewrite` | `brief_rewrite` | `POST /api/jarvis/recompile` |
 | `cockpit brief status` | `brief_status` | `GET /api/ops/brief-status` |
+| `cockpit correct` | `brief_correct` | `POST /api/jarvis/corrections` |
 | `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
 | `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
 | `cockpit docs read` | `docs_read` | `GET /api/docs/documents/[id]` |
@@ -59,6 +61,7 @@ three tables below.
 | `cockpit issue update` | `work_update_issue` | `PATCH /api/work/issues/[id]` |
 | `cockpit jarvis` | `jarvis_ask` | `POST /api/jarvis/cli` |
 | `cockpit jarvis --trace` | `jarvis_trace` | `GET /api/ops/trace/[id]` |
+| `cockpit model set` | `model_set` | `POST /api/settings/jarvis-model` |
 | `cockpit model show` | `model_show` | `GET /api/settings/jarvis-model` |
 | `cockpit msg channels` | `msg_channels` | `GET /api/msg/channels` |
 | `cockpit msg create` | `msg_create_channel` | `POST /api/msg/channels` |
@@ -67,44 +70,40 @@ three tables below.
 | `cockpit msg send` | `msg_send` | `POST /api/msg/channels/[id]/messages` |
 | `cockpit msg thread` | `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` |
 | `cockpit notes list` | `notes_list` | `GET /api/notes/library` |
+| `cockpit notes move` | `notes_move` | `POST /api/notes/move` |
+| `cockpit notes paste` | `notes_paste` | `POST /api/notes/upload (text)` |
+| `cockpit notes share` | `notes_share` | `POST /api/notes/share` |
 | `cockpit notes shelf` | `notes_shelf` | `GET /api/notes/shelf` |
 | `cockpit notes shelves` | `notes_shelves` | `GET /api/notes/library` |
 | `cockpit notes show` | `notes_show` | `GET /api/notes/library/[id]` |
+| `cockpit notes unshare` | `notes_unshare` | `POST /api/notes/share (share=false)` |
+| `cockpit notes upload` | `notes_upload` | `POST /api/notes/upload` |
+| `cockpit ops recompile` | `ops_recompile` | `POST /api/ops/recompile` |
 | `cockpit ops status` | `ops_status` | `GET /api/ops/status` |
 | `cockpit project list` | `work_list_projects` | `GET /api/work/projects` |
 | `cockpit scout board` | `scout_board` | `GET /api/cockpit/scout` |
+| `cockpit scout dismiss` | `scout_dismiss` | `POST /api/cockpit/scout (dismiss)` |
+| `cockpit scout start` | `scout_start` | `POST /api/cockpit/scout (start)` |
+| `cockpit scout undo` | `scout_undo` | `POST /api/cockpit/scout (undo_dismiss)` |
 | `cockpit search` | `tower_search` | `GET /api/search` |
+| `cockpit settings delete` | `settings_delete` | `DELETE /api/settings/env-blobs` |
 | `cockpit settings list` | `settings_list` | `GET /api/settings/env-blobs` |
+| `cockpit settings set` | `settings_set` | `POST /api/settings/{jarvis-model,switches,model-routing,env-blobs} + PUT /api/settings/cli-floor` |
 | `cockpit settings show` | `settings_show` | `GET /api/settings/* + /api/team/members` |
 | `cockpit slack coverage` | `slack_coverage` | `GET /api/ops/slack/coverage` |
 | `cockpit slack read` | `slack_read` | `POST /api/ops/slack/read` |
 | `cockpit team device-list` | `team_device_list` | `GET /api/team/devices` |
+| `cockpit team device-revoke` | `team_device_revoke` | `POST /api/ambient/devices/[deviceId]/revoke` |
+| `cockpit team invite` | `team_invite` | `POST /api/team/invite` |
 | `cockpit team members` | `team_members` | `GET /api/team/members` |
+| `cockpit team role` | `team_role` | `PATCH /api/team/members/[userId]/role` |
 | `cockpit workbook` | `workbook_read` | `GET /api/cockpit/workbook` |
 
 ### Owed a twin
 
 This table should only ever shrink.
 
-| CLI verb | Who owes it, and why it is not built yet |
-| --- | --- |
-| `cockpit brief rewrite` | BLI-3756 batch 2 — spends a model call; wants its own gate on this surface |
-| `cockpit correct` | BLI-3756 batch 2 — filing a correction against a claim has no tool |
-| `cockpit model set` | BLI-3756 batch 2 — a shorthand over settings personal; follows settings |
-| `cockpit notes move` | BLI-3756 batch 2 — needs a signed-in session server-side; reachable, just unwritten |
-| `cockpit notes paste` | BLI-3756 batch 2 — the CLI takes the body on stdin; a tool would take it as an argument |
-| `cockpit notes share` | BLI-3756 batch 2 — a deliberate act; wants an explicit confirmation on this surface |
-| `cockpit notes unshare` | BLI-3756 batch 2 — same gate as notes share |
-| `cockpit notes upload` | BLI-3756 batch 2 — takes local file paths, which an MCP server on the same machine can also read |
-| `cockpit ops recompile` | BLI-3756 batch 2 — spends a model call; wants its own gate on this surface |
-| `cockpit scout dismiss` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
-| `cockpit scout start` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
-| `cockpit scout undo` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
-| `cockpit settings delete` | BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface |
-| `cockpit settings set` | BLI-3756 batch 2 — mostly reachable, but env CONTENT is stdin-only by rule; a tool must keep that |
-| `cockpit team device-revoke` | BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface |
-| `cockpit team invite` | BLI-3756 batch 2 — super_admin; a tool would relay, not decide |
-| `cockpit team role` | BLI-3756 batch 2 — super_admin; a tool would relay, not decide |
+_Nothing. Every Tower verb an agent could want has a door (BLI-3756)._
 
 ### Terminal-only
 
@@ -192,10 +191,52 @@ generated table above; what is worth knowing before you call one:
   standing sentences, and a truncated read saying so) and the per-project
   document library, rendered by the same walker the page uses.
 
-Writes — `brief rewrite`, `correct`, `notes move|share|unshare|paste|upload`,
-`ops recompile`, `scout start|dismiss|undo`, `settings set|delete`,
-`team invite|role|device-revoke`, `model set` — are batch 2, each with the
-reason it waited in the generated "Owed a twin" table.
+## The write tools (BLI-3756 batch 2)
+
+The seventeen things a person can DO from `cockpit` and could not do from an
+agent. Same doors, same device token, same refusal words — plus one rule the
+reads never needed:
+
+**An act that cannot be undone is refused without `confirm: true`.** The CLI's
+gate is `--yes` or a person at a keyboard; a client has no keyboard, so the
+explicit flag is the whole of it here, and the reason label is the CLI's own
+`confirmation_required`. It guards `notes_share` (sharing lets everyone signed
+in read the note), `settings_delete`, `team_role` and `team_device_revoke`.
+Taking a share BACK asks for nothing — nobody needs to be talked out of
+narrowing who can read something.
+
+- **`brief_rewrite` / `brief_correct`** — ask for a page to be written again,
+  and say that one line on it is wrong. `brief_rewrite` QUEUES and returns the
+  request id immediately; it does not wait, because an 800-second compile
+  outlives any client deadline and "the tool timed out" would be
+  indistinguishable from "the compile failed". `brief_correct` refuses a claim
+  id the page does not carry BEFORE writing, and Tower's push-back ("the record
+  disagrees") is a normal result — the correction is filed either way.
+- **`notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+  `notes_move`** — put a note in from this machine's disk or from text, share
+  it, take it back, move it to another shelf. A path whose NAME looks like a
+  key or credential file is refused without being opened; so is a missing,
+  empty or over-20-MB file. A large note is one model call server-side and can
+  take minutes — your client may give up first, and the upload keeps going.
+- **`ops_recompile`** — write one person's page again. It spends a model call;
+  `dry_run: true` resolves the person and reads the current page without
+  compiling. If Tower's own 800-second budget runs out the effect is UNKNOWN,
+  not failed, and it says so rather than inviting you to pay twice.
+- **`scout_start` / `scout_dismiss` / `scout_undo`** — move one card. Each
+  reads the board first, matches the id EXACTLY (no prefixes on this surface —
+  a near-miss would settle a card nobody decided on), and a 403 names the gate
+  without costing you the read.
+- **`settings_set` / `settings_delete` / `model_set`** — write one settings
+  section, delete an env file, or just change which model answers you. Env
+  content is an argument here rather than stdin (a tool call has no argv, no
+  shell history and no process list), and the rule that survives is the one
+  that mattered: it is **never echoed back** — not in the answer, not in the
+  structured payload, not in a log.
+- **`team_invite` / `team_role` / `team_device_revoke`** — invite somebody,
+  change a role, end a machine's pairing. All three relay a super_admin
+  decision made on the server. `team_device_revoke` looks the device up and
+  names it back to you first; without `confirm: true` that naming IS the
+  answer and nothing is revoked.
 
 ## `docs_*` / `msg_*` tools (BLI-3706)
 
@@ -205,7 +246,7 @@ reason it waited in the generated "Owed a twin" table.
 | `docs_tree` | `GET /api/docs/tree` | The library as its nesting rather than a flat list. Never a body. |
 | `docs_read` | `GET /api/docs/documents/[id]` | One document's title and full body, by id or slug (resolved against `docs_list` first). |
 | `docs_create` | `POST /api/docs/documents` | Creates a document. Omitting `body_markdown` creates an empty one. |
-| `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). |
+| `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). Emptying a document that holds text needs `allow_empty: true` (BLI-3757's guard). |
 | `msg_channels` | `GET /api/msg/channels` | Every channel you are a member of. |
 | `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, newest first. `channel` is an id or a `#name`. |
 | `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` | One thread's replies, oldest first, so it reads as a conversation. |

package/dist/agent-door.d.ts

@@ -12,4 +12,11 @@ export interface AgentDoorResponse {
     /** Set only when no JSON answer was produced at all — DNS, TLS, timeout, non-JSON body. */
     transportError: string | null;
 }
-export declare function callAgentDoor(session: AgentDoorSession, fetchImpl: FetchImpl, method: "GET" | "POST" | "PATCH", path: string, body?: unknown, timeoutMs?: number): Promise<AgentDoorResponse>;
+/**
+ * The four verbs Tower's agent doors answer to. `PUT` is the CLI floor
+ * (`PUT /api/settings/cli-floor`) and `DELETE` is an env blob — both arrived
+ * with BLI-3756 batch 2, and both are the door's own choice of verb, not this
+ * package's.
+ */
+export type AgentDoorMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+export declare function callAgentDoor(session: AgentDoorSession, fetchImpl: FetchImpl, method: AgentDoorMethod, path: string, body?: unknown, timeoutMs?: number): Promise<AgentDoorResponse>;

package/dist/agent-door.js

@@ -9,16 +9,21 @@ export async function callAgentDoor(session, fetchImpl, method, path, body, time
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     timer.unref?.();
+    // A note goes in as multipart, exactly as `cockpit notes upload` sends it,
+    // so `content-type` must be left to fetch: it is the only thing that knows
+    // the boundary it just generated, and a hand-set JSON header would make the
+    // route read an empty form.
+    const multipart = typeof FormData !== "undefined" && body instanceof FormData;
     let response;
     try {
         response = await fetchImpl(url, {
             method,
             headers: {
                 authorization: `Bearer ${session.deviceToken}`,
-                "content-type": "application/json",
+                ...(multipart ? {} : { "content-type": "application/json" }),
                 accept: "application/json",
             },
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            ...(body === undefined ? {} : { body: multipart ? body : JSON.stringify(body) }),
             signal: controller.signal,
         });
     }

package/dist/brief-write-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `brief_rewrite` / `brief_correct` MCP tools (BLI-3756 batch 2) — the two
+ * things a person can DO to the daily page, over the same doors
+ * `cockpit brief rewrite` and `cockpit correct` call with the same device
+ * token.
+ *
+ * Reads live in `brief-tools.ts`; these two write, and each carries one
+ * judgement the read side never has to make.
+ *
+ * **`brief_rewrite` asks and does not wait.** The CLI queues the compile and
+ * then watches the page for up to fifteen minutes, because a terminal can sit
+ * there. A tool call cannot: the client's own deadline would cut the call
+ * long before an 800-second compile finished, and "the tool timed out" is
+ * indistinguishable from "the compile failed" — the exact confusion this repo
+ * keeps paying for. So this tool sends `mode: "queue"`, reports the request id
+ * the moment it exists, and says in its own answer that the page is not
+ * written yet and `brief_read` is how to find out. That is the CLI's
+ * `--no-wait` shape, chosen deliberately and named out loud rather than
+ * silently.
+ *
+ * **`brief_correct` treats push-back as the answer, not an error.** The
+ * corrections door checks the claim against the live record BEFORE writing and
+ * can answer that the record disagrees. That sentence is what the caller came
+ * for: the correction WAS filed, with its outcome recorded, so it comes back
+ * as a normal result. Only a failure to file at all is an error.
+ *
+ * A claim id the page does not carry is refused HERE, before any write, in the
+ * CLI's own words — filing it anyway would land a correction on a clause
+ * nobody can find, which is how a ledger fills with rows that mean nothing.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type BriefWriteDeps = ToolDeps;
+/** The same ceiling `cockpit correct` enforces before it sends anything. */
+export declare const MAX_CORRECTION_LENGTH = 4000;
+export declare function registerBriefWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: BriefWriteDeps): void;

package/dist/brief-write-tools.js

@@ -0,0 +1,178 @@
+/**
+ * `brief_rewrite` / `brief_correct` MCP tools (BLI-3756 batch 2) — the two
+ * things a person can DO to the daily page, over the same doors
+ * `cockpit brief rewrite` and `cockpit correct` call with the same device
+ * token.
+ *
+ * Reads live in `brief-tools.ts`; these two write, and each carries one
+ * judgement the read side never has to make.
+ *
+ * **`brief_rewrite` asks and does not wait.** The CLI queues the compile and
+ * then watches the page for up to fifteen minutes, because a terminal can sit
+ * there. A tool call cannot: the client's own deadline would cut the call
+ * long before an 800-second compile finished, and "the tool timed out" is
+ * indistinguishable from "the compile failed" — the exact confusion this repo
+ * keeps paying for. So this tool sends `mode: "queue"`, reports the request id
+ * the moment it exists, and says in its own answer that the page is not
+ * written yet and `brief_read` is how to find out. That is the CLI's
+ * `--no-wait` shape, chosen deliberately and named out loud rather than
+ * silently.
+ *
+ * **`brief_correct` treats push-back as the answer, not an error.** The
+ * corrections door checks the claim against the live record BEFORE writing and
+ * can answer that the record disagrees. That sentence is what the caller came
+ * for: the correction WAS filed, with its outcome recorded, so it comes back
+ * as a normal result. Only a failure to file at all is an error.
+ *
+ * A claim id the page does not carry is refused HERE, before any write, in the
+ * CLI's own words — filing it anyway would land a correction on a clause
+ * nobody can find, which is how a ledger fills with rows that mean nothing.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** The same ceiling `cockpit correct` enforces before it sends anything. */
+export const MAX_CORRECTION_LENGTH = 4000;
+/** A rewrite queues in seconds; the compile it queues takes minutes. */
+const QUEUE_DEADLINE_MS = 60_000;
+const SUBJECT = z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Whose page — a name, email or person id. Omit for your own. Changes the SUBJECT, never who is asking.");
+/**
+ * Which page, and whose. The same read both verbs open with, and the only way
+ * either learns the person id the write doors need.
+ */
+async function readPage(deps, session, params) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/jarvis/brief?${params.toString()}`, undefined, QUEUE_DEADLINE_MS);
+    if (!response.ok)
+        return { ok: false, text: doorFailureText("brief", response) };
+    const body = response.body;
+    if (!body.ok || !body.page?.personId) {
+        return {
+            ok: false,
+            text: body.reply ?? "There is no page here to work on yet. The first one is compiled by the daily job.",
+        };
+    }
+    return { ok: true, body };
+}
+export function registerBriefWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("brief_rewrite", {
+        title: "Ask for a Tower daily page to be written again",
+        description: "Queues a recompile of the TODAY page — the website's button and `cockpit brief rewrite`, same door. It spends "
+            + "a model call and takes several minutes, so this tool ASKS and returns the request id immediately; it does "
+            + "not wait. Read the result later with brief_read. An admin may ask about anybody; everyone else about their "
+            + "own page, decided on the server.",
+        inputSchema: { subject: SUBJECT },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams({ tldr: "1" });
+        if (args.subject)
+            params.set("p", String(args.subject));
+        const page = await readPage(deps, session, params);
+        if (!page.ok)
+            return errorResult(page.text);
+        const personId = page.body.page?.personId;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/recompile", { personIds: [personId], mode: "queue" }, QUEUE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_rewrite", response));
+        const answer = response.body;
+        const request = (answer.queued ?? [])[0];
+        if (!answer.ok || !request?.requestId) {
+            return errorResult(answer.reply ?? "Tower did not accept that ask.");
+        }
+        const whose = request.name ?? page.body.page?.displayName ?? "that page";
+        const scheduled = answer.compileScheduled !== false;
+        // Queue-only, said as queue-only. The ask is a real row; what is
+        // missing is somebody to run it in the next minute, and pretending
+        // otherwise would leave a caller watching a page that was never going
+        // to change.
+        const sentence = scheduled
+            ? `Asked. ${whose} is being written again — this takes a few minutes. Call brief_read then; nothing here waits for it.`
+            : `${whose} is on the list to be written again, but this Tower could not start the work now `
+                + `(${answer.compileReason ?? "no reason given"}). The daily compile will reach it. Nothing is lost.`;
+        return textResult(sentence, {
+            ok: true,
+            outcome: scheduled ? "queued" : "queued_only",
+            requestId: request.requestId,
+            personId,
+            compileScheduled: scheduled,
+            compileReason: answer.compileReason ?? null,
+        });
+    }));
+    register("brief_correct", {
+        title: "Say that one line on a Tower page is wrong",
+        description: "Files a correction against ONE claim on the daily page — `cockpit correct`, same door and same ledger. Get "
+            + "claim ids from brief_read with `claims: true`. Tower checks the claim against the live record before "
+            + "writing and may answer that the record disagrees; that push-back is the RESULT, not a failure — the "
+            + "correction is filed either way, with its outcome recorded.",
+        inputSchema: {
+            claim_id: z.string().min(1).max(200).describe("A claim id from brief_read({claims: true})."),
+            text: z
+                .string()
+                .min(1)
+                .max(MAX_CORRECTION_LENGTH)
+                .describe("What is wrong, and what is true instead."),
+            subject: SUBJECT,
+            version: z.string().min(1).max(100).optional().describe("Correct one exact stored page id instead of the newest."),
+            supersedes: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("A correction on the same clause that this one takes back."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const claimId = String(args.claim_id ?? "");
+        const params = new URLSearchParams({ claims: "1" });
+        if (args.subject)
+            params.set("p", String(args.subject));
+        if (args.version)
+            params.set("v", String(args.version));
+        const page = await readPage(deps, session, params);
+        if (!page.ok)
+            return errorResult(page.text);
+        const claim = (page.body.claims ?? []).find((candidate) => candidate.claimId === claimId);
+        if (!claim) {
+            return errorResult(`Refused (unknown_claim): that page has no line called “${claimId}”. `
+                + "Call brief_read with `claims: true` to see the ids. Nothing was filed.");
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/corrections", {
+            personId: page.body.page?.personId,
+            pageId: page.body.page?.pageId ?? null,
+            claimId,
+            // The line as it reads now, so the ledger records what was
+            // disputed and the live check has the sentence to work from.
+            quotedText: claim.text ?? null,
+            correctionText: String(args.text ?? ""),
+            contextLinks: claim.links ?? [],
+            clauseOnPage: true,
+            clauseIsObserved: Boolean(claim.observed),
+            ...(args.supersedes ? { supersedes: String(args.supersedes) } : {}),
+        }, QUEUE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_correct", response));
+        const filed = response.body;
+        if (!filed.correctionId) {
+            return errorResult(filed.error ?? "Tower did not record that correction.");
+        }
+        const said = [
+            filed.reply ?? "Filed.",
+            filed.finding ? `The record says: ${filed.finding}` : "",
+            filed.link ?? "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return textResult(said, {
+            ok: true,
+            correctionId: filed.correctionId,
+            tier: filed.tier ?? null,
+            outcome: filed.outcome ?? null,
+            pushBack: filed.pushBack ?? null,
+            finding: filed.finding ?? null,
+            link: filed.link ?? null,
+        });
+    }));
+}

package/dist/docs-msg-tools.js

@@ -131,13 +131,20 @@ export function registerDocsMsgTools(server, deps) {
     }));
     register("docs_update", {
         title: "Update a Tower document",
-        description: "Updates a document's title, body, visibility, or parent (a parent change IS a move). Only the fields you pass change.",
+        description: "Updates a document's title, body, visibility, or parent (a parent change IS a move). Only the fields you "
+            + "pass change. Emptying a document that holds text needs allow_empty: true.",
         inputSchema: {
             id: z.string().min(1).max(200).describe("A document id, or its slug."),
             title: z.string().min(1).max(200).optional(),
             body_markdown: z.string().max(200_000).optional(),
             visibility: z.enum(["org", "private"]).optional(),
             parent_id: z.string().uuid().nullable().optional(),
+            allow_empty: z
+                .boolean()
+                .optional()
+                .describe("Only when you mean to CLEAR the page. A body_markdown that would empty a document that holds "
+                + "text is refused with refused_empty_body unless this is true (BLI-3757 — a blank save is far more "
+                + "often a surface that lost the content than a person who meant it)."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
@@ -151,6 +158,9 @@ export function registerDocsMsgTools(server, deps) {
             ...(args.body_markdown !== undefined ? { body_markdown: args.body_markdown } : {}),
             ...(args.visibility !== undefined ? { visibility: args.visibility } : {}),
             ...(args.parent_id !== undefined ? { parent_id: args.parent_id } : {}),
+            // BLI-3759: sent only when the caller asked for it; the door's own
+            // refusal comes back verbatim otherwise, never retried with the flag.
+            ...(args.allow_empty ? { allow_empty: true } : {}),
         });
         if (!response.ok)
             return errorResult(doorFailureText("docs_update", response));

package/dist/jarvis-answer-envelope.d.ts

@@ -34,7 +34,7 @@
  * Every key of the envelope, in the order it is written. The literal list IS
  * the contract: both copies assert against it, so a drift is a red suite.
  */
-export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "degraded", "degraded_reasons"];
+export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "proposal_id", "degraded", "degraded_reasons"];
 /**
  * The closed set of ways an answer can be second-rate without being a failure.
  * A degraded answer is still an answer — it is printed, returned and counted —
@@ -77,6 +77,16 @@ export interface JarvisAnswerEnvelope {
      * `thread_id` above and deliberately named apart from it.
      */
     trace_thread_id: string | null;
+    /**
+     * BLI-3755: the coding-arm proposal this turn made, when it made one.
+     *
+     * It is what an AGENT surface is given INSTEAD of the eight-hex approval
+     * code, which is never sent here: a code a program can read is a code it
+     * could approve with, and that is not approval. The person fetches the code
+     * on a surface a person reads and hands it back. Null on every turn that
+     * proposed no coding task, which is nearly all of them.
+     */
+    proposal_id: string | null;
     degraded: boolean;
     degraded_reasons: JarvisDegradedReason[];
 }
@@ -103,5 +113,7 @@ export interface JarvisAnswerEnvelopeInput {
     trace?: ReadonlyArray<{
         status?: string;
     }> | null;
+    /** `body.proposalId` — BLI-3755's coding-arm proposal id, when the turn made one. */
+    proposalId?: string | null;
 }
 export declare function buildJarvisAnswerEnvelope(input: JarvisAnswerEnvelopeInput): JarvisAnswerEnvelope;

package/dist/jarvis-answer-envelope.js

@@ -41,6 +41,7 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "turn_id",
     "thread_id",
     "trace_thread_id",
+    "proposal_id",
     "degraded",
     "degraded_reasons",
 ];
@@ -76,6 +77,7 @@ export function buildJarvisAnswerEnvelope(input) {
         turn_id: turnId,
         thread_id: input.thread ?? null,
         trace_thread_id: input.traceThread ?? null,
+        proposal_id: input.proposalId ?? null,
         degraded: reasons.length > 0,
         degraded_reasons: reasons,
     };

package/dist/jarvis-door.js

@@ -72,7 +72,14 @@ export async function takeTurn(deps, session, door, body, remember) {
     // `accept: application/json` (which `callAgentDoor` always sends) is what
     // makes the dashboard answer one JSON body instead of the NDJSON stream the
     // terminal takes — an MCP tool has nobody to show live trace lines to.
-    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/cli", body, TURN_TIMEOUT_MS);
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/cli", 
+    // BLI-3755: every turn this server takes says who is reading the answer.
+    // An MCP tool result is read by a MODEL, so the coding arm withholds its
+    // approval code and answers with a `proposal_id` instead — the one thing
+    // this server could not prove about a code it relayed was that a person
+    // had ever seen it. Sent on every tool, not just the dispatch, because the
+    // arm is on the belt of every turn.
+    { ...body, surface: "agent" }, TURN_TIMEOUT_MS);
     if (!response.ok) {
         log(`${TAG} turn failed ${JSON.stringify({
             door,
@@ -102,6 +109,7 @@ export async function takeTurn(deps, session, door, body, remember) {
         modelFallback: reply.model?.fallback,
         revised: reply.revised,
         trace: reply.trace,
+        proposalId: reply.proposalId,
     });
     remember({ turnId: envelope.turn_id, traceThreadId: envelope.trace_thread_id });
     log(`${TAG} answered ${JSON.stringify({
@@ -109,6 +117,9 @@ export async function takeTurn(deps, session, door, body, remember) {
         reply_chars: envelope.answer.length,
         sources: envelope.sources.length,
         trace_steps: reply.trace?.length ?? 0,
+        // BLI-3755: whether this turn left a coding-arm proposal behind. The id
+        // itself is in the envelope; this line says one was made.
+        proposal_recorded: envelope.proposal_id !== null,
         degraded: envelope.degraded,
         degraded_reasons: envelope.degraded_reasons,
         has_turn_id: envelope.turn_id !== null,
@@ -117,6 +128,10 @@ export async function takeTurn(deps, session, door, body, remember) {
     const footer = [
         envelope.turn_id ? `turn_id: ${envelope.turn_id} (open it with jarvis_trace)` : null,
         envelope.thread_id ? `thread_id: ${envelope.thread_id}` : null,
+        envelope.proposal_id
+            ? `proposal_id: ${envelope.proposal_id} — the person fetches the approval code for it themself, `
+                + `in a Tower tab, their Slack DM, or their own \`cockpit jarvis\` terminal. You were not sent one.`
+            : null,
         envelope.degraded ? `degraded: ${envelope.degraded_reasons.join(", ")}` : null,
     ]
         .filter((line) => line !== null)

package/dist/jarvis-tools.d.ts

@@ -32,16 +32,24 @@
  * and cannot compute a code for any plan, so an invented code is refused by
  * the dashboard exactly as it always was.
  *
- * Lock 2 is weaker on THIS surface than it is in a terminal, and saying so is
- * the honest thing to do. In a terminal the person types the code themselves.
- * Through MCP the code arrives as a tool argument, and the dashboard cannot
- * tell a code a person handed their agent from one the agent lifted out of the
- * previous answer by itself. So: this tool takes the code as a parameter, it
- * NEVER derives, guesses or fabricates one, its description tells the model in
- * plain words that the code must come from the person, and every relay is
- * logged (presence and length only, never the code). Anything stronger — a
- * per-code single use, an out-of-band confirmation — is a server-side change
- * to the gate itself and belongs with the gate, not here.
+ * Lock 2 is weaker on THIS surface than it is in a terminal: in a terminal the
+ * person types the code themselves, while through MCP it arrives as a tool
+ * argument and nothing on the wire distinguishes a code a person handed their
+ * agent from one the agent lifted out of the previous answer. BLI-3755 closed
+ * the two halves of that gap where the gate lives, not here:
+ *
+ *   * `jarvis_ask` and `jarvis_dispatch` tell the dashboard they are an AGENT
+ *     surface (`jarvis-door.ts` sends it on every turn), so a proposal comes
+ *     back with a `proposal_id` and NO code. There is nothing in the previous
+ *     answer to lift. The person fetches the code where a person reads — a
+ *     Tower tab, their Slack DM, their own `cockpit jarvis` — and hands it on.
+ *   * A code is spendable ONCE. A replay is refused with `approval_code_spent`,
+ *     so a code that did reach an agent buys at most the one run the person
+ *     approved.
+ *
+ * What is unchanged here: this server holds no secret and cannot compute a code
+ * for any plan, it never derives, guesses or fabricates one, and every relay is
+ * logged (presence and length only, never the code).
  */
 import { type JarvisDeps } from "./jarvis-door.js";
 export type { JarvisDeps } from "./jarvis-door.js";