@bli-cockpit/cli 0.2.211 → 0.2.213

package/dist/commands/agent-door.js

@@ -52,6 +52,7 @@ export async function askAgentDoor(door, options) {
             httpStatus: status,
             reason: doorReason(body) ?? `http_${status}`,
             detail: doorMessage(body) ?? `Tower answered ${status} and said nothing about why.`,
+            body,
         };
     }
     return { ok: true, httpStatus: result.response.status, body };
@@ -76,10 +77,11 @@ export function emitAgentDoor(door, body, exitCode = 0) {
     writeLine(door.io.stdout, JSON.stringify(body));
     return exitCode;
 }
-export function failAgentDoor(door, tag, reason, detail) {
-    writeLine(door.io.stderr, `${tag} refused ${JSON.stringify({ reason })}`);
+/** `extra` is for a command that has more to say than the reason (`refusal`); a caller that passes none prints exactly what it always did. */
+export function failAgentDoor(door, tag, reason, detail, extra = {}) {
+    writeLine(door.io.stderr, `${tag} refused ${JSON.stringify({ reason, ...extra })}`);
     if (door.json) {
-        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail, ...extra }));
     }
     else {
         writeLine(door.io.stderr, detail);

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

@@ -0,0 +1,371 @@
+/**
+ * `cockpit manager` argument parsing (BLI-5006): client actions and timeline items from the terminal.
+ *
+ *   cockpit manager clients
+ *   cockpit manager client <client>
+ *   cockpit manager run <run-id>
+ *   cockpit manager list <client> [--timeline] [--needs-review] [--status open|done|dropped|closed|all] [--owner <name> | --no-owner] [--overdue] [--kind <kind>] [--search <text>] [--archived] [--review dismissed|all]
+ *   cockpit manager queue <client>
+ *   cockpit manager show <id> [--timeline]
+ *   cockpit manager add <client> --title <t> [--owners "A, B"] [--due YYYY-MM-DD] [--meeting <timeline-id>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]
+ *   cockpit manager add <client> --timeline --kind <kind> --title <t> [--date YYYY-MM-DD] [--owner <one name>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]
+ *   cockpit manager edit <id> --version <v> [--timeline] [--title] [--detail] [--due <date>|none] [--owners "A, B"|none]
+ *                            (timeline: --kind, --date <date>|none, --owner <one name>|none)
+ *   cockpit manager done|reopen <action> --version <v>
+ *   cockpit manager link <action> --version <v> --meeting <timeline-id> | --none
+ *   cockpit manager approve <id> --version <v> [--timeline] [--restore]   (--restore brings a dismissed item back)
+ *   cockpit manager dismiss|archive|unarchive <id> --version <v> [--timeline]
+ *   cockpit manager proposal <id> <proposal-id> accept|dismiss|add-new --version <v> [--timeline]
+ *
+ * Every verb is one `/api/manager` door on this machine's device token. A bare `cockpit manager`,
+ * `help` and `--help` are the help, never a list and never another command.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export const MANAGER_VERBS = [
+    "clients", "client", "run", "list", "queue", "show", "add", "edit", "done", "reopen", "link",
+    "approve", "dismiss", "proposal", "archive", "unarchive",
+];
+export const MANAGER_ACTION_STATUSES = ["open", "done", "dropped", "closed", "all"];
+export const MANAGER_TIMELINE_KINDS = ["meeting", "document", "milestone", "internal"];
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VERSION = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+const ONE_VERB = `manager takes one verb: ${MANAGER_VERBS.join(", ")}. Example: \`cockpit manager clients\` or \`cockpit manager list <client>\`.`;
+const OWN_FLAGS = [
+    "--timeline", "--needs-review", "--status", "--owner", "--owners", "--no-owner", "--kind", "--search", "--archived", "--review",
+    "--title", "--detail", "--due", "--date", "--meeting", "--none", "--version", "--request-id", "--restore", "--overdue", "--source-url", "--source-note",
+];
+const COMMON_FLAGS = ["--home", "--dashboard-url", "--json", "--help"];
+const VALUE_FLAGS = [
+    "--status", "--owner", "--owners", "--kind", "--search", "--review", "--title", "--detail", "--due", "--date", "--meeting",
+    "--version", "--request-id", "--source-url", "--source-note", "--home", "--dashboard-url",
+];
+/** Which flags each verb owns, so a flag on the wrong verb is refused by name rather than ignored. */
+export const FLAGS_BY_VERB = {
+    clients: [],
+    client: [],
+    run: [],
+    list: ["--timeline", "--needs-review", "--status", "--owner", "--no-owner", "--overdue", "--kind", "--search", "--archived", "--review"],
+    queue: [],
+    show: ["--timeline"],
+    add: ["--timeline", "--title", "--detail", "--owners", "--owner", "--due", "--meeting", "--kind", "--date", "--source-url", "--source-note", "--request-id"],
+    edit: ["--timeline", "--version", "--title", "--detail", "--owners", "--owner", "--due", "--kind", "--date"],
+    done: ["--version"],
+    reopen: ["--version"],
+    link: ["--version", "--meeting", "--none"],
+    approve: ["--timeline", "--version", "--restore"],
+    dismiss: ["--timeline", "--version"],
+    proposal: ["--timeline", "--version"],
+    archive: ["--timeline", "--version"],
+    unarchive: ["--timeline", "--version"],
+};
+/** Positional words each verb takes, named for the refusal. */
+const POSITIONALS = {
+    clients: [],
+    client: ["client"],
+    run: ["run id"],
+    list: ["client"],
+    queue: ["client"],
+    show: ["id"],
+    add: ["client"],
+    edit: ["id"],
+    done: ["action id"],
+    reopen: ["action id"],
+    link: ["action id"],
+    approve: ["id"],
+    dismiss: ["id"],
+    proposal: ["id", "proposal id", "accept, dismiss or add-new"],
+    archive: ["id"],
+    unarchive: ["id"],
+};
+/** A value flag given twice would silently keep only the last; say so instead. */
+function refuseRepeatedFlags(args) {
+    for (const flag of VALUE_FLAGS) {
+        const times = args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`)).length;
+        if (times > 1) {
+            throw new Error(flag === "--owners"
+                ? '--owners was given more than once. Put everyone in one list: --owners "Pip Moss, Rowan Ash".'
+                : `${flag} was given more than once. Give it once.`);
+        }
+    }
+}
+export function parseManagerArgs(args) {
+    refuseRepeatedFlags(args);
+    const values = parseNamedArgs(args, { allowedFlags: [...OWN_FLAGS, ...COMMON_FLAGS], valueFlags: VALUE_FLAGS });
+    const base = {
+        kind: "manager",
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+    const first = values.positionals[0];
+    if (values.booleans.has("--help") || first === undefined || first === "help" || first === "-h") {
+        return { ...base, action: "clients", help: true, timeline: false };
+    }
+    if (!MANAGER_VERBS.includes(first))
+        throw new Error(ONE_VERB);
+    const verb = first;
+    const owned = FLAGS_BY_VERB[verb];
+    const stray = [...values.flags.keys(), ...values.booleans].find((flag) => OWN_FLAGS.includes(flag) && !owned.includes(flag));
+    if (stray)
+        throw new Error(`${stray} does not belong to \`cockpit manager ${verb}\`.`);
+    const rest = values.positionals.slice(1);
+    const wanted = POSITIONALS[verb];
+    if (rest.length !== wanted.length) {
+        throw new Error(wanted.length === 0
+            ? `\`cockpit manager ${verb}\` takes no positional arguments.`
+            : `\`cockpit manager ${verb}\` takes exactly: ${wanted.map((word) => `<${word}>`).join(" ")}${verb === "list" || verb === "queue" || verb === "add" || verb === "client" ? " (quote a client's name that has spaces)" : ""}.`);
+    }
+    const timeline = values.booleans.has("--timeline");
+    const shape = { ...base, action: verb, timeline };
+    const flag = (name) => values.flags.get(name);
+    if (verb === "list" || verb === "queue" || verb === "add" || verb === "client")
+        shape.client = rest[0];
+    else if (verb === "run")
+        shape.runId = readId(rest[0], "A run");
+    else if (verb !== "clients")
+        shape.id = readId(rest[0], verb === "done" || verb === "reopen" || verb === "link" ? "An action" : "An item");
+    if (verb === "proposal") {
+        shape.proposalId = rest[1];
+        shape.decision = readDecision(rest[2]);
+    }
+    const needsVersion = !["clients", "client", "run", "list", "queue", "show", "add"].includes(verb);
+    if (needsVersion)
+        shape.version = readVersion(flag("--version"), verb);
+    if (verb === "list")
+        readListFilters(values, shape);
+    if (verb === "add")
+        readAddFields(values, shape);
+    if (verb === "edit")
+        readEditFields(values, shape);
+    if (verb === "link")
+        readLink(values, shape);
+    if (verb === "approve" && values.booleans.has("--restore"))
+        shape.restore = true;
+    return shape;
+}
+function readId(value, what) {
+    if (!ID.test(value))
+        throw new Error(`${what} id looks like 8f14e45f-ceea-467a-9575-1d3a4e7b2c10 (\`cockpit manager list <client>\` prints them).`);
+    return value;
+}
+function readVersion(raw, verb) {
+    if (raw === undefined) {
+        throw new Error(`\`cockpit manager ${verb}\` needs --version <version>: the item's version exactly as \`cockpit manager show <id>\` prints it. It keeps you from writing over a change someone else made.`);
+    }
+    if (!VERSION.test(raw))
+        throw new Error("--version is the item's version exactly as `cockpit manager show <id>` prints it, like 2026-10-09T17:03:11.123456+00:00.");
+    return raw;
+}
+function readDecision(word) {
+    if (word === "accept" || word === "dismiss")
+        return word;
+    if (word === "add-new" || word === "add_as_new")
+        return "add_as_new";
+    throw new Error("The last word of `cockpit manager proposal` is accept, dismiss or add-new.");
+}
+/** One calendar date, `YYYY-MM-DD`, that exists (`2026-02-30` does not). */
+export function isCalendarDate(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match)
+        return false;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(Date.UTC(2000, 0, 1));
+    date.setUTCFullYear(year, month - 1, day);
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+function readDate(raw, flag) {
+    if (!isCalendarDate(raw))
+        throw new Error(`${flag} wants a real date written YYYY-MM-DD, like 2026-10-31.`);
+    return raw;
+}
+/** "A, B" is two people: split on commas, trim, drop blanks. */
+export function splitOwners(raw) {
+    return raw.split(",").map((name) => name.trim()).filter((name) => name !== "");
+}
+function readKind(raw, flag) {
+    if (!MANAGER_TIMELINE_KINDS.includes(raw))
+        throw new Error(`${flag} wants one of ${MANAGER_TIMELINE_KINDS.join(", ")}.`);
+    return raw;
+}
+function readListFilters(values, shape) {
+    const status = values.flags.get("--status");
+    const owner = values.flags.get("--owner");
+    const noOwner = values.booleans.has("--no-owner");
+    const kind = values.flags.get("--kind");
+    const review = values.flags.get("--review");
+    const overdue = values.booleans.has("--overdue");
+    if (shape.timeline && (status || owner || noOwner || overdue))
+        throw new Error(`${status ? "--status" : owner ? "--owner" : noOwner ? "--no-owner" : "--overdue"} filters actions, and a timeline list does not take it. Drop --timeline, or filter the timeline with --kind.`);
+    if (!shape.timeline && kind)
+        throw new Error("--kind filters the timeline. Add --timeline.");
+    if (owner && noOwner)
+        throw new Error("--owner and --no-owner say opposite things. Give one.");
+    if (status && !MANAGER_ACTION_STATUSES.includes(status))
+        throw new Error(`--status wants one of ${MANAGER_ACTION_STATUSES.join(", ")}.`);
+    if (review !== undefined && review !== "dismissed" && review !== "all")
+        throw new Error("--review wants dismissed or all (dismissed items are hidden unless you ask).");
+    if (kind)
+        shape.kindFilter = readKind(kind, "--kind");
+    if (status)
+        shape.status = status;
+    if (owner)
+        shape.ownerFilter = owner.trim();
+    if (noOwner)
+        shape.noOwner = true;
+    if (overdue)
+        shape.overdue = true;
+    if (review)
+        shape.review = review === "dismissed" ? "rejected" : "all";
+    if (values.booleans.has("--archived"))
+        shape.archived = true;
+    const search = optionalNonEmpty(values.flags.get("--search"));
+    if (search)
+        shape.search = search;
+    if (values.booleans.has("--needs-review"))
+        shape.needsReview = true;
+}
+/** The flags only an action has, and the flags only a timeline item has, refused on the wrong one in plain words. */
+function refuseWrongItemFlags(values, shape) {
+    const given = (name) => values.flags.has(name) || values.booleans.has(name);
+    if (shape.timeline) {
+        if (given("--owners"))
+            throw new Error("A timeline item has one owner: use --owner <name> (or --owner none). --owners is for an action.");
+        const action = ["--due", "--meeting"].find(given);
+        if (action)
+            throw new Error(`${action} belongs to an action; a timeline item has a --date. Drop --timeline for an action.`);
+    }
+    else {
+        if (given("--owner"))
+            throw new Error("An action has several owners: use --owners \"A, B\" (or --owners none). --owner is for a timeline item.");
+        const item = ["--kind", "--date"].find(given);
+        if (item)
+            throw new Error(`${item} belongs to a timeline item. Add --timeline, or use --due for an action's date.`);
+    }
+}
+const isNone = (value) => value.trim().toLowerCase() === "none";
+/** `--owners "A, B"` replaces the whole list; `none` is the only way to clear it; a list of blanks is neither. */
+function readOwnersList(raw) {
+    if (isNone(raw))
+        return [];
+    // Commas separate people (the web form's rule), so a name can hold neither a comma nor the quotes around one.
+    if (raw.includes('"'))
+        throw new Error('--owners splits people on commas, so a name cannot hold a comma or a double quote. Write the names without them: --owners "Pip Moss, Rowan Ash".');
+    const owners = splitOwners(raw);
+    if (owners.length === 0)
+        throw new Error("--owners names nobody. Give one or more people separated by commas, or none to clear them.");
+    return owners;
+}
+function readOneOwner(raw) {
+    if (isNone(raw))
+        return null;
+    const name = raw.trim();
+    if (name === "")
+        throw new Error("--owner needs a name, or none to clear it.");
+    return name;
+}
+function readAddFields(values, shape) {
+    refuseWrongItemFlags(values, shape);
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    if (!title)
+        throw new Error("`cockpit manager add` needs --title <text>.");
+    shape.title = title;
+    const detail = values.flags.get("--detail");
+    if (detail !== undefined)
+        shape.detail = detail;
+    const requestId = values.flags.get("--request-id");
+    if (requestId !== undefined)
+        shape.requestId = readId(requestId, "A request");
+    readSource(values, shape);
+    if (shape.timeline) {
+        const kind = values.flags.get("--kind");
+        if (!kind)
+            throw new Error(`\`cockpit manager add --timeline\` needs --kind ${MANAGER_TIMELINE_KINDS.join("|")}.`);
+        shape.itemKind = readKind(kind, "--kind");
+        const date = values.flags.get("--date");
+        if (date && !isNone(date))
+            shape.occurredAt = readDate(date, "--date");
+        const owner = values.flags.get("--owner");
+        const name = owner === undefined ? null : readOneOwner(owner);
+        if (name)
+            shape.ownerName = name;
+        return;
+    }
+    const due = values.flags.get("--due");
+    if (due && !isNone(due))
+        shape.dueAt = readDate(due, "--due");
+    const meeting = values.flags.get("--meeting");
+    if (meeting)
+        shape.timelineItemId = readId(meeting, "A timeline item");
+    const owners = values.flags.get("--owners");
+    const list = owners === undefined ? [] : readOwnersList(owners);
+    if (list.length > 0)
+        shape.owners = list;
+}
+/** Where an item a person adds came from (the web form's Source field): a link, a note, or both. The server checks them again. */
+function readSource(values, shape) {
+    const url = optionalNonEmpty(values.flags.get("--source-url"));
+    if (url !== undefined) {
+        if (!/^https?:\/\/\S+$/i.test(url.trim()))
+            throw new Error("--source-url wants a link starting with http:// or https://. Put anything else in --source-note.");
+        shape.sourceUrl = url.trim();
+    }
+    const note = optionalNonEmpty(values.flags.get("--source-note"));
+    if (note !== undefined) {
+        if (note.trim().length > 1000)
+            throw new Error("--source-note is at most 1,000 characters. A link can be longer: use --source-url.");
+        shape.sourceNote = note.trim();
+    }
+}
+function readEditFields(values, shape) {
+    refuseWrongItemFlags(values, shape);
+    let changes = 0;
+    const title = values.flags.get("--title");
+    if (title !== undefined) {
+        if (title.trim() === "")
+            throw new Error("--title cannot be blank.");
+        shape.title = title.trim();
+        changes += 1;
+    }
+    const detail = values.flags.get("--detail");
+    if (detail !== undefined) {
+        shape.detail = detail;
+        changes += 1;
+    }
+    const owners = values.flags.get("--owners");
+    if (owners !== undefined) {
+        shape.owners = readOwnersList(owners);
+        changes += 1;
+    }
+    const owner = values.flags.get("--owner");
+    if (owner !== undefined) {
+        shape.ownerName = readOneOwner(owner);
+        changes += 1;
+    }
+    const due = values.flags.get("--due");
+    if (due !== undefined) {
+        shape.dueAt = isNone(due) ? null : readDate(due, "--due");
+        changes += 1;
+    }
+    const date = values.flags.get("--date");
+    if (date !== undefined) {
+        shape.occurredAt = isNone(date) ? null : readDate(date, "--date");
+        changes += 1;
+    }
+    const kind = values.flags.get("--kind");
+    if (kind !== undefined) {
+        shape.itemKind = readKind(kind, "--kind");
+        changes += 1;
+    }
+    if (changes === 0) {
+        throw new Error("`cockpit manager edit` has nothing to change. Give at least one of --title, --detail, --owners, --due (--kind, --date, --owner on a timeline item). A flag you leave out keeps its value; `none` clears owners, a due date or a date.");
+    }
+}
+function readLink(values, shape) {
+    const meeting = values.flags.get("--meeting");
+    const none = values.booleans.has("--none");
+    if (meeting && none)
+        throw new Error("--meeting and --none say opposite things. Give one.");
+    if (!meeting && !none)
+        throw new Error("`cockpit manager link` needs --meeting <timeline-id> to link, or --none to unlink.");
+    shape.timelineItemId = meeting ? readId(meeting, "A timeline item") : null;
+}

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

@@ -43,6 +43,7 @@ export { parseUsageArgs } from "./local-args-tower-usage.js";
 export { parseLogsArgs } from "./local-args-tower-logs.js";
 export { parseBrainArgs } from "./local-args-tower-brain.js";
 export { parseApprovalsArgs } from "./local-args-tower-approvals.js";
+export { parseManagerArgs } from "./local-args-tower-manager.js";
 export { parseImageArgs } from "./local-args-tower-image.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';

package/dist/commands/local-args.js

@@ -19,7 +19,7 @@ import { parseGlossaryArgs } from "./glossary.js";
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseApprovalsArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseApprovalsArgs, parseManagerArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -146,6 +146,8 @@ export function parseLocalArgs(argv) {
             return parseBrainArgs(argv.slice(1));
         case "approvals":
             return parseApprovalsArgs(argv.slice(1));
+        case "manager":
+            return parseManagerArgs(argv.slice(1));
         case "image":
             return parseImageArgs(argv.slice(1));
         default:

package/dist/commands/local-command-shapes-manager.js

@@ -0,0 +1,9 @@
+/**
+ * `cockpit manager` command shape (BLI-5006), beside `local-command-shapes-approvals.ts` for the
+ * same reason: `local-command-shapes.ts` sits at the readability ceiling.
+ *
+ * The parser (`local-args-tower-manager.ts`) turns the typed words into the fields a request
+ * carries, so `manager.ts` only builds paths and bodies. A field that is ABSENT is "leave it
+ * alone"; an explicit clear is `owners: []`, `ownerName: null`, `dueAt: null`, `occurredAt: null`.
+ */
+export {};

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

@@ -89,6 +89,47 @@ export const TOWER_OPS_COMMAND_HELP = [
             "approvals_edit, approvals_reject, approvals_rules, approvals_rules_create, approvals_rules_revoke.",
         ],
     ],
+    [
+        "manager",
+        [
+            "Usage: cockpit manager <clients|client|run|list|queue|show|add|edit|done|reopen|link|approve|dismiss|proposal|archive|unarchive> ... [--dashboard-url <url>] [--json]",
+            "",
+            "Tower Manager's client actions and timeline items, from the terminal: the same things the manager page does.",
+            "  cockpit manager clients                      every client, with its id",
+            "  cockpit manager client <client>              one client: state, last read, pages waiting;  run <run-id>  one run's receipt",
+            "  cockpit manager list <client> [--timeline] [--needs-review] [--status open|done|dropped|closed|all] [--owner <name>|--no-owner] [--overdue] [--kind <kind>] [--search <text>] [--archived] [--review dismissed|all]",
+            "                                               actions (default), or with --timeline the timeline; --status, --owner, --no-owner and --overdue (open actions due before today) are for actions, --kind for the timeline.",
+            "                                               Dismissed and archived items are hidden: --review dismissed (or all) and --archived find them. A list holds at most 500 rows and says when it is cut.",
+            "  cockpit manager queue <client>               changes from syncs after onboarding that nobody has looked at yet (the onboarding's own items are not in it)",
+            "                                               an empty queue does not mean everything is reviewed: list <client> --needs-review --status all, and list <client> --timeline --needs-review",
+            "  cockpit manager show <id> [--timeline]       one item in full: detail, sources, suggested changes with their ids, what a sync changed",
+            "  cockpit manager add <client> --title <text> [--owners \"A, B\"] [--due YYYY-MM-DD] [--meeting <timeline-id>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]",
+            "  cockpit manager add <client> --timeline --kind meeting|document|milestone|internal --title <text> [--date YYYY-MM-DD] [--owner <one name>] [--detail <text>] [--source-url <url>] [--source-note <text>] [--request-id <uuid>]",
+            "                                               no --date makes an undated timeline item, which lands in \"Needs a date\"",
+            "                                               --source-url (an http(s) link) and --source-note say where it came from, as the web form's Source does; show prints them",
+            "  cockpit manager edit <id> --version <v> [--timeline] [--title <text>] [--detail <text>] [--due <date>|none] [--owners \"A, B\"|none]",
+            "                                               on a timeline item: [--kind <kind>] [--date <date>|none] [--owner <one name>|none]",
+            "  cockpit manager done <action> --version <v>      tick an action off (an AI action you tick off counts as reviewed by you, and suggested changes it makes moot close);  reopen <action> --version <v>  open it again",
+            "  cockpit manager link <action> --version <v> --meeting <timeline-id>   link an action to the meeting it came from;  --none  unlinks it",
+            "  cockpit manager approve <id> --version <v> [--timeline] [--restore]    the AI's item is right: mark it reviewed;  --restore  brings a DISMISSED item back into the lists, marked reviewed by you (without it, a dismissed item is refused)",
+            "  cockpit manager dismiss <id> --version <v> [--timeline]    the AI's item is wrong: dismiss it (kept, hidden from the lists)",
+            "  cockpit manager proposal <id> <proposal-id> accept|dismiss|add-new --version <v> [--timeline]   decide one suggested change; add-new makes it an item of its own",
+            "  cockpit manager archive <id> --version <v> [--timeline]    delete an item: it moves to the Deleted list (list --archived), kept;  unarchive <id> --version <v>  brings it back",
+            "approve, dismiss and proposal decide the AI's suggestion as YOU: your name is recorded as the reviewer, and the item leaves the review queue unless a suggested change still waits on it.",
+            "<client> is the client's id, or its exact name (any case; `clients` lists them); a name that matches no client, or several, is refused with the names. Ids and versions are printed by list, queue and show. Items you add are reviewed already.",
+            "--version is the item's version exactly as list or show prints it, copied as it is. Every change to an existing item names it: if someone or a sync changed the item",
+            "since, the write is refused with a sentence saying so and nothing is written; run show again for the new version and retry.",
+            "--owners on an action takes, as the web form says, \"One or more people, separated by commas\" (\"Rowan Ash, Juniper Twig\"), and it REPLACES the whole list. Leave it out and the owners stay;",
+            "--owners none clears them. A timeline item has ONE owner: --owner <name> or --owner none. The same pattern clears a date: --due none, --date none.",
+            "Owner names are kept as written, not matched to accounts: use the spelling `list` shows, so one person stays one name. A flag you leave out is never sent, and a flag given twice is refused. A date is YYYY-MM-DD. `cockpit manager`, `manager help` and `manager --help` print this and change nothing.",
+            "add always sends a request id (--request-id <uuid>, else a fresh one) and prints it. If Tower does not answer, nothing was confirmed: rerun the same command with",
+            "--request-id <id> and it retries without making a duplicate.",
+            "--json writes the door's body to stdout, verbatim, and nothing else (an add's body also carries requestId); a refusal is { ok: false, error, detail, refusal? } and exits 1.",
+            "Progress lines on stderr start with [tag]; stdout is the answer (2>/dev/null hides them). Creating a client, syncing, Rebuild brief and merging owners are on the manager page only. Teaching: docs/architecture/tower-manager.md.",
+            "The bli-tower MCP server has the twins: manager_clients, manager_client, manager_run, manager_list, manager_queue, manager_show, manager_add, manager_edit,",
+            "manager_done, manager_reopen, manager_link, manager_approve, manager_dismiss, manager_proposal, manager_archive, manager_unarchive.",
+        ],
+    ],
     [
         "image",
         [

package/dist/commands/local-help.js

@@ -87,6 +87,7 @@ export const rootCommandNames = new Set([
     "logs",
     "brain",
     "approvals",
+    "manager",
     "image",
     ...SURFACE_ALIASES.keys(),
 ]);
@@ -148,6 +149,7 @@ export function localCommandHelp(command) {
         "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
         "  cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
         "  cockpit approvals [list|show <id>|create|approve <id> [--edit]|edit <id> [--approve]|reject <id>|rules [--active true|false]|rules create <card-id> [--any-audience] [--label <text>]|rules revoke <rule-id> [--reason <text>]] [--status <s>] [--limit <n>] [--before <cursor>] [--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 usage sessions [--person <exact-name>] [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--tool claude|codex] [--since <window>] [--until <iso>] [--cursor <cursor>] [--limit <n>] [--json]",

package/dist/commands/local.js

@@ -55,6 +55,7 @@ import { runUsage } from "./usage.js";
 import { runSpeed } from "./speed.js";
 import { runLogs } from "./logs.js";
 import { runApprovals } from "./approvals.js";
+import { runManager } from "./manager.js";
 import { runImage } from "./image.js";
 import { runBrain } from "./brain.js";
 import { parseLocalArgs } from "./local-args.js";
@@ -228,21 +229,15 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
                 return await runSourcesCheck(command, io);
             case "glossary":
                 return await runGlossary(command, io);
-            case "docs":
-                return await runDocs(command, io);
-            case "msg":
-                return await runMsg(command, io);
-            case "issue":
-                return await runIssue(command, io);
+            case "docs": return await runDocs(command, io);
+            case "msg": return await runMsg(command, io);
+            case "issue": return await runIssue(command, io);
             case "cal": return runCal(command, io);
-            case "mail":
-                return await runMail(command, io);
+            case "mail": return await runMail(command, io);
             case "project": return await runProject(command, io);
             case "search": return await runSearch(command, io);
-            case "github":
-                return await runGithub(command, io);
-            case "release":
-                return await runRelease(command, io);
+            case "github": return await runGithub(command, io);
+            case "release": return await runRelease(command, io);
             case "careers": return await runCareers(command, io);
             case "rename": return await runRename(command, io);
             case "setup": return await runSetup(command, io);
@@ -251,6 +246,7 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
             case "logs": return await runLogs(command, io);
             case "brain": return await runBrain(command, io);
             case "approvals": return await runApprovals(command, io);
+            case "manager": return await runManager(command, io);
             case "image": return await runImage(command, io);
         }
     }

package/dist/commands/manager-render.js

@@ -0,0 +1,168 @@
+/**
+ * How `cockpit manager` prints clients, items and a decision for a person (BLI-5006).
+ *
+ * The words are the door's own (a title, an owner, a proposal's fields, a sync's reason); this file
+ * only lays them out. Every item ends with a dim `id` line and its `version`, because the verbs take
+ * both: an id to name the item, and the version (its `updatedAt`) so a write cannot land on top of a
+ * change nobody read. Readable, not exhaustive: `--json` is the whole answer and never comes through here.
+ */
+import { dim } from "./cli-io.js";
+const QUEUE_REASON = {
+    added: "added by a sync, not looked at yet",
+    changed: "changed by a sync since you last saw it",
+    proposal: "has a suggested change waiting",
+};
+export function clientLines(clients, color) {
+    if (clients.length === 0)
+        return ["Tower has no clients yet."];
+    return clients.flatMap((client) => [
+        `${client.name}  [${client.enabled === false ? "disabled" : client.onboardingStatus}]${client.running ? "  [reading now]" : ""}`,
+        `  ${client.lastSyncedAt ? `last synced ${client.lastSyncedAt}` : "never synced"}${client.pagesWaiting ? `, ${client.pagesWaiting} pages waiting to be read` : ""}`,
+        dim(`  id ${client.id}`, color),
+        "",
+    ]).slice(0, -1);
+}
+/** "needs review" when nobody has looked at it; a suggested change waiting is said too. */
+export function reviewLabel(item) {
+    const parts = [item.reviewStatus === "unreviewed" ? "needs review" : item.reviewStatus === "rejected" ? "dismissed" : "reviewed"];
+    const proposals = item.proposedChanges?.length ?? 0;
+    if (proposals > 0)
+        parts.push(`${proposals} suggested change${proposals === 1 ? "" : "s"} waiting`);
+    if (item.syncChange)
+        parts.push("changed by sync");
+    if (item.archivedAt)
+        parts.push("archived");
+    return parts.join(", ");
+}
+/** "owners Pip Moss, Rowan Ash" / "owner Pip Moss", or "no owner" (never a person called "nobody"). */
+function ownersText(item, timeline) {
+    const names = item.owners ?? (item.ownerName ? [item.ownerName] : []);
+    if (names.length === 0)
+        return "no owner";
+    return `${timeline || names.length === 1 ? "owner" : "owners"} ${names.join(", ")}`;
+}
+function whenText(item, timeline) {
+    if (timeline)
+        return item.occurredAt ? item.occurredAt : "no date (it sits in Needs a date)";
+    if (!item.dueAt)
+        return "no due date";
+    return `due ${item.dueAt}${item.overdue ? " (overdue)" : ""}`;
+}
+/** The short row: title, who, when, status, review state, and the id and version the verbs take. */
+export function itemRowLines(item, timeline, color) {
+    const review = reviewLabel(item);
+    const facts = timeline
+        ? [item.kind ?? "item", whenText(item, true), ownersText(item, true)]
+        : [ownersText(item, false), whenText(item, false), item.status ?? "open"];
+    return [`${item.title}  [${review}]`, `  ${facts.join(" | ")}`, dim(`  id ${item.id}  version ${item.updatedAt}`, color)];
+}
+export function listLines(list, timeline, color) {
+    const noun = timeline ? "timeline item" : "action";
+    const shown = list.items.length;
+    const head = shown < list.total ? `Showing ${shown} of ${list.total} ${noun}s.` : `${list.total} ${noun}${list.total === 1 ? "" : "s"}.`;
+    const c = list.counts;
+    const cut = list.truncated ? " A list holds at most 500 rows: narrow it with --status, --owner, --kind, --search or --needs-review." : "";
+    const lines = [`${head}${cut}`, `The client has ${c.openActions} open ${c.openActions === 1 ? "action" : "actions"} (${c.overdue} overdue) and ${c.toReview} ${c.toReview === 1 ? "item" : "items"} to review.`];
+    if (shown === 0)
+        lines.push(`No ${noun}s match.`);
+    for (const item of list.items)
+        lines.push("", ...itemRowLines(item, timeline, color));
+    return lines;
+}
+export function queueLines(queue, color) {
+    const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+    const lines = [`${count(queue.total.timeline, "timeline item")} and ${count(queue.total.actions, "action")} from syncs after onboarding are waiting for a person.`];
+    if (queue.truncated)
+        lines.push(`Showing ${queue.timeline.length} and ${queue.actions.length}: the oldest first.`);
+    for (const [heading, items, timeline] of [["Timeline items", queue.timeline, true], ["Actions", queue.actions, false]]) {
+        if (items.length === 0)
+            continue;
+        lines.push("", `${heading}:`);
+        for (const item of items) {
+            const rows = itemRowLines(item, timeline, color);
+            lines.push("", rows[0], `  ${QUEUE_REASON[item.queuedFor ?? ""] ?? "waiting for review"}`, ...rows.slice(1));
+        }
+    }
+    // The queue leaves out the onboarding's own items by design, so an empty one is not "all reviewed".
+    lines.push("", "Everything not yet reviewed, onboarding included: `cockpit manager list <client> --needs-review --status all` and `list <client> --timeline --needs-review`. `show <id>` lists an item's suggested changes.");
+    return lines;
+}
+function valueText(value, label) {
+    if (value === null || value === undefined || (Array.isArray(value) && value.length === 0))
+        return "(none)";
+    const text = Array.isArray(value) ? value.join(", ") : value;
+    return label ? `${label} (${text})` : text;
+}
+function sourceLine(source) {
+    if (source.addedBy === "human")
+        return `from a person: ${[source.url, source.note].filter(Boolean).join(" | ") || "(empty)"}`;
+    const page = source.pageTitle ?? source.pageUrl ?? "a page";
+    return `${page}${source.quote ? `: "${source.quote}"` : ""}${source.verified === false ? " (not found in the page)" : ""}`;
+}
+/** One item in full: the detail, the sources, every suggested change with its id, and what a sync changed and why. */
+export function itemDetailLines(detail, timeline, color) {
+    const item = detail.item;
+    const lines = [...itemRowLines(item, timeline, color)];
+    if (!timeline && detail.timelineItem)
+        lines.push(`  From the meeting: ${detail.timelineItem.title}${detail.timelineItem.occurredAt ? ` (${detail.timelineItem.occurredAt})` : ""}`);
+    if (timeline && detail.actions && detail.actions.length > 0)
+        lines.push(`  ${detail.actions.length} action${detail.actions.length === 1 ? "" : "s"} came from it: ${detail.actions.map((action) => action.title).join("; ")}`);
+    if (item.detail)
+        lines.push("", "Detail:", ...item.detail.split("\n").map((line) => `  ${line}`));
+    const unverified = item.unverifiedSourceCount ?? 0;
+    const sources = item.sourceCount ?? detail.evidence?.length ?? 0;
+    lines.push("", `Sources: ${sources === 0 ? (item.origin === "human" ? "none (a person added it)" : "none") : sources}${unverified > 0 ? ` (${unverified} quote${unverified === 1 ? "" : "s"} not found in a page the AI was given)` : ""}`);
+    for (const source of (detail.evidence ?? []))
+        lines.push(`  ${sourceLine(source)}`);
+    const proposals = item.proposedChanges ?? [];
+    if (proposals.length > 0) {
+        lines.push("", "Suggested changes waiting for you:");
+        for (const proposal of proposals) {
+            const fields = Object.entries(proposal.fields).map(([name, value]) => `${name}: ${valueText(value, proposal.labels?.[name])}`);
+            lines.push(`  ${proposal.id} (${proposal.kind}): ${fields.join("; ") || "no field change"}`);
+        }
+        lines.push(`  Decide one with: cockpit manager proposal <id> <proposal id> accept|dismiss|add-new --version <version>${timeline ? " --timeline" : ""}`);
+    }
+    const change = item.syncChange;
+    if (change) {
+        lines.push("", `Changed by sync, ${change.at}${change.reason ? `: ${change.reason}` : ""}`);
+        for (const [name, field] of Object.entries(change.fields)) {
+            lines.push(`  ${name}: ${valueText(field.from, field.fromLabel)} -> ${valueText(field.to, field.toLabel)}`);
+        }
+    }
+    return lines;
+}
+/** One client in full: its state, its last read and how many pages wait. */
+export function clientDetailLines(client, color) {
+    const lines = [...clientLines([client], color)];
+    if (client.notionRootUrl)
+        lines.push(`  Notion root: ${client.notionRootUrl}`);
+    if (client.queued)
+        lines.push("  Queued behind another run (Sync all).");
+    if (client.storedPages !== undefined)
+        lines.push(`  ${client.storedPages} stored pages${client.incompletePages ? `, ${client.incompletePages} only partly handed over by Notion` : ""}`);
+    const read = client.lastRead;
+    if (read) {
+        lines.push(`  Last read: ${read.kind}, ${read.reason}, started ${read.startedAt}${read.finishedAt ? `, finished ${read.finishedAt}` : ", still running"}`);
+        lines.push(`    ${read.pagesSeen} pages seen, ${read.pagesChanged} changed; ${read.opsApplied} changes applied, ${read.opsProposed} proposed, ${read.opsRejected} refused`);
+    }
+    else {
+        lines.push("  No read yet.");
+    }
+    const rebuild = client.lastBriefRebuild;
+    if (rebuild)
+        lines.push(`  Last Rebuild brief: ${rebuild.reason}, started ${rebuild.startedAt}, ${rebuild.pages} pages, ${rebuild.briefWritten ? "brief replaced" : "old brief kept"}`);
+    return lines;
+}
+/** One run's receipt: what it read, what it changed, and why it ended. */
+export function runLines(run) {
+    return [
+        `${run.kind} run: ${run.reason}`,
+        `  started ${run.startedAt}${run.finishedAt ? `, finished ${run.finishedAt}` : ", still running"}`,
+        `  ${run.pagesSeen} pages seen, ${run.pagesChanged} changed, ${run.pagesFetched} fetched, ${run.pagesArchived} archived; ${run.versionsConsumed} versions read`,
+        `  ${run.opsApplied} changes applied, ${run.opsProposed} proposed, ${run.opsRejected} refused${run.batchNo !== null ? ` (batch ${run.batchNo})` : ""}`,
+        ...(run.model ? [`  model ${run.model}${run.tokensIn !== null ? `, ${run.tokensIn} tokens in, ${run.tokensOut ?? 0} out` : ""}`] : []),
+        ...(run.clientId ? [`  client ${run.clientId}`] : []),
+        `  id ${run.id}`,
+    ];
+}

package/dist/commands/manager-requests.js

@@ -0,0 +1,100 @@
+const BASE = "/api/manager";
+const enc = encodeURIComponent;
+export function planManagerRequest(command, clientId, newRequestId) {
+    const table = command.timeline ? "timeline" : "actions";
+    const item = `${BASE}/${table}/${enc(command.id ?? "")}`;
+    const seen = { expectedUpdatedAt: command.version };
+    const write = (method, path, body) => ({ method, path, body, logFields: itemLog(table) });
+    switch (command.action) {
+        case "clients":
+            return { method: "GET", path: `${BASE}/clients`, logFields: (a) => ({ clients: arrayLength(a, "clients") }) };
+        case "client":
+            return { method: "GET", path: `${BASE}/clients/${enc(clientId ?? "")}`, logFields: () => ({}) };
+        case "run":
+            return { method: "GET", path: `${BASE}/runs/${enc(command.runId ?? "")}`, logFields: () => ({}) };
+        case "list":
+            return { method: "GET", path: `${BASE}/clients/${enc(clientId ?? "")}/${table}${listQuery(command)}`, logFields: (a) => ({ table, returned: arrayLength(a, "items"), total: numberField(a, "total") }) };
+        case "queue":
+            return { method: "GET", path: `${BASE}/clients/${enc(clientId ?? "")}/review-queue`, logFields: (a) => ({ timeline: arrayLength(a, "timeline"), actions: arrayLength(a, "actions") }) };
+        case "show":
+            return { method: "GET", path: item, logFields: itemLog(table) };
+        case "add": {
+            const path = `${BASE}/clients/${enc(clientId ?? "")}/${table}`;
+            const requestId = command.requestId ?? newRequestId();
+            const common = {
+                title: command.title,
+                ...(command.detail === undefined ? {} : { detail: command.detail }),
+                ...(command.sourceUrl ? { sourceUrl: command.sourceUrl } : {}),
+                ...(command.sourceNote ? { sourceNote: command.sourceNote } : {}),
+                requestId,
+            };
+            if (command.timeline) {
+                return { ...write("POST", path, { kind: command.itemKind, ...common, ...(command.occurredAt ? { occurredAt: command.occurredAt } : {}), ...(command.ownerName ? { ownerName: command.ownerName } : {}) }), requestId };
+            }
+            return { ...write("POST", path, { ...common, ...(command.owners ? { owners: command.owners } : {}), ...(command.dueAt ? { dueAt: command.dueAt } : {}), ...(command.timelineItemId ? { timelineItemId: command.timelineItemId } : {}) }), requestId };
+        }
+        case "edit": {
+            const fields = {};
+            if (command.title !== undefined)
+                fields["title"] = command.title;
+            if (command.detail !== undefined)
+                fields["detail"] = command.detail;
+            if (command.itemKind !== undefined)
+                fields["kind"] = command.itemKind;
+            if (command.dueAt !== undefined)
+                fields["dueAt"] = command.dueAt;
+            if (command.occurredAt !== undefined)
+                fields["occurredAt"] = command.occurredAt;
+            if (command.owners !== undefined)
+                fields["owners"] = command.owners;
+            if (command.ownerName !== undefined)
+                fields["ownerName"] = command.ownerName;
+            return write("PATCH", item, { ...seen, ...fields });
+        }
+        case "done": return write("POST", `${item}/status`, { ...seen, status: "done" });
+        case "reopen": return write("POST", `${item}/status`, { ...seen, status: "open" });
+        case "link": return write("POST", `${item}/link`, { ...seen, timelineItemId: command.timelineItemId ?? null });
+        case "approve": return write("POST", `${item}/review`, { ...seen, decision: "accept" });
+        case "dismiss": return write("POST", `${item}/review`, { ...seen, decision: "dismiss" });
+        case "proposal": return write("POST", `${item}/proposal`, { ...seen, decision: command.decision, proposalId: command.proposalId });
+        case "archive": return write("POST", `${item}/archive`, seen);
+        case "unarchive": return write("POST", `${item}/unarchive`, seen);
+    }
+}
+function listQuery(command) {
+    const query = new URLSearchParams();
+    if (command.timeline && command.kindFilter)
+        query.set("kind", command.kindFilter);
+    if (!command.timeline && command.status)
+        query.set("status", command.status);
+    if (!command.timeline && command.ownerFilter)
+        query.set("owner", command.ownerFilter);
+    if (!command.timeline && command.noOwner)
+        query.set("noOwner", "true");
+    if (!command.timeline && command.overdue)
+        query.set("overdue", "true");
+    if (command.review)
+        query.set("review", command.review);
+    if (command.archived)
+        query.set("archived", "true");
+    if (command.needsReview)
+        query.set("needsReview", "true");
+    if (command.search)
+        query.set("q", command.search);
+    const text = query.toString();
+    return text ? `?${text}` : "";
+}
+function itemLog(table) {
+    return (answer) => {
+        const item = answer && typeof answer === "object" ? answer.item : undefined;
+        return { table, item_id: item?.id ?? null, review_status: item?.reviewStatus ?? null };
+    };
+}
+function arrayLength(answer, key) {
+    const value = answer && typeof answer === "object" ? answer[key] : undefined;
+    return Array.isArray(value) ? value.length : null;
+}
+function numberField(answer, key) {
+    const value = answer && typeof answer === "object" ? answer[key] : undefined;
+    return typeof value === "number" ? value : null;
+}

package/dist/commands/manager.js

@@ -0,0 +1,211 @@
+/**
+ * `cockpit manager` (BLI-5006): Tower Manager's client actions and timeline items from the terminal.
+ *
+ * Plain words: Tower reads a client's Notion pages and keeps their actions and timeline. This lists
+ * them, adds and edits them, ticks them off, links an action to the meeting it came from, and
+ * decides the AI's suggestions, the same things the manager page does.
+ *
+ * Sixteen verbs, each one `/api/manager` door on this machine's device token, the same door the MCP
+ * twins (`manager_*`) use; the door passes Railway's answer through unchanged. Every write on an
+ * existing item carries `--version`, the item's `updatedAt` as `list`/`show` print it: a stale one is
+ * refused with the door's own sentence and nothing is written. `approve`, `dismiss` and `proposal`
+ * decide as the CALLER (their name is the one recorded). `approve` reads the item first: a dismissed one is brought back
+ * only with `--restore`. `--json` carries the door's body, verbatim.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { colorEnabled, writeLine } from "./cli-io.js";
+import { localCommandHelp } from "./local-help.js";
+import { clientDetailLines, clientLines, itemDetailLines, itemRowLines, runLines, listLines, queueLines, } from "./manager-render.js";
+import { planManagerRequest } from "./manager-requests.js";
+const TAG = "[manager cli]";
+/**
+ * Longer than the door waits for the manager server (50 s, `MANAGER_DOOR_TIMEOUT_MS`) and than the door's own
+ * platform limit (`maxDuration` 60 s), so a slow write comes back as the door's named 504 rather than this end
+ * giving up first while the write may still land.
+ */
+export const MANAGER_DEADLINE_MS = 65_000;
+const staleHint = (id, timeline) => `Run \`cockpit manager show ${id}${timeline ? " --timeline" : ""}\` for the current version and try again.`;
+/** Refusals that mean "the item is not as you last saw it": reading it again is the way forward. */
+/** The verbs that change an existing item. */
+const WRITES = new Set(["edit", "done", "reopen", "link", "approve", "dismiss", "proposal", "archive", "unarchive"]);
+const RESEEN_REFUSALS = new Set(["item_changed", "item_busy", "proposal_decided", "no_proposal"]);
+export async function runManager(command, io) {
+    if (command.help) {
+        writeLine(io.stderr, `${TAG} help printed ${JSON.stringify({ reason: "no_verb_or_help_asked" })}`);
+        writeLine(io.stdout, localCommandHelp("manager"));
+        return 0;
+    }
+    let door;
+    try {
+        door = await openAgentDoor("manager", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    let clientId;
+    if (command.client !== undefined) {
+        const resolved = await resolveClient(door, command.client);
+        if (typeof resolved !== "string")
+            return resolved.exit;
+        clientId = resolved;
+    }
+    // Approving a dismissed item brings it back (the web's Restore): say so first, and write nothing unless --restore was given.
+    if (command.action === "approve") {
+        const stopped = await checkRestore(command, door);
+        if (stopped !== undefined)
+            return stopped;
+    }
+    const plan = planManagerRequest(command, clientId, randomUUID);
+    return execute(command, door, plan, colorEnabled(io));
+}
+async function execute(command, door, plan, color) {
+    const answer = await askAgentDoor(door, { path: plan.path, method: plan.method, label: `manager ${command.action}`, timeoutMs: MANAGER_DEADLINE_MS, ...(plan.body === undefined ? {} : { body: plan.body }) });
+    if (!answer.ok)
+        return refuse(door, answer, command, plan.requestId);
+    writeLine(door.io.stderr, `${TAG} ${command.action} answered ${JSON.stringify({ http_status: answer.httpStatus, ...(plan.requestId ? { request_id: plan.requestId } : {}), ...plan.logFields(answer.body) })}`);
+    // An add's JSON is the door's body plus the `requestId` it was sent under, so a retry can name it.
+    if (door.json)
+        return emitAgentDoor(door, plan.requestId && answer.body && typeof answer.body === "object" ? { ...answer.body, requestId: plan.requestId } : answer.body);
+    const out = door.io.stdout;
+    const lines = renderAnswer(command, answer.body, color);
+    if (plan.requestId)
+        lines.push(`  request id ${plan.requestId} (to retry this add without making a duplicate, rerun it with --request-id ${plan.requestId})`);
+    for (const line of lines)
+        writeLine(out, line);
+    return 0;
+}
+/** What `approve` needs to know before it writes: is the item dismissed? A number is the exit code of a refusal; undefined means go on and write. */
+async function checkRestore(command, door) {
+    const read = { ...command, action: "show" };
+    const plan = planManagerRequest(read, undefined, randomUUID);
+    const answer = await askAgentDoor(door, { path: plan.path, method: plan.method, label: "manager approve (read)", timeoutMs: MANAGER_DEADLINE_MS });
+    if (!answer.ok)
+        return refuse(door, answer, read);
+    const dismissed = answer.body?.item?.reviewStatus === "rejected";
+    writeLine(door.io.stderr, `${TAG} approve read the item ${JSON.stringify({ http_status: answer.httpStatus, dismissed, restore: command.restore === true })}`);
+    if (dismissed && command.restore !== true) {
+        return failAgentDoor(door, TAG, "restore_needed", "This item is dismissed. Approving it brings it back into the lists, marked reviewed by you. To do that, run the same command with --restore.");
+    }
+    if (!dismissed && command.restore === true) {
+        return failAgentDoor(door, TAG, "not_dismissed", "--restore is only for a dismissed item; this one is not dismissed. Run approve without --restore.");
+    }
+    return undefined;
+}
+function renderAnswer(command, body, color) {
+    const timeline = command.timeline;
+    switch (command.action) {
+        case "clients": return clientLines(body.clients, color);
+        case "client": return clientDetailLines(body, color);
+        case "run": return runLines(body);
+        case "list": return listLines(body, timeline, color);
+        case "queue": return queueLines(body, color);
+        case "show": return itemDetailLines(body, timeline, color);
+        default: return [...writeSentence(command, body), ...itemRowLines(body.item, timeline, color)];
+    }
+}
+/** What a write did, in one sentence a person reads; the item's new version follows on its row. */
+function writeSentence(command, body) {
+    const as = "as you";
+    // Approving the item or deciding one change leaves the queue only when no other suggested change waits on it.
+    const waiting = body.item?.proposedChanges?.length ?? 0;
+    const queue = waiting === 0 ? "It leaves the review queue." : `${waiting === 1 ? "Its other suggested change still waits" : `Its ${waiting} other suggested changes still wait`} in the review queue.`;
+    switch (command.action) {
+        case "add": return [command.timeline && !command.occurredAt ? "Added. It has no date, so it sits in \"Needs a date\"." : "Added."];
+        case "edit": return ["Saved your changes."];
+        // Railway writes nothing when the action already has that status, so its version comes back unchanged.
+        case "done": return [body.item?.updatedAt === command.version ? "Already done; nothing changed." : "Marked done."];
+        case "reopen": return [body.item?.updatedAt === command.version ? "Already open; nothing changed." : "Reopened."];
+        case "link": return [command.timelineItemId ? `Linked to ${body.timelineItem?.title ?? "that meeting"}.` : "Unlinked from its meeting."];
+        case "approve": return [command.restore ? `Restored: ${body.item?.title ?? "that item"}, back in the lists and marked reviewed by you.` : `Approved ${as}. ${queue.replace("other ", "")}`];
+        case "dismiss": return [`Dismissed ${as}. It leaves the review queue.`];
+        case "proposal": return [
+            command.decision === "add_as_new" && body.added ? `Decided ${as}: added as a new item, ${body.added.title} (id ${body.added.id}).` : `Decided ${as}: ${command.decision === "accept" ? "accepted" : command.decision === "dismiss" ? "dismissed" : "added as a new item"}. ${queue}`,
+        ];
+        case "archive": return ["Archived (deleted from the lists; `unarchive` brings it back)."];
+        case "unarchive": return ["Brought back."];
+        default: return [];
+    }
+}
+/** The client as an id, or its exact name (case-insensitive) looked up in `clients`; anything else is refused by name. */
+async function resolveClient(door, ref) {
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref))
+        return ref;
+    const answer = await askAgentDoor(door, { path: "/api/manager/clients", method: "GET", label: "manager clients", timeoutMs: MANAGER_DEADLINE_MS });
+    if (!answer.ok)
+        return { exit: refuse(door, answer, undefined) };
+    const clients = answer.body.clients;
+    const wanted = ref.trim().toLowerCase();
+    const matches = clients.filter((client) => client.name.trim().toLowerCase() === wanted);
+    if (matches.length === 1) {
+        writeLine(door.io.stderr, `${TAG} client resolved ${JSON.stringify({ client_id: matches[0].id, by: "name", clients: clients.length })}`);
+        return matches[0].id;
+    }
+    const names = clients.map((client) => client.name).join(", ");
+    const detail = matches.length === 0
+        ? `No client is named "${ref}". ${clients.length === 0 ? "Tower has no clients yet." : `Clients: ${names}. (\`cockpit manager clients\` lists them with their ids.)`}`
+        : `${matches.length} clients are named "${ref}". Use the id instead: ${matches.map((client) => client.id).join(", ")}.`;
+    return { exit: failAgentDoor(door, TAG, matches.length === 0 ? "client_not_found" : "client_name_ambiguous", detail, { clients: clients.length, matches: matches.length }) };
+}
+/**
+ * A refusal keeps Railway's own sentence: `message` (the door's own shape), else `error` when `reason`
+ * is a string too (Railway's `{ error, reason, refusal? }`). The label is `reason`; `refusal` is the finer
+ * label, shown beside it on stderr and in the `--json` object.
+ */
+/** What to do next after a refusal that is not "read it again", so every refusal ends with a way forward. */
+function nextStep(reason, refusal, command) {
+    const id = command?.id ?? "<id>";
+    const flag = command?.timeline ? " --timeline" : "";
+    if (reason === "not_found" && command?.id) {
+        return command.timeline
+            ? " Check the id with `cockpit manager list <client> --timeline`; for an action, drop --timeline."
+            : ` Check the id with \`cockpit manager list <client>\`; for a timeline item, add --timeline${command.action === "done" || command.action === "reopen" || command.action === "link" ? " (done, reopen and link are for actions only)" : ""}.`;
+    }
+    // The door's key check (no such key, or a revoked one): this machine needs signing in again.
+    if (reason === "http_401")
+        return " Sign this machine in to Tower again with `cockpit login`, then retry.";
+    if (reason === "gateway_unreachable")
+        return " Check the address (--dashboard-url, or the one `cockpit login` saved) and your network, then try again.";
+    if ((reason === "manager_unreachable" || reason === "manager_timeout") && (command === undefined || !WRITES.has(command.action) && command.action !== "add")) {
+        return " Try again in a minute; if it keeps failing, Tower's manager server may be down.";
+    }
+    switch (refusal) {
+        // Another person's or another client's add already used this id: a fresh one makes the item.
+        case "request_reused": return " Run the add again without --request-id to make a new item.";
+        case "proposal_replaced": return ` Run \`cockpit manager show ${id}${flag}\` to see the suggested changes waiting and their ids.`;
+        case "item_archived": return ` Bring it back first: \`cockpit manager unarchive ${id}${flag} --version <v>\` (\`list <client>${flag} --archived\` prints its version).`;
+        case "item_dismissed": return ` Restore it first: \`cockpit manager approve ${id}${flag} --version <v> --restore\` (\`list <client>${flag} --review dismissed\` prints its version).`;
+        case "person_item_not_dismissable": return ` To delete an item a person added, use \`cockpit manager archive ${id}${flag} --version <v>\`.`;
+        case "timeline_not_live": return " Link to a live timeline item of the same client: `cockpit manager list <client> --timeline` lists them.";
+        case "item_not_archived": return " It is already in the lists; nothing to bring back.";
+        default: return "";
+    }
+}
+function refuse(door, answer, command, requestId) {
+    const body = answer.body && typeof answer.body === "object" ? answer.body : {};
+    const text = (value) => (typeof value === "string" && value.trim() !== "" ? value : undefined);
+    const sentence = text(body["message"]) ?? (text(body["reason"]) ? text(body["error"]) : undefined) ?? answer.detail;
+    const refusal = text(body["refusal"]);
+    const reseen = answer.reason === "invalid_state" && (refusal === undefined || RESEEN_REFUSALS.has(refusal));
+    const hint = reseen && command?.id
+        ? ` ${staleHint(command.id, command.timeline)}`
+        : nextStep(answer.reason, refusal, command);
+    // An add with no answer from Tower (or a server error) may or may not have been made: the same request id makes the retry safe.
+    const unconfirmed = requestId !== undefined && (answer.httpStatus === undefined || answer.httpStatus >= 500);
+    const noAnswer = answer.httpStatus === undefined || answer.httpStatus >= 500;
+    // A change to an existing item with no answer may or may not have landed: look before trying again.
+    const changedUnknown = !unconfirmed && noAnswer && command?.id !== undefined && WRITES.has(command.action);
+    const retry = unconfirmed
+        ? ` Nothing was confirmed: Tower did not say whether the item was made. Rerun the same command with \`--request-id ${requestId}\` to retry without making a duplicate.`
+        : changedUnknown
+            ? ` It may or may not have been saved: run \`cockpit manager show ${command.id}${command.timeline ? " --timeline" : ""}\` to see, and use the version it prints if you try again.`
+            : "";
+    const stop = hint || retry ? (/[.!?]$/.test(sentence) ? "" : ".") : "";
+    return failAgentDoor(door, TAG, answer.reason, `${sentence}${stop}${hint}${retry}`, { ...(refusal ? { refusal } : {}), ...(unconfirmed ? { requestId } : {}) });
+}

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.211");
+    writeLine(io?.stdout ?? process.stdout, "0.2.213");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.211",
+  "version": "0.2.213",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,9 +27,9 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.65",
-    "@bli-cockpit/mcp": "0.1.120",
-    "@bli-cockpit/telemetry-core": "0.1.74"
+    "@bli-cockpit/memory-mcp": "0.1.66",
+    "@bli-cockpit/mcp": "0.1.122",
+    "@bli-cockpit/telemetry-core": "0.1.75"
   },
   "repository": {
     "type": "git",