@bli-cockpit/cli 0.2.57 → 0.2.59

package/dist/commands/browser-open.js

@@ -0,0 +1,88 @@
+/**
+ * Opening a URL in the person's own browser (BLI-3731).
+ *
+ * One sign-in means the terminal hands the browser a link. That is the whole
+ * job here, and it follows the same discipline `commands/editor.ts` wrote down
+ * for spawning a program on somebody's behalf:
+ *
+ * 1. **`spawnSync` with an ARRAY of arguments and `shell: false`.** Nothing is
+ *    interpolated into a command line, ever.
+ * 2. **Windows does NOT go through `cmd /c start`.** `start` is a cmd builtin,
+ *    so reaching it means handing cmd.exe a string it re-parses — and `&` in a
+ *    query string is a command separator there. `rundll32 url.dll,
+ *    FileProtocolHandler <url>` takes the URL as one argv and never sees a
+ *    shell. (Our own URL has no `&` today; the point is that it cannot ever
+ *    matter.)
+ * 3. **The URL is validated before it is spawned.** Only `https:` and a
+ *    loopback `http:` are opened, so a bad dashboard URL cannot turn into a
+ *    `file:` or a custom protocol handler.
+ *
+ * Opening is BEST EFFORT and never fatal: the caller has already printed the
+ * link, so a machine with no browser — an SSH session, a locked-down Windows
+ * host — loses nothing but a convenience. Every branch returns a reason label,
+ * success included, and the caller logs it.
+ */
+import { spawnSync } from "node:child_process";
+/** `https:` anywhere, `http:` only on loopback — a dev dashboard is the reason. */
+export function isOpenableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return (parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1"));
+}
+export function openInBrowser(url, options = {}) {
+    if (!isOpenableUrl(url)) {
+        return {
+            ok: false,
+            reason: "url_not_openable",
+            detail: "Only https:// (or http:// on localhost) links are opened.",
+        };
+    }
+    const platform = options.platform ?? process.platform;
+    const spawnImpl = options.spawn ?? spawnSync;
+    const opener = openerFor(platform, url);
+    if (!opener) {
+        return {
+            ok: false,
+            reason: "no_opener_for_platform",
+            detail: `No known browser opener for ${platform}; open the link by hand.`,
+        };
+    }
+    const result = spawnImpl(opener.program, opener.args, {
+        stdio: "ignore",
+        shell: false,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            reason: "opener_not_started",
+            detail: `${opener.program} could not be started; open the link by hand.`,
+        };
+    }
+    if (typeof result.status === "number" && result.status !== 0) {
+        return {
+            ok: false,
+            reason: "opener_exited_nonzero",
+            detail: `${opener.program} exited ${result.status}; open the link by hand.`,
+        };
+    }
+    return { ok: true, reason: "launched", program: opener.program };
+}
+function openerFor(platform, url) {
+    if (platform === "darwin")
+        return { program: "open", args: [url] };
+    if (platform === "win32") {
+        // See rule 2 in the header: never `cmd /c start`.
+        return { program: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url] };
+    }
+    if (platform === "linux")
+        return { program: "xdg-open", args: [url] };
+    return null;
+}

package/dist/commands/docs.js

@@ -14,6 +14,14 @@
  * /api/docs/documents` already returns — the same read `docs list` prints,
  * never a second query the server does not already answer.
  *
+ * THE LIST IS METADATA (BLI-3737). It carries id, slug, title, visibility,
+ * parent, author, updated_at and `body_chars` — never a body. On 2026-09-05
+ * `cockpit docs list --json` answered 603,779 bytes for 155 documents,
+ * because the door's select still carried `body_markdown`; an agent had to
+ * spend the whole library to learn 155 titles. `--parent`, `--query` and
+ * `--limit` ride to the door as query parameters, so the narrowing happens in
+ * the database rather than here.
+ *
  * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
  * `needs_rls_client`, `document_not_found_or_unreadable`,
  * `document_not_writable`, `title_too_long`, `content_too_long`,
@@ -30,7 +38,7 @@ export async function runDocs(command, io) {
     const door = await openAgentDoor("docs", command, io);
     switch (command.action) {
         case "list":
-            return listDocs(door);
+            return listDocs(command, door);
         case "tree":
             return treeDocs(door);
         case "read":
@@ -41,9 +49,21 @@ export async function runDocs(command, io) {
             return updateDoc(command, door);
     }
 }
-async function listDocs(door) {
+/** `--parent`, `--query`, `--limit` as the door's own query parameters (BLI-3737). */
+export function docsListPath(command) {
+    const params = new URLSearchParams();
+    if (command.parentId)
+        params.set("parent_id", command.parentId);
+    if (command.query)
+        params.set("query", command.query);
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const search = params.toString();
+    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
+}
+async function listDocs(command, door) {
     const answer = await askAgentDoor(door, {
-        path: "/api/docs/documents",
+        path: docsListPath(command),
         method: "GET",
         label: "docs list",
         timeoutMs: READ_DEADLINE_MS,
@@ -54,14 +74,15 @@ async function listDocs(door) {
     if (door.json)
         return emitAgentDoor(door, { ok: true, documents });
     if (documents.length === 0) {
-        writeLine(door.io.stdout, "No documents.");
+        writeLine(door.io.stdout, command.query ? `No document matches "${command.query}".` : "No documents.");
         return 0;
     }
     for (const doc of documents) {
-        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+        const size = typeof doc.body_chars === "number" ? `${doc.body_chars}c`.padStart(8) : "       ?";
+        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${size}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
     }
     writeLine(door.io.stdout, "");
-    writeLine(door.io.stdout, `${documents.length} document(s).`);
+    writeLine(door.io.stdout, `${documents.length} document(s). Bodies come from \`cockpit docs read <id|slug>\`.`);
     return 0;
 }
 function renderTree(nodes, io, depth) {

package/dist/commands/doctor-report.js

@@ -1,4 +1,5 @@
 import { redactedHealthDetail } from "../health-detail.js";
+import { setupReceiptBlock } from "./setup-receipt-lines.js";
 export function ok(id, code, message) {
     return { id, status: "ok", code, message };
 }
@@ -37,7 +38,9 @@ export async function maybeReportDoctorEvents(context, rows) {
         io: context.io,
     });
 }
-export function writeDoctorOutput(command, io, rows) {
+export function writeDoctorOutput(command, io, rows, 
+/** BLI-3731. Absent means it could not be read; doctor says so rather than nothing. */
+setupReceipt) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({
             status: rows.some((row) => row.status === "fail" || row.hardStop)
@@ -45,6 +48,8 @@ export function writeDoctorOutput(command, io, rows) {
                 : "pass",
             dry_run: command.dryRun,
             steps: rows,
+            setup_receipt: setupReceipt?.receipt ?? null,
+            memory_install: setupReceipt?.memory ?? null,
         }, null, 2));
         return;
     }
@@ -61,6 +66,17 @@ export function writeDoctorOutput(command, io, rows) {
         writeLine(io.stderr, `${row.id}:`);
         writeLine(io.stderr, row.message);
     }
+    // BLI-3731. The invariant table says whether collection is healthy; this
+    // says whether the machine is CONNECTED — the browser sign-in, the device
+    // session, both agent hosts and the scheduler, every word read back off this
+    // host. Printed last because it is what a person came to check on day one.
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, "Connected:");
+    for (const line of setupReceipt
+        ? setupReceiptBlock(setupReceipt, { indent: "  " })
+        : ["  unknown — this machine could not be read this run."]) {
+        writeLine(io.stdout, line);
+    }
 }
 function doctorEvent(row) {
     const status = row.status === "fail" || row.hardStop

package/dist/commands/doctor.js

@@ -2,6 +2,7 @@ import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, rea
 import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
 import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
 import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, } from "./doctor-report.js";
+import { refreshSetupReceipt } from "./setup-receipt.js";
 import { checkCliLatest, fixCliLatest, latestCliVersionFromNpm, reexecDoctor, } from "./doctor-update.js";
 export async function runDoctor(command, io, hooks, overrides = {}) {
     const deps = { ...defaultDoctorDeps(hooks), ...overrides };
@@ -40,12 +41,15 @@ export async function runDoctorWithDeps(command, io, deps) {
             break;
         if (fixed.reexecExitCode !== undefined) {
             await maybeReportDoctorEvents(context, rows);
-            writeDoctorOutput(command, io, rows);
+            writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
             return fixed.reexecExitCode;
         }
     }
     await maybeReportDoctorEvents(context, rows);
-    writeDoctorOutput(command, io, rows);
+    // Doctor is the surface a person opens when something is wrong, so it
+    // re-READS the machine rather than quoting a cache — and caching what it
+    // read is what keeps the 15-minute heartbeat from paying for the probe.
+    writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
     return rows.some((row) => row.status === "fail" || row.hardStop) ? 1 : 0;
 }
 function doctorInvariants() {
@@ -129,6 +133,12 @@ function defaultDoctorDeps(hooks) {
         fixDisk: fixDiskState,
         checkSync: checkSyncState,
         fixSync: fixSyncState,
+        readSetupReceipt: (context) => refreshSetupReceipt(context.io, {
+            ...(context.command.homeDir ? { homeDir: context.command.homeDir } : {}),
+            ...(context.command.dashboardUrl
+                ? { dashboardUrl: context.command.dashboardUrl }
+                : {}),
+        }),
     };
 }
 // Re-exported so every consumer keeps importing from `./doctor.js` regardless

package/dist/commands/heartbeat.js

@@ -23,10 +23,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
+import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, memoryInstallGaps, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
+import { readCachedSetupReceipt } from "./setup-receipt.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
@@ -108,8 +110,40 @@ export function buildCollectorHeartbeat(options) {
         ...(typeof options.facts.sessionsPendingUpload === "number"
             ? { sessions_pending_upload: options.facts.sessionsPendingUpload }
             : {}),
+        ...(options.memoryInstall ? { memory_install: options.memoryInstall } : {}),
+        ...(options.setupReceipt ? { setup_receipt: options.setupReceipt } : {}),
     };
 }
+/**
+ * The cached memory receipt for this tick, or null with a named reason
+ * (BLI-3729).
+ *
+ * Reads the file `cockpit memory install` / `cockpit memory status` left
+ * behind; it does NOT re-inspect the host configs, which would cost five file
+ * reads and a `--print-config` spawn every fifteen minutes to re-prove a state
+ * that changes about once a month. The reason is returned rather than logged
+ * here so the ONE heartbeat log line carries it.
+ */
+export async function readHeartbeatMemoryReceipt(options) {
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const result = await readMemoryReceiptFile({
+        stateDir: paths.state_dir,
+        readText: async (file) => {
+            try {
+                return await fs.promises.readFile(file, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        ...(options.now ? { now: options.now } : {}),
+        parse: (value) => {
+            const parsed = MemoryInstallReceiptSchema.safeParse(value);
+            return parsed.success ? parsed.data : null;
+        },
+    });
+    return { receipt: result.receipt, reason: result.reason };
+}
 /**
  * Sends the heartbeat. Returns whether it landed; never throws.
  *
@@ -148,10 +182,34 @@ export async function sendCollectorHeartbeatBestEffort(options) {
         }));
         return false;
     }
+    const memory = await readHeartbeatMemoryReceipt({
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
+        ...(options.now ? { now: options.now } : {}),
+    }).catch(() => ({ receipt: null, reason: "receipt_read_threw" }));
+    // BLI-3731. Read the CACHE, never re-probe: computing the receipt costs five
+    // file reads and a `--print-config` spawn, and these facts change about
+    // monthly. `cockpit memory install`, `onboard` and `doctor` refresh it; a
+    // tick only carries it. Both branches say something, because "the ops board
+    // shows no receipt for this machine" has two very different causes.
+    const setupReceipt = await readCachedSetupReceipt(options.homeDir, options.now ?? new Date());
+    console.error(setupReceipt
+        ? "[heartbeat] carrying this machine's setup receipt"
+        : "[heartbeat] no usable setup receipt to carry; the ops board keeps the last one it has", JSON.stringify(setupReceipt
+        ? {
+            reason: "setup_receipt_cached",
+            gap_count: setupReceiptGaps(setupReceipt).length,
+            gaps: setupReceiptGaps(setupReceipt),
+        }
+        : {
+            reason: "setup_receipt_absent_or_stale",
+            next_action: "run `cockpit doctor` to refresh it",
+        }));
     const heartbeat = buildCollectorHeartbeat({
         roots: options.roots,
         facts: options.facts,
+        setupReceipt,
         ...(options.now ? { now: options.now } : {}),
+        memoryInstall: memory.receipt,
     });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
@@ -184,6 +242,12 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             sessions_outside_root: heartbeat.sessions_outside_root ?? null,
             sessions_new_this_tick: heartbeat.sessions_new_this_tick ?? null,
             sessions_pending_upload: heartbeat.sessions_pending_upload ?? null,
+            // BLI-3729. Both branches: a tick that reports no receipt says WHY,
+            // and a tick that reports one says whether memory is fully on. "Is BLI
+            // Memory switched on for this machine?" is now answerable from
+            // sync.err.log alone.
+            memory_receipt: memory.reason,
+            memory_gaps: memory.receipt ? memoryInstallGaps(memory.receipt) : null,
         }));
         return true;
     }

package/dist/commands/issue-contracts.js

@@ -0,0 +1,99 @@
+/**
+ * What `cockpit issue` hands between its own halves (BLI-3716): the row
+ * shapes the `/api/work/**` doors answer with, the two deadlines, and the
+ * three "which one did you mean" resolvers both the read half (`issue.ts`)
+ * and the write half (`issue-write.ts`) need.
+ *
+ * Split out so neither half carries the other's weight — the same table-of-
+ * contents discipline `commands/session-sync*.ts` and `commands/backfill*.ts`
+ * follow, applied before the file got large rather than after.
+ */
+import { askAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+export const TAG = "[issue cli]";
+export const READ_DEADLINE_MS = 30_000;
+export const WRITE_DEADLINE_MS = 60_000;
+export const BODY_MAX_CHARS = 200_000;
+/** A project id from a project NAME or a uuid — exact after case-folding. */
+export async function resolveProjectId(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/work/projects?include_archived=true",
+        method: "GET",
+        label: "issue project resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "list_failed", reason: answer.reason, detail: answer.detail };
+    const projects = answer.body.projects ?? [];
+    const wanted = ref.toLowerCase();
+    const match = projects.find((project) => project.id === ref || project.name.toLowerCase() === wanted);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+/** A parent issue's uuid from any issue reference, via the door's own resolver. */
+export async function resolveIssueUuid(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "GET",
+        label: "issue parent resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "failed", reason: answer.reason, detail: answer.detail };
+    const issue = answer.body.issue;
+    if (!issue?.id) {
+        return {
+            status: "failed",
+            reason: "issue_not_found_or_unreadable",
+            detail: `That issue does not exist, or you cannot read it: ${ref}`,
+        };
+    }
+    return { status: "ok", id: issue.id };
+}
+/** Body on stdin, never argv — `--file` is the safest way on Windows. */
+export async function readBody(command, io) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `An issue description is limited to ${BODY_MAX_CHARS} characters.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "description_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The project/parent halves both `create` and `update` need, resolved once. */
+export async function resolveRefs(command, door) {
+    let projectId;
+    let parentId;
+    if (command.project) {
+        const resolved = await resolveProjectId(door, command.project);
+        if (resolved.status === "list_failed")
+            return { ok: false, reason: resolved.reason, detail: resolved.detail };
+        if (resolved.status === "not_found") {
+            return {
+                ok: false,
+                reason: "project_not_found_or_unreadable",
+                detail: `No project here is called "${command.project}" — run \`cockpit project list\` for the names.`,
+            };
+        }
+        projectId = resolved.id;
+    }
+    if (command.parentRef) {
+        const resolved = await resolveIssueUuid(door, command.parentRef);
+        if (resolved.status === "failed")
+            return { ok: false, reason: resolved.reason, detail: resolved.detail };
+        parentId = resolved.id;
+    }
+    return { ok: true, ...(projectId ? { projectId } : {}), ...(parentId ? { parentId } : {}) };
+}

package/dist/commands/issue-write.js

@@ -0,0 +1,129 @@
+/**
+ * The verbs that CHANGE something: `cockpit issue create|update|move|comment`
+ * (BLI-3716). The reads and the router live in `issue.ts`, the shared shapes
+ * and resolvers in `issue-contracts.ts`.
+ *
+ * Every write prints a receipt line on stderr naming what it did and to
+ * which row, success included — `--json` owns stdout, so a receipt that went
+ * there would corrupt the one machine-readable object a caller parses.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { TAG, WRITE_DEADLINE_MS, readBody, resolveRefs, } from "./issue-contracts.js";
+export async function createIssue(command, door) {
+    if (!command.title)
+        return failAgentDoor(door, TAG, "invalid_body", "issue create needs --title.");
+    const refs = await resolveRefs(command, door);
+    if (!refs.ok)
+        return failAgentDoor(door, TAG, refs.reason, refs.detail);
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    const answer = await askAgentDoor(door, {
+        path: "/api/work/issues",
+        method: "POST",
+        label: "issue create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            title: command.title,
+            ...(body.text ? { description: body.text } : {}),
+            ...(refs.projectId ? { project_id: refs.projectId } : {}),
+            ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+            ...(command.priority === undefined ? {} : { priority: command.priority }),
+            ...(command.assignee ? { assignee_id: command.assignee } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null, description_bytes: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `Created ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`);
+    return 0;
+}
+export async function updateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const refs = await resolveRefs(command, door);
+    if (!refs.ok)
+        return failAgentDoor(door, TAG, refs.reason, refs.detail);
+    let description;
+    if (command.bodyStdin || command.filePath) {
+        const body = await readBody(command, door.io);
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        description = body.text;
+    }
+    if (description === undefined
+        && command.title === undefined
+        && command.priority === undefined
+        && command.assignee === undefined
+        && refs.projectId === undefined
+        && refs.parentId === undefined) {
+        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --assignee, --project, --parent, or a description on --body-stdin/--file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "PATCH",
+        label: "issue update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.title !== undefined ? { title: command.title } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(command.priority === undefined ? {} : { priority: command.priority }),
+            ...(command.assignee ? { assignee_id: command.assignee } : {}),
+            ...(refs.projectId ? { project_id: refs.projectId } : {}),
+            ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`);
+    return 0;
+}
+export async function moveIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/state`,
+        method: "POST",
+        label: "issue move",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { state: command.moveState },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} moved ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null, to_state: command.moveState })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `${issue?.identifier ?? ref} is now ${issue?.state ?? command.moveState}.`);
+    return 0;
+}
+export async function commentIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "invalid_body", 'A comment is never taken on the command line — pipe it in: `echo "..." | cockpit issue comment BLI-3654`.');
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/comments`,
+        method: "POST",
+        label: "issue comment",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { body_markdown: body.text },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const comment = answer.body.comment;
+    writeLine(door.io.stderr, `${TAG} commented ${JSON.stringify({ comment_id: comment?.id ?? null, byte_size: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, comment });
+    writeLine(door.io.stdout, `Commented on ${ref} (${comment?.id ?? ""}).`);
+    return 0;
+}