@bli-cockpit/cli 0.2.244 → 0.2.245

package/dist/commands/issue-contracts.js

@@ -119,11 +119,18 @@ export async function readBody(command, io) {
         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. */
+/**
+ * The project/parent halves both `create` and `update` need, resolved once. Three answers per field: `undefined`
+ * (not asked to change), `null` (`none`: clear it, update only; the parser refuses it elsewhere, BLI-22367), or a
+ * uuid. A project or ticket literally named "none" is reached by its uuid.
+ */
 export async function resolveRefs(command, door) {
     let projectId;
     let parentId;
-    if (command.project) {
+    if (command.project && command.project.toLowerCase() === "none") {
+        projectId = null;
+    }
+    else if (command.project) {
         const resolved = await resolveProjectId(door, command.project);
         if (resolved.status === "list_failed")
             return { ok: false, reason: resolved.reason, detail: resolved.detail };
@@ -136,11 +143,65 @@ export async function resolveRefs(command, door) {
         }
         projectId = resolved.id;
     }
-    if (command.parentRef) {
+    if (command.parentRef && command.parentRef.toLowerCase() === "none") {
+        parentId = null;
+    }
+    else 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 } : {}) };
+    return { ok: true, ...(projectId !== undefined ? { projectId } : {}), ...(parentId !== undefined ? { parentId } : {}) };
+}
+/**
+ * The receipt for a write the door REFUSED. The door's own receipt wins. Without one, a 4xx answer that names its
+ * reason is a known refusal before anything was written: `not_committed`, never "check again" (BLI-22367; the
+ * self-parent and unknown-label refusals used to say `unknown_check_again` forever). Only a lost answer, a
+ * `mutation_unknown`, a 5xx, or a status with no reason label stays `unknown_check_again`.
+ */
+export function receiptAfterRefusal(answer, requestId) {
+    const sent = answer.body?.mutation;
+    if (sent && typeof sent === "object" && sent.outcome)
+        return sent;
+    const status = answer.httpStatus;
+    const known = typeof status === "number" && status >= 400 && status < 500
+        && answer.reason !== "mutation_unknown" && !/^http_\d+$/.test(answer.reason);
+    return known
+        ? { request_id: requestId, outcome: "not_committed", reason: answer.reason }
+        : { request_id: requestId, outcome: "unknown_check_again" };
+}
+const DELIVERY_WORDS = {
+    pending: "queued, not delivered yet",
+    delivered: "delivered",
+    failed: "failed; the Tower save stands",
+    not_mirrored: "not mirrored",
+    tower_only: "not mirrored (Tower-only)",
+    unknown_check_again: "status unknown; check cockpit ticket mutation-status",
+};
+/**
+ * One sentence a person reads after a committed write: the Tower save first, the Linear copy second, so a pending
+ * or failed delivery never reads as a failed save (contract C1).
+ */
+export function savedLine(receipt) {
+    if (!receipt || receipt.outcome !== "committed")
+        return null;
+    const revision = receipt.revision === undefined ? "" : ` (revision ${receipt.revision})`;
+    if (receipt.reason === "unchanged")
+        return `Saved in Tower${revision}: nothing needed to change.`;
+    const status = receipt.delivery?.status;
+    if (!status)
+        return `Saved in Tower${revision}.`;
+    const words = DELIVERY_WORDS[status] ?? status;
+    const why = receipt.delivery?.reason ? ` (${receipt.delivery.reason})` : "";
+    return `Saved in Tower${revision}. Linear copy: ${words}${why}.`;
+}
+/**
+ * The canonical ticket link (contract C3): the door's own `canonical_url` when it sent one, else
+ * `<configured dashboard url>/tickets/<IDENTIFIER>`. Never a Linear link.
+ */
+export function canonicalTicketUrl(dashboardUrl, identifier, sent) {
+    if (typeof sent === "string" && /^https?:\/\//.test(sent))
+        return sent;
+    return `${dashboardUrl.replace(/\/+$/, "")}/tickets/${encodeURIComponent(identifier)}`;
 }

package/dist/commands/issue-list-page.js

@@ -10,8 +10,23 @@
  */
 import { askAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
-import { READ_DEADLINE_MS, TAG, withSizeLabel } from "./issue-contracts.js";
+import { TAG, withSizeLabel } from "./issue-contracts.js";
 const ALL_PAGE_SIZE = 500;
+/**
+ * `--all` page deadline and bounded retry (BLI-22367). A live export timed out on page 5 of 16 (`turn_timed_out`
+ * at the 30 s read deadline) while the database answered every `work_issue_page` call in at most 288 ms
+ * (pg_stat_statements, 2026-10-19): the stall was transport or the serverless function, not the query. A 500-row
+ * page gets a longer deadline than a 100-row read, and a page that times out, cannot reach Tower or gets a 5xx is
+ * asked again FROM THE SAME CURSOR, at most twice, before the walk stops honestly with `failed_partial` and the
+ * resume cursor. A 4xx (an invalid cursor or filter) is never retried. Every retry is counted on the coverage line.
+ */
+export const ALL_PAGE_DEADLINE_MS = 60_000;
+export const allWalkRetry = { delaysMs: [1_000, 3_000] };
+function retryablePageFailure(answer) {
+    if (answer.httpStatus !== undefined)
+        return answer.httpStatus >= 500;
+    return answer.reason === "turn_timed_out" || answer.reason === "gateway_unreachable";
+}
 /** The additive page fields as `--json` output, only the ones the door sent. */
 export function pageFieldsOf(body) {
     const fields = {};
@@ -61,20 +76,33 @@ export async function streamAllIssues(command, door, base) {
     let pages = 0;
     let expected = null;
     let cursor = null;
+    let retries = 0;
     for (;;) {
         if (cursor)
             query.set("cursor", cursor);
-        const answer = await askAgentDoor(door, {
+        let answer = await askAgentDoor(door, {
             path: `/api/work/issues?${query.toString()}`,
             method: "GET",
             label: "issue list",
-            timeoutMs: READ_DEADLINE_MS,
+            timeoutMs: ALL_PAGE_DEADLINE_MS,
         });
+        for (let attempt = 0; !answer.ok && retryablePageFailure(answer) && attempt < allWalkRetry.delaysMs.length; attempt += 1) {
+            retries += 1;
+            console.error(`${TAG} page retry`, JSON.stringify({ page: pages + 1, attempt: attempt + 2, reason: answer.reason, http_status: answer.httpStatus ?? null }));
+            await new Promise((resolve) => setTimeout(resolve, allWalkRetry.delaysMs[attempt]));
+            answer = await askAgentDoor(door, {
+                path: `/api/work/issues?${query.toString()}`,
+                method: "GET",
+                label: "issue list",
+                timeoutMs: ALL_PAGE_DEADLINE_MS,
+            });
+        }
         if (!answer.ok) {
-            console.error(`${TAG} walk interrupted`, JSON.stringify({ reason: answer.reason, pages, returned }));
+            console.error(`${TAG} walk interrupted`, JSON.stringify({ reason: answer.reason, pages, returned, retries }));
             writeLine(door.io.stdout, JSON.stringify({
                 type: "coverage", coverage: "failed_partial", reason: answer.reason, detail: answer.detail,
-                pages, returned, unique: seen.size, expected, next_cursor: cursor,
+                pages, requested: expected, returned, unique: seen.size, expected, retries, next_cursor: cursor,
+                resume: cursor ? `cockpit ticket list --cursor ${cursor} --limit ${query.get("limit")} --json (same filters), then continue page by page` : "start again; the first page failed",
             }));
             return 1;
         }
@@ -94,7 +122,7 @@ export async function streamAllIssues(command, door, base) {
     }
     const exact = expected === null || expected === returned;
     writeLine(door.io.stdout, JSON.stringify({
-        type: "coverage", coverage: "complete", pages, returned, unique: seen.size, expected,
+        type: "coverage", coverage: "complete", pages, requested: expected, returned, unique: seen.size, expected, retries,
         ...(returned === seen.size && exact ? {} : { note: "returned, unique and expected do not all agree; rows changed during the walk" }),
     }));
     return 0;

package/dist/commands/issue-page-args.js

@@ -0,0 +1,64 @@
+/**
+ * `cockpit ticket list` page and filter flags (BLI-21315) and `--archived` (BLI-22367), split out of
+ * `local-args-tower-work.ts` so that parser stays within its size band. Pure argument checks: no I/O.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+/**
+ * `list --archived` (BLI-22367): archived tickets only, most recently archived first. The archived page takes
+ * --q, --project, --limit, --cursor and --all; any other filter is refused here rather than silently ignored.
+ */
+export function readArchivedFlag(action, values) {
+    if (!values.booleans.has("--archived"))
+        return false;
+    if (action !== "list")
+        throw new Error("--archived belongs to `cockpit ticket list` (archived tickets only).");
+    const unsupported = ["--state", "--assignee", "--label", "--created-after", "--created-before", "--updated-after", "--updated-before", "--sort", "--dir"]
+        .filter((flag) => values.flags.has(flag));
+    if (unsupported.length > 0)
+        throw new Error(`list --archived takes --q, --project, --limit, --cursor and --all; not ${unsupported.join(", ")}.`);
+    return true;
+}
+const INSTANT = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d{1,6})?(?:Z|[+-]\d\d:\d\d))?$/;
+/** BLI-21315: the cursor contract's flags. Filters and sort belong to `list`; `--cursor` also to `history`. */
+export function readIssuePage(action, values) {
+    const named = ["--q", "--created-after", "--created-before", "--updated-after", "--updated-before", "--sort", "--dir"];
+    for (const flag of named) {
+        if (values.flags.has(flag) && action !== "list")
+            throw new Error(`${flag} belongs to \`cockpit ticket list\`.`);
+    }
+    if (values.booleans.has("--all") && action !== "list")
+        throw new Error("--all belongs to `cockpit ticket list`.");
+    if (values.flags.has("--cursor") && action !== "list" && action !== "history") {
+        throw new Error("--cursor belongs to `cockpit ticket list` and `cockpit ticket history`.");
+    }
+    const instants = {};
+    for (const flag of ["--created-after", "--created-before", "--updated-after", "--updated-before"]) {
+        const value = optionalNonEmpty(values.flags.get(flag));
+        if (value !== undefined && (!INSTANT.test(value) || !Number.isFinite(Date.parse(value)))) {
+            throw new Error(`${flag} must be a UTC instant like 2026-10-01T00:00:00Z or a date like 2026-10-01.`);
+        }
+        instants[flag] = value;
+    }
+    const sort = optionalNonEmpty(values.flags.get("--sort"));
+    if (sort !== undefined && sort !== "updated_at" && sort !== "created_at")
+        throw new Error("--sort must be updated_at or created_at.");
+    const dir = optionalNonEmpty(values.flags.get("--dir"));
+    if (dir !== undefined && dir !== "asc" && dir !== "desc")
+        throw new Error("--dir must be asc or desc.");
+    const all = values.booleans.has("--all");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    if (all && cursor)
+        throw new Error("--all walks from the start; drop --cursor, or pass --cursor without --all to read one page.");
+    const q = optionalNonEmpty(values.flags.get("--q"));
+    return {
+        ...(cursor ? { cursor } : {}),
+        ...(q ? { q } : {}),
+        ...(instants["--created-after"] ? { createdAfter: instants["--created-after"] } : {}),
+        ...(instants["--created-before"] ? { createdBefore: instants["--created-before"] } : {}),
+        ...(instants["--updated-after"] ? { updatedAfter: instants["--updated-after"] } : {}),
+        ...(instants["--updated-before"] ? { updatedBefore: instants["--updated-before"] } : {}),
+        ...(sort ? { sort } : {}),
+        ...(dir ? { dir } : {}),
+        ...(all ? { all } : {}),
+    };
+}

package/dist/commands/issue-relations.js

@@ -9,7 +9,7 @@ import { randomUUID } from "node:crypto";
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
-import { askTicketWrite, refuseWrite } from "./issue-write.js";
+import { askTicketWrite, printSaved, refuseWrite, reportCommit } from "./issue-write.js";
 import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
 export const RELATION_VALUE_FLAGS = ["--blocks", "--blocked-by", "--related", "--duplicate-of", "--relation"];
 const KIND_FLAGS = [
@@ -120,10 +120,11 @@ export async function unrelateIssue(command, door) {
 }
 function finishWrite(door, body, requestId, sentence, tag) {
     writeLine(door.io.stderr, `${TAG} ${tag} ${JSON.stringify({ relation_id: body.relation_id ?? null })}`);
-    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    reportCommit(door, body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, issue: body.issue, relation_id: body.relation_id, mutation: body.mutation });
     writeLine(door.io.stdout, sentence);
+    printSaved(door, body.mutation);
     return 0;
 }
 /** `unrelate <id> --blocks B`: the edge id, found through the same read `relations` prints. */

package/dist/commands/issue-show.js

@@ -15,7 +15,7 @@ import { mirroredTicketIdInTitle } from "@bli-cockpit/telemetry-core";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 import { assigneeLabel, resolveAssigneeDirectory, withAssigneeIdentity } from "./issue-directory.js";
-import { READ_DEADLINE_MS, TAG, sizeForEstimate, withSizeLabel, } from "./issue-contracts.js";
+import { READ_DEADLINE_MS, TAG, canonicalTicketUrl, sizeForEstimate, withSizeLabel, } from "./issue-contracts.js";
 async function fetchOneIssue(door, ref) {
     const answer = await askAgentDoor(door, {
         path: `/api/work/issues/${encodeURIComponent(ref)}`,
@@ -25,7 +25,8 @@ async function fetchOneIssue(door, ref) {
     });
     if (!answer.ok)
         return { ref, ok: false, reason: answer.reason, detail: answer.detail };
-    const issue = answer.body.issue;
+    const detailBody = answer.body;
+    const issue = detailBody.issue;
     if (!issue) {
         return {
             ref,
@@ -54,6 +55,8 @@ async function fetchOneIssue(door, ref) {
         ok: true,
         issue,
         comments,
+        canonicalUrl: canonicalTicketUrl(door.dashboardUrl, issue.identifier, detailBody.canonical_url),
+        ...(detailBody.resolved_from ? { resolvedFrom: detailBody.resolved_from } : {}),
         ...(linearTicketId ? { linearTicketId } : {}),
         ...(commentsAnswer.ok ? {} : { commentsUnreadReason: commentsAnswer.reason }),
     };
@@ -64,6 +67,12 @@ function renderOneIssue(door, result, directory) {
     const size = sizeForEstimate(issue.estimate ?? null);
     writeLine(door.io.stdout, `${issue.state}  ·  priority ${issue.priority ?? 0}${size ? `  ·  size ${size}` : ""}  ·  assignee ${assigneeLabel(issue.assignee_id, directory)}  ·  updated ${issue.updated_at}`);
     writeLine(door.io.stdout, `id ${issue.id}${issue.parent_id ? `  ·  parent ${issue.parent_id}` : ""}`);
+    const archivedAt = issue.archived_at;
+    if (archivedAt)
+        writeLine(door.io.stdout, `ARCHIVED ${archivedAt} — hidden from lists and the board; \`cockpit ticket unarchive ${issue.identifier}\` brings it back.`);
+    writeLine(door.io.stdout, `Link: ${result.canonicalUrl}`);
+    if (result.resolvedFrom)
+        writeLine(door.io.stdout, `(found through the old Linear id ${result.resolvedFrom.ref})`);
     if (linearTicketId)
         writeLine(door.io.stdout, `Linear: ${linearTicketId}`);
     writeLine(door.io.stdout, "");
@@ -100,6 +109,8 @@ function readIssueJson(result, directory) {
     return {
         issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
         comments: result.comments,
+        canonical_url: result.canonicalUrl,
+        ...(result.resolvedFrom ? { resolved_from: result.resolvedFrom } : {}),
         ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
         ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
     };

package/dist/commands/issue-versions.js

@@ -12,6 +12,7 @@ import { randomUUID } from "node:crypto";
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
+import { printSaved, refuseWrite, reportCommit } from "./issue-write.js";
 import { READ_DEADLINE_MS, TAG, WRITE_DEADLINE_MS } from "./issue-contracts.js";
 export async function listIssueVersions(command, door) {
     const ref = command.issueRef ?? "";
@@ -75,19 +76,15 @@ export async function restoreIssueVersion(command, door) {
         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);
-    }
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
     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 })}`);
+    reportCommit(door, body.mutation, 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 ?? "?"}.`);
+    printSaved(door, body.mutation);
     return 0;
 }

package/dist/commands/issue-write.js

@@ -10,7 +10,7 @@ import { randomUUID } from "node:crypto";
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
-import { TAG, WRITE_DEADLINE_MS, maybeWithSizeLabel, readBody, resolveRefs, } from "./issue-contracts.js";
+import { TAG, WRITE_DEADLINE_MS, maybeWithSizeLabel, readBody, resolveRefs, receiptAfterRefusal, savedLine, } from "./issue-contracts.js";
 export async function createIssue(command, door) {
     if (!command.title)
         return failAgentDoor(door, TAG, "invalid_body", "issue create needs --title.");
@@ -44,10 +44,11 @@ export async function createIssue(command, door) {
         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 })}`);
+    reportCommit(door, answer.body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `Created ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`);
+    printSaved(door, answer.body.mutation);
     return 0;
 }
 export async function updateIssue(command, door) {
@@ -63,7 +64,7 @@ export async function updateIssue(command, door) {
         description = body.text;
     }
     if (!changesAnything(command, description, refs)) {
-        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --size, --assignee, --due, --project, --parent, --cycle, or a description on --body-stdin/--file.");
+        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --size, --assignee, --due, --project, --parent, --cycle (none clears size, assignee, due, project, parent and cycle), or a description on --body-stdin/--file.");
     }
     const requestId = command.requestId ?? randomUUID();
     writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
@@ -79,8 +80,8 @@ export async function updateIssue(command, door) {
             ...(command.estimate === undefined ? {} : { estimate: command.estimate }),
             ...(command.assignee ? { assignee_id: command.assignee === "none" ? null : command.assignee } : {}),
             ...(command.due !== undefined ? { due_date: command.due } : {}),
-            ...(refs.projectId ? { project_id: refs.projectId } : {}),
-            ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+            ...(refs.projectId !== undefined ? { project_id: refs.projectId } : {}),
+            ...(refs.parentId !== undefined ? { parent_id: refs.parentId } : {}),
             ...(command.cycle === undefined ? {} : { cycle: command.cycle }),
         },
     });
@@ -88,10 +89,11 @@ export async function updateIssue(command, door) {
         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 })}`);
+    reportCommit(door, answer.body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`);
+    printSaved(door, answer.body.mutation);
     return 0;
 }
 export async function moveIssue(command, door) {
@@ -109,10 +111,11 @@ export async function moveIssue(command, door) {
         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 })}`);
+    reportCommit(door, answer.body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, issue, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `${issue?.identifier ?? ref} is now ${issue?.state ?? command.moveState}.`);
+    printSaved(door, answer.body.mutation);
     return 0;
 }
 export async function commentIssue(command, door) {
@@ -136,10 +139,11 @@ export async function commentIssue(command, door) {
         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 })}`);
+    reportCommit(door, answer.body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, comment, mutation: answer.body.mutation });
     writeLine(door.io.stdout, `Commented on ${ref} (${comment?.id ?? ""}).`);
+    printSaved(door, answer.body.mutation);
     return 0;
 }
 /** `ticket label <id> --add <name> --remove <name>`: one receipt, one history row (BLI-21422). */
@@ -162,10 +166,41 @@ export async function labelIssue(command, door) {
     const body = answer.body;
     const names = (body.labels ?? []).map((l) => l.name);
     writeLine(door.io.stderr, `${TAG} labelled ${JSON.stringify({ issue_id: body.issue?.id ?? null, added: command.addLabels?.length ?? 0, removed: command.removeLabels?.length ?? 0, now: names.length })}`);
-    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(answer.body.mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    reportCommit(door, answer.body.mutation, requestId);
     if (door.json)
         return emitAgentDoor(door, { ok: true, issue: maybeWithSizeLabel(body.issue), labels: body.labels ?? [], mutation: answer.body.mutation });
     writeLine(door.io.stdout, `${body.issue?.identifier ?? ref} labels: ${names.length ? names.join(", ") : "none"}.`);
+    printSaved(door, answer.body.mutation);
+    return 0;
+}
+/**
+ * `ticket archive <id>` / `ticket unarchive <id>` (BLI-22367): hide a ticket from lists, the board and counts,
+ * or bring it back. Nothing is deleted; the ticket stays readable with `show` and every field, comment and
+ * history row survives. Tower-only: the receipt says the Linear copy is not mirrored (archive_is_tower_only).
+ */
+export async function archiveIssue(command, door, archived) {
+    const ref = command.issueRef ?? "";
+    const verb = archived ? "archive" : "unarchive";
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision, action: verb })}`);
+    const answer = await askTicketWrite(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/${verb}`,
+        method: "POST",
+        label: `issue ${verb}`,
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { request_id: requestId, ...(command.expectedRevision === undefined ? {} : { expected_revision: command.expectedRevision }) },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} ${archived ? "archived" : "unarchived"} ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null })}`);
+    reportCommit(door, answer.body.mutation, requestId);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue: maybeWithSizeLabel(issue), mutation: answer.body.mutation });
+    writeLine(door.io.stdout, archived
+        ? `Archived ${issue?.identifier ?? ref}. It is hidden from lists and the board; \`cockpit ticket unarchive ${issue?.identifier ?? ref}\` brings it back.`
+        : `Unarchived ${issue?.identifier ?? ref}. It is back in lists and on the board.`);
+    printSaved(door, answer.body.mutation);
     return 0;
 }
 /** A truncated or missing response body cannot be called a successful ticket write. */
@@ -197,16 +232,36 @@ function changesAnything(command, description, refs) {
         || refs.parentId !== undefined
         || command.cycle !== undefined;
 }
-/** Says where the local commit stands, then fails with the door's own reason. */
+/** The local commit receipt on stderr, plus the "Saved in Tower ... Linear copy: ..." sentence when --json owns stdout. */
+export function reportCommit(door, mutation, requestId) {
+    writeLine(door.io.stderr, `${TAG} local commit receipt ${JSON.stringify(mutation ?? { outcome: "unknown_check_again", request_id: requestId })}`);
+    const line = savedLine(mutation);
+    if (door.json && line)
+        writeLine(door.io.stderr, `${TAG} ${line}`);
+}
+/** The same sentence under a text answer (contract C1): the Tower save first, the Linear copy second. */
+export function printSaved(door, mutation) {
+    const line = savedLine(mutation);
+    if (line)
+        writeLine(door.io.stdout, line);
+}
+/**
+ * Says where the local commit stands, then fails with the door's own reason. A known refusal says nothing changed
+ * (`not_committed`); only a genuinely unknown answer asks for a status check and an identical retry (BLI-22367).
+ */
 export 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" };
+    const mutation = receiptAfterRefusal(answer, requestId);
+    if (mutation.outcome === "not_committed") {
+        writeLine(door.io.stderr, `${TAG} not committed: nothing changed ${JSON.stringify({ reason: mutation.reason ?? answer.reason, request_id: requestId })}. Fix the input and send it again with a new request id.`);
+    }
+    else {
+        writeLine(door.io.stderr, `${TAG} result unknown: check local commit with cockpit ticket mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+    }
     if (door.json) {
-        writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason: answer.reason, request_id: requestId })}`);
+        writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason: answer.reason, request_id: requestId, outcome: mutation.outcome })}`);
         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 })}`);
+    if (mutation.current)
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, outcome: mutation.outcome, current_state: mutation.current.state, current_revision: mutation.current.revision })}`);
     return failAgentDoor(door, TAG, answer.reason, answer.detail);
 }

package/dist/commands/issue.js

@@ -32,8 +32,8 @@ import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js"
 import { readTicketBoard } from "./tickets-board.js";
 import { showIssue } from "./issue-show.js";
 import { addIssuePageQuery, pageFieldsOf, pageFooter, streamAllIssues } from "./issue-list-page.js";
-import { READ_DEADLINE_MS, TAG, resolveProjectId, sizeForEstimate, withSizeLabel, } from "./issue-contracts.js";
-import { commentIssue, createIssue, labelIssue, moveIssue, updateIssue } from "./issue-write.js";
+import { READ_DEADLINE_MS, TAG, resolveProjectId, sizeForEstimate, withSizeLabel, savedLine, } from "./issue-contracts.js";
+import { archiveIssue, commentIssue, createIssue, labelIssue, moveIssue, updateIssue } from "./issue-write.js";
 import { batchIssues } from "./issue-batch.js";
 import { runInbox } from "./inbox.js";
 import { runWorkNotify } from "./work-notify.js";
@@ -52,6 +52,8 @@ export async function runIssue(command, io) {
                 return failAgentDoor(door, TAG, answer.reason, answer.detail);
             if (door.json)
                 return emitAgentDoor(door, { ok: true, ...answer.body });
+            const receipt = answer.body.mutation;
+            writeLine(door.io.stdout, statusSentence(receipt, command.issueRef ?? ""));
             writeLine(door.io.stdout, JSON.stringify(answer.body));
             return 0;
         }
@@ -71,6 +73,10 @@ export async function runIssue(command, io) {
             return commentIssue(command, door);
         case "label":
             return labelIssue(command, door);
+        case "archive":
+            return archiveIssue(command, door, true);
+        case "unarchive":
+            return archiveIssue(command, door, false);
         case "relations":
             return showRelations(command, door);
         case "relate":
@@ -101,11 +107,21 @@ export async function runIssue(command, io) {
             return runWorkNotify(command, io, door);
     }
 }
+/** `mutation-status` in words: committed (with the Linear copy), refused (nothing changed), or no receipt yet. */
+export function statusSentence(receipt, requestId) {
+    if (receipt?.outcome === "committed")
+        return savedLine(receipt) ?? "Saved in Tower.";
+    if (receipt?.outcome === "not_committed")
+        return `Not committed: nothing changed (${receipt.reason ?? "refused"}).`;
+    return `No receipt for ${requestId} yet: the write may still be in flight, or it never reached Tower (a refusal before the write leaves no receipt). Retry the identical input with --request-id ${requestId}.`;
+}
 function issueLine(issue, directory) {
     const assignee = issue.assignee_id ? `  [${assigneeLabel(issue.assignee_id, directory)}]` : "";
     const size = sizeForEstimate(issue.estimate ?? null);
     const sizeTag = size ? `  (${size})` : "";
-    return `${issue.identifier.padEnd(9)}  ${issue.state.padEnd(11)}  ${issue.title}${sizeTag}${assignee}`;
+    const archived = issue.archived_at;
+    const archivedTag = archived ? `  (archived ${archived.slice(0, 10)})` : "";
+    return `${issue.identifier.padEnd(9)}  ${issue.state.padEnd(11)}  ${issue.title}${sizeTag}${assignee}${archivedTag}`;
 }
 /**
  * What the list did not show (BLI-10447): a capped window of a larger set,
@@ -202,6 +218,9 @@ async function listIssues(command, door) {
 /** The list query for the filters given, or the exit code of the project lookup that failed. */
 async function buildIssueListQuery(command, door) {
     const query = new URLSearchParams();
+    // BLI-22367: archived tickets only; every other list hides them.
+    if (command.archived)
+        query.set("archived", "only");
     if (command.stateFilter)
         query.set("state", command.stateFilter);
     if (command.assignee)