@bli-cockpit/cli 0.2.238 → 0.2.240

package/dist/commands/local-args-tower-msg.js

@@ -1,6 +1,7 @@
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
-const MSG_ACTIONS = new Set(["channels", "read", "send", "thread", "create", "dm", "show"]);
-const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MSG_ACTIONS = new Set(["channels", "read", "send", "thread", "create", "dm", "show", "unread", "edit", "delete", "outcome"]);
+const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send", "unread"]);
 /**
  * `--members a@x.test,b@y.test` — addresses only, split on commas, never
  * fuzzy (BLI-3749). The door resolves each one exactly, so a typo comes back
@@ -35,24 +36,73 @@ export function parseMsgArgs(args) {
             "--private",
             "--members",
             "--description",
+            "--from",
+            "--mark-read",
+            "--request-id",
+            "--expected-revision",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit", "--members", "--description", "--before"],
+        valueFlags: [
+            "--home", "--dashboard-url", "--channel", "--thread", "--limit", "--members", "--description", "--before", "--from",
+            "--request-id", "--expected-revision",
+        ],
     });
     const { action, rest } = parseMsgAction(values.positionals);
     if (values.flags.has("--before") && action !== "read" && action !== "thread") {
         throw new Error("--before belongs to msg read or msg thread.");
     }
+    const { markRead, unreadFrom } = parseMsgReadLineFlags(action, values);
     const { channelName, dmEmail } = parseMsgCreateTarget(action, rest);
     const { isPrivate, memberEmails, description } = parseMsgCreateFlags(action, values);
     const { channelRef, threadId, limit } = parseMsgReadTarget(action, rest, values);
-    return buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit);
+    const writeSafety = parseMsgWriteSafety(action, rest, values);
+    return buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom, writeSafety);
+}
+/** `send|edit|delete --request-id`, `edit|delete --expected-revision`, and the id `edit`/`delete`/`outcome` name (BLI-21314). */
+function parseMsgWriteSafety(action, rest, values) {
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID_PATTERN.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    if (requestId && action !== "send" && action !== "edit" && action !== "delete") {
+        throw new Error("--request-id belongs to `cockpit msg send`, `edit` or `delete`.");
+    }
+    const expectedRevision = optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision");
+    if (expectedRevision !== undefined && action !== "edit" && action !== "delete") {
+        throw new Error("--expected-revision belongs to `cockpit msg edit` or `delete`.");
+    }
+    let targetId;
+    if (action === "edit" || action === "delete" || action === "outcome") {
+        targetId = optionalNonEmpty(rest[0]);
+        if (!targetId) {
+            throw new Error(action === "outcome"
+                ? "msg outcome needs the request UUID, e.g. `cockpit msg outcome <request-uuid>`."
+                : `msg ${action} needs a message id, e.g. \`cockpit msg ${action} <message-id>\`.`);
+        }
+        if (rest.length > 1)
+            throw new Error(`msg ${action} takes one id, not ${rest.length}.`);
+        if (action === "outcome" && !UUID_PATTERN.test(targetId))
+            throw new Error("msg outcome takes a request UUID.");
+    }
+    return { targetId, requestId, expectedRevision };
+}
+/** `read --mark-read` and `unread --from <message-id>` (BLI-21299): the read line, moved on purpose. */
+function parseMsgReadLineFlags(action, values) {
+    const markRead = values.booleans.has("--mark-read");
+    if (markRead && action !== "read")
+        throw new Error("--mark-read belongs to `cockpit msg read`.");
+    const unreadFrom = optionalNonEmpty(values.flags.get("--from"));
+    if (action === "unread" && !unreadFrom) {
+        throw new Error("msg unread needs --from <message-id>, e.g. `cockpit msg unread general --from <message-id>`.");
+    }
+    if (unreadFrom && action !== "unread")
+        throw new Error("--from belongs to `cockpit msg unread`.");
+    return { markRead, unreadFrom };
 }
 function parseMsgAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "channels" : first);
     if (!MSG_ACTIONS.has(action)) {
-        throw new Error(`Unknown msg command: ${first}. Try channels, read, send, thread, create, dm, or show.`);
+        throw new Error(`Unknown msg command: ${first}. Try channels, read, unread, send, thread, create, dm, or show; to change a message: edit, delete or outcome.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -113,7 +163,7 @@ function parseMsgReadTarget(action, rest, values) {
         if (rest.length > 1)
             throw new Error(`msg thread takes one thread id, not ${rest.length}.`);
     }
-    else if (action !== "create" && action !== "dm" && rest.length > 0) {
+    else if (action !== "create" && action !== "dm" && action !== "edit" && action !== "delete" && action !== "outcome" && rest.length > 0) {
         throw new Error(`msg ${action} does not take "${rest[0]}".`);
     }
     const threadFlag = optionalNonEmpty(values.flags.get("--thread"));
@@ -129,7 +179,7 @@ function parseMsgReadTarget(action, rest, values) {
     }
     return { channelRef, threadId, limit };
 }
-function buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit) {
+function buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom, writeSafety) {
     return {
         kind: "msg",
         action,
@@ -144,6 +194,11 @@ function buildMsgCommand(values, action, channelRef, channelName, dmEmail, membe
         isPrivate,
         ...(threadId ? { threadId } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(markRead ? { markRead } : {}),
+        ...(unreadFrom ? { unreadFrom } : {}),
+        ...(writeSafety.targetId ? { targetId: writeSafety.targetId } : {}),
+        ...(writeSafety.requestId ? { requestId: writeSafety.requestId } : {}),
+        ...(writeSafety.expectedRevision === undefined ? {} : { expectedRevision: writeSafety.expectedRevision }),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-args-tower-setup.js

@@ -1,13 +1,20 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
 export function parseSetupArgs(args) {
-    const values = parseNamedArgs(args, { allowedFlags: ["--person", "--compare", "--since", "--details", "--json", "--home", "--dashboard-url"], valueFlags: ["--since", "--person", "--compare", "--home", "--dashboard-url"] });
+    const values = parseNamedArgs(args, { allowedFlags: ["--until", "--machines", "--person", "--compare", "--since", "--details", "--json", "--home", "--dashboard-url"], valueFlags: ["--until", "--since", "--person", "--compare", "--home", "--dashboard-url"] });
     if (values.positionals.length)
         throw new Error("setup takes --person or --compare, not a subcommand.");
     const compare = optionalNonEmpty(values.flags.get("--compare"));
     if (compare && (compare.split(",").length !== 2 || compare.split(",").some(value => !value.trim())))
         throw new Error("--compare takes two people (first names or emails) separated by a comma.");
     const since = optionalNonEmpty(values.flags.get("--since"));
-    if (since && since !== "7d" && since !== "30d" && (!/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z)?$/.test(since) || !Number.isFinite(Date.parse(since)) || new Date(since).toISOString().slice(0, 10) !== since.slice(0, 10) || Date.parse(since) >= Date.now()))
-        throw new Error("--since takes 7d, 30d, or an ISO date before now.");
-    return { kind: "setup", since, details: values.booleans.has("--details"), person: optionalNonEmpty(values.flags.get("--person")), compare, json: values.booleans.has("--json"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")) };
+    const until = optionalNonEmpty(values.flags.get("--until"));
+    const validDate = (value) => /^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(`${value.slice(0, 10)}T00:00:00Z`).toISOString().slice(0, 10) === value.slice(0, 10);
+    const end = until ? Date.parse(until) : Date.now();
+    const duration = since ? /^([1-9]\d*)([dh])$/.exec(since) : null;
+    const start = duration ? end - Number(duration[1]) * (duration[2] === "d" ? 86400000 : 3600000) : since ? Date.parse(since) : end - 30 * 86400000;
+    if (!Number.isFinite(end) || !Number.isFinite(start) || start >= end || (until && !validDate(until)) ||
+        (duration && Number(duration[1]) > (duration[2] === "d" ? 365 : 8760)) ||
+        (since && !duration && !validDate(since)))
+        throw new Error("--since takes a duration (1d, 7d, 30d, 90d) or an absolute start; --until takes an absolute end after the start.");
+    return { kind: "setup", since, until, machines: values.booleans.has("--machines"), details: values.booleans.has("--details"), person: optionalNonEmpty(values.flags.get("--person")), compare, json: values.booleans.has("--json"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")) };
 }

package/dist/commands/local-args-tower-work.js

@@ -27,6 +27,8 @@ const ISSUE_ACTIONS = new Set([
     "move",
     "comment",
     "history",
+    "versions",
+    "restore",
 ]);
 /** Every verb except `list` and `create` names ONE issue first. */
 const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
@@ -36,6 +38,8 @@ const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
     "move",
     "comment",
     "history",
+    "versions",
+    "restore",
 ]);
 /**
  * The closed state vocabulary, copied verbatim from
@@ -63,6 +67,16 @@ const ISSUE_ALLOWED_FLAGS = [
     "--size",
     "--parent",
     "--file",
+    "--version",
+    "--cursor",
+    "--q",
+    "--created-after",
+    "--created-before",
+    "--updated-after",
+    "--updated-before",
+    "--sort",
+    "--dir",
+    "--all",
     "--body-stdin",
     "--json",
 ];
@@ -82,6 +96,15 @@ const ISSUE_VALUE_FLAGS = [
     "--size",
     "--parent",
     "--file",
+    "--version",
+    "--cursor",
+    "--q",
+    "--created-after",
+    "--created-before",
+    "--updated-after",
+    "--updated-before",
+    "--sort",
+    "--dir",
 ];
 export function parseIssueArgs(args) {
     const values = parseNamedArgs(args, {
@@ -96,15 +119,19 @@ export function parseIssueArgs(args) {
         throw new Error("--request-id must be a UUID.");
     if (action === "mutation-status" && !UUID_PATTERN.test(issueRef ?? ""))
         throw new Error("mutation-status needs a request UUID.");
-    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment"].includes(action)) {
-        throw new Error("Write-safety flags belong to create, update, move or comment.");
+    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore"].includes(action)) {
+        throw new Error("Write-safety flags belong to create, update, move, comment or restore.");
     }
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const title = readIssueTitle(action, values);
-    if (action !== "board" && (values.flags.has("--label") || values.flags.has("--rows"))) {
-        throw new Error("--label and --rows filter cockpit tickets board only.");
+    if (action !== "board" && values.flags.has("--rows")) {
+        throw new Error("--rows widens cockpit tickets board only.");
     }
+    if (action !== "board" && action !== "list" && values.flags.has("--label")) {
+        throw new Error("--label filters cockpit tickets board and cockpit tickets list.");
+    }
+    const page = readIssuePage(action, values);
     const boardProject = optionalNonEmpty(values.flags.get("--project"));
     if (action === "board" && boardProject && !UUID_PATTERN.test(boardProject))
         throw new Error("board --project requires a uuid.");
@@ -112,13 +139,58 @@ export function parseIssueArgs(args) {
     const estimate = readIssueSize(values);
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
-    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit);
+    const versionNumber = readIssueVersion(action, values);
+    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page);
+}
+const INSTANT = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d{1,6})?(?:Z|[+-]\d\d:\d\d))?$/;
+/** BLI-21315: the cursor contract's flags. Filters and sort belong to `list`; `--cursor` also to `history`. */
+function readIssuePage(action, values) {
+    const named = ["--q", "--created-after", "--created-before", "--updated-after", "--updated-before", "--sort", "--dir"];
+    for (const flag of named) {
+        if (values.flags.has(flag) && action !== "list")
+            throw new Error(`${flag} belongs to \`cockpit ticket list\`.`);
+    }
+    if (values.booleans.has("--all") && action !== "list")
+        throw new Error("--all belongs to `cockpit ticket list`.");
+    if (values.flags.has("--cursor") && action !== "list" && action !== "history") {
+        throw new Error("--cursor belongs to `cockpit ticket list` and `cockpit ticket history`.");
+    }
+    const instants = {};
+    for (const flag of ["--created-after", "--created-before", "--updated-after", "--updated-before"]) {
+        const value = optionalNonEmpty(values.flags.get(flag));
+        if (value !== undefined && (!INSTANT.test(value) || !Number.isFinite(Date.parse(value)))) {
+            throw new Error(`${flag} must be a UTC instant like 2026-10-01T00:00:00Z or a date like 2026-10-01.`);
+        }
+        instants[flag] = value;
+    }
+    const sort = optionalNonEmpty(values.flags.get("--sort"));
+    if (sort !== undefined && sort !== "updated_at" && sort !== "created_at")
+        throw new Error("--sort must be updated_at or created_at.");
+    const dir = optionalNonEmpty(values.flags.get("--dir"));
+    if (dir !== undefined && dir !== "asc" && dir !== "desc")
+        throw new Error("--dir must be asc or desc.");
+    const all = values.booleans.has("--all");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    if (all && cursor)
+        throw new Error("--all walks from the start; drop --cursor, or pass --cursor without --all to read one page.");
+    const q = optionalNonEmpty(values.flags.get("--q"));
+    return {
+        ...(cursor ? { cursor } : {}),
+        ...(q ? { q } : {}),
+        ...(instants["--created-after"] ? { createdAfter: instants["--created-after"] } : {}),
+        ...(instants["--created-before"] ? { createdBefore: instants["--created-before"] } : {}),
+        ...(instants["--updated-after"] ? { updatedAfter: instants["--updated-after"] } : {}),
+        ...(instants["--updated-before"] ? { updatedBefore: instants["--updated-before"] } : {}),
+        ...(sort ? { sort } : {}),
+        ...(dir ? { dir } : {}),
+        ...(all ? { all } : {}),
+    };
 }
 function readIssueAction(values) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!ISSUE_ACTIONS.has(action)) {
-        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, history, or mutation-status.`);
+        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, history, versions, restore, or mutation-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -206,14 +278,24 @@ function readIssueAssignee(action, values) {
     }
     return assignee;
 }
+/** `restore` names the version it wants; there is no "restore the previous one" (BLI-21300). */
+function readIssueVersion(action, values) {
+    const version = optionalPositiveInteger(values.flags.get("--version"), "--version");
+    if (action === "restore" && version === undefined) {
+        throw new Error("issue restore needs --version <n>; list them with `cockpit ticket versions <id>`.");
+    }
+    if (version !== undefined && action !== "restore")
+        throw new Error("--version belongs to `cockpit ticket restore`.");
+    return version;
+}
 function readIssueLimit(action, values) {
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
-    if (limit !== undefined && action !== "list" && action !== "history") {
-        throw new Error("--limit belongs to `cockpit issue list` or `cockpit issue history`.");
+    if (limit !== undefined && action !== "list" && action !== "history" && action !== "versions") {
+        throw new Error("--limit belongs to `cockpit issue list`, `history` or `versions`.");
     }
     return limit;
 }
-function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit) {
+function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page) {
     return {
         kind: "issue",
         requestId: optionalNonEmpty(values.flags.get("--request-id")),
@@ -230,6 +312,8 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
         rows: optionalNonEmpty(values.flags.get("--rows")),
         project: optionalNonEmpty(values.flags.get("--project")),
         ...(limit === undefined ? {} : { limit }),
+        ...page,
+        ...(versionNumber === undefined ? {} : { versionNumber }),
         title,
         ...(priority === undefined ? {} : { priority }),
         ...(estimate === undefined ? {} : { estimate }),
@@ -241,8 +325,8 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
 }
 export function parseProjectArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--dashboard-url", "--archived", "--json"],
-        valueFlags: ["--home", "--dashboard-url"],
+        allowedFlags: ["--home", "--dashboard-url", "--archived", "--cursor", "--limit", "--json"],
+        valueFlags: ["--home", "--dashboard-url", "--cursor", "--limit"],
     });
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
@@ -257,6 +341,8 @@ export function parseProjectArgs(args) {
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         includeArchived: values.booleans.has("--archived"),
+        ...(optionalNonEmpty(values.flags.get("--cursor")) ? { cursor: optionalNonEmpty(values.flags.get("--cursor")) } : {}),
+        ...(values.flags.has("--limit") ? { limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit") } : {}),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-help-commands-tower-ops.js

@@ -197,10 +197,10 @@ export const TOWER_OPS_COMMAND_HELP = [
             "  cockpit drills start                          open the next drill: the change or command, what it printed, and the question. The cause is NOT shown",
             "  cockpit drills answer --confidence <1-5>      your answer on stdin (or --text), and how sure you are; then the real cause and the guard are shown",
             "  cockpit drills theme                          your theme and the choices",
-            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    video-game (the default), boxing, muay-thai, crime-drama, anime, sports, or your own words",
+            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    plain (the default: no theme), video-game, sports, movies-tv, music, anime, cooking, or anything you're into",
             "  cockpit drills review                         your own week: hits, wins, highs, lows, where you have stopped improving, what to practise",
-            "A drill replays a real mistake the team already paid for. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
-            "Each of your top patterns is a boss: pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
+            "A drill replays a real mistake the team already paid for, shown straight with no theme unless you pick one. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
+            "Each of your top patterns is something to beat (a boss, if you pick a theme): pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
             "Anything that needs your hit history says so when it is not connected yet, instead of showing a zero.",
             "--home <dir> and --dashboard-url <url> are for tests and staging.",
             "--json writes one object to stdout (the door's body) and nothing else; a refusal is { ok: false, error, detail } and exits 1.",

package/dist/commands/local-help-commands-tower.js

@@ -47,7 +47,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]] [flags]",
+            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]|mutation-status <request-uuid>|share <id|slug> --add|--remove <email>|access <id|slug>] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
             "list [--parent <id>|root] [--query <text> [--word]] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB). --json shape: { documents: [{ id, slug, title, visibility, parent_id, source, updated_at, body_chars }] }.",
@@ -62,29 +62,35 @@ export const TOWER_COMMAND_HELP = [
             "  --json shape: one ref answers { document }, unchanged from before BLI-10450. Several refs answer { documents: [{ ref, ok, document } | { ref, ok: false, error, detail }] }.",
             "read --parent <id>|root --bodies [--limit <n>] — every document filed directly under that parent, bodies included, in ONE call (GET /api/docs/documents?parent_id=...&bodies=true). --limit here caps the DOCUMENT COUNT (1-50), not characters. --json shape: { documents: [{ id, ..., body_markdown }] }.",
             "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default. --json shape: { document }.",
-            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document }.",
+            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] [--expected-revision <n>] [--request-id <uuid>] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb. --json shape: { document, mutation }.",
+            "  --expected-revision <n> is the page revision you read (`docs read --json` shows document.revision). The save is one atomic step: if someone saved since, nothing is written and you get revision_conflict with the current page (--json: mutation.current). Omit it for an unconditional save. Every save advances the revision.",
+            "  --request-id <uuid> makes a retry apply once (minted and printed when absent). Reusing it with different input is request_id_reused. If the response is lost, run `cockpit docs mutation-status <uuid>`, then retry the SAME input with the SAME id.",
+            "mutation-status <request-uuid> — your own save receipt: committed (with the stored revision), not_committed (with the reason) or unknown_check_again (no receipt yet; it never proves nothing changed). --json shape: { mutation }.",
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
+            "access <id|slug> — who may do what on a page and why, in plain sentences (BLI-21313): your role (author, admin, granted_editor, reader), can_read/can_edit/can_manage, the named editors you may see (the owner and administrators see all; a named editor sees only their own grant), and the grant history for the owner and administrators. The same explanation the page, its versions and its export carry. --json shape: { ok, document_id, permission: { role, can_read, can_edit, can_manage, editors, editors_complete, reasons }, events }.",
+            "share <id|slug> --add <email> | --remove <email> [--reason \"<note>\"] — owner or administrator only. Names (or removes) an editor of an ORGANIZATION page by exact email, never fuzzy. An editor can change the title and text; they cannot change visibility, move, delete or manage editors, and nobody new gains the right to read. A page you made private refuses with private_page_grant_needs_decision (sharing a private page waits for a decision) and nothing is written. Other refusals: not_grant_manager, person_not_found, grantee_is_author, document_not_found_or_unreadable. Adding someone already named, or removing someone not named, answers outcome unchanged. --json shape: { ok, outcome, reason, document_id, grantee_id, request_id, permission }.",
             "delete <id|slug> [<id|slug>...] — soft-deletes one or more documents (BLI-10555): the browser's own delete, sets deleted_at, never a real SQL DELETE. Recoverable — only a super_admin clearing deleted_at brings it back, there is no self-service undo. Deleting a parent does NOT delete its children; they keep their own parent_id and stay exactly where they were. Several refs resolve against ONE shared list call, then one DELETE each — one bad ref never loses the rest. --json shape: one ref answers { ok, document_id }; several answer { documents: [{ ref, ok, document_id } | { ref, ok: false, error, detail }] }.",
             "link <id|slug> <notion-url|page-id> — ties the document to a Notion page so the two-way sync moves it both ways. The page is the truth from then on: the next sync pulls it over this copy and keeps the copy as a version. `link <id|slug> --clear` unties it. Refusals: invalid_notion_page, notion_page_already_linked, document_not_writable.",
             "sync-status [<id|slug>] — every linked document's Notion sync state, or one's: synced (the body is what both sides last agreed on), tower_changed (edited here since; the next write-back pushes it), never_synced (linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull, not here. Metadata only, never a body.",
             "export <id|slug> [--format md|pdf|docx|txt] [--out <path>] — writes the document as a file (ticket 20694): md is the stored Markdown exactly, txt is readable plain text, docx is a Word file with real headings, lists, tables and links, pdf is a paginated page with the title and last-updated date in the header. Default format md; default path is the document's slug plus the extension in the current directory (--out names a file, or a directory to put it in), and an existing file is replaced. Prints the path; --json shape: { ok, path, bytes, format }. To copy a page's text, `cockpit docs read` already does it.",
             "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
-            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-            "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr. A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
             "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
         ],
     ],
     [
         "msg",
         [
-            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>|show <message-id>] [flags]",
+            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|unread <channel> --from <message-id>|send <channel>|edit <message-id>|delete <message-id>|outcome <request-uuid>|thread <id> --channel <channel>|show <message-id>] [flags]",
             "",
             "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
             "channels — every channel you are a member of (or, as a super_admin, every channel).",
             "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
             "dm <email> — opens (or re-opens) the direct message with one person. Idempotent: the same address always resolves to the same channel, and you never have to name yourself.",
-            "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
-            "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
+            "read <channel> [--limit <n>] [--thread <id>] [--mark-read] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead. The first page also says where the messages come from (for an imported Slack channel: how long ago the archive was checked, or that it is unknown) and where YOUR read line stands. Reading never moves the read line; --mark-read moves it to the newest message shown, and says plainly if that failed.",
+            "unread <channel> --from <message-id> — marks that message and everything after it unread, so the web sidebar badge and the NEW MESSAGES line start there. Opening or reading a channel never clears unseen history.",
+            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit.",
+            "edit <message-id> [--expected-revision <n>] [--request-id <uuid>] — replaces your own message's text (piped in). With --expected-revision, an edit of a message that has moved on is refused revision_conflict and nothing is saved over it; the current revision is printed. A message you did not write, or one that was deleted, is refused by name. delete <message-id> [--expected-revision <n>] [--request-id <uuid>] — deletes by tombstone: the text is cleared and every surface reads \"This message was deleted\", but the row stays so its thread, replies and reply count survive. Search and unread counts ignore it. A repeat answers already_deleted. outcome <request-uuid> — your own write receipt for a send, edit or delete: committed, not_committed (with the reason) or unknown_check_again. Run it after a timeout before retrying.",
             "thread <id> --channel <channel> [--before <cursor>] [--limit <n>] — one thread's replies by the parent message's id.",
             "show <message-id> — exact message, thread root and bounded neighbors. read/thread --before takes the preceding nextCursor; repeat until hasMore is false.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
@@ -95,10 +101,10 @@ export const TOWER_COMMAND_HELP = [
     [
         "issue",
         [
-            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>|mutation-status <request-uuid>] [flags]",
+            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>|versions <id>|restore <id> --version <n>|mutation-status <request-uuid>] [flags]",
             "",
             "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
-            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
+            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--label <name>] [--q <text>] [--created-after|--created-before|--updated-after|--updated-before <utc instant|date>] [--sort updated_at|created_at] [--dir desc|asc] [--limit <n>] [--cursor <c>] [--all] — the issues you may see, most recently updated first. A page is 100 by default and at most 500. Filters run in the database BEFORE the page, so a label or title match deep in the set is found. --q is a case-insensitive title contains (% and _ are literal); *-after is inclusive, *-before is exclusive. --json adds next_cursor, has_more, coverage (complete|capped|failed_partial), requested, returned, unique: pass next_cursor back as --cursor with the same other flags. --all walks every page and streams ONE JSON OBJECT PER LINE (NDJSON; rows carry assignee_id, no names), then a final {\"type\":\"coverage\",...} line naming the coverage; an interrupted walk ends with coverage failed_partial, the reason and the resume cursor, and exits 1. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
             "board [--json] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <uuid>] [--label <name>] [--rows <state:n,...>] — the Tickets board, counts, coverage and top five cards per column, through GET /api/work/board. Also cockpit tickets board.",
             "show <id> [<id>...] — one or more issues: title, state, priority, size, assignee (name and email, not just its id), description, and every comment on each. Several ids read in one call — one bad id never loses the rest.",
             "  --json shape: one id answers { issue, comments }, unchanged from before BLI-10450 (plus `estimate`/`size`, BLI-10575). Several ids answer { issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }.",
@@ -108,7 +114,9 @@ export const TOWER_COMMAND_HELP = [
             "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
             "Writes accept --request-id <uuid> and --expected-revision <n>. Keep the UUID and identical fields across retries; JSON includes mutation receipt and mirror delivery separately.",
             "mutation-status <request-uuid> — check your own local commit and mirror delivery after a lost response; no receipt means unknown_check_again.",
-            "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
+            "history <id> [--limit <n>] [--cursor <c>] — every recorded state move and reassignment, oldest first; --json carries the same page fields as list.",
+            "versions <id> [--limit <n>] — every saved description, newest first, each with its number, id, author, source and time (BLI-21300). --json shape: { versions: [{ id, version, markdown, author_id, source, restored_from_version, created_at }] }.",
+            "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }.",
             "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
             "A refusal keeps Tower's own reason label — needs_rls_client, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
@@ -145,7 +153,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "cal",
         [
-            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find "<words>"|calendars|add-ical|create|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [flags]',
+            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find "<words>"|calendars|add-ical|create|duplicate <event id>|batch|undo [<change id>]|rsvp <event id> --response <accepted|declined|tentative>|change <event id>|cancel <event id> --yes|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [flags]',
             "",
             "Every calendar you attached, in one place — plus any calendar a colleague marked shared.",
             "today [--offset 1] [--tz <zone>] — what is on today, in YOUR zone (this machine's, unless --tz says otherwise). --offset 1 is tomorrow, -1 yesterday.",
@@ -164,11 +172,16 @@ export const TOWER_COMMAND_HELP = [
             "      A work @buildlaunchiterate.ca calendar does not need this: connect Google in the browser and `cockpit cal calendars` will list them.",
             'create [--account <name>|--calendar <id>] --title "<what>" --at <iso> --until <iso> [--location "<where>"] [--attendee a@x,b@y] [--all-day] [--meet] — creates the event AT GOOGLE, then here. Attendees are invited by Google; --meet asks for a Google Meet room and prints its address (or says meet_not_available and keeps the event).',
             "      Only a Google calendar can be written to: an iCal secret address is a read address, and `write_not_supported_for_provider` says so by name.",
+            "rsvp <event id> --response accepted|declined|tentative [--comment \"<text>\"] [--scope instance|series] [--occurrence <iso>] [--account <name>] [--key <k>] — answers YOUR invitation; only your own guest entry changes and nobody else is emailed by Tower. Refuses with not_a_guest when you are not on the guest list.",
+            "change <event id> [--title ..] [--at <iso>] [--until <iso>] [--location ..] [--scope instance|following|series] [--occurrence <iso>] [--color 1-11|none] [--reminder <minutes[:popup|email]>|default]... [--visibility default|public|private|confidential] [--transparency opaque|transparent] — a recurring event REQUIRES --scope (instance and following also need --occurrence): instance = this event, following = this and following events (starts a NEW series), series = all events. --reminder repeats, at most 5; `default` alone means the calendar default. Refusals keep the door's reason (scope_required, occurrence_required, scope_not_supported, following_is_series, write_refused). cancel <event id> --yes [--scope instance|following|series] [--occurrence <iso>] [--account <name>] — same scope rules as change; `following` trims the series and prints the new end. create also takes --color, --reminder, --visibility and --transparency.",
             "share <id> --org-visible|--private — makes one of YOUR calendars readable by everyone at BLI, or private again. Sharing never lets anybody else change it.",
             "sync <id> [--full] — reads that calendar now instead of waiting for the cron. --full ignores the sync token / ETag and re-reads everything.",
             "sync-status [<id>] — every calendar's health, or one's: last successful sync, the last pass's own reason, how many events it carried, failures in the last 24h, and the lag between an event's own provider clock and when Tower stored it (ticket 10730).",
             "detach <id> — removes the calendar and its stored events from Tower. The calendar itself is untouched at Google.",
-            "change <event id> [--account <name>] [--title <title>] [--at <iso> --until <iso>] [--location <place>] — changes an event on its own account.",
+            "change <event id> [--account <name>] [--title <title>] [--at <iso> --until <iso>] [--location <place>] [--all-day|--timed] [--tz <zone>] [--expected-version <v>] [--idempotency-key <k>] [--reason <why>] — changes an event on its own account and prints the change id (undo it with `undo`). --all-day converts to an all-day event (--at/--until are dates, --until the day AFTER the last day); --timed converts back. --expected-version refuses (version_conflict) instead of overwriting an event that changed since you read it. Recurring events are refused until scoped edits ship.",
+            "duplicate <event id> [--at <iso> --until <iso>] [--calendar <id>|--account <name>] [--keep-invitees] [--idempotency-key <k>] — copies ONE non-recurring event. The copy has NO guests unless you pass --keep-invitees (Google then emails each one) and no Meet room. Same times unless --at/--until are given; --calendar/--account puts the copy on another of your calendars on purpose. The same --idempotency-key twice makes one copy.",
+            'batch [--idempotency-key <k>] [--reason <why>] — up to 25 changes from JSON on stdin: {"changes":[{"event_id":"…","starts_at":"…","ends_at":"…","expected_version":"…"}]} (or a bare array; fields as `change`: title, location, all_day, time_zone). Each is its own write: the output lists every item and the ones left unchanged, and the exit code is 1 unless all were written.',
+            "undo [<change id>] — a NEW write that puts the recorded earlier values back (or removes the event a create or duplicate made), never a deletion of history. No id means your latest change. Refuses when the event changed again since (undo_stale), when that change was already undone, and for guest changes, cancellations and calendar moves.",
             "cancel <event id> --yes [--account <name>] — same door as delete; a named account must own the event.",
             "delete <event id> --yes — removes ONE event, AT GOOGLE first, then here. Refuses without --yes: a delete can email everybody on it, exactly like create's invitations do. Google already having it gone (404/410) is answered as success, not a refusal.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
@@ -179,10 +192,10 @@ export const TOWER_COMMAND_HELP = [
     [
         "project",
         [
-            "Usage: cockpit project [list] [--archived] [--json]",
+            "Usage: cockpit project [list] [--archived] [--limit <n>] [--cursor <c>] [--json]",
             "",
             "The projects issues are filed under. Bare `cockpit project` lists them.",
-            "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+            "list [--archived] [--limit <n>] [--cursor <c>] — id, active/archived, name. --archived includes archived projects. A page is at most 500; when more exist the output (and --json: next_cursor, has_more, coverage, requested, returned, unique) carries the cursor to pass back as --cursor.",
             "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],

package/dist/commands/local-help-commands.js

@@ -28,7 +28,7 @@ const COMMAND_HELP = new Map([
     // BLI-3709: the Tower nouns live next door, split along the same seam the
     // argument parsers already use — see `local-help-commands-tower.ts`.
     ...TOWER_COMMAND_HELP,
-    ["setup", ["Usage: cockpit setup [--since <7d|30d|date>] [--details] [--person <name|email>] [--compare <name,name>] [--json]", "Read agent setups beside windowed outcomes (default 30 days), or compare two people by first name or email."]],
+    ["setup", ["Usage: cockpit setup [--since <duration|date>] [--until <date>] [--machines] [--details] [--person <name|email>] [--compare <name,name>] [--json]", "Read agent setups beside windowed outcomes (default 30 days), or compare two people by first name or email."]],
     [
         "onboard",
         [

package/dist/commands/local-help.js

@@ -144,7 +144,7 @@ const COMMAND_SUMMARY_LINES = [
     "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>|show <message-id>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
     "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--size S|M|L] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
     "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--attach <path>]... [--dashboard-url <url>] [--json]",
-    "  cockpit cal [event <id> [--occurrence-start <iso>]|export <id> [--occurrence-start <iso>]|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
+    "  cockpit cal [event <id> [--occurrence-start <iso>]|export <id> [--occurrence-start <iso>]|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|duplicate <event id> [--keep-invitees]|batch|undo [<change id>]|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
     "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
     "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",
     `  cockpit search "<words>" [--kind <category,...>] [--limit <n>] [--dashboard-url <url>] [--json]`,
@@ -168,7 +168,7 @@ const COMMAND_SUMMARY_LINES = [
     "  cockpit drills [list|start|answer --confidence <1-5> [--text <words>] [--attempt <id>]|theme|theme set <theme> [--play <t>] [--watch <t>] [--train <t>]|review] [--dashboard-url <url>] [--json]",
     "  cockpit manager <clients|client <client>|run <run-id>|list <client>|queue <client>|show <id>|add <client> --title <t>|edit <id> --version <v>|done|reopen|link|approve|dismiss|proposal|archive|unarchive> [--timeline] [--dashboard-url <url>] [--json]",
     "  cockpit image <describe <file> [--session <id>]|show <sha256-or-prefix>> [--dashboard-url <url>] [--json]",
-    "  cockpit setup [--since <7d|30d|date>] [--details] [--person <name|email>] [--compare <name,name>] [--json]",
+    "  cockpit setup [--since <duration|date>] [--until <date>] [--machines] [--details] [--person <name|email>] [--compare <name,name>] [--json]",
     "  cockpit usage sessions [--person <exact-name>] [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--tool claude|codex] [--since <window>] [--until <iso>] [--cursor <cursor>] [--limit <n>] [--json]",
     "  cockpit usage session <id> [--from-window <n>] [--json]",
     "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/msg-read-line.js

@@ -0,0 +1,32 @@
+/**
+ * The read line, from a terminal (BLI-21299), split out of `msg.ts` to keep it
+ * under the file-size ratchet: the two fields every channel read now carries
+ * (`provenance`, `readBoundary`) and the `read --mark-read` step. The web page,
+ * MCP `msg_read` `mark_read` and this all call `POST /api/msg/channels/[id]/read`.
+ */
+import { askAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const WRITE_DEADLINE_MS = 30_000;
+/** POST the read line to the newest top-level message of a page just read (newest first). */
+export async function markReadThrough(door, channelId, messages) {
+    const newest = messages.find((message) => !message.thread_parent_id);
+    if (!newest) {
+        writeLine(door.io.stderr, `${TAG} mark-read skipped ${JSON.stringify({ channel_id: channelId, reason: "nothing_to_mark" })}`);
+        return { ok: false, reason: "nothing_to_mark", detail: "There was no top-level message on this page to mark read." };
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/channels/${encodeURIComponent(channelId)}/read`,
+        method: "POST",
+        label: "msg mark-read",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { message_id: newest.id },
+    });
+    if (!answer.ok) {
+        writeLine(door.io.stderr, `${TAG} mark-read failed ${JSON.stringify({ channel_id: channelId, reason: answer.reason })}`);
+        return { ok: false, reason: answer.reason, detail: answer.detail };
+    }
+    const changed = answer.body.move?.changed === true;
+    writeLine(door.io.stderr, `${TAG} mark-read ${JSON.stringify({ channel_id: channelId, message_id: newest.id, changed })}`);
+    return { ok: true, messageId: newest.id, changed };
+}