@bli-cockpit/cli 0.2.242 → 0.2.244

package/dist/commands/sources-check.js

@@ -1,3 +1,25 @@
+/**
+ * `cockpit sources check [--older-than <days>] [--json]` — does Tower hold
+ * each agent transcript on this machine? (BLI-11122)
+ *
+ * On 2026-09-30 an agent freeing disk ran `find ~/.codex/... -mtime +60
+ * -delete` on the premise that the files were already in Tower; 349 of 1,491
+ * had no copy. This door is the machine answer that was missing: for every
+ * local Codex and Claude transcript it asks Tower which current objects it
+ * holds and answers `stored_full`, `stored_slim` (BLI-17273: Tower holds only the
+ * slim form, keep the file), `stored_partial` or `not_stored`, with the reason
+ * (`sources-verdict.ts`), judged against THIS machine's image mode.
+ *
+ * READ-ONLY, and nothing else: Tower never deletes a person's raw transcripts.
+ * Deleting one is the person's own act, outside Tower. This command reads the
+ * files and the server's list; it never writes, moves or deletes a file under
+ * `~/.codex` or `~/.claude`. `docs/runbooks/freeing-disk-on-a-collector-machine.md`.
+ *
+ * A server that cannot be asked is a failure with its reason (exit 1), never
+ * "not stored". A list cut short (`capped`, `failed_partial`) still answers,
+ * marked incomplete: a missing page can only understate what Tower holds.
+ */
+import { fetchSourceInventory, reconcileSource } from "./sources-reconciliation.js";
 import { writeLine } from "./cli-io.js";
 import { readDescribedImageKeys } from "../image-description-state.js";
 import { resolveImageHandlingMode } from "../image-mode-state.js";
@@ -12,6 +34,10 @@ export async function runSourcesCheck(command, io, now = new Date()) {
     const startedAt = Date.now();
     const paths = getCollectorRuntimePaths(command.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => null);
+    if (command.reconcile && !config) {
+        console.error("[collector sources] reconciliation not run", JSON.stringify({ reason: "local_config_unavailable_opt_out_unknown" }));
+        return fail(io, command, "local_config_unavailable_opt_out_unknown", "Local collection preferences could not be read; no transcript store was scanned.");
+    }
     const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
     if (!session || session.session_state !== "valid" || typeof session.device_token !== "string" || !session.device_token) {
@@ -25,7 +51,9 @@ export async function runSourcesCheck(command, io, now = new Date()) {
     }
     const homeDir = command.homeDir ?? paths.home_dir;
     const olderThanMs = command.olderThanDays === null ? null : now.getTime() - command.olderThanDays * DAY_MS;
-    const local = await discoverLocalTranscripts({ homeDir, olderThanMs });
+    const optOutAll = command.reconcile === true && config?.raw_evidence_upload === "disabled";
+    const optOutClaude = command.reconcile === true && config?.collect_claude_jsonl === false;
+    const local = await discoverLocalTranscripts({ homeDir, olderThanMs, skipAll: optOutAll, skipClaude: optOutClaude });
     const cursors = {
         codex: await readRawEvidenceCursor(paths),
         claude_code: await readRawEvidenceCursor(paths, { filename: CLAUDE_CURSOR_FILENAME, sessionsOnly: true }),
@@ -38,6 +66,36 @@ export async function runSourcesCheck(command, io, now = new Date()) {
     console.error("[collector sources] judging against this machine's image mode", JSON.stringify({ reason: `image_mode_from_${imageMode.source}`, mode: imageMode.mode, slim_aware: imageMode.slimAware }));
     const report = emptyReport(command, remote, local.newer_count, local.file_read_failed + local.directory_read_failed);
     await judgeLocalTranscripts(local.files, remote, cursors, imageMode, describedKeys, report);
+    if (command.reconcile) {
+        const inventory = await fetchSourceInventory({ dashboardUrl, deviceToken: session.device_token, fetchImpl: io.fetch });
+        const { rows: _rows, ...inventoryCounts } = inventory;
+        const counts = { missing_row: 0, missing_pointer: 0, stale_revision: 0, unavailable_evidence: 0, explicit_opt_out: 0, unverifiable: 0, revision_verified: 0 };
+        const optOutSources = optOutAll ? ["codex", "claude_code"] : optOutClaude ? ["claude_code"] : [];
+        counts.explicit_opt_out = optOutSources.length;
+        for (const file of local.files) {
+            const finding = await reconcileSource({ file, inventory, remote,
+                cursor: file.kind === "claude_subagent" ? null : cursors[file.source].sessions[file.session_id] ?? null,
+                facts: fileFacts(file, undefined, { mode: imageMode.mode, describedKeys, slimAware: imageMode.slimAware }),
+            }).catch(() => ({ state: "unavailable_evidence", reason: "local_revision_unreadable" }));
+            counts[finding.state]++;
+            const entry = report.files.find(entry => entry.path === file.file_path);
+            if (entry)
+                entry.reconciliation = finding;
+        }
+        report.reconciliation = { counts, inventory: inventoryCounts,
+            scan: { started_at: new Date(startedAt).toISOString(), finished_at: new Date().toISOString(),
+                roots: ["codex/sessions", "codex/archived_sessions", "claude/projects"], older_than_days: command.olderThanDays, opt_out_sources: optOutSources },
+            limitations: ["Snapshot scan, not a live completeness guarantee; absent local sources cannot be discovered.", "Missing historical source identifiers remain unverifiable.", "Pointer metadata does not prove bucket bytes are readable; no storage bodies fetched.", "explicit_opt_out counts sources, not undiscovered files; opted-out stores are not scanned."],
+        };
+        if (inventory.status !== "exhausted" || report.local.unreadable > 0 || counts.unavailable_evidence > 0) {
+            report.status = "incomplete";
+            report.reason = "reconciliation_partial";
+        }
+    }
+    if (report.local.unreadable > 0) {
+        report.status = "incomplete";
+        report.reason = "local_scan_incomplete";
+    }
     reportSourcesCheck(report, remote, startedAt);
     if (command.json)
         writeLine(io.stdout, JSON.stringify(report, null, 2));
@@ -93,6 +151,7 @@ function reportSourcesCheck(report, remote, startedAt) {
         stored_partial: report.counts.stored_partial,
         not_stored: report.counts.not_stored,
         reasons: report.reasons,
+        ...(report.reconciliation ? { reconciliation: report.reconciliation.counts } : {}),
         elapsed_ms: Date.now() - startedAt,
     }));
 }
@@ -135,6 +194,8 @@ export function sourcesCheckLines(report) {
         `  stored in part  ${report.counts.stored_partial.files} file(s), ${mb(report.counts.stored_partial.bytes)} MB`,
         `  not stored       ${report.counts.not_stored.files} file(s), ${mb(report.counts.not_stored.bytes)} MB`,
     ];
+    if (report.reconciliation)
+        lines.push(`  reconciliation   ${Object.entries(report.reconciliation.counts).map(([state, count]) => `${state} ${count}`).join(", ")}`, `  row inventory    ${report.reconciliation.inventory.status}; ${report.reconciliation.inventory.unique} unique of ${report.reconciliation.inventory.returned} returned (${report.reconciliation.inventory.requested} requested)`, `  scan             ${report.reconciliation.scan.started_at} to ${report.reconciliation.scan.finished_at}; roots ${report.reconciliation.scan.roots.join(", ")}; opted out ${report.reconciliation.scan.opt_out_sources.join(", ") || "none"}`, ...report.reconciliation.limitations.map(reason => `  limitation       ${reason}`));
     const reasons = Object.entries(report.reasons).sort((a, b) => b[1] - a[1]);
     if (reasons.length > 0)
         lines.push(`  why              ${reasons.map(([reason, count]) => `${reason} ${count}`).join(", ")}`);
@@ -144,7 +205,7 @@ export function sourcesCheckLines(report) {
         lines.push(`  unreadable       ${report.local.unreadable} file(s) could not be read and are not answered`);
     lines.push(`  Tower's list     ${report.remote.status}: ${report.remote.unique} current transcript object(s) over ${report.remote.pages} page(s)`);
     if (report.status === "incomplete") {
-        lines.push(`  INCOMPLETE       Tower's list was cut short (${report.reason}); "not stored" and "stored in part" may be understated. Run it again.`);
+        lines.push(`  INCOMPLETE       The scan or evidence list is incomplete (${report.reason}); missing evidence is inconclusive. Run it again.`);
     }
     lines.push("Tower never deletes these files. `--json` lists every file with its path and verdict. Only a \"stored in full\" file is safe to delete by your own hand (never \"stored slim\"); see docs/runbooks/freeing-disk-on-a-collector-machine.md.");
     return lines;

package/dist/commands/sources-discovery.js

@@ -153,7 +153,7 @@ function shapeOrder(shape) {
 }
 async function findTranscriptFiles(options, roots, result, recordFailure) {
     const found = [];
-    const stack = [...roots.codex, roots.claudeProjects];
+    const stack = options.skipAll ? [] : [...roots.codex, ...(options.skipClaude ? [] : [roots.claudeProjects])];
     const seen = new Set();
     while (stack.length > 0) {
         const dir = stack.pop();

package/dist/commands/sources-reconciliation.js

@@ -0,0 +1,87 @@
+/** Metadata reconciliation only. Never writes cursors, starts collection or fetches bodies. */
+import fs from "node:fs/promises";
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+export async function fetchSourceInventory(options) {
+    const rows = new Map();
+    const result = { status: "capped", reason: "page_limit", requested: 0, returned: 0, unique: 0, pages: 0, rows: [] };
+    let after = null;
+    try {
+        for (let page = 0; page < (options.maxPages ?? 400); page++) {
+            result.requested += 500;
+            const response = await options.fetchImpl(`${options.dashboardUrl}/api/ambient/evidence/transcripts?inventory=1`, {
+                method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.deviceToken}` },
+                body: JSON.stringify({ schema_version: "evidence-transcripts.v1", after, limit: 500 }),
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (!response.ok)
+                throw new Error(`http_${response.status}`);
+            const body = await response.json();
+            if (body.schema_version !== "source-reconciliation.v1" || !Array.isArray(body.rows) || body.rows.length > 500 ||
+                !(body.next_after === null || (typeof body.next_after === "string" && uuid.test(body.next_after))))
+                throw new Error("invalid_response");
+            const valid = body.rows.every((row) => row && typeof row.id === "string" && uuid.test(row.id) &&
+                typeof row.source === "string" && (row.codex_session_id === null || typeof row.codex_session_id === "string") &&
+                (row.raw_evidence_pointer_id === null || (typeof row.raw_evidence_pointer_id === "string" && uuid.test(row.raw_evidence_pointer_id))));
+            if (!valid)
+                throw new Error("invalid_response");
+            const next = body.next_after;
+            if (next && (next <= (after ?? "") || body.rows.length === 0 || next !== body.rows.at(-1).id))
+                throw new Error("cursor_not_advancing");
+            result.pages++;
+            result.returned += body.rows.length;
+            for (const row of body.rows)
+                rows.set(row.id, row);
+            if (!next) {
+                result.status = "exhausted";
+                result.reason = "ok";
+                break;
+            }
+            after = next;
+        }
+    }
+    catch (error) {
+        result.status = result.pages ? "failed_partial" : "unavailable";
+        result.reason = error instanceof Error && /^(http_\d+|invalid_response|cursor_not_advancing)$/.test(error.message) ? error.message : "request_failed";
+    }
+    result.rows = [...rows.values()];
+    result.unique = rows.size;
+    console.error("[collector sources] row inventory", JSON.stringify({ reason: result.reason, status: result.status, requested: result.requested, returned: result.returned, unique: result.unique, pages: result.pages }));
+    return result;
+}
+export async function reconcileSource(input) {
+    const answer = (state, reason) => ({ state, reason });
+    const { file, inventory, remote, cursor, facts } = input;
+    if (file.session_id_source === "path_hash")
+        return answer("unverifiable", "source_identifier_missing");
+    const rows = inventory.rows.filter(row => row.source === file.source && row.codex_session_id === file.session_id);
+    if (!rows.length && inventory.rows.some(row => (!row.source || row.source === file.source) && !row.codex_session_id?.trim())) {
+        return answer("unverifiable", "historical_source_identifier_missing");
+    }
+    if (!rows.length)
+        return inventory.status === "exhausted"
+            ? answer("missing_row", "source_row_absent") : answer("unavailable_evidence", `row_inventory_${inventory.status}`);
+    // Duplicate device rows are expected; any usable pointer can answer this file.
+    const pointers = new Set(rows.map(row => row.raw_evidence_pointer_id).filter(Boolean));
+    if (!pointers.size)
+        return inventory.status === "exhausted"
+            ? answer("missing_pointer", "source_rows_without_pointer") : answer("unavailable_evidence", `row_inventory_${inventory.status}`);
+    const objects = (remote.files.get(file.key) ?? []).filter(object => !object.stub &&
+        (file.kind === "claude_subagent" || (object.ref_id && pointers.has(object.ref_id))));
+    if (!objects.length)
+        return answer("unavailable_evidence", remote.status === "exhausted" ? "pointer_not_in_current_transcripts_or_stub" : `transcripts_${remote.status}`);
+    const split = facts.slimSplit ? await facts.slimSplit() : null;
+    const form = split?.slim ?? (facts.slimAware && facts.wholeForm ? await facts.wholeForm() : await facts.sanitized());
+    const stat = await fs.stat(file.file_path);
+    if (stat.size !== file.byte_size || stat.mtimeMs !== file.mtime_ms)
+        return answer("unavailable_evidence", "local_file_changed_during_check");
+    if (form && objects.some(object => object.content_hash_sha256 === form.sha256 || object.content_hash_sha256 === split?.full.sha256))
+        return answer("revision_verified", "current_redacted_hash_matches_pointer");
+    // Sync refreshes the observed file hash even when growth damping retains an older
+    // durable upload. uploaded_byte_size is the raw source size at that upload.
+    if (form && objects.every(object => object.content_hash_sha256 !== null) && cursor?.uploaded_object_key &&
+        objects.some(object => object.object_key === cursor.uploaded_object_key || object.ref_id === cursor.uploaded_object_key) &&
+        cursor.uploaded_byte_size !== null && cursor.uploaded_byte_size < file.byte_size) {
+        return answer("stale_revision", "local_tail_newer_than_cursor_upload");
+    }
+    return answer("unverifiable", form ? "revision_hash_mismatch_or_legacy_hash_missing" : "redacted_revision_unavailable");
+}

package/dist/commands/sync-doctor.js

@@ -14,6 +14,7 @@ import { doctorNeedsPerson, sanitizeEventCode } from "./doctor-report.js";
 import { runSelfUpdate } from "./install-update.js";
 import { reportInstallEventsBestEffort } from "./install-receipts.js";
 import { clearDoctorRequest, requestedDoctorId } from "./sync-doctor-request.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
 export async function runDoctorAfterSync(command, io, dashboardUrl, overrides = {}, facts) {
     if (shouldSuppressFleetReceipts({ dashboardUrl }).suppressed) {
         console.error("[sync-doctor] checkout does not repair the fleet machine", JSON.stringify({ reason: "receipt_suppressed:dev_build" }));
@@ -69,11 +70,23 @@ export async function runDoctorAfterSync(command, io, dashboardUrl, overrides =
         await lock.handle.release();
     }
 }
+/**
+ * Ticket 21952. launchd hands the tick `PATH=/usr/bin:/bin:/usr/sbin:/sbin`, where neither `node` nor `npm` lives, so
+ * the tick doctor's `npm view` and `npm install` could not start on any Mac: every macOS receipt read
+ * `latest_version_unknown -> fail:npm_install_failed` while already on the newest CLI, and Windows (whose scheduler
+ * keeps the user's PATH) read `already_latest`. The scheduled self-update already runs npm with the running node's bin
+ * dir on PATH (`envWithNodeRuntimeOnPath`); the tick doctor now does the same. A caller's explicit env still wins.
+ */
+export function withNodeRuntimeOnPath(io) {
+    const env = envWithNodeRuntimeOnPath(io.env ?? process.env);
+    const wrap = (runner) => runner ? (cmd, args, options) => runner(cmd, args, { ...options, env: options?.env ?? env }) : undefined;
+    return { exec: wrap(io.exec), interactiveExec: wrap(io.interactiveExec) };
+}
 async function collectDoctorReceipt(command, io, dashboardUrl, overrides, facts, paths, requestId) {
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
     let receipt = null;
     const quiet = new Writable({ write(_chunk, _encoding, done) { done(); } });
-    const doctorIo = { ...io, stdout: quiet };
+    const doctorIo = { ...io, stdout: quiet, ...withNodeRuntimeOnPath(io) };
     await runDoctor({ kind: "doctor", alias: "doctor", automaticTick: true, homeDir: command.homeDir, dashboardUrl, json: true, dryRun: false }, doctorIo, {
         selfUpdate: (updateIo, options) => runSelfUpdate({ ...updateIo, stdout: quiet }, options),
         runLogin: async () => { throw new Error("automatic_doctor_cannot_prompt"); },

package/dist/commands/sync-report.js

@@ -152,7 +152,7 @@ function syncResult(run) {
         notice: run.notice,
         // BLI-4022: unlike the reasons, the hold survives a successful run — it is
         // what the tick withheld, not why it failed.
-        holdNotice: run.hold?.notice ?? null,
+        holdNotice: run.hold?.notice ?? run.budgetHold?.notice ?? null,
         sessionsObserved: run.sessions_observed,
         sessionsOutsideRoot: run.sessions_outside_root,
         outsideRootDirectories: run.outside_root_directories,

package/dist/commands/template-args.js

@@ -0,0 +1,122 @@
+/**
+ * `cockpit ticket templates [list|show|versions|save|update|apply]` argument parsing (BLI-21779, P11).
+ * `templates` is an `issue` action; its flags are read here so `local-args-tower-work.ts` only dispatches,
+ * the way `view-args.ts` does for views.
+ *
+ * Property flags mean the same on save, update and apply: `--description <text|->` (`-` reads stdin),
+ * `--state`, `--priority 0-4`, `--size S|M|L`, `--project <name|id>`, `--label <name>` (repeatable).
+ * On save and update, the value `none` clears a preset; on apply, `none` clears what the template would
+ * have copied. Nothing here carries a title except `apply`, and nothing stores one.
+ */
+import { estimateForSize } from "./issue-contracts.js";
+import { optionalNonEmpty, optionalUrl } from "./local-arg-values.js";
+export const TEMPLATE_VERBS = ["list", "show", "versions", "save", "update", "apply"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATES = ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
+const NONE = (value) => value.trim().toLowerCase() === "none";
+export function parseTemplateArgs(values, rest) {
+    const first = rest[0];
+    const verb = (first === undefined ? "list" : first);
+    if (!TEMPLATE_VERBS.includes(verb)) {
+        throw new Error(`Unknown templates command: ${first}. Try list, show, versions, save, update or apply.`);
+    }
+    const positional = rest.slice(first === undefined ? 0 : 1);
+    const needsRef = verb !== "list" && verb !== "save";
+    if (needsRef && positional.length !== 1)
+        throw new Error(`ticket templates ${verb} takes exactly one template id or name.`);
+    if (!needsRef && positional.length > 0)
+        throw new Error(`ticket templates ${verb} does not take "${positional[0]}".`);
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    const writes = verb === "save" || verb === "update" || verb === "apply";
+    for (const flag of ["--description", "--state", "--priority", "--size", "--project", "--label"]) {
+        if (given(flag) && !writes)
+            throw new Error(`${flag} belongs to \`cockpit ticket templates save\`, \`update\` and \`apply\`.`);
+    }
+    if (given("--name") && verb !== "save" && verb !== "update")
+        throw new Error("--name belongs to `cockpit ticket templates save` and `update`.");
+    if (verb !== "update" && (given("--archive") || given("--restore") || given("--expected-updated-at"))) {
+        throw new Error("--archive, --restore and --expected-updated-at belong to `cockpit ticket templates update`.");
+    }
+    if (verb !== "apply" && (given("--title") || given("--assignee") || given("--parent") || given("--due"))) {
+        throw new Error("--title, --assignee, --parent and --due belong to `cockpit ticket templates apply`; a template never stores them.");
+    }
+    if (verb !== "list" && given("--include-archived"))
+        throw new Error("--include-archived belongs to `cockpit ticket templates list`.");
+    if (given("--archive") && given("--restore"))
+        throw new Error("Give --archive or --restore, not both.");
+    if ((verb === "save" || verb === "apply") === false && given("--request-id")) {
+        throw new Error("--request-id belongs to `cockpit ticket templates save` and `apply`.");
+    }
+    if (given("--expected-revision") || given("--limit") || given("--shared") || given("--private")) {
+        throw new Error("That flag does not belong to ticket templates.");
+    }
+    const name = optionalNonEmpty(values.flags.get("--name"));
+    if (verb === "save" && !name)
+        throw new Error('ticket templates save needs --name "<name>".');
+    const rawDescription = values.flags.get("--description");
+    const rawState = optionalNonEmpty(values.flags.get("--state"));
+    if (rawState && !NONE(rawState) && !STATES.includes(rawState))
+        throw new Error(`--state must be one of: ${STATES.join(", ")} (or none).`);
+    const rawPriority = optionalNonEmpty(values.flags.get("--priority"));
+    let priority;
+    if (rawPriority !== undefined) {
+        if (NONE(rawPriority))
+            priority = null;
+        else {
+            priority = Number(rawPriority);
+            if (!Number.isInteger(priority) || priority < 0 || priority > 4) {
+                throw new Error("--priority must be 0-4 (0 none, 1 urgent, 2 high, 3 medium, 4 low), or the word none to clear it.");
+            }
+        }
+    }
+    const rawSize = optionalNonEmpty(values.flags.get("--size"));
+    const estimate = rawSize === undefined ? undefined : NONE(rawSize) ? null : estimateForSize(rawSize);
+    const rawProject = optionalNonEmpty(values.flags.get("--project"));
+    const labelValues = (values.flagValues.get("--label") ?? []).map((v) => v.trim()).filter(Boolean);
+    const labels = labelValues.length === 1 && NONE(labelValues[0]) ? [] : labelValues;
+    const assignee = optionalNonEmpty(values.flags.get("--assignee"));
+    if (assignee !== undefined && assignee !== "me" && !UUID.test(assignee))
+        throw new Error('--assignee must be "me" or a person\'s uuid.');
+    const due = optionalNonEmpty(values.flags.get("--due"));
+    if (due && !NONE(due) && !/^\d{4}-\d{2}-\d{2}$/.test(due))
+        throw new Error("--due must be YYYY-MM-DD (or none).");
+    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 requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const changes = rawDescription !== undefined || rawState !== undefined || priority !== undefined || estimate !== undefined
+        || rawProject !== undefined || labelValues.length > 0 || name !== undefined;
+    if (verb === "update" && !changes && !given("--archive") && !given("--restore")) {
+        throw new Error("ticket templates update needs a field to change: --name, --description, --state, --priority, --size, --project, --label, --archive or --restore.");
+    }
+    const templates = {
+        verb,
+        ...(needsRef ? { ref: positional[0] } : {}),
+        ...(name ? { name } : {}),
+        ...(rawDescription === undefined ? {} : { description: NONE(rawDescription) ? null : rawDescription }),
+        ...(rawState === undefined ? {} : { state: NONE(rawState) ? null : rawState }),
+        ...(priority === undefined ? {} : { priority }),
+        ...(estimate === undefined ? {} : { estimate }),
+        ...(rawProject === undefined ? {} : { project: NONE(rawProject) ? null : rawProject }),
+        ...(labelValues.length > 0 ? { labels } : {}),
+        ...(optionalNonEmpty(values.flags.get("--title")) ? { title: optionalNonEmpty(values.flags.get("--title")) } : {}),
+        ...(assignee ? { assignee } : {}),
+        ...(optionalNonEmpty(values.flags.get("--parent")) ? { parentRef: optionalNonEmpty(values.flags.get("--parent")) } : {}),
+        ...(due === undefined ? {} : { due: NONE(due) ? null : due }),
+        ...(given("--archive") ? { archived: true } : given("--restore") ? { archived: false } : {}),
+        ...(given("--include-archived") ? { includeArchived: true } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+    };
+    return {
+        kind: "issue",
+        action: "templates",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(requestId ? { requestId } : {}),
+        json: values.booleans.has("--json"),
+        templates,
+    };
+}

package/dist/commands/templates.js

@@ -0,0 +1,162 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { BODY_MAX_CHARS, READ_DEADLINE_MS, WRITE_DEADLINE_MS, resolveRefs, sizeForEstimate } from "./issue-contracts.js";
+const TAG = "[ticket templates cli]";
+const presetText = (t) => {
+    const parts = [];
+    if (t.state)
+        parts.push(`state ${t.state}`);
+    if (t.priority !== null)
+        parts.push(`priority ${t.priority}`);
+    if (t.estimate !== null)
+        parts.push(`size ${sizeForEstimate(t.estimate) ?? t.estimate}`);
+    if (t.project_id)
+        parts.push(`project ${t.project_id}`);
+    if (t.label_names.length > 0)
+        parts.push(`labels ${t.label_names.join(", ")}`);
+    return parts.length === 0 ? "no presets" : parts.join(", ");
+};
+const templateLine = (t) => `${t.id}  ${t.name}  [v${t.version}${t.archived_at ? ", archived" : ""}${t.mine ? ", yours" : ""}]  ${presetText(t)}`;
+/** `--json` rows get a `size` letter beside the raw estimate, like every ticket read. */
+const withSize = (row) => ({ ...row, size: sizeForEstimate(row.estimate ?? null) });
+export async function runTemplates(command, io, door) {
+    const t = command.templates;
+    const ref = t.ref ? encodeURIComponent(t.ref) : "";
+    switch (t.verb) {
+        case "list": {
+            const answer = await askAgentDoor(door, {
+                path: `/api/work/templates${t.includeArchived ? "?include_archived=true" : ""}`,
+                method: "GET", label: "ticket templates list", timeoutMs: READ_DEADLINE_MS,
+            });
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            const body = answer.body;
+            const templates = body.templates ?? [];
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body, templates: templates.map(withSize) });
+            if (templates.length === 0)
+                writeLine(door.io.stdout, "No templates yet. Save one with `cockpit ticket templates save --name <name>`.");
+            for (const row of templates)
+                writeLine(door.io.stdout, templateLine(row));
+            if (body.archived_hidden)
+                writeLine(door.io.stdout, `\n${body.archived_hidden} archived template(s) not shown (--include-archived).`);
+            return 0;
+        }
+        case "show": {
+            const answer = await askAgentDoor(door, { path: `/api/work/templates/${ref}`, method: "GET", label: "ticket templates show", timeoutMs: READ_DEADLINE_MS });
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            const body = answer.body;
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, template: withSize(body.template) });
+            const row = body.template;
+            writeLine(door.io.stdout, templateLine(row));
+            writeLine(door.io.stdout, row.description ? `\n${row.description}` : "\n(no description)");
+            return 0;
+        }
+        case "versions": {
+            const answer = await askAgentDoor(door, { path: `/api/work/templates/${ref}/versions`, method: "GET", label: "ticket templates versions", timeoutMs: READ_DEADLINE_MS });
+            if (!answer.ok)
+                return failAgentDoor(door, TAG, answer.reason, answer.detail);
+            const body = answer.body;
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body, template: withSize(body.template), versions: (body.versions ?? []).map((v) => withSize(v)) });
+            writeLine(door.io.stdout, `${body.template.name}: ${body.versions?.length ?? 0} version(s), current v${body.template.version}.`);
+            for (const v of body.versions ?? [])
+                writeLine(door.io.stdout, `v${v.version}  ${v.created_at}  ${v.name}${v.archived ? "  (archived)" : ""}`);
+            return 0;
+        }
+        case "save":
+        case "update":
+            return writeTemplate(command, io, door, ref);
+        case "apply":
+            return applyTemplate(command, io, door, ref);
+    }
+}
+/** `--description -` reads the text from stdin; anything else is the text itself. */
+async function readDescription(value, io) {
+    if (value !== "-")
+        return { ok: true, text: value };
+    if (isInteractiveStdin(io))
+        return { ok: false, detail: "--description - reads the text from stdin, and nothing is piped in." };
+    try {
+        return { ok: true, text: await readPipedText(io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `A template description is limited to ${BODY_MAX_CHARS} characters.` }) };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function writeTemplate(command, io, door, ref) {
+    const t = command.templates;
+    const description = await readDescription(t.description, io);
+    if (!description.ok)
+        return failAgentDoor(door, TAG, "invalid_body", description.detail);
+    const payload = {
+        ...(t.verb === "save" && command.requestId ? { request_id: command.requestId } : {}),
+        ...(t.verb === "update" && t.expectedUpdatedAt ? { expected_updated_at: t.expectedUpdatedAt } : {}),
+        ...(t.name === undefined ? {} : { name: t.name }),
+        ...(description.text === undefined ? {} : { description: description.text }),
+        ...(t.state === undefined ? {} : { state: t.state }),
+        ...(t.priority === undefined ? {} : { priority: t.priority }),
+        ...(t.estimate === undefined ? {} : { estimate: t.estimate }),
+        ...(t.project === undefined ? {} : { project: t.project }),
+        ...(t.labels ? { label_names: t.labels } : {}),
+        ...(t.archived === undefined ? {} : { archived: t.archived }),
+    };
+    const answer = await askAgentDoor(door, {
+        path: t.verb === "save" ? "/api/work/templates" : `/api/work/templates/${ref}`,
+        method: t.verb === "save" ? "POST" : "PATCH",
+        label: `ticket templates ${t.verb}`,
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: payload,
+    });
+    if (!answer.ok) {
+        const mutation = answer.body?.mutation;
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+    }
+    const body = answer.body;
+    console.error(`${TAG} ${t.verb} done`, JSON.stringify({ template_id: body.template.id, version: body.template.version, replayed: Boolean(body.replayed) }));
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body, template: withSize(body.template) });
+    writeLine(door.io.stdout, `${t.verb === "save" ? (body.replayed ? "Already saved" : "Saved") : "Updated"}: ${body.template.name} (${body.template.id}), version ${body.template.version}${body.template.archived_at ? ", archived" : ""}.`);
+    return 0;
+}
+async function applyTemplate(command, io, door, ref) {
+    const t = command.templates;
+    const description = await readDescription(t.description, io);
+    if (!description.ok)
+        return failAgentDoor(door, TAG, "invalid_body", description.detail);
+    // A project name or a parent identifier is resolved to ids here, the way `ticket create` does.
+    const refs = await resolveRefs({ project: t.project ?? undefined, parentRef: t.parentRef }, door);
+    if (!refs.ok)
+        return failAgentDoor(door, TAG, refs.reason, refs.detail);
+    const payload = {
+        ...(command.requestId ? { request_id: command.requestId } : {}),
+        ...(t.title ? { title: t.title } : {}),
+        ...(description.text === undefined ? {} : { description: description.text }),
+        ...(t.state === undefined ? {} : { state: t.state }),
+        ...(t.priority === undefined ? {} : { priority: t.priority }),
+        ...(t.estimate === undefined ? {} : { estimate: t.estimate }),
+        ...(t.project === null ? { project_id: null } : refs.projectId ? { project_id: refs.projectId } : {}),
+        ...(t.labels ? { labels: t.labels } : {}),
+        ...(t.assignee ? { assignee_id: t.assignee } : {}),
+        ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+        ...(t.due === undefined ? {} : { due_date: t.due }),
+    };
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/templates/${ref}/apply`, method: "POST", label: "ticket templates apply", timeoutMs: WRITE_DEADLINE_MS, body: payload,
+    });
+    if (!answer.ok) {
+        const mutation = answer.body?.mutation;
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+    }
+    const body = answer.body;
+    console.error(`${TAG} apply done`, JSON.stringify({ template_id: body.template?.id, version: body.template?.version, labels: body.labels?.status }));
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body, issue: withSize(body.issue) });
+    writeLine(door.io.stdout, `Created ${body.issue.identifier ?? ""} from template v${body.template?.version ?? "?"}: ${body.issue.title ?? ""}`);
+    if (body.labels?.status === "failed") {
+        writeLine(door.io.stderr, `The ticket exists but its labels (${(body.labels.names ?? []).join(", ")}) were not applied: ${body.labels.reason}. Add them with \`cockpit ticket label\`.`);
+    }
+    return 0;
+}