@bli-cockpit/mcp 0.1.3 → 0.1.5

package/dist/jarvis-tools.js

@@ -24,6 +24,15 @@
  * `jarvis_ask` answers with `jarvis-answer-envelope.ts` — the same object
  * `cockpit jarvis --json` prints. A script and an agent read one shape.
  *
+ * ## One conversation per call (BLI-3786)
+ *
+ * A thread is single-writer: two turns in one conversation at the same time
+ * read each other's messages, and one can answer the other's question. Every
+ * tool here therefore sends NO thread unless the caller named one, and the
+ * door mints a conversation for that call alone and reports it as `thread_id`.
+ * Passing that id back is how an agent continues deliberately. `"main"` is the
+ * shared terminal default nobody chose and is never sent from here.
+ *
  * ## The approval code, and what this surface can and cannot prove
  *
  * The coding arm's gate (BLI-2981) has two locks: the code is an HMAC over the
@@ -32,16 +41,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 { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
@@ -62,10 +79,12 @@ export function registerJarvisTools(server, deps) {
         title: "Ask JARVIS",
         description: "Asks JARVIS one question and returns its answer, the Source: lines behind it, this turn's "
             + "turn_id and the conversation's thread_id. Same JARVIS, same tool belt and same evidence "
-            + "rules as Tower web chat, the Slack DM and `cockpit jarvis`. Pass thread to continue an "
-            + "earlier conversation; pass the returned turn_id to jarvis_trace to see how the answer was "
-            + "reached. JARVIS speaks as the person this machine is paired to and cannot be made to "
-            + "speak as anyone else.",
+            + "rules as Tower web chat, the Slack DM and `cockpit jarvis`. A thread is SINGLE-WRITER: "
+            + "omit thread and this turn gets a FRESH conversation of its own, so two questions asked at "
+            + "the same time can never read each other's; pass the thread_id the answer returned to "
+            + "continue that conversation deliberately. Pass the returned turn_id to jarvis_trace to see "
+            + "how the answer was reached. JARVIS speaks as the person this machine is paired to and "
+            + "cannot be made to speak as anyone else.",
         inputSchema: {
             question: z.string().min(1).max(50_000).describe("What to ask, in plain words."),
             thread: z
@@ -73,7 +92,9 @@ export function registerJarvisTools(server, deps) {
                 .min(1)
                 .max(200)
                 .optional()
-                .describe('The conversation to continue. Omit for "main", the default terminal thread.'),
+                .describe("The thread_id of a conversation to continue, exactly as an earlier answer returned "
+                + 'it. Omit for a fresh conversation for this call alone. "main" is the shared '
+                + "default nobody chose, so it is treated as naming nothing here."),
             subject: z
                 .string()
                 .min(1)
@@ -97,7 +118,10 @@ export function registerJarvisTools(server, deps) {
     }, async (args) => withSession(deps, async (session) => {
         const { result } = await takeTurn(deps, session, "jarvis_ask", {
             question: String(args.question ?? ""),
-            thread: typeof args.thread === "string" ? args.thread : "main",
+            // BLI-3786: no thread means no thread. The door mints one for this
+            // call and reports it as thread_id; sending "main" here would put
+            // every agent on one conversation, which is the bug this replaced.
+            ...(typeof args.thread === "string" ? { thread: args.thread } : {}),
             ...(typeof args.subject === "string" ? { subject: args.subject } : {}),
             ...(typeof args.date === "string" ? { date: args.date } : {}),
             ...(typeof args.model === "string" ? { model: args.model } : {}),
@@ -167,10 +191,13 @@ export function registerJarvisTools(server, deps) {
         title: "Dispatch a coding task to JARVIS's coding arm",
         description: "Asks JARVIS to run a coding task on the runner: it clones the repo, works, pushes a branch "
             + "and opens a pull request. It never merges. TWO CALLS, always. Call this once WITHOUT "
-            + "approval_code to get the plan and the 8-character confirmation code back; show both to the "
-            + "person; call it again with the code THEY give you and the same instruction. Never derive, "
-            + "guess, or reuse a code the person has not just handed you — a code you produce yourself is "
-            + "exactly what the approval gate exists to refuse.",
+            + "approval_code: you get the plan and a proposal_id back, and DELIBERATELY no code — a code "
+            + "you can read is a code you could approve with. Show the person the plan and the "
+            + "proposal_id and ask them to fetch the code themself, in a Tower browser tab, their Slack "
+            + "DM with JARVIS, or their own `cockpit jarvis` terminal. Then call this again with the code "
+            + "THEY give you and the same instruction. A code approves exactly ONE run: a reused one is "
+            + "refused (approval_code_spent) and the answer is a fresh approval, never a retry. Never "
+            + "derive, guess, or reuse a code the person has not just handed you.",
         inputSchema: {
             instruction: z
                 .string()
@@ -188,9 +215,15 @@ export function registerJarvisTools(server, deps) {
                 .min(1)
                 .max(64)
                 .optional()
-                .describe("The 8-character hex confirmation code THE PERSON read back to you from the previous "
-                + "call's plan. Omit it on the first call."),
-            thread: z.string().min(1).max(200).optional().describe('Defaults to "main".'),
+                .describe("The 8-character hex confirmation code THE PERSON fetched for this proposal and handed "
+                + "to you. Omit it on the first call — that call is never given one."),
+            thread: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("The thread_id of a conversation to continue. Omit for a fresh one — the approval "
+                + "code is bound to the PLAN, not to a conversation, so a dispatch needs no thread."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const log = deps.log ?? defaultLog;
@@ -212,7 +245,7 @@ export function registerJarvisTools(server, deps) {
         const question = [
             code.length > 0
                 ? "Dispatch this coding task to the coding arm now."
-                : "Propose a coding task for the coding arm. Do not dispatch it yet — read back the plan and the confirmation code so the person can approve it.",
+                : "Propose a coding task for the coding arm. Do not dispatch it yet — read back the plan and the proposal id so the person can fetch the approval code themselves.",
             ...(typeof args.repo === "string" ? [`Repo: ${args.repo}`] : []),
             "",
             String(args.instruction ?? ""),
@@ -220,7 +253,7 @@ export function registerJarvisTools(server, deps) {
                 ? ["", `The person approved this plan. Confirmation code: ${code.toLowerCase()}`]
                 : []),
         ].join("\n");
-        const { result } = await takeTurn(deps, session, "jarvis_dispatch", { question, thread: typeof args.thread === "string" ? args.thread : "main" }, remember);
+        const { result } = await takeTurn(deps, session, "jarvis_dispatch", { question, ...(typeof args.thread === "string" ? { thread: args.thread } : {}) }, remember);
         return result;
     }));
     register("jarvis_check", {
@@ -235,14 +268,19 @@ export function registerJarvisTools(server, deps) {
                 .max(200)
                 .optional()
                 .describe("The task id JARVIS named when it dispatched. Omit to ask about the recent ones."),
-            thread: z.string().min(1).max(200).optional().describe('Defaults to "main".'),
+            thread: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("The thread_id of a conversation to continue. Omit for a fresh one."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const task = typeof args.task === "string" ? args.task.trim() : "";
         const question = task.length > 0
             ? `Check the coding task ${task} and tell me its status, its branch and its pull request if it has one.`
             : "Check the coding tasks dispatched for me recently and tell me the status of each.";
-        const { result } = await takeTurn(deps, session, "jarvis_check", { question, thread: typeof args.thread === "string" ? args.thread : "main" }, remember);
+        const { result } = await takeTurn(deps, session, "jarvis_check", { question, ...(typeof args.thread === "string" ? { thread: args.thread } : {}) }, remember);
         return result;
     }));
 }

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

@@ -0,0 +1,34 @@
+/**
+ * `notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+ * `notes_move` MCP tools (BLI-3756 batch 2) — putting a meeting note in,
+ * sharing it, taking it back and moving it to another shelf, over the same
+ * `/api/notes/**` doors `cockpit notes` calls with the same device token.
+ *
+ * Reads live in `notes-tools.ts`. Three rules this half keeps.
+ *
+ * **The local screen runs before the network, on the name first.** A path is
+ * refused for a secret-shaped NAME without its bytes ever being read, then for
+ * being missing, unreadable, empty or over 20 MB — the same four checks and
+ * the same sentences as `commands/notes-file.ts`, because the server's own
+ * guard is the authority and this only avoids spending a round trip on a file
+ * it is certain to refuse. If the two ever disagree, the server wins.
+ *
+ * **Sharing is deliberate.** `cockpit notes share` asks before it acts unless
+ * `--yes` is passed; a client has no keyboard, so `confirm: true` is the whole
+ * of that gate here and a share without it is refused in the CLI's own words.
+ * Taking a note BACK narrows who can read it, and nobody needs to be talked
+ * out of that — `notes_unshare` asks for nothing, exactly as the CLI does not.
+ *
+ * **A slow door is named, not hidden.** `/api/notes/upload` reads the whole
+ * note with one model call and is budgeted to 300 seconds server-side; this
+ * waits slightly longer so the server's named failure wins the race whenever
+ * it manages to send one. An MCP client's own deadline may still be shorter —
+ * the description says so rather than letting a cut call read as a refusal.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type NotesWriteDeps = ToolDeps;
+/** Mirrors `UPLOADED_NOTE_MAX_BYTES`; a courtesy check, not a second authority. */
+export declare const NOTE_FILE_MAX_BYTES: number;
+export declare function registerNotesWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: NotesWriteDeps): void;

package/dist/notes-write-tools.js

@@ -0,0 +1,211 @@
+/**
+ * `notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+ * `notes_move` MCP tools (BLI-3756 batch 2) — putting a meeting note in,
+ * sharing it, taking it back and moving it to another shelf, over the same
+ * `/api/notes/**` doors `cockpit notes` calls with the same device token.
+ *
+ * Reads live in `notes-tools.ts`. Three rules this half keeps.
+ *
+ * **The local screen runs before the network, on the name first.** A path is
+ * refused for a secret-shaped NAME without its bytes ever being read, then for
+ * being missing, unreadable, empty or over 20 MB — the same four checks and
+ * the same sentences as `commands/notes-file.ts`, because the server's own
+ * guard is the authority and this only avoids spending a round trip on a file
+ * it is certain to refuse. If the two ever disagree, the server wins.
+ *
+ * **Sharing is deliberate.** `cockpit notes share` asks before it acts unless
+ * `--yes` is passed; a client has no keyboard, so `confirm: true` is the whole
+ * of that gate here and a share without it is refused in the CLI's own words.
+ * Taking a note BACK narrows who can read it, and nobody needs to be talked
+ * out of that — `notes_unshare` asks for nothing, exactly as the CLI does not.
+ *
+ * **A slow door is named, not hidden.** `/api/notes/upload` reads the whole
+ * note with one model call and is budgeted to 300 seconds server-side; this
+ * waits slightly longer so the server's named failure wins the race whenever
+ * it manages to send one. An MCP client's own deadline may still be shorter —
+ * the description says so rather than letting a cut call read as a refusal.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isSecretLikePathSegment } from "@bli-cockpit/telemetry-core";
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+/** Mirrors `UPLOADED_NOTE_MAX_BYTES`; a courtesy check, not a second authority. */
+export const NOTE_FILE_MAX_BYTES = 20 * 1024 * 1024;
+/** The route's own ceiling is 300 s. Wait past it so its sentence wins. */
+const UPLOAD_DEADLINE_MS = 305_000;
+const WRITE_DEADLINE_MS = 60_000;
+const PASTE_MAX_CHARS = 2_000_000;
+/** The sentence the CLI prints for a refusal caught locally, kept word for word. */
+function refusalSentence(refusal, filePath) {
+    switch (refusal) {
+        case "file_not_found":
+            return `I could not find that file: ${filePath}`;
+        case "file_unreadable":
+            return `I could not read that file: ${filePath}`;
+        case "file_empty":
+            return `There is nothing in that file: ${filePath}`;
+        case "file_too_big":
+            return "That file is too big to put in as a note — keep it under 20 MB.";
+        case "looks_like_a_key_file":
+            // The same rule the server's gate applies, said the same way: the name
+            // is all it takes to decide, and looking inside to be sure would already
+            // be the thing the rule forbids.
+            return `That name looks like a key or credential file, so I did not open it: ${filePath}`;
+    }
+}
+/** Reads and locally screens one note file. Never throws. */
+async function readNoteFile(filePath) {
+    const fileName = path.basename(filePath);
+    const refuse = (refusal) => ({
+        ok: false,
+        refusal,
+        sentence: refusalSentence(refusal, filePath),
+    });
+    if (isSecretLikePathSegment(fileName))
+        return refuse("looks_like_a_key_file");
+    let size;
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile())
+            return refuse("file_unreadable");
+        size = info.size;
+    }
+    catch (error) {
+        return refuse(error.code === "ENOENT" ? "file_not_found" : "file_unreadable");
+    }
+    if (size === 0)
+        return refuse("file_empty");
+    if (size > NOTE_FILE_MAX_BYTES)
+        return refuse("file_too_big");
+    try {
+        return { ok: true, bytes: await readFile(filePath), fileName };
+    }
+    catch {
+        return refuse("file_unreadable");
+    }
+}
+/** The route's own words for what happened. Never rephrased here. */
+function saidByTower(body) {
+    const said = [body.headline ?? "Tower answered without a sentence.", ...(body.lines ?? [])];
+    if (body.noteId)
+        said.push(`Note id: ${body.noteId}`);
+    return said.join("\n");
+}
+async function postForm(deps, session, tool, form) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/upload", form, UPLOAD_DEADLINE_MS);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    const body = response.body;
+    const text = saidByTower(body);
+    // `stored: false` is the door saying it did not keep the note. That is a
+    // refusal with a reason, not a success with a caveat.
+    return body.stored === true
+        ? textResult(text, { ok: true, noteId: body.noteId ?? null, scope: body.scope ?? null })
+        : errorResult(text);
+}
+export function registerNotesWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("notes_upload", {
+        title: "Put a local file in as a Tower meeting note",
+        description: "Uploads a transcript or note file from THIS machine's disk — the same door `cockpit notes upload` uses. "
+            + "A name that looks like a key or credential file is refused without being opened; so is a missing, empty or "
+            + "over-20-MB file. Tower reads the whole note with one model call, so a large file can take a couple of "
+            + "minutes and your client may give up first — the upload keeps going; notes_list will show it.",
+        inputSchema: {
+            path: z.string().min(1).max(4096).describe("An absolute path on this machine."),
+            exclude: z
+                .string()
+                .min(1)
+                .max(2000)
+                .optional()
+                .describe("Anything in the note to leave out, in plain words — forwarded to the reader verbatim."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const filePath = String(args.path ?? "");
+        const read = await readNoteFile(filePath);
+        if (!read.ok)
+            return errorResult(`Refused (${read.refusal}): ${read.sentence} Nothing was sent.`);
+        const form = new FormData();
+        form.set("file", new File([new Uint8Array(read.bytes)], read.fileName));
+        if (args.exclude)
+            form.set("exclusions", String(args.exclude));
+        return postForm(deps, session, "notes_upload", form);
+    }));
+    register("notes_paste", {
+        title: "Put text in as a Tower meeting note",
+        description: "Stores text you already have as a meeting note — the same door as notes_upload, which is what "
+            + "`cockpit notes paste` posts to. The CLI takes the body on stdin; here it is an argument, so the text "
+            + "travels in the request and is never echoed back to you.",
+        inputSchema: {
+            text: z.string().min(1).max(PASTE_MAX_CHARS).describe("The note itself."),
+            name: z.string().min(1).max(300).optional().describe("What to call it. Tower names it by date if you do not."),
+            exclude: z.string().min(1).max(2000).optional().describe("Anything to leave out, in plain words."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const text = String(args.text ?? "");
+        if (text.trim() === "") {
+            return errorResult("Refused (empty_paste): there was nothing to paste. Nothing was sent.");
+        }
+        const form = new FormData();
+        form.set("text", text);
+        if (args.name)
+            form.set("name", String(args.name));
+        if (args.exclude)
+            form.set("exclusions", String(args.exclude));
+        return postForm(deps, session, "notes_paste", form);
+    }));
+    register("notes_share", {
+        title: "Share a Tower meeting note with the team",
+        description: "Lets everyone signed in read one note. Deliberate: refused without `confirm: true`, the same rule as the "
+            + "CLI's --yes. Use notes_unshare to take it back.",
+        inputSchema: {
+            note_id: z.string().min(1).max(200).describe("A note id, as notes_list or notes_shelf reports it."),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "Sharing a note lets everyone signed in read it. Pass confirm: true to do it without being asked.");
+        if (refusal)
+            return refusal;
+        return shareCall(deps, session, args, true);
+    }));
+    register("notes_unshare", {
+        title: "Take a shared Tower note back",
+        description: "Makes one note yours again. No confirmation: taking a note back narrows who can read it, and nobody needs "
+            + "to be talked out of that — the same asymmetry `cockpit notes unshare` has.",
+        inputSchema: { note_id: z.string().min(1).max(200).describe("A note id.") },
+    }, async (args) => withSession(deps, async (session) => shareCall(deps, session, args, false)));
+    register("notes_move", {
+        title: "Move a Tower meeting note to another shelf",
+        description: "Puts one note on a different shelf, or clears its shelf with `clear: true` — the empty string the browser's "
+            + "own move box sends. A shelf is free text; notes_shelves lists the ones in use.",
+        inputSchema: {
+            note_id: z.string().min(1).max(200).describe("A note id."),
+            to: z.string().min(1).max(200).optional().describe("The shelf to move it to."),
+            clear: z.boolean().optional().describe("Take it off every shelf instead."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const clearing = args.clear === true;
+        if (!clearing && !args.to) {
+            return errorResult("Refused (no_destination): say which shelf with `to`, or pass `clear: true`. Nothing was moved.");
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/move", { note_id: String(args.note_id ?? ""), category: clearing ? "" : String(args.to) }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_move", response));
+        const body = response.body;
+        const text = [body.headline ?? "Tower answered without a sentence.", ...(body.lines ?? [])].join("\n");
+        return body.ok === true
+            ? textResult(text, { ok: true, shelf: body.shelf ?? null })
+            : errorResult(text);
+    }));
+}
+/** Share and unshare are one door and one body; only the boolean differs. */
+async function shareCall(deps, session, args, share) {
+    const tool = share ? "notes_share" : "notes_unshare";
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/share", { note_id: String(args.note_id ?? ""), share }, WRITE_DEADLINE_MS);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    const body = response.body;
+    return textResult(saidByTower(body), { ok: true, shared: share, noteId: body.noteId ?? null });
+}

package/dist/ops-tools.d.ts

@@ -11,16 +11,12 @@
  * unhealthy ones so an agent does not have to know the vocabulary to notice a
  * red board.
  *
- * `ops recompile` stays out: it spends a model call and wants its own gate on
- * this surface (batch 2).
+ * `ops_recompile` (BLI-3756 batch 2) is the one write here: it spends a model
+ * call, so it is the only tool in this file that can cost money, and the only
+ * one whose failure can leave the effect UNKNOWN rather than known.
  */
 import { type ToolDeps } from "./tool-result.js";
 export type OpsDeps = ToolDeps;
-/**
- * The verdicts that mean something is wrong, verbatim from `commands/ops.ts`.
- * `failing` is its own word and not a shade of `stale` (BLI-3723): a failing
- * reader's input is CURRENT and its answer is bad.
- */
 export declare const UNHEALTHY_VERDICTS: Set<string>;
 export declare function registerOpsTools(server: {
     registerTool: (...args: never[]) => unknown;

package/dist/ops-tools.js

@@ -11,8 +11,9 @@
  * unhealthy ones so an agent does not have to know the vocabulary to notice a
  * red board.
  *
- * `ops recompile` stays out: it spends a model call and wants its own gate on
- * this surface (batch 2).
+ * `ops_recompile` (BLI-3756 batch 2) is the one write here: it spends a model
+ * call, so it is the only tool in this file that can cost money, and the only
+ * one whose failure can leave the effect UNKNOWN rather than known.
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
@@ -22,7 +23,23 @@ import { doorFailureText, errorResult, registrarFor, textResult, queryString, wi
  * `failing` is its own word and not a shade of `stale` (BLI-3723): a failing
  * reader's input is CURRENT and its answer is bad.
  */
-export const UNHEALTHY_VERDICTS = new Set(["stale", "never_produced", "unreadable", "failing"]);
+/**
+ * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
+ * seconds; waiting slightly past it is what lets this tool tell "Tower gave up"
+ * from "the network did", instead of hanging up first and blaming the wrong
+ * one. A client with a shorter deadline of its own will cut the call first —
+ * the description says so.
+ */
+const RECOMPILE_DEADLINE_MS = 830_000;
+const TOWER_RECOMPILE_CEILING_SECONDS = 800;
+export const UNHEALTHY_VERDICTS = new Set([
+    "stale",
+    "never_produced",
+    "unreadable",
+    "failing",
+    // BLI-3762: a job that wrote less than it owed is not healthy. Amber counts.
+    "degraded",
+]);
 function numberOf(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
@@ -148,4 +165,48 @@ export function registerOpsTools(server, deps) {
             coverage: read["coverage"] ?? null,
         });
     }));
+    register("ops_recompile", {
+        title: "Write one person's Tower page again",
+        description: "Compiles a daily page on demand — `cockpit ops recompile`, same door. It SPENDS A MODEL CALL and takes "
+            + "several minutes; pass `dry_run: true` to resolve the person and see which page is being served without "
+            + "compiling anything. Your own page always; anybody else's is admin only, decided on the server. Tower's own "
+            + "budget is 800 seconds — if that runs out the effect is UNKNOWN, not failed, and this says so.",
+        inputSchema: {
+            person: z.string().min(1).max(200).describe("An email, a display name, or a person id."),
+            dry_run: z.boolean().optional().describe("Resolve the person and read the current page; compile nothing."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const dryRun = args.dry_run === true;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/ops/recompile", { person: String(args.person ?? ""), dryRun }, RECOMPILE_DEADLINE_MS);
+        if (!response.ok) {
+            // The ceiling is its own outcome, and its effect is UNKNOWN rather
+            // than failed: the compile may well have finished after the
+            // connection was cut. Said in the CLI's own words, because a caller
+            // told "it failed" would reasonably ask for it again and pay twice.
+            if (response.transportError) {
+                return errorResult(`Refused (recompile_ceiling_exceeded): Tower's ${TOWER_RECOMPILE_CEILING_SECONDS}-second budget for one `
+                    + "recompile ran out before it answered. That is not the same as the compile failing: it may have "
+                    + "finished after the connection was cut. Call brief_read for that person to see which page is being "
+                    + "served now.");
+            }
+            return errorResult(doorFailureText("ops_recompile", response));
+        }
+        const body = response.body;
+        const status = typeof body["status"] === "string" ? body["status"] : "compiled";
+        const displayName = typeof body["displayName"] === "string" ? body["displayName"] : String(args.person ?? "");
+        const pageId = typeof body["pageId"] === "string" ? body["pageId"] : null;
+        if (status === "dry_run") {
+            const latest = typeof body["latestPageId"] === "string" ? body["latestPageId"] : null;
+            return textResult(`${displayName} is on the roster.\n`
+                + (latest
+                    ? `The page being served for them right now is ${latest}.`
+                    : "Nothing has ever been written for them.")
+                + "\nNothing was compiled — this was a dry run.", body);
+        }
+        return textResult(`Wrote ${displayName}'s page again: ${pageId ?? "(no id returned)"}\n`
+            + (body["isNowLive"] === true
+                ? "It is the page being served now."
+                : "It is NOT the page being served: a scheduled compile is stamped for a later delivery window, so that "
+                    + "one still wins. Nothing was lost — this is a new version alongside it."), body);
+    }));
 }

package/dist/pages-tools.d.ts

@@ -14,11 +14,15 @@
  * signals and reports the totals in `coverage`; a truncated board and a quiet
  * board must never read alike.
  *
- * Moving a Scout card (`start`/`dismiss`/`undo`) is super_admin server-side and
- * stays in batch 2.
+ * Moving a Scout card (`scout_start`/`scout_dismiss`/`scout_undo`, BLI-3756
+ * batch 2) is super_admin server-side, so those three RELAY a decision rather
+ * than making one — and each reads the board first, so an id is matched
+ * exactly against cards that exist and a refusal still hands back the read.
  */
 import { type ToolDeps } from "./tool-result.js";
 export type PagesDeps = ToolDeps;
 export declare function registerPagesTools(server: {
     registerTool: (...args: never[]) => unknown;
 }, deps: PagesDeps): void;
+/** The three verbs `cockpit scout` has beyond reading the board. */
+export declare const SCOUT_ACTIONS: readonly ["start", "dismiss", "undo"];

package/dist/pages-tools.js

@@ -14,8 +14,10 @@
  * signals and reports the totals in `coverage`; a truncated board and a quiet
  * board must never read alike.
  *
- * Moving a Scout card (`start`/`dismiss`/`undo`) is super_admin server-side and
- * stays in batch 2.
+ * Moving a Scout card (`scout_start`/`scout_dismiss`/`scout_undo`, BLI-3756
+ * batch 2) is super_admin server-side, so those three RELAY a decision rather
+ * than making one — and each reads the board first, so an id is matched
+ * exactly against cards that exist and a refusal still hands back the read.
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
@@ -120,4 +122,69 @@ export function registerPagesTools(server, deps) {
             .join("\n\n");
         return textResult(`WORKBOOK · ${projects.length} project(s) · ${docCount} document(s).${lines ? `\n\n${lines}` : ""}`, { projects });
     }));
+    // BLI-3756 batch 2: the three verbs that MOVE a Scout card. Deciding a card
+    // is super_admin server-side and reading the board is not, so a refusal here
+    // never costs the caller the read it already had — the open cards come back
+    // beside the refusal, exactly as `cockpit scout` leaves the board on stdout.
+    for (const action of SCOUT_ACTIONS) {
+        register(`scout_${action}`, {
+            title: SCOUT_TITLES[action],
+            description: SCOUT_DESCRIPTIONS[action],
+            inputSchema: {
+                experiment_id: z
+                    .string()
+                    .min(1)
+                    .max(200)
+                    .describe("A full experiment id, exactly as scout_board reports it. No prefixes on this surface."),
+            },
+        }, async (args) => withSession(deps, async (session) => {
+            const experimentId = String(args.experiment_id ?? "");
+            // The board is read FIRST, as the CLI does: it is what says whether
+            // the id names a card that exists, and it is what a refused caller
+            // still gets to keep.
+            const read = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/cockpit/scout");
+            if (!read.ok)
+                return errorResult(doorFailureText(`scout_${action}`, read));
+            const board = (read.body.board ?? {});
+            const open = board.experiments ?? [];
+            const card = [...open, ...(board.settled ?? [])].find((one) => one.id === experimentId);
+            if (!card) {
+                // The exact-match rule, and the list to fix a wrong guess from in
+                // one step. Never a prefix: a near-miss that resolved to the wrong
+                // card would settle an experiment nobody decided on.
+                const known = open.map((one) => `  ${one.id ?? "?"}  ${one.title ?? ""}`).join("\n");
+                return errorResult(`Refused (unknown_experiment): no card on the Scout board has the id "${experimentId}". `
+                    + `Ids come from scout_board and are matched exactly.${known ? `\n\nOpen cards:\n${known}` : ""}`);
+            }
+            const serverAction = action === "undo" ? "undo_dismiss" : action;
+            const applied = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/cockpit/scout", {
+                experiment_id: experimentId,
+                action: serverAction,
+            });
+            if (!applied.ok) {
+                const gate = applied.status === 403
+                    ? " Deciding a Scout card is a super_admin action; reading the board is not."
+                    : "";
+                return errorResult(`${doorFailureText(`scout_${action}`, applied)}${gate}`);
+            }
+            return textResult(`${SCOUT_PAST_TENSE[action]} ${experimentId} · ${card.claimSummary ?? card.title ?? "that card"}`, { ok: true, action: serverAction, experiment: applied.body.experiment ?? null });
+        }));
+    }
 }
+/** The three verbs `cockpit scout` has beyond reading the board. */
+export const SCOUT_ACTIONS = ["start", "dismiss", "undo"];
+const SCOUT_TITLES = {
+    start: "Start a Scout experiment",
+    dismiss: "Dismiss a Scout card",
+    undo: "Restore a dismissed Scout card",
+};
+const SCOUT_DESCRIPTIONS = {
+    start: "Marks one experiment card as being run — `cockpit scout start`, same door. super_admin, decided on the server.",
+    dismiss: "Sets one experiment card aside — `cockpit scout dismiss`, same door. Reversible with scout_undo. super_admin, decided on the server.",
+    undo: "Puts a dismissed card back on the board — `cockpit scout undo`, which the door calls `undo_dismiss`. super_admin, decided on the server.",
+};
+const SCOUT_PAST_TENSE = {
+    start: "Started",
+    dismiss: "Dismissed",
+    undo: "Restored",
+};