@bli-cockpit/cli 0.2.212 → 0.2.217

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/notes-accounts.js

@@ -19,12 +19,14 @@
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { ask, emit, fail, READ_DEADLINE_MS, TAG } from "./notes-door.js";
 import { printCoverage, readCoverage } from "./notes-recordings.js";
-import { signInToWisprflow } from "./notes-wisprflow-login.js";
+import { connectWisprflowInBrowser } from "./notes-wisprflow-login.js";
+// BLI-17974: the sync loop lives in `notes-sync-loop.ts`; re-exported so `notes.ts` is unchanged.
+export { syncNotetaker } from "./notes-sync-loop.js";
 /** A pass can take a while; a read never should. */
 const WRITE_DEADLINE_MS = 120_000;
 /** An API key is long; anything past this is not one, and is refused by size. */
 const KEY_MAX_CHARS = 500;
-/** BLI-12926: a Wispr Flow sign-in bundle holds an OAuth refresh token, which can run longer. */
+/** BLI-12926: a pre-built Wispr Flow sign-in bundle (`--key-stdin`) holds an OAuth refresh token, which can run longer. */
 const SIGN_IN_MAX_CHARS = 4000;
 /**
  * Granola, read through the one door that answers for it
@@ -102,7 +104,7 @@ export async function listNotesAccounts(command, door) {
         writeLine(door.io.stdout, "");
         writeLine(door.io.stdout, 'Connect one:  printf "%s" "<your fellow api key>" | cockpit notes connect --provider fellow --workspace <subdomain> --key-stdin');
         writeLine(door.io.stdout, '          or:  printf "%s" "<your circleback api key>" | cockpit notes connect --provider circleback --key-stdin');
-        writeLine(door.io.stdout, "          or:  cockpit notes connect --provider wisprflow   (signs in through your browser; no key)");
+        writeLine(door.io.stdout, "          or:  cockpit notes connect --provider wisprflow   (opens Wispr's sign-in in your browser and waits; no key)");
         if (coverage)
             printCoverage(door, coverage);
         return 0;
@@ -126,37 +128,51 @@ export async function listNotesAccounts(command, door) {
     void command;
     return 0;
 }
-export async function connectNotetaker(command, door) {
-    let apiKey;
+/**
+ * BLI-17973. Wispr Flow has no API key: this calls the same start door the
+ * Settings button, the MCP tool and JARVIS call, opens the address it returns
+ * and polls the same status door. Nothing is read from stdin and no credential
+ * passes through here; the server holds the sign-in's state and seals the result.
+ */
+async function connectWisprflowViaBrowser(command, door, options) {
+    if (command.name) {
+        writeLine(door.io.stderr, `${TAG} --name ignored for wisprflow ${JSON.stringify({ reason: "web_sign_in_names_the_account" })}`);
+    }
+    const connected = await connectWisprflowInBrowser(door, options);
+    if (!connected.ok)
+        return fail(door, connected.reason, connected.detail);
+    if (door.json)
+        return emit(door, { ok: true, account: connected.account, already_connected: connected.already });
+    writeLine(door.io.stdout, connected.already
+        ? `Wispr Flow is already connected (${connected.account.id}).`
+        : `Connected wisprflow (${connected.account.id}).`);
+    writeLine(door.io.stdout, "Nothing is read until a sync runs: `cockpit notes sync <id>`, or wait for the half-hourly cron.");
+    return 0;
+}
+export async function connectNotetaker(command, door, wisprflow = {}) {
     if (command.provider === "wisprflow" && !command.keyStdin) {
-        // BLI-12926. Wispr Flow has no API key: the person signs in through their
-        // browser and what gets sealed is the sign-in. Nothing is read from stdin.
-        const signedIn = await signInToWisprflow({ io: door.io });
-        if (!signedIn.ok)
-            return fail(door, signedIn.reason, signedIn.detail);
-        apiKey = signedIn.bundle;
+        return connectWisprflowViaBrowser(command, door, wisprflow);
     }
-    else {
-        // The key comes from stdin and nowhere else. An interactive terminal with
-        // nothing piped in is told how, rather than left waiting on a prompt that
-        // would echo the secret into the scrollback.
-        if (isInteractiveStdin(door.io)) {
-            return fail(door, "key_required_on_stdin", 'The API key is read from stdin, never from a flag. Try: printf "%s" "<your key>" | cockpit notes connect --provider fellow --workspace <subdomain> --key-stdin');
-        }
-        try {
-            apiKey = (await readPipedText(door.io.stdin, {
-                // A Wispr Flow sign-in bundle carries an OAuth refresh token, which
-                // can be far longer than any API key.
-                maxChars: command.provider === "wisprflow" ? SIGN_IN_MAX_CHARS : KEY_MAX_CHARS,
-                overflowMessage: "That is longer than any notetaker API key; nothing was sent.",
-            })).trim();
-        }
-        catch (error) {
-            return fail(door, "key_unreadable", error instanceof Error ? error.message : String(error));
-        }
-        if (apiKey === "") {
-            return fail(door, "key_required_on_stdin", "Nothing arrived on stdin, so nothing was connected.");
-        }
+    // The key comes from stdin and nowhere else. An interactive terminal with
+    // nothing piped in is told how, rather than left waiting on a prompt that
+    // would echo the secret into the scrollback.
+    if (isInteractiveStdin(door.io)) {
+        return fail(door, "key_required_on_stdin", 'The API key is read from stdin, never from a flag. Try: printf "%s" "<your key>" | cockpit notes connect --provider fellow --workspace <subdomain> --key-stdin');
+    }
+    let apiKey;
+    try {
+        apiKey = (await readPipedText(door.io.stdin, {
+            // A pre-built Wispr Flow sign-in bundle carries an OAuth refresh token,
+            // which can be far longer than any API key.
+            maxChars: command.provider === "wisprflow" ? SIGN_IN_MAX_CHARS : KEY_MAX_CHARS,
+            overflowMessage: "That is longer than any notetaker API key; nothing was sent.",
+        })).trim();
+    }
+    catch (error) {
+        return fail(door, "key_unreadable", error instanceof Error ? error.message : String(error));
+    }
+    if (apiKey === "") {
+        return fail(door, "key_required_on_stdin", "Nothing arrived on stdin, so nothing was connected.");
     }
     const answer = await ask(door, {
         path: "/api/notes/accounts",
@@ -281,34 +297,6 @@ export async function detachNotetaker(command, door) {
     writeLine(door.io.stdout, "The meetings it already filed stay where they are.");
     return 0;
 }
-export async function syncNotetaker(command, door) {
-    const accountId = command.accountId ?? "";
-    if (accountId === "") {
-        // One account per call on purpose: the sweep over ALL of them is the cron,
-        // and a terminal asking for "everything" would hide which one failed.
-        return fail(door, "account_required", "Name the notetaker to sync: `cockpit notes sync <account-id>`. `cockpit notes accounts` lists the ids.");
-    }
-    const answer = await ask(door, {
-        path: `/api/notes/accounts/${encodeURIComponent(accountId)}/sync`,
-        method: "POST",
-        label: "notes sync",
-        timeoutMs: WRITE_DEADLINE_MS,
-    });
-    if (!answer.ok)
-        return fail(door, answer.reason, answer.detail);
-    const run = answer.body.run;
-    if (door.json)
-        return emit(door, { ok: true, run });
-    if (!run) {
-        writeLine(door.io.stdout, "Tower answered without a run.");
-        return 0;
-    }
-    // The ledger row's own words, relayed rather than rephrased.
-    writeLine(door.io.stdout, `${run.reason}: ${run.notesAdded} stored, ${run.notesUpdated} unchanged, ${run.notesSkipped} skipped.`);
-    if (run.detail)
-        writeLine(door.io.stdout, run.detail);
-    return run.ok ? 0 : 1;
-}
 /**
  * `sync-status [<account id>]` → `GET /api/notes/sync-status`. Ticket 10730:
  * the read the integrations audit went to `notes_sync_runs` directly for.