@bli-cockpit/cli 0.2.243 → 0.2.245

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)

package/dist/commands/local-args-collector-sources.js

@@ -9,7 +9,7 @@
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 export function parseSourcesArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--older-than", "--home", "--dashboard-url", "--json"],
+        allowedFlags: ["--older-than", "--home", "--dashboard-url", "--json", "--reconcile"],
         valueFlags: ["--older-than", "--home", "--dashboard-url"],
     });
     const action = values.positionals[0] ?? "check";
@@ -17,6 +17,7 @@ export function parseSourcesArgs(args) {
         throw new Error("sources has one verb: `cockpit sources check [--older-than <days>] [--json]`.");
     }
     return {
+        reconcile: values.booleans.has("--reconcile"),
         kind: "sources",
         action: "check",
         olderThanDays: optionalPositiveInteger(values.flags.get("--older-than"), "--older-than") ?? null,

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

@@ -0,0 +1,120 @@
+/**
+ * `cockpit milestone` argument parsing (BLI-22360).
+ *
+ *   list [--project <ref>] [--archived]
+ *   show <ref> [--project <ref>] [--limit <n>] [--cursor <c>]
+ *   create --project <ref> --name "<n>" [--description <text|->] [--target YYYY-MM-DD]
+ *   update <ref> [--project <ref>] [--name <n>] [--description <text|-|none>] [--target <day|none>] [--expected-updated-at <ts>]
+ *   archive|restore <ref> [--project <ref>] [--expected-updated-at <ts>]
+ *   add|remove <ref> <ticket> [<ticket> ...] [--project <ref>]
+ *
+ * A milestone ref is an id or an exact, case-insensitive name; two milestones with one name are refused by the door
+ * (`milestone_ref_ambiguous`) with their ids, never guessed. `--request-id` belongs to every write.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const ACTIONS = ["list", "show", "create", "update", "archive", "restore", "add", "remove"];
+const WRITES = ["create", "update", "archive", "restore", "add", "remove"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+export const MILESTONE_TICKETS_MAX = 50;
+function target(value, action) {
+    if (value === undefined)
+        return undefined;
+    if (value.trim().toLowerCase() === "none") {
+        if (action !== "update")
+            throw new Error("--target none clears a date on `milestone update`; leave --target off instead.");
+        return null;
+    }
+    if (!DAY.test(value) || new Date(`${value}T12:00:00Z`).toISOString().slice(0, 10) !== value) {
+        throw new Error("--target must be a calendar date as YYYY-MM-DD, or none.");
+    }
+    return value;
+}
+export function parseMilestoneArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home", "--dashboard-url", "--json", "--archived", "--project", "--name", "--description", "--target",
+            "--limit", "--cursor", "--request-id", "--expected-updated-at",
+        ],
+        valueFlags: [
+            "--home", "--dashboard-url", "--project", "--name", "--description", "--target",
+            "--limit", "--cursor", "--request-id", "--expected-updated-at",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!ACTIONS.includes(action)) {
+        throw new Error(`Unknown milestone command: ${first}. Try list, show, create, update, archive, restore, add or remove.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    let ref;
+    let tickets = [];
+    if (action === "list" || action === "create") {
+        if (rest.length > 0)
+            throw new Error(`milestone ${action} does not take "${rest[0]}".`);
+    }
+    else if (action === "add" || action === "remove") {
+        if (rest.length < 2)
+            throw new Error(`milestone ${action} takes a milestone and at least one ticket: milestone ${action} <milestone> BLI-123 [BLI-124 ...].`);
+        ref = rest[0];
+        tickets = [...new Set(rest.slice(1).flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean))];
+        if (tickets.length > MILESTONE_TICKETS_MAX)
+            throw new Error(`At most ${MILESTONE_TICKETS_MAX} tickets per call.`);
+    }
+    else {
+        if (rest.length !== 1)
+            throw new Error(`milestone ${action} takes exactly one milestone id or name.`);
+        ref = rest[0];
+    }
+    if (action !== "create" && action !== "update" && (given("--name") || given("--description") || given("--target"))) {
+        throw new Error("--name, --description and --target belong to milestone create and update.");
+    }
+    if (action !== "list" && given("--archived"))
+        throw new Error("--archived belongs to milestone list.");
+    if (action !== "show" && (given("--limit") || given("--cursor")))
+        throw new Error("--limit and --cursor belong to milestone show.");
+    if (!WRITES.includes(action) && given("--request-id"))
+        throw new Error("--request-id belongs to the milestone writes.");
+    if (!["update", "archive", "restore"].includes(action) && given("--expected-updated-at")) {
+        throw new Error("--expected-updated-at belongs to milestone update, archive and restore.");
+    }
+    const project = optionalNonEmpty(values.flags.get("--project"));
+    const name = optionalNonEmpty(values.flags.get("--name"));
+    if (action === "create" && (!project || !name))
+        throw new Error('milestone create needs --project <project> and --name "<name>".');
+    const rawDescription = values.flags.get("--description");
+    const description = rawDescription === undefined ? undefined
+        : action === "update" && rawDescription.trim().toLowerCase() === "none" ? null : rawDescription;
+    const targetDate = target(values.flags.get("--target"), action);
+    if (action === "update" && name === undefined && description === undefined && targetDate === undefined) {
+        throw new Error("milestone update needs --name, --description (or none) or --target (or none). Archive with `milestone archive`.");
+    }
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const expectedUpdatedAt = optionalNonEmpty(values.flags.get("--expected-updated-at"));
+    if (expectedUpdatedAt && Number.isNaN(Date.parse(expectedUpdatedAt))) {
+        throw new Error("--expected-updated-at must be the updated_at timestamp you last read.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    return {
+        kind: "milestone",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(ref === undefined ? {} : { ref }),
+        ...(project ? { project } : {}),
+        includeArchived: values.booleans.has("--archived"),
+        ...(name ? { name } : {}),
+        ...(description === undefined ? {} : { description }),
+        ...(targetDate === undefined ? {} : { targetDate }),
+        tickets,
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor ? { cursor } : {}),
+        ...(requestId ? { requestId } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+        json: values.booleans.has("--json"),
+    };
+}

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

@@ -23,6 +23,7 @@ import { NOTIFY_ACTIONS, NOTIFY_VALUE_FLAGS, isNotifyAction, parseNotifyArgs } f
 import { VIEW_BOOLEAN_FLAGS, VIEW_VALUE_FLAGS, parseViewArgs } from "./view-args.js";
 import { parseTemplateArgs } from "./template-args.js";
 import { CYCLE_BOOLEAN_FLAGS, CYCLE_VALUE_FLAGS, parseCycleArgs, readCycleField } from "./cycle-args.js";
+import { readArchivedFlag, readIssuePage } from "./issue-page-args.js";
 const ISSUE_ACTIONS = new Set([
     "mutation-status",
     "board",
@@ -37,6 +38,9 @@ const ISSUE_ACTIONS = new Set([
     "restore",
     "label",
     "batch",
+    // BLI-22367: reversible archive. `restore` stays the description-version verb.
+    "archive",
+    "unarchive",
     "relations",
     "relate",
     "unrelate",
@@ -56,6 +60,8 @@ const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
     "versions",
     "restore",
     "label",
+    "archive",
+    "unarchive",
     "relations",
     "relate",
     "unrelate",
@@ -99,6 +105,7 @@ const ISSUE_ALLOWED_FLAGS = [
     "--sort",
     "--dir",
     "--all",
+    "--archived",
     "--body-stdin",
     "--json",
     ...VIEW_BOOLEAN_FLAGS,
@@ -174,9 +181,10 @@ export function parseIssueArgs(args) {
         throw new Error("--request-id must be a UUID.");
     if (action === "mutation-status" && !UUID_PATTERN.test(issueRef ?? ""))
         throw new Error("mutation-status needs a request UUID.");
-    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore", "label", "batch", "relate", "unrelate"].includes(action)) {
-        throw new Error("Write-safety flags belong to create, update, move, comment, restore, label, relate, unrelate or batch.");
+    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore", "label", "batch", "relate", "unrelate", "archive", "unarchive"].includes(action)) {
+        throw new Error("Write-safety flags belong to create, update, move, comment, restore, label, relate, unrelate, archive, unarchive or batch.");
     }
+    const archived = readArchivedFlag(action, values);
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const fields = readIssueFields(action, values);
@@ -192,61 +200,18 @@ export function parseIssueArgs(args) {
     if (action === "board" && boardProject && !UUID_PATTERN.test(boardProject))
         throw new Error("board --project requires a uuid.");
     const priority = readIssuePriority(values);
-    const estimate = readIssueSize(values);
+    const estimate = readIssueSize(action, values);
+    checkNoneClears(action, values);
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
     const versionNumber = readIssueVersion(action, values);
-    return { ...buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields), ...readRelationFlags(action, values) };
-}
-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`. */
-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 } : {}),
-    };
+    return { ...buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields), ...readRelationFlags(action, values), ...(archived ? { archived } : {}) };
 }
 function readIssueAction(values) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!ISSUE_ACTIONS.has(action)) {
-        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, label, relations, relate, unrelate, views, templates, cycles, inbox, read, unread, subscribe, unsubscribe, notifications, history, versions, restore, batch, or mutation-status.`);
+        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, label, archive, unarchive, relations, relate, unrelate, views, templates, cycles, inbox, read, unread, subscribe, unsubscribe, notifications, history, versions, restore, batch, or mutation-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -318,9 +283,37 @@ function readIssuePriority(values) {
     }
     return priority;
 }
-function readIssueSize(values) {
+/**
+ * `--size S|M|L`, or `none` on update to clear the size (BLI-22367). Only ever what the person typed: no surface
+ * picks a size for them.
+ */
+function readIssueSize(action, values) {
     const raw = optionalNonEmpty(values.flags.get("--size"));
-    return raw === undefined ? undefined : estimateForSize(raw);
+    if (raw === undefined)
+        return undefined;
+    if (raw.toLowerCase() === "none") {
+        if (action !== "update")
+            throw new Error("--size none clears a size on `cockpit ticket update`; leave --size off to create without one.");
+        return null;
+    }
+    return estimateForSize(raw);
+}
+/**
+ * ONE spelling clears a field on update: `none` (BLI-22367). `--parent none` and `--project none` join the existing
+ * `--assignee none`, `--due none`, `--cycle none` and `--size none`. On create there is nothing to clear, so `none`
+ * is refused rather than looked up as a ticket or project called "none".
+ */
+function checkNoneClears(action, values) {
+    for (const flag of ["--parent", "--project"]) {
+        const value = optionalNonEmpty(values.flags.get(flag));
+        if (value?.toLowerCase() !== "none")
+            continue;
+        if (action === "update")
+            continue;
+        throw new Error(action === "create"
+            ? `${flag} none clears it on \`cockpit ticket update\`; leave ${flag} off to create without one.`
+            : `${flag} none clears it on \`cockpit ticket update\` only.`);
+    }
 }
 function readIssueAssignee(action, values) {
     // An assignee is `me`, `unassigned`, or a person's uuid. A name or an

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

@@ -33,6 +33,7 @@ export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
 export { parseGithubArgs } from "./local-args-tower-github.js";
+export { parseMilestoneArgs } from "./local-args-tower-milestone.js";
 export { parseSearchArgs } from "./local-args-tower-search.js";
 export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";

package/dist/commands/local-args.js

@@ -19,6 +19,7 @@ import { parseGlossaryArgs } from "./glossary.js";
 import { parseSpendArgs } from "./spend.js";
 import { parsePushArgs } from "./push.js";
 import { parseRootsArgs } from "./roots.js";
+import { parseMilestoneArgs } from "./local-args-tower-milestone.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
 import { parseCiArgs, parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseHitsArgs, parseIntentionsArgs, parseWhoArgs, parsePeopleArgs, parseApprovalsArgs, parseDrillsArgs, parseManagerArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
@@ -90,6 +91,7 @@ const COMMAND_PARSERS = new Map([
     ["mail", (_command, rest) => parseMailArgs(rest)],
     ["cal", (_command, rest) => parseCalArgs(rest)],
     ["project", (_command, rest) => parseProjectArgs(rest)],
+    ["milestone", (_command, rest) => parseMilestoneArgs(rest)],
     ["search", (_command, rest) => parseSearchArgs(rest)],
     ["github", (_command, rest) => parseGithubArgs(rest)],
     ["release", (_command, rest) => parseReleaseArgs(rest)],

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

@@ -0,0 +1 @@
+export {};

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

@@ -226,10 +226,10 @@ export const TOWER_OPS_COMMAND_HELP = [
             "                                               \"YYYY-MM-DD: \" dates a bullet, without it the bullet is undated. none clears --next or --blocker. blocked needs a blocker (given, or already on the card),",
             "                                               and a blocker goes only on a Blocked card: sent with any other health it is refused (summary_blocker_needs_blocked); sending only a new health drops the stored one.",
             "                                               --version is summary.updatedAt from `home <client> --json`, or none when the client has no card yet (then --health, --headline and at least one --bullet are all needed).",
-            "                                               Limits: headline 140 characters, each bullet 160, next and blocker 200; a longer text is refused here with its length. A day spelled with a month name at the start of a bullet (\"Oct 3: x\") is refused, never saved undated. --version none is for a client with no card: on one that has a card the write is refused with \"This client already has a card: pass its version\". The edit is marked as yours and stands until the client's",
-            "                                               data changes, an action goes overdue or an open action passes 14 days overdue; the next check after that writes the card again (newest wins).",
+            "                                               Limits: headline 140 characters, each bullet 160, next and blocker 200; a longer text is refused here with its length. A day spelled with a month name at the start of a bullet (\"Oct 3: x\") is refused, never saved undated. --version none is for a client with no card: on one that has a card the write is refused with \"This client already has a card: pass its version\". The edit is stored as written by your agent",
+            "                                               (source agent, \"Written by <you>'s agent\"): Tower's check never rewrites it, whatever changes; your agent's next edit, or a person's on the page, replaces it.",
             "                                               A saved card that says On track while an open action is more than 14 days overdue is saved anyway and prints a \"Warning: ...\" line naming the action overdue longest.",
-            "                                               Write the card after your item writes: your own later item writes count as data changes, and the next check rewrites the card.",
+            "                                               Write the card after your item writes: the check will not rewrite it to take them in.",
             "                                               Health rule: an open action more than 14 days overdue, as `cockpit manager home` shows it (Tower's today, America/Vancouver), means the card is at_risk (or blocked, with a named blocker).",
             "                                               Do not set on_track over one; tell the person instead. The headline or a bullet must name the action overdue longest, with the day it was due.",
             "  cockpit manager list <client> [--timeline] [--needs-review] [--status open|done|dropped|closed|all] [--owner <name>|--no-owner] [--overdue] [--kind <kind>] [--search <text>] [--archived] [--review dismissed|all]",
@@ -261,7 +261,7 @@ export const TOWER_OPS_COMMAND_HELP = [
             "                                               --version and --timeline stay flags. A field given as a flag and in the file is refused, so is an unknown key. The file gets the flags' own checks. Example:  cat fields.json | cockpit manager summary Acme --version none --fields-file -",
             "Free text (the flags above and every value in a fields file) that holds a provider key (an sk-, rk_, sb_secret_, ghp_, github_pat_, AKIA/ASIA, xoxb- key, any JWT, a PEM private key) or a password given a value (\"password: x\") is refused, naming the flag or key; ordinary words, a commit sha, a URL and the words \"service-role key\" are plain text.",
             "On a flag, free text (--headline, --bullet, --title, --detail, --next, --blocker, --owners, --source-note) goes in SINGLE quotes so the shell leaves $ alone: \"$12k\" in double quotes loses the $12k (zsh and bash read it as a variable). In bash and zsh write an apostrophe inside single quotes as '\\'' (end the quote, a backslash-escaped apostrophe, reopen); in PowerShell double the apostrophe ('Rowan''s deck'). The command prints what it saved: check it is your words.",
-            "<client> is the client's id, or its exact name (any case; `clients` lists them); a name that matches no client, or several, is refused with the names. Ids and versions are printed by list, queue and show. Items you add are reviewed already.",
+            "<client> is the client's id, or its exact name (any case; `clients` lists them); a name that matches no client, or several, is refused with the names. Ids and versions are printed by list, queue and show. Items you add here are stored as added by your agent, not yet checked (they count in needs review until a person approves or dismisses them), never as you having checked them; text tagged [HR] is refused (item_hr_tagged, summary_hr_tagged).",
             "--version is the item's version exactly as list or show prints it, copied as it is. Every change to an existing item names it: if someone or a sync changed the item",
             "since, the write is refused with a sentence saying so and nothing is written; run show again for the new version and retry.",
             "--owners on an action takes, as the web form says, \"One or more people, separated by commas\" (\"Rowan Ash, Juniper Twig\"), and it REPLACES the whole list. Leave it out and the owners stay;",