@bli-cockpit/cli 0.2.237 → 0.2.239

package/dist/commands/heartbeat.js

@@ -19,25 +19,23 @@
  *   The path itself never leaves the machine, exactly as with `cwd_hash` on the
  *   session rows.
  */
-import { noteDoctorRequest } from "./sync-doctor-request.js";
 import crypto from "node:crypto";
 import { collectAgentSetup } from "./agent-setup.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, memoryInstallGaps, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
+import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
 import { readCachedSetupReceipt } from "./setup-receipt.js";
 import { readStagingInventory } from "../disk-usage.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { noteHeartbeatRefusal, readHeartbeatSession, recordHeartbeatTokenExpiry, recordHeartbeatPendingToken, TOKEN_ROTATION_HEADER, } from "./heartbeat-token.js";
+import { postHeartbeat } from "./heartbeat-post.js";
+import { readHeartbeatSession } from "./heartbeat-token.js";
 import { withTokenRotationLock } from "./heartbeat-token-lock.js";
-import { classifySyncHealthError } from "../sync-health-class.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 import { readMemoryHookCounts } from "./memory-hook-counts.js";
 import { readMemoryHookPerformance } from "./memory-hook-performance.js";
-const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
  *
@@ -226,23 +224,8 @@ export async function sendCollectorHeartbeatBestEffort(options) {
     return withTokenRotationLock(options.homeDir, options.lock, false, () => sendCollectorHeartbeatLocked(options));
 }
 async function sendCollectorHeartbeatLocked(options) {
-    // BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
-    // device row, so an agent's worktree could keep a genuinely dead machine
-    // looking alive to the BLI-3550 reader.
-    const suppression = shouldSuppressFleetReceipts({
-        dashboardUrl: options.dashboardUrl,
-        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
-    });
-    if (suppression.suppressed) {
-        console.error("[heartbeat] dev build; this tick is not checking in with the fleet", JSON.stringify({
-            reason: "receipt_suppressed:dev_build",
-            detected_by: suppression.reason,
-            root_count: options.roots.length,
-            sync_status: options.facts.status,
-            fix: "set COCKPIT_DEV=0 to heartbeat from a checkout deliberately",
-        }));
+    if (isDevBuildSuppressed(options))
         return false;
-    }
     // BLI-4019. Whether this machine may knock at all, and the two log lines
     // that go with it, live in `heartbeat-token.ts` — the check-in goes out even
     // when the local copy says `expired`, because that is the door the server
@@ -255,12 +238,46 @@ async function sendCollectorHeartbeatLocked(options) {
         ...(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());
+    logSetupReceiptCarried(setupReceipt);
+    const heartbeat = buildCollectorHeartbeat({
+        roots: options.roots,
+        facts: options.facts,
+        setupReceipt: setupReceipt ? { ...setupReceipt, agent_setup: await collectAgentSetup(options.homeDir ?? os.homedir()) } : null,
+        ...(options.now ? { now: options.now } : {}),
+        memoryInstall: memory.receipt,
+    });
+    return postHeartbeat(options, session.device_token, heartbeat, memory);
+}
+/**
+ * BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
+ * device row, so an agent's worktree could keep a genuinely dead machine
+ * looking alive to the BLI-3550 reader.
+ */
+function isDevBuildSuppressed(options) {
+    const suppression = shouldSuppressFleetReceipts({
+        dashboardUrl: options.dashboardUrl,
+        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
+    });
+    if (!suppression.suppressed)
+        return false;
+    console.error("[heartbeat] dev build; this tick is not checking in with the fleet", JSON.stringify({
+        reason: "receipt_suppressed:dev_build",
+        detected_by: suppression.reason,
+        root_count: options.roots.length,
+        sync_status: options.facts.status,
+        fix: "set COCKPIT_DEV=0 to heartbeat from a checkout deliberately",
+    }));
+    return true;
+}
+/**
+ * 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.
+ */
+function logSetupReceiptCarried(setupReceipt) {
     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
@@ -273,103 +290,4 @@ async function sendCollectorHeartbeatLocked(options) {
             reason: "setup_receipt_absent_or_stale",
             next_action: "run `cockpit doctor` to refresh it",
         }));
-    const heartbeat = buildCollectorHeartbeat({
-        roots: options.roots,
-        facts: options.facts,
-        setupReceipt: setupReceipt ? { ...setupReceipt, agent_setup: await collectAgentSetup(options.homeDir ?? os.homedir()) } : null,
-        ...(options.now ? { now: options.now } : {}),
-        memoryInstall: memory.receipt,
-    });
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
-    try {
-        const response = await options.io.fetch(`${options.dashboardUrl}/api/ambient/heartbeat`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${session.device_token}`,
-                // BLI-17994. "I store a renewed token if you send one": the dashboard
-                // only rotates for a collector that says so.
-                [TOKEN_ROTATION_HEADER]: "1",
-            },
-            body: JSON.stringify(heartbeat),
-            signal: controller.signal,
-        });
-        noteHeartbeatRefusal(response.ok ? null : response.status);
-        if (!response.ok) {
-            // A heartbeat is not retried, so the reason has to be said once, here.
-            // BLI-4019: the CLASS comes from `sync-health-class.ts`, the one place
-            // that decides what a failure is — a 401/403 is `auth_failed` and
-            // anything else is not, read off the observed status and never off the
-            // words in a message (BLI-3551's rule).
-            // BLI-17994. The door names why it refused (`device_token_expired`,
-            // `device_token_replaced`) in a `reason` field; say it here rather than
-            // leaving a bare status.
-            const refusal = await Promise.resolve().then(() => response.clone().json()).catch(() => null);
-            console.error("[heartbeat] the dashboard refused this tick's heartbeat", JSON.stringify({
-                reason: "heartbeat_rejected",
-                health_class: classifySyncHealthError({ httpStatus: response.status }),
-                http_status: response.status,
-                root_count: heartbeat.roots.length,
-                ...(typeof refusal?.["reason"] === "string" ? { server_reason: refusal["reason"] } : {}),
-                ...(response.status === 401 || response.status === 403
-                    ? {
-                        next_action: "this token expired, was replaced or was revoked: run `cockpit doctor` to pair this machine again",
-                    }
-                    : {}),
-            }));
-            return false;
-        }
-        // The reply carries `token_expires_at` (and a `pending_device_token` when
-        // the token was near its end); the sibling records both, so this machine's
-        // own copy follows the server rather than drifting.
-        const reply = await response.clone().json().catch(() => null);
-        noteDoctorRequest(reply?.device_action);
-        // BLI-17994. Store a pending successor if the door handed one out (the
-        // date does not move: a pending token has not been used), then the date the
-        // door reports, which moves only when this request promoted a token.
-        await recordHeartbeatPendingToken(options.homeDir, reply);
-        await recordHeartbeatTokenExpiry(options.homeDir, response);
-        console.error("[heartbeat] checked in", JSON.stringify({
-            reason: "heartbeat_recorded",
-            http_status: response.status,
-            root_count: heartbeat.roots.length,
-            sync_status: heartbeat.last_sync_status,
-            sync_reason: heartbeat.last_sync_reason ?? null,
-            sessions_observed: heartbeat.sessions_observed ?? null,
-            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,
-            // BLI-3788. The hooks are registered (above) AND they either worked or
-            // did not (here). A prompt hook that misses its deadline prints
-            // nothing to the person, so these counts are the only trace one leaves
-            // on this machine; `null` means no counter file, never zero misses.
-            memory_hook_runs_24h: memory.receipt?.hook_runs_24h ?? null,
-            memory_hook_timeouts_24h: memory.receipt?.hook_timeouts_24h ?? null,
-            memory_hook_stats: memory.receipt?.hook_stats_reason ?? null,
-            // BLI-3884. Which route answered those recalls. `null` on a machine
-            // whose memory-mcp does not name one yet — never zero, which would
-            // read as "the daemon answered none".
-            memory_hook_via_daemon_24h: memory.receipt?.hook_via_daemon_24h ?? null,
-            memory_hook_via_direct_24h: memory.receipt?.hook_via_direct_24h ?? null,
-        }));
-        return true;
-    }
-    catch (error) {
-        console.error("[heartbeat] could not reach the dashboard this tick", JSON.stringify({
-            reason: "heartbeat_transport_failed",
-            root_count: heartbeat.roots.length,
-            ...describeError(error),
-        }));
-        return false;
-    }
-    finally {
-        clearTimeout(timeout);
-    }
 }

package/dist/commands/install-update.js

@@ -102,21 +102,7 @@ export async function runUpdate(command, io) {
         addInstallEvent(installEvents, "npm_install", "fail", error.eacces
             ? "npm_install_eacces"
             : "npm_install_failed");
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                status: "blocked",
-                step: "npm_install",
-                command: `npm ${selfUpdateInstallArgs().join(" ")}`,
-                exit_code: error.result.code,
-            }, null, 2));
-        }
-        else {
-            writeLine(io.stderr, "BLOCKED: npm install failed; Tower CLI was not refreshed.");
-            if (error.eacces) {
-                writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
-                writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
-            }
-        }
+        writeSelfUpdateBlocked(command, io, error);
         return finish(error.result.code || 1);
     }
     addInstallEvent(installEvents, "npm_install", "ok");
@@ -131,6 +117,22 @@ export async function runUpdate(command, io) {
     addInstallEvent(installEvents, "onboard_rerun", onboard.code === 0 ? "ok" : "fail", onboard.code === 0 ? undefined : updateOnboardFailureCode(onboard));
     return finish(onboard.code);
 }
+function writeSelfUpdateBlocked(command, io, error) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "blocked",
+            step: "npm_install",
+            command: `npm ${selfUpdateInstallArgs().join(" ")}`,
+            exit_code: error.result.code,
+        }, null, 2));
+        return;
+    }
+    writeLine(io.stderr, "BLOCKED: npm install failed; Tower CLI was not refreshed.");
+    if (error.eacces) {
+        writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
+        writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
+    }
+}
 export async function runSelfUpdate(io, options = {}) {
     const exec = io.exec ?? defaultExec();
     const tag = options.tag ?? "latest";

package/dist/commands/issue-show.js

@@ -91,40 +91,39 @@ export async function showIssue(command, door) {
         results.push(await fetchOneIssue(door, ref));
     // BLI-10450: one directory call for the whole batch, never one per issue.
     const directory = await resolveAssigneeDirectory(door, results.filter((result) => result.ok).map((result) => result.issue.assignee_id));
-    // A single ref keeps the pre-BLI-10450 shape and failure path exactly.
-    if (refs.length === 1) {
-        const [result] = results;
-        if (!result || !result.ok) {
-            return failAgentDoor(door, TAG, result?.reason ?? "issue_not_found_or_unreadable", result?.detail ?? "That issue does not exist, or you cannot read it.");
-        }
-        if (door.json) {
-            return emitAgentDoor(door, {
-                ok: true,
-                issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
-                comments: result.comments,
-                ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
-                ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
-            });
-        }
-        renderOneIssue(door, result, directory);
-        return 0;
+    if (refs.length === 1)
+        return reportSingleIssue(door, results[0], directory);
+    return reportSeveralIssues(door, results, directory);
+}
+/** The JSON body for one issue that was read: the issue, its comments and any Linear link. */
+function readIssueJson(result, directory) {
+    return {
+        issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
+        comments: result.comments,
+        ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
+        ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
+    };
+}
+// A single ref keeps the pre-BLI-10450 shape and failure path exactly.
+function reportSingleIssue(door, result, directory) {
+    if (!result || !result.ok) {
+        return failAgentDoor(door, TAG, result?.reason ?? "issue_not_found_or_unreadable", result?.detail ?? "That issue does not exist, or you cannot read it.");
     }
-    // Several refs: `{ ok, issues: [...] }`, one entry per ref in the order
-    // given, each carrying `ref` so a caller can match an answer back to what
-    // it asked for. One bad id never loses the rest of the batch.
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...readIssueJson(result, directory) });
+    renderOneIssue(door, result, directory);
+    return 0;
+}
+// Several refs: `{ ok, issues: [...] }`, one entry per ref in the order
+// given, each carrying `ref` so a caller can match an answer back to what
+// it asked for. One bad id never loses the rest of the batch.
+function reportSeveralIssues(door, results, directory) {
     const failed = results.filter((result) => !result.ok);
     if (door.json) {
         return emitAgentDoor(door, {
             ok: failed.length === 0,
             issues: results.map((result) => result.ok
-                ? {
-                    ref: result.ref,
-                    ok: true,
-                    issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
-                    comments: result.comments,
-                    ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
-                    ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
-                }
+                ? { ref: result.ref, ok: true, ...readIssueJson(result, directory) }
                 : { ref: result.ref, ok: false, error: result.reason, detail: result.detail }),
         }, failed.length === 0 ? 0 : 1);
     }

package/dist/commands/issue-versions.js

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+/**
+ * `cockpit ticket versions <id>` and `cockpit ticket restore <id> --version <n>`
+ * (BLI-21300): the saved descriptions of one ticket, and the write that puts an
+ * older one back as a NEW version. Same doors the browser uses
+ * (`GET .../versions`, `POST .../versions/restore`).
+ *
+ * `restore` takes the version NUMBER the person read in `versions`, looks up
+ * that version's id in the same list, and sends the id: the door never guesses
+ * "the previous one". A number the list does not carry is refused here with
+ * the numbers that do exist, before anything is written.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+export async function listIssueVersions(command, door) {
+    const ref = command.issueRef ?? "";
+    const query = command.limit === undefined ? "" : `?limit=${command.limit}`;
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/versions${query}`,
+        method: "GET",
+        label: "issue versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const versions = answer.body.versions ?? [];
+    console.error(`${TAG} versions ${JSON.stringify({ count: versions.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, versions });
+    if (versions.length === 0) {
+        writeLine(door.io.stdout, `No saved description versions for ${ref}.`);
+        return 0;
+    }
+    for (const row of versions) {
+        const from = row.restored_from_version ? ` (restored from ${row.restored_from_version})` : "";
+        writeLine(door.io.stdout, `v${row.version}  ${row.id}  ${row.created_at}  ${row.source}${from}  ${row.markdown.length} chars`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${versions.length} version(s), newest first. Restore one with: cockpit ticket restore ${ref} --version <n>`);
+    return 0;
+}
+export async function restoreIssueVersion(command, door) {
+    const ref = command.issueRef ?? "";
+    const wanted = command.versionNumber;
+    const listed = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/versions?limit=500`,
+        method: "GET",
+        label: "issue versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!listed.ok)
+        return failAgentDoor(door, TAG, listed.reason, listed.detail);
+    const versions = listed.body.versions ?? [];
+    const chosen = versions.find(row => row.version === wanted);
+    if (!chosen) {
+        const have = versions.map(row => row.version).join(", ") || "none";
+        console.error(`${TAG} restore refused ${JSON.stringify({ reason: "version_not_found", requested: wanted ?? null, available: versions.length })}`);
+        return failAgentDoor(door, TAG, "version_not_found", `${ref} has no version ${wanted}. Versions: ${have}.`);
+    }
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision, version: chosen.version })}`);
+    let answer;
+    try {
+        answer = await askAgentDoor(door, {
+            path: `/api/work/issues/${encodeURIComponent(ref)}/versions/restore`,
+            method: "POST",
+            label: "issue restore",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { request_id: requestId, expected_revision: command.expectedRevision, version_id: chosen.id },
+        });
+    }
+    catch {
+        console.error(`${TAG} response lost`, JSON.stringify({ reason: "mutation_unknown" }));
+        writeLine(door.io.stderr, `${TAG} check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+        return failAgentDoor(door, TAG, "mutation_unknown", "Result unknown. Check this request ID before retrying with identical input.");
+    }
+    if (!answer.ok) {
+        writeLine(door.io.stderr, `${TAG} check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+        const mutation = answer.body?.mutation ?? { request_id: requestId, outcome: "unknown_check_again" };
+        if (door.json)
+            return emitAgentDoor(door, { ok: false, error: answer.reason, detail: answer.detail, mutation }, 1);
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    }
+    const body = answer.body;
+    const newVersion = body.mutation?.description_version;
+    writeLine(door.io.stderr, `${TAG} restored ${JSON.stringify({ restored_version: chosen.version, new_version: newVersion ?? null })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue: body.issue, mutation: body.mutation });
+    writeLine(door.io.stdout, `Restored version ${chosen.version} of ${ref} as new version ${newVersion ?? "?"}.`);
+    return 0;
+}

package/dist/commands/issue-write.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 /**
  * 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
@@ -19,12 +20,14 @@ export async function createIssue(command, door) {
     const body = await readBody(command, door.io);
     if (!body.ok)
         return failAgentDoor(door, TAG, body.reason, body.detail);
-    const answer = await askAgentDoor(door, {
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
         path: "/api/work/issues",
         method: "POST",
         label: "issue create",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: {
+        body: { request_id: requestId, expected_revision: command.expectedRevision,
             title: command.title,
             ...(body.text ? { description: body.text } : {}),
             ...(refs.projectId ? { project_id: refs.projectId } : {}),
@@ -35,11 +38,12 @@ export async function createIssue(command, door) {
         },
     });
     if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        return refuseWrite(door, answer, requestId);
     const issue = maybeWithSizeLabel(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") })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, issue });
+        return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `Created ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`);
     return 0;
 }
@@ -55,21 +59,17 @@ export async function updateIssue(command, door) {
             return failAgentDoor(door, TAG, body.reason, body.detail);
         description = body.text;
     }
-    if (description === undefined
-        && command.title === undefined
-        && command.priority === undefined
-        && command.estimate === undefined
-        && command.assignee === undefined
-        && refs.projectId === undefined
-        && refs.parentId === undefined) {
+    if (!changesAnything(command, description, refs)) {
         return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --size, --assignee, --project, --parent, or a description on --body-stdin/--file.");
     }
-    const answer = await askAgentDoor(door, {
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
         path: `/api/work/issues/${encodeURIComponent(ref)}`,
         method: "PATCH",
         label: "issue update",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: {
+        body: { request_id: requestId, expected_revision: command.expectedRevision,
             ...(command.title !== undefined ? { title: command.title } : {}),
             ...(description !== undefined ? { description } : {}),
             ...(command.priority === undefined ? {} : { priority: command.priority }),
@@ -80,29 +80,33 @@ export async function updateIssue(command, door) {
         },
     });
     if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        return refuseWrite(door, answer, requestId);
     const issue = maybeWithSizeLabel(answer.body.issue);
     writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, issue });
+        return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     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, {
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
         path: `/api/work/issues/${encodeURIComponent(ref)}/state`,
         method: "POST",
         label: "issue move",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: { state: command.moveState },
+        body: { request_id: requestId, expected_revision: command.expectedRevision, state: command.moveState },
     });
     if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        return refuseWrite(door, answer, requestId);
     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 })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, issue });
+        return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `${issue?.identifier ?? ref} is now ${issue?.state ?? command.moveState}.`);
     return 0;
 }
@@ -114,19 +118,62 @@ export async function commentIssue(command, door) {
     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, {
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askTicketWrite(door, {
         path: `/api/work/issues/${encodeURIComponent(ref)}/comments`,
         method: "POST",
         label: "issue comment",
         timeoutMs: WRITE_DEADLINE_MS,
-        body: { body_markdown: body.text },
+        body: { request_id: requestId, expected_revision: command.expectedRevision, body_markdown: body.text },
     });
     if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        return refuseWrite(door, answer, requestId);
     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") })}`);
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, comment });
+        return emitAgentDoor(door, { ok: true, comment, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `Commented on ${ref} (${comment?.id ?? ""}).`);
     return 0;
+}
+/** A truncated or missing response body cannot be called a successful ticket write. */
+async function askTicketWrite(door, options) {
+    try {
+        const answer = await askAgentDoor(door, options);
+        if (!answer.ok)
+            return answer;
+        const body = answer.body;
+        if (body && (body.issue || body.comment))
+            return answer;
+    }
+    catch {
+        console.error(`${TAG} response lost`, JSON.stringify({ reason: "mutation_unknown" }));
+    }
+    const requestId = options.body.request_id;
+    return { ok: false, reason: "mutation_unknown", detail: "Result unknown. Check this request ID before retrying with identical input.",
+        body: { mutation: { request_id: requestId, outcome: "unknown_check_again" } } };
+}
+/** Did the person ask for at least one field to change? */
+function changesAnything(command, description, refs) {
+    return description !== undefined
+        || command.title !== undefined
+        || command.priority !== undefined
+        || command.estimate !== undefined
+        || command.assignee !== undefined
+        || refs.projectId !== undefined
+        || refs.parentId !== undefined;
+}
+/** Says where the local commit stands, then fails with the door's own reason. */
+function refuseWrite(door, answer, requestId) {
+    writeLine(door.io.stderr, `${TAG} check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+    const mutation = answer.body?.mutation ?? { request_id: requestId, outcome: "unknown_check_again" };
+    if (door.json) {
+        writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason: answer.reason, request_id: requestId })}`);
+        return emitAgentDoor(door, { ok: false, error: answer.reason, detail: answer.detail, mutation }, 1);
+    }
+    const receipt = mutation;
+    if (receipt.current)
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, outcome: receipt.outcome, current_state: receipt.current.state, current_revision: receipt.current.revision })}`);
+    return failAgentDoor(door, TAG, answer.reason, answer.detail);
 }