@bli-cockpit/cli 0.2.242 → 0.2.243

package/dist/commands/msg.js

@@ -17,21 +17,24 @@
  */
 import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
-import { writeLine } from "./cli-io.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
 import { markReadThrough } from "./msg-read-line.js";
+import { runMsgActivityVerb } from "./msg-activity.js";
 import { runMsgDraft } from "./msg-draft.js";
+import { runMsgSearch } from "./msg-search.js";
+import { openDm } from "./msg-dm.js";
+import { runMsgMark } from "./msg-mark.js";
+import { runMsgChannel } from "./msg-channel.js";
+import { runMsgFile } from "./msg-file.js";
 import { deleteMessage, editMessage, messageOutcome, messageText, readContent, refuseMsgWrite } from "./msg-write.js";
 const TAG = "[msg cli]";
-const READ_DEADLINE_MS = 30_000;
-const WRITE_DEADLINE_MS = 30_000;
+const [READ_DEADLINE_MS, WRITE_DEADLINE_MS] = [30_000, 30_000];
 export async function runMsg(command, io) {
     const door = await openAgentDoor("msg", command, io);
     switch (command.action) {
-        case "show":
-            return showMessage(command, door);
-        case "channels":
-            return listChannels(door);
+        case "show": return showMessage(command, door);
+        case "channels": return listChannels(door);
         case "read":
             return readChannel(command, door);
         case "unread":
@@ -46,12 +49,35 @@ export async function runMsg(command, io) {
             return messageOutcome(command, door);
         case "draft":
             return draftVerb(command, door);
+        case "file":
+            return fileVerb(command, door);
         case "thread":
             return readThread(command, door);
-        case "create":
-            return createChannel(command, door);
-        case "dm":
-            return openDm(command, door);
+        case "create": return createChannel(command, door);
+        case "dm": return openDm(command, door);
+        case "search":
+            return runMsgSearch(command, door);
+        case "channel":
+        case "members":
+        case "hide":
+        case "unhide":
+            return runMsgChannel(command, door, (ref) => resolveChannelId(door, ref));
+        case "save":
+        case "saved":
+        case "pin":
+        case "pins":
+        case "forward":
+        case "schedule":
+        case "remind":
+        case "scheduled":
+        case "context":
+            return runMsgMark(command, door, (ref) => resolveChannelId(door, ref));
+        case "activity":
+        case "follow":
+        case "unfollow":
+        case "react":
+        case "notify":
+            return runMsgActivityVerb(command, door, (ref) => resolveChannelId(door, ref));
     }
 }
 /** `msg draft`: `list` needs no channel; every other verb resolves the channel the same way read and send do. */
@@ -66,6 +92,18 @@ async function draftVerb(command, door) {
         return channelNotFound(door, ref);
     return runMsgDraft(command, door, resolved.id);
 }
+/** `msg file`: `upload` and `list` name a channel; the other verbs name a file. */
+async function fileVerb(command, door) {
+    if (command.fileVerb !== "upload" && command.fileVerb !== "list")
+        return runMsgFile(command, door, null);
+    const ref = command.channelRef ?? "";
+    const resolved = await resolveChannelId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found")
+        return channelNotFound(door, ref);
+    return runMsgFile(command, door, resolved.id);
+}
 async function fetchChannels(door) {
     const answer = await readThroughCache({
         io: door.io,
@@ -276,10 +314,16 @@ async function sendMessage(command, door) {
         return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
     if (resolved.status === "not_found")
         return channelNotFound(door, ref);
-    const content = await readContent(door.io);
-    if (!content.ok)
-        return failAgentDoor(door, TAG, content.reason, content.detail);
-    if (content.text === "")
+    // BLI-21521: with --file the text is optional; stdin is read only when something is piped in.
+    const fileIds = command.fileIds ?? [];
+    let text = "";
+    if (fileIds.length === 0 || !isInteractiveStdin(door.io)) {
+        const content = await readContent(door.io);
+        if (!content.ok)
+            return failAgentDoor(door, TAG, content.reason, content.detail);
+        text = content.text;
+    }
+    if (text === "" && fileIds.length === 0)
         return failAgentDoor(door, TAG, "invalid_body", "There was nothing to send. Nothing was sent.");
     // BLI-21314: every send carries a request id, so a lost response can be checked and a retry posts once.
     const requestId = command.requestId ?? randomUUID();
@@ -289,7 +333,8 @@ async function sendMessage(command, door) {
         label: "msg send",
         timeoutMs: WRITE_DEADLINE_MS,
         body: {
-            content: content.text,
+            ...(text === "" ? {} : { content: text }),
+            ...(fileIds.length > 0 ? { file_ids: fileIds } : {}),
             request_id: requestId,
             ...(command.threadId ? { thread_parent_id: command.threadId } : {}),
         },
@@ -297,7 +342,7 @@ async function sendMessage(command, door) {
     if (!answer.ok)
         return refuseMsgWrite(door, answer, requestId, "send");
     const { message = null, mutation = null } = answer.body;
-    writeLine(door.io.stderr, `${TAG} sent ${JSON.stringify({ channel_id: resolved.id, message_id: message?.id ?? null, request_id: requestId, chars: content.text.length })}`);
+    writeLine(door.io.stderr, `${TAG} sent ${JSON.stringify({ channel_id: resolved.id, message_id: message?.id ?? null, request_id: requestId, chars: text.length, files: fileIds.length })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, message, mutation });
     writeLine(door.io.stdout, `Sent to ${ref} (${message?.id ?? "?"}).`);
@@ -360,28 +405,6 @@ function reportChannelCreationToHuman(door, channel, name, requestedMembers, mem
         writeLine(door.io.stdout, `Not added (${failure.reason}): ${failure.userId}`);
     }
 }
-async function openDm(command, door) {
-    const email = command.dmEmail ?? "";
-    if (email === "")
-        return failAgentDoor(door, TAG, "invalid_body", "msg dm needs an email address.");
-    const answer = await askAgentDoor(door, {
-        path: "/api/msg/channels",
-        method: "POST",
-        label: "msg dm",
-        timeoutMs: WRITE_DEADLINE_MS,
-        body: { dm_participant_emails: [email] },
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const channel = answer.body.channel ?? null;
-    writeLine(door.io.stderr, `${TAG} dm resolved ${JSON.stringify({ channel_id: channel?.id ?? null })}`);
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, channel });
-    // Idempotent by contract (`get_or_create_dm`), so the wording says what is
-    // true either way rather than claiming a creation that may not have happened.
-    writeLine(door.io.stdout, `Direct message with ${email}: ${channel?.id ?? "?"}`);
-    return 0;
-}
 async function showMessage(command, door) {
     const answer = await askAgentDoor(door, { path: `/api/msg/messages/${encodeURIComponent(command.threadId ?? "")}`, method: "GET", label: "msg show", timeoutMs: READ_DEADLINE_MS });
     if (!answer.ok)

package/dist/commands/project-args.js

@@ -0,0 +1,82 @@
+/**
+ * `cockpit project` argument parsing (BLI-3716 list, BLI-21659 show/create/update/archive/restore).
+ *
+ * A description never travels on argv by default: `--file <path>` reads it from a local file (safest on Windows);
+ * `--description <text>` is the short form and `--description none` clears it. Write-safety flags
+ * (`--request-id`, `--expected-updated-at`) belong to the four write verbs.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ACTIONS = ["list", "show", "create", "update", "archive", "restore"];
+const WRITES = ["create", "update", "archive", "restore"];
+export function parseProjectArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home", "--dashboard-url", "--archived", "--cursor", "--limit", "--json",
+            "--name", "--description", "--file", "--color", "--request-id", "--expected-updated-at",
+        ],
+        valueFlags: [
+            "--home", "--dashboard-url", "--cursor", "--limit",
+            "--name", "--description", "--file", "--color", "--request-id", "--expected-updated-at",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!ACTIONS.includes(action)) {
+        throw new Error(`Unknown project command: ${first}. Try list, show, create, update, archive or restore.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    const needsRef = action !== "list" && action !== "create";
+    if (needsRef && rest.length !== 1)
+        throw new Error(`project ${action} takes exactly one project id or name.`);
+    if (!needsRef && rest.length > 0)
+        throw new Error(`project ${action} does not take "${rest[0]}".`);
+    const given = (flag) => values.flags.has(flag);
+    const isWrite = WRITES.includes(action);
+    if (!isWrite && (given("--request-id") || given("--expected-updated-at"))) {
+        throw new Error("--request-id and --expected-updated-at belong to create, update, archive and restore.");
+    }
+    if (action !== "create" && action !== "update" && (given("--name") || given("--description") || given("--file"))) {
+        throw new Error("--name, --description and --file belong to project create and update.");
+    }
+    if (action !== "create" && given("--color"))
+        throw new Error("--color belongs to project create.");
+    if (action !== "list" && (given("--cursor") || given("--limit") || values.booleans.has("--archived"))) {
+        throw new Error("--archived, --cursor and --limit belong to project list.");
+    }
+    if (given("--description") && given("--file"))
+        throw new Error("Give --description or --file, not both.");
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID_PATTERN.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 name = optionalNonEmpty(values.flags.get("--name"));
+    if (action === "create" && !name)
+        throw new Error('project create needs --name "<name>".');
+    const rawDescription = values.flags.get("--description");
+    const description = rawDescription === undefined ? undefined : rawDescription.trim().toLowerCase() === "none" ? null : rawDescription;
+    const filePath = optionalNonEmpty(values.flags.get("--file"));
+    if (action === "update" && name === undefined && description === undefined && filePath === undefined) {
+        throw new Error("project update needs --name, --description (or none) or --file.");
+    }
+    return {
+        kind: "project",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        includeArchived: values.booleans.has("--archived"),
+        ...(optionalNonEmpty(values.flags.get("--cursor")) ? { cursor: optionalNonEmpty(values.flags.get("--cursor")) } : {}),
+        ...(values.flags.has("--limit") ? { limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit") } : {}),
+        ...(needsRef ? { ref: rest[0] } : {}),
+        ...(name === undefined ? {} : { name }),
+        ...(description === undefined ? {} : { description }),
+        ...(filePath === undefined ? {} : { filePath }),
+        ...(optionalNonEmpty(values.flags.get("--color")) ? { color: optionalNonEmpty(values.flags.get("--color")) } : {}),
+        ...(requestId ? { requestId } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/project.js

@@ -1,20 +1,21 @@
 /**
- * `cockpit project list` — the projects issues are filed under (BLI-3716).
+ * `cockpit project list|show|create|update|archive|restore` — the projects issues are filed under
+ * (BLI-3716 list; BLI-21659 the rest).
  *
- * One verb, because `GET /api/work/projects` is the whole of the Work
- * surface's project door today (BLI-3703 scoped projects to list-only; there
- * is no create/update/delete route to put a terminal in front of). Its own
- * command rather than `cockpit issue projects` because a person says
- * "projects", and `cockpit issue list --project <name>` resolves a name
- * against exactly this list.
+ * Its own command rather than `cockpit issue projects` because a person says "projects", and
+ * `cockpit issue list --project <name>` resolves a name against exactly this list. Writes go through
+ * `/api/work/projects` (receipt, `tower_only` delivery: nothing reaches Linear); no verb deletes a project.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 import { pageFieldsOf, pageFooter } from "./issue-list-page.js";
+import { readBody } from "./issue-contracts.js";
 const TAG = "[project cli]";
 const READ_DEADLINE_MS = 30_000;
 export async function runProject(command, io) {
     const door = await openAgentDoor("project", command, io);
+    if (command.action !== "list")
+        return await runProjectVerb(command, door);
     const params = new URLSearchParams();
     if (command.includeArchived)
         params.set("include_archived", "true");
@@ -47,4 +48,67 @@ export async function runProject(command, io) {
     if (footer)
         writeLine(door.io.stdout, footer);
     return 0;
+}
+async function runProjectVerb(command, door) {
+    const base = "/api/work/projects";
+    const ref = command.ref ? `${base}/${encodeURIComponent(command.ref)}` : base;
+    if (command.action === "show") {
+        const answer = await askAgentDoor(door, { path: ref, method: "GET", label: "project 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, ...body, ...pageFieldsOf(body) });
+        const project = body.project;
+        const out = door.io.stdout;
+        writeLine(out, `${project?.name ?? command.ref}  (${project?.archived_at ? "archived" : "active"}, ${project?.source ?? "native"})`);
+        writeLine(out, `id ${project?.id ?? ""}  updated ${project?.updated_at ?? ""}`);
+        if (project?.description)
+            writeLine(out, project.description);
+        for (const issue of body.issues ?? [])
+            writeLine(out, `${issue.identifier ?? ""}  ${issue.state ?? ""}  ${issue.title ?? ""}`);
+        const footer = pageFooter(body, "tickets");
+        if (footer)
+            writeLine(out, footer);
+        if (body.href)
+            writeLine(out, `Filtered list: ${body.href}`);
+        return 0;
+    }
+    const payload = {
+        ...(command.requestId ? { request_id: command.requestId } : {}),
+        ...(command.expectedUpdatedAt ? { expected_updated_at: command.expectedUpdatedAt } : {}),
+    };
+    if (command.action === "create" || command.action === "update") {
+        if (command.name !== undefined)
+            payload["name"] = command.name;
+        if (command.color !== undefined)
+            payload["color"] = command.color;
+        if (command.filePath) {
+            const read = await readBody({ filePath: command.filePath }, door.io);
+            if (!read.ok)
+                return failAgentDoor(door, TAG, read.reason, read.detail);
+            payload["description"] = read.text;
+        }
+        else if (command.description !== undefined) {
+            payload["description"] = command.description;
+        }
+    }
+    const path = command.action === "create" ? base : command.action === "update" ? ref : `${ref}/${command.action}`;
+    const answer = await askAgentDoor(door, {
+        path,
+        method: command.action === "update" ? "PATCH" : "POST",
+        label: `project ${command.action}`,
+        timeoutMs: READ_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} ${command.action} committed`, JSON.stringify({ project_id: body.project?.id, delivery: body.mutation?.delivery?.status }));
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, project: body.project, mutation: body.mutation });
+    writeLine(door.io.stdout, `${command.action} committed: ${body.project?.name ?? ""} (${body.project?.id ?? ""}), delivery ${body.mutation?.delivery?.status ?? "tower_only"}.`);
+    return 0;
 }

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.242");
+    writeLine(io?.stdout ?? process.stdout, "0.2.243");
     return 0;
   }
 

package/dist/commands/search.js

@@ -26,6 +26,8 @@
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
+import { appendDocSearchParams } from "./docs-search-args.js";
+import { appendMsgSearchParams } from "./msg-search-args.js";
 const TAG = "[search cli]";
 const READ_DEADLINE_MS = 30_000;
 /** Group headings, in the order a person reads them. Mirrors the overlay. */
@@ -56,6 +58,12 @@ export async function runSearch(command, io) {
         params.set("kinds", command.kinds.join(","));
     if (command.limit !== undefined)
         params.set("limit", String(command.limit));
+    // BLI-21658: message filters ride the same door, which answers them only for kinds=msg.
+    if (command.msgFilters)
+        appendMsgSearchParams(params, command.msgFilters);
+    // BLI-21697: document filters ride the same door, which answers them only for kinds=doc.
+    if (command.docFilters)
+        appendDocSearchParams(params, command.docFilters);
     const answer = await askAgentDoor(door, {
         path: `/api/search?${params.toString()}`,
         method: "GET",
@@ -139,6 +147,21 @@ function render(door, body) {
             writeLine(door.io.stdout, `${KIND_LABELS[kind] ?? kind.toUpperCase()} did not answer (${reason}). Nothing from there is in this list.`);
         }
     }
+    // Named, so a filtered list is not read as the ranked, semantic one (BLI-21658).
+    if (body.degraded?.msg === "filtered_lexical_only") {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "MESSAGES were filtered: keyword matching only (filtered_lexical_only), newest first, not ranked.");
+        if (body.msgPaging?.hasMore && body.msgPaging.nextCursor) {
+            writeLine(door.io.stdout, `More messages exist: \`cockpit msg search ... --before ${body.msgPaging.nextCursor}\` continues with the same filters.`);
+        }
+    }
+    if (body.degraded?.doc === "filtered_lexical_only") {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "DOCUMENTS were filtered: keyword matching only (filtered_lexical_only), not ranked by meaning.");
+        if (body.docCoverage && body.docCoverage.coverage !== "exhausted") {
+            writeLine(door.io.stdout, `Documents coverage: ${body.docCoverage.coverage}${body.docCoverage.reason ? ` (${body.docCoverage.reason})` : ""}; ${body.docCoverage.matched} matched.`);
+        }
+    }
     writeLine(door.io.stdout, "");
     writeLine(door.io.stdout, `${hits.length} result(s) in ${body.elapsedMs ?? 0} ms.`);
     return 0;

package/dist/commands/session-sync-failures.js

@@ -13,7 +13,7 @@
  * without saying why.
  */
 import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
-import { isDeliveryHoldReason } from "./session-sync-hold.js";
+import { budgetStarved, isDeliveryHoldReason } from "./session-sync-hold.js";
 import { sourceScanFailureReason } from "./session-sync-scan.js";
 /**
  * The label used when a sync fails and nothing on the way there said why.
@@ -55,8 +55,15 @@ export function createSyncFailureLedger() {
  * hold in `session-sync-hold.ts` and rides the same receipt — and a tick that
  * ALSO failed for a real reason still fails on that reason. Nothing is
  * silenced; only the verdict changed.
+ *
+ * Ticket 21952 does the same for the per-tick size budget. Overflow defers to the next tick by design, so a tick that
+ * sent something and held the rest reports a named hold (`held_budget:` in `session-sync-hold.ts`) instead of failing:
+ * one machine was RED on every tick from 2026-10-15 while it uploaded 2 GiB each time. Only a STARVED tick, one that
+ * deferred evidence and let nothing through, still fails `deferred_byte_budget` / `deferred_object_budget`. Without
+ * `budgetUse` (an older caller) the old rule stands: any deferral fails.
  */
-export function recordWorktreeDeliveryFailures(ledger, outcomes) {
+export function recordWorktreeDeliveryFailures(ledger, outcomes, budgetUse) {
+    const budgetHolds = budgetUse !== undefined && !budgetStarved(budgetUse);
     for (const outcome of outcomes) {
         recordWorktreeSyncFailure(ledger, outcome);
         const { sync } = outcome;
@@ -71,15 +78,21 @@ export function recordWorktreeDeliveryFailures(ledger, outcomes) {
         for (const reason of sync.raw_evidence_retry_reasons ?? []) {
             if (isDeliveryHoldReason(reason))
                 continue;
+            if (budgetHolds && isBudgetDeferralReason(reason))
+                continue;
             ledger.add({
                 label: "raw_evidence_retry_required",
                 rendered: `raw_evidence_retry:${reason}`,
             });
         }
-        ledger.fail(sync.raw_evidence_deferred_byte_budget > 0, "deferred_byte_budget");
-        ledger.fail(sync.raw_evidence_deferred_object_budget > 0, "deferred_object_budget");
+        ledger.fail(!budgetHolds && sync.raw_evidence_deferred_byte_budget > 0, "deferred_byte_budget");
+        ledger.fail(!budgetHolds && sync.raw_evidence_deferred_object_budget > 0, "deferred_object_budget");
     }
 }
+/** The two reasons the per-tick budget writes when it defers a file. Exact labels, never a pattern. */
+function isBudgetDeferralReason(reason) {
+    return reason === "deferred_byte_budget" || reason === "deferred_object_budget";
+}
 function recordWorktreeSyncFailure(ledger, { worktree, sync }) {
     if (sync.status === "uploaded")
         return;

package/dist/commands/session-sync-health.js

@@ -13,7 +13,7 @@ import { collectionRootLabel } from "./heartbeat.js";
 import { workDirectories } from "../root-work.js";
 import { createSyncFailureLedger, recordSourceScanFailures, recordUnexplainedFailure, recordUnpostedSessionReportFailure, recordWorktreeDeliveryFailures, } from "./session-sync-failures.js";
 import { countSessionsNewThisTick, countSessionsPendingUpload, } from "./session-sync-counters.js";
-import { logDeliveryHold, summarizeDeliveryHold } from "./session-sync-hold.js";
+import { logBudgetHold, logDeliveryHold, summarizeBudgetHold, summarizeDeliveryHold } from "./session-sync-hold.js";
 /**
  * Decide whether this tick failed, and record every condition that decided it.
  *
@@ -23,7 +23,7 @@ import { logDeliveryHold, summarizeDeliveryHold } from "./session-sync-hold.js";
 export function decideSyncHealth(options) {
     const { outcomes } = options.worktreePass;
     const ledger = createSyncFailureLedger();
-    recordWorktreeDeliveryFailures(ledger, outcomes);
+    recordWorktreeDeliveryFailures(ledger, outcomes, options.worktreePass.budgetUse);
     recordSourceScanFailures(ledger, options.scan);
     const sessionsOutsideRoot = options.sessions.filter((session) => OUTSIDE_APPROVED_ROOT_REASONS.has(session.attribution_reason)).length;
     const nothingInRoot = nothingInRootCount({
@@ -54,6 +54,10 @@ export function decideSyncHealth(options) {
     const hold = summarizeDeliveryHold(outcomes);
     if (hold && ok)
         logDeliveryHold(hold);
+    // Ticket 21952: the size-budget hold, said on every tick that has one, ok or not.
+    const budgetHold = summarizeBudgetHold(options.worktreePass.budgetUse);
+    if (budgetHold)
+        logBudgetHold(budgetHold);
     const records = ledger.sortedRecords();
     return {
         ok,
@@ -61,6 +65,7 @@ export function decideSyncHealth(options) {
         failure_records: records,
         notice,
         hold,
+        budgetHold,
         sessions_outside_root: sessionsOutsideRoot,
         outside_root_directories: workDirectories([...(options.scan.codexAttribution.results ?? []), ...(options.scan.claudeAttribution.results ?? [])].filter(result => OUTSIDE_APPROVED_ROOT_REASONS.has(result.reason)))
             .map(entry => ({ ...collectionRootLabel(entry.directory), count: entry.count }))

package/dist/commands/session-sync-hold.js

@@ -11,7 +11,7 @@
  * reads every `session-sync*.ts` sibling and demands that only the failure
  * ledger writes one, and this file is not it.
  */
-import { formatDeliveryHoldNotice, } from "../delivery-hold-notice.js";
+import { formatBudgetHoldNotice, formatDeliveryHoldNotice, } from "../delivery-hold-notice.js";
 import { DELIVERY_BACKOFF_HOLDING_REASON } from "../raw-evidence-staging.js";
 /**
  * Is this reason a delivery hold rather than a delivery failure?
@@ -87,4 +87,45 @@ export function logDeliveryHold(hold) {
         last_reason: hold.lastReason,
         next_action: "nothing until the next attempt is due; run `cockpit doctor` if it is already past",
     }));
+}
+/** The token's leading word, owned with its grammar by `delivery-hold-notice.ts` so the fleet board parses what this writes. */
+export { BUDGET_HOLD_NOTICE_PREFIX } from "../delivery-hold-notice.js";
+/** Reads the shared budget's counters, or null when the pass carried none. */
+export function budgetUseOf(budget) {
+    if (!budget)
+        return undefined;
+    return {
+        admittedBytes: budget.admittedBytes ?? 0,
+        admittedObjects: budget.admittedObjects ?? 0,
+        deferredBytes: budget.deferredBytes ?? 0,
+        deferredObjects: budget.deferredObjects ?? 0,
+    };
+}
+/**
+ * Did the budget hold anything back while still letting something through?
+ *
+ * The collector's design is that overflow defers and converges: the next tick starts with a fresh budget and picks up
+ * what this one held. A tick that admitted at least one object made progress, so what it deferred is a hold. A tick
+ * that deferred and admitted NOTHING made no progress at all, which stays a failure (`budgetStarved`).
+ */
+export function summarizeBudgetHold(use) {
+    if (!use || use.deferredObjects <= 0 || budgetStarved(use))
+        return null;
+    const notice = formatBudgetHoldNotice(use);
+    return notice ? { ...use, notice } : null;
+}
+/** True when the budget deferred evidence and let nothing through this tick. */
+export function budgetStarved(use) {
+    return Boolean(use && use.deferredObjects > 0 && use.admittedObjects === 0);
+}
+/** The run's line for a size-budget hold: bytes sent, bytes held, and that the next tick takes the rest. */
+export function logBudgetHold(hold) {
+    console.error("[session-sync] raw evidence held back by the per-tick size budget, the next tick takes the rest", JSON.stringify({
+        reason: hold.notice,
+        sent_bytes: hold.admittedBytes,
+        sent_objects: hold.admittedObjects,
+        held_bytes: hold.deferredBytes,
+        held_objects: hold.deferredObjects,
+        next_action: "none; the next tick starts with a fresh budget",
+    }));
 }

package/dist/commands/session-sync-upload.js

@@ -13,6 +13,7 @@ import { liveSyncTargetKey, liveSyncTargetWorktrees, matchesLiveSyncWorktree, }
 import { isOutsideRootsWorkspace } from "./backfill-outside-roots.js";
 import { giveOutsideRootsTheirOwnAllowance, outsideRootsLast, } from "./session-sync-outside-roots.js";
 import { runYieldingAtBoundaries } from "./sync-yield.js";
+import { budgetUseOf } from "./session-sync-hold.js";
 const CLAUDE_DAMP_GROWTH_BYTES = 256 * 1024;
 const CLAUDE_DAMP_MAX_AGE_MS = 6 * 60 * 60 * 1000;
 /**
@@ -54,6 +55,7 @@ export async function syncEveryTargetWorktree(options) {
         claudePriorDurablePointers: claudeDurablePointersFromCursor(options.plan.claudeCursorBefore),
         growthDampedSessionCount: dampedClaudePointers.size,
         yieldedWorktreesLeft: loop.left,
+        budgetUse: budgetUseOf(rawEvidenceBudget),
     };
 }
 function syncTargetWithAllowance(options, worktree, syncWorktrees, rawEvidenceBudget, discoveredWorktreeKeys, dampedClaudePointers) {

package/dist/commands/session-sync.js

@@ -190,6 +190,7 @@ async function finishAttributedSync(options, context) {
         failure_records: health.failure_records,
         notice: health.notice,
         hold: health.hold,
+        budgetHold: health.budgetHold ?? null,
         yielded_worktrees_left: worktreePass.yieldedWorktreesLeft,
         sessions_observed: sessions.length,
         sessions_outside_root: health.sessions_outside_root,

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,