@bli-cockpit/cli 0.2.98 → 0.2.100

package/dist/commands/doctor-pipeline.js

@@ -1,9 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectBackfillLock } from "../backfill-lock.js";
-import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
-import { describeError } from "../health-detail.js";
 import { runStagingPrune } from "../disk-prune.js";
 import { retentionOptionsFromEnv } from "../disk-retention.js";
 import { readDiskFootprint } from "../disk-usage.js";
@@ -13,7 +12,8 @@ import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.
 import { runBackfillCommand } from "./backfill.js";
 import { diskRowMessage, mib, redeliveryLine } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
-import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, parseDoctorSyncJson, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";
+import { fail, needsFix, ok, skipped } from "./doctor-report.js";
 /**
  * The `backfill-complete`, `gc-checked`, `disk-bounded`, and `sync-fresh`
  * check family: does the collection pipeline itself have everything it
@@ -22,31 +22,15 @@ import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
  * is committed, disk-bounded reads per-file against the upload ledger
  * (BLI-3619), and sync-fresh is the one check whose "fix" is a live proof
  * (`cockpit sync`) rather than a local computation.
- */
-const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
-/**
- * Pure so it can be unit-tested without touching the real machine's home
- * directory (`getCollectorRuntimePaths()` defaults to `os.homedir()` and
- * doctor never threads `--home` through the backfill steps). Returns `null`
- * when the marker does not cover the roots/sources — the caller falls
- * through to the lock/never-run diagnosis in that case.
  *
- * BLI-2727: a marker whose only outstanding entries are deterministic
- * oversized-file skips is still a completed backfill — it reads green with a
- * named note, never a red `needs_fix`/`fail`, so an unliftable file cap never
- * reads as "backfill never completed" on repeat doctor runs.
+ * This module is the half that TOUCHES the machine: it runs the catch-up,
+ * prunes the disk, execs a sync. The verdicts those steps reach — what a
+ * completion marker proves, what a stand-aside receipt means, when an
+ * unfinished backfill is busy rather than broken — are pure functions in
+ * `doctor-pipeline-verdicts.ts`, and every one of them is re-exported from
+ * here so callers keep one address.
  */
-export function backfillCompletionStepState(marker, roots) {
-    if (!backfillCompletionCovers(marker, roots, ["codex", "claude_code"])) {
-        return null;
-    }
-    const oversized = marker?.oversized_skips;
-    if (oversized && oversized.count > 0) {
-        return ok("backfill-complete", "complete_with_oversized_skips", `caught up on old Codex and Claude sessions in every saved folder ` +
-            `(complete_with_oversized_skips · ${oversized.count} file${oversized.count === 1 ? "" : "s"} too big to upload)`);
-    }
-    return ok("backfill-complete", "complete", "caught up on old Codex and Claude sessions in every saved folder");
-}
+const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export async function checkBackfillState(context) {
     const paths = getCollectorRuntimePaths();
     const roots = await doctorRoots(context);
@@ -70,7 +54,8 @@ export async function fixBackfillState(context) {
         yes: true,
         json: true,
     }, capture.io);
-    const output = capture.stdout() + "\n" + capture.stderr();
+    const stdout = capture.stdout();
+    const output = `${stdout}\n${capture.stderr()}`;
     if (code === 0) {
         // Re-read the marker this run just wrote instead of hand-rolling a second
         // message: `checkBackfillState`'s pure core already knows how to say
@@ -81,11 +66,9 @@ export async function fixBackfillState(context) {
             return recheck;
         return ok("backfill-complete", "completed", "ran `cockpit backfill --all --yes`");
     }
-    const reason = jsonField(output, "failure_reason");
-    if (reason === "backfill_already_running") {
-        return fail("backfill-complete", "backfill_already_running", "backfill lock is still held and no scope-valid completion marker exists");
-    }
-    return fail("backfill-complete", reason ?? "backfill_failed", "backfill did not complete");
+    const verdict = backfillFixVerdict(parseDoctorBackfillJson(stdout), jsonField(output, "failure_reason"));
+    console.error("[cockpit-doctor] catch-up run did not finish", JSON.stringify({ reason: verdict.code, row_status: verdict.status, exit_code: code }));
+    return verdict;
 }
 export async function checkGcState(context) {
     if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
@@ -196,11 +179,6 @@ function captureStream(target, chunks, forward) {
         },
     };
 }
-function jsonField(output, field) {
-    const escaped = field.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-    const match = output.match(new RegExp(`"${escaped}"\\s*:\\s*"([^"]+)"`, "u"));
-    return match?.[1] ?? null;
-}
 export async function checkSyncState(context) {
     const roots = await doctorRoots(context);
     if (roots.length === 0) {
@@ -211,75 +189,6 @@ export async function checkSyncState(context) {
     // and only turns green from those command receipts.
     return needsFix("sync-fresh", "per_root_verification_required", `fresh upload proof is required for ${roots.length} saved root${roots.length === 1 ? "" : "s"}`);
 }
-/**
- * `cockpit sync --json` prints exactly one JSON document to stdout (stderr is
- * for human text; see AGENTS.md logging conventions), so this is a real parse
- * rather than the doctor module's usual regex field-scrape — which cannot
- * disambiguate same-named fields nested under `codex_sessions.codex` vs
- * `codex_sessions.claude` (BLI-2728).
- */
-function parseDoctorSyncJson(stdout) {
-    try {
-        const parsed = JSON.parse(stdout.trim());
-        return parsed && typeof parsed === "object" ? parsed : null;
-    }
-    catch (error) {
-        // `null` sends doctor back to its regex field-scrape, quietly losing the
-        // BLI-2728 disambiguation. Something wrote to stdout that was not the one
-        // JSON document the contract promises — a stray console.log in the
-        // collector would do exactly this and look like nothing at all.
-        console.error("[cockpit-doctor] sync --json stdout was not one JSON document", JSON.stringify({
-            reason: "sync_json_unparseable",
-            byte_size: stdout.length,
-            ...describeError(error),
-        }));
-        return null;
-    }
-}
-/**
- * BLI-2728: a tick that only deferred objects past the per-tick raw-evidence
- * object budget (`RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET`, adapters/raw-evidence.ts)
- * is a backlog that is draining, not a failure — `attributedSyncRunStatus`
- * marks the run not-fully-`ok` (so `cockpit sync` exits non-zero and doctor's
- * exec sees `code !== 0`) purely because objects remain queued, with the
- * per-repo upload itself still having succeeded. A genuine failure (auth,
- * server rejection, network, a real upload_failed outcome, an unposted
- * session report) must still read red — this only fires when NOTHING else in
- * the tick's own summary looks wrong. Pure so it is unit-testable without a
- * live exec/fs harness; the remaining-object count is read straight from the
- * tick's own summary, never recomputed.
- */
-export function syncBacklogDrainingVerdict(parsed) {
-    if (!parsed)
-        return null;
-    const deferredObjects = positiveNumberOrZero(parsed.raw_evidence_deferred_object_budget);
-    if (deferredObjects <= 0)
-        return null;
-    const deferredBytes = positiveNumberOrZero(parsed.raw_evidence_deferred_byte_budget);
-    const failedCount = positiveNumberOrZero(parsed.raw_evidence_failed_count);
-    const retryReasons = Array.isArray(parsed.raw_evidence_retry_reasons)
-        ? parsed.raw_evidence_retry_reasons.length
-        : 0;
-    const sessions = asRecord(parsed.codex_sessions);
-    const reportPosted = sessions?.["report_posted"];
-    const codexReadFailures = positiveNumberOrZero(asRecord(sessions?.["codex"])?.["read_failures"]);
-    const claudeSessions = asRecord(sessions?.["claude"]);
-    const claudeReadFailures = positiveNumberOrZero(claudeSessions?.["read_failures"]);
-    const claudeSidecarsFailed = positiveNumberOrZero(claudeSessions?.["sidecars_failed"]);
-    const onlyDeferredObjectBudget = deferredBytes === 0 &&
-        failedCount === 0 &&
-        retryReasons === 0 &&
-        reportPosted === true &&
-        codexReadFailures === 0 &&
-        claudeReadFailures === 0 &&
-        claudeSidecarsFailed === 0;
-    return onlyDeferredObjectBudget ? { remainingObjects: deferredObjects } : null;
-}
-function positiveNumberOrZero(value) {
-    return typeof value === "number" && Number.isFinite(value) && value > 0
-        ? value
-        : 0;
-}
 export async function fixSyncState(context) {
     const exec = context.io.exec;
     if (!exec)
@@ -301,6 +210,23 @@ export async function fixSyncState(context) {
         const parsed = parseDoctorSyncJson(result.stdout);
         const output = `${result.stdout}\n${result.stderr}`;
         const status = jsonField(output, "status");
+        // BLI-4303, before any verdict: a sync that stood aside for the collection
+        // lock never ran, so neither its exit code nor its missing `uploaded`
+        // receipt says anything about this machine's health.
+        const standAside = syncStandAsideVerdict(parsed, status);
+        if (standAside) {
+            console.error("[cockpit-doctor] sync stood aside for a running collection run", JSON.stringify({
+                reason: standAside.code,
+                owner_alive: standAside.ownerAlive,
+                held_since: standAside.heldSince,
+            }));
+            return standAside.ownerAlive
+                ? ok("sync-fresh", standAside.code, "a background sync is running right now and owns the collection lock " +
+                    `(last heartbeat ${standAside.heldSince}); this machine is collecting`)
+                : needsFix("sync-fresh", standAside.code, "sync stood aside for a collection lock whose owner has stopped " +
+                    `reporting (last heartbeat ${standAside.heldSince ?? "unknown"}); ` +
+                    "rerun `cockpit doctor` — the next sync takes the lock over");
+        }
         if (result.code !== 0) {
             const draining = syncBacklogDrainingVerdict(parsed);
             if (draining) {
@@ -317,4 +243,8 @@ export async function fixSyncState(context) {
     return ok("sync-fresh", "synced", roots.length === 1
         ? "ran `cockpit sync` and received an uploaded receipt"
         : `received uploaded receipts for ${roots.length} saved roots`);
-}
+}
+// Re-exported so `doctor.ts`, the doctor tests and every other caller keep
+// importing these from `./doctor-pipeline.js` regardless of which sibling
+// computes them.
+export { backfillCompletionStepState, backfillFixVerdict, isCollectionBusyReason, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
+import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
-import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
+import { backfillCompletionStepState, backfillFixVerdict, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline.js";
 import { checkMcpAnswersState } from "./doctor-mcp.js";
 import { checkMemoryDaemonState } from "./doctor-memory-daemon.js";
 import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
@@ -14,7 +15,7 @@ export async function runDoctorWithDeps(command, io, deps) {
     const context = { command, io, deps };
     const rows = [];
     for (const invariant of doctorInvariants()) {
-        const checked = await invariant.check(context);
+        const checked = await withStage(`doctor:check:${invariant.id}`, () => invariant.check(context));
         if (checked.status === "ok" || checked.status === "skipped") {
             rows.push(checked);
             continue;
@@ -31,7 +32,10 @@ export async function runDoctorWithDeps(command, io, deps) {
                 break;
             continue;
         }
-        const fixed = await invariant.fix(context, checked);
+        // BLI-4110: named so a crash inside a repair says WHICH repair. The
+        // 2026-09-09 incident printed a bare `read ENOTCONN` stack and the only
+        // way to place it was the log line that happened to precede it.
+        const fixed = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, checked));
         rows.push({ ...fixed, fixed: fixed.status !== "fail" });
         if (fixed.hardStop)
             break;
@@ -174,4 +178,4 @@ function defaultDoctorDeps(hooks) {
 }
 // Re-exported so every consumer keeps importing from `./doctor.js` regardless
 // of which sibling a symbol now lives in.
-export { backfillCompletionStepState, syncBacklogDrainingVerdict };
+export { backfillCompletionStepState, backfillFixVerdict, syncBacklogDrainingVerdict, syncStandAsideVerdict, };

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

@@ -14,9 +14,17 @@ import { isTeamDeviceRevokeReasonLabel, TEAM_DEVICE_REVOKE_REASON_LABELS, } from
 /** The shortest prefix `cockpit scout start` will resolve. Below this, ids collide. */
 export const SCOUT_MIN_PREFIX_LENGTH = 6;
 /**
- * `cockpit scout [--days <n>]` reads the board; `cockpit scout start|dismiss|undo
- * <id>` moves one card. Positional shape modelled on `autostart`: an optional
- * action word first, then what it acts on.
+ * `cockpit scout [board] [--days <n>]` reads the board; `cockpit scout
+ * start|dismiss|undo <id>` moves one card. Positional shape modelled on
+ * `autostart`: an optional action word first, then what it acts on.
+ *
+ * `board` is spellable as well as implied (BLI-4048). The parsed command has
+ * always carried `action: "board"`, the MCP twin has always been `scout_board`,
+ * and three documents printed `cockpit scout board` under a "CLI verb" heading
+ * while the parser answered "scout action must be start, dismiss, or undo" —
+ * the promise was older than the refusal. Every sibling noun (`ops status`,
+ * `slack coverage`, `notes list`) lets a person name the read it defaults to,
+ * so scout does too, and the word costs one branch.
  */
 export function parseScoutArgs(args) {
     const values = parseNamedArgs(args, {
@@ -24,7 +32,7 @@ export function parseScoutArgs(args) {
         valueFlags: ["--home", "--dashboard-url", "--days"],
     });
     if (values.positionals.length > 2) {
-        throw new Error("scout accepts at most an action (start|dismiss|undo) and one experiment id.");
+        throw new Error("scout accepts at most an action (board|start|dismiss|undo) and one experiment id.");
     }
     const [rawAction, rawRef] = values.positionals;
     const base = {
@@ -33,10 +41,13 @@ export function parseScoutArgs(args) {
         days: optionalPositiveInteger(values.flags.get("--days"), "--days"),
         json: values.booleans.has("--json"),
     };
-    if (!rawAction)
+    if (!rawAction || rawAction === "board") {
+        if (rawRef)
+            throw new Error("scout board reads the whole board; it takes no experiment id.");
         return { kind: "scout", action: "board", ...base };
+    }
     if (rawAction !== "start" && rawAction !== "dismiss" && rawAction !== "undo") {
-        throw new Error("scout action must be start, dismiss, or undo.");
+        throw new Error("scout action must be board, start, dismiss, or undo.");
     }
     const experimentRef = optionalNonEmpty(rawRef);
     if (!experimentRef) {

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

@@ -0,0 +1,20 @@
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from './local-arg-values.js';
+export function parseCareersArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ['--role', '--min-score', '--since', '--home', '--dashboard-url', '--json'], valueFlags: ['--role', '--min-score', '--since', '--home', '--dashboard-url'] });
+    const action = values.positionals[0] ?? 'list';
+    if (action !== 'list' && action !== 'show' && action !== 'rescreen')
+        throw new Error('careers takes list, show, or rescreen.');
+    const id = values.positionals[1];
+    if (action !== 'list' && !id)
+        throw new Error(`careers ${action} needs an application id.`);
+    if (values.positionals.length > (action === 'list' ? 1 : 2))
+        throw new Error('Unexpected careers argument.');
+    const rawScore = values.flags.get('--min-score');
+    const minScore = rawScore === undefined ? undefined : Number(rawScore);
+    if (minScore !== undefined && (!Number.isFinite(minScore) || minScore < 0 || minScore > 100))
+        throw new Error('--min-score must be 0 to 100.');
+    const since = optionalNonEmpty(values.flags.get('--since'));
+    if (since && !Number.isFinite(Date.parse(since)))
+        throw new Error('--since must be a date.');
+    return { kind: 'careers', action, id, role: optionalNonEmpty(values.flags.get('--role')), minScore, since: since ? new Date(since).toISOString() : undefined, homeDir: optionalNonEmpty(values.flags.get('--home')), dashboardUrl: optionalUrl(values.flags.get('--dashboard-url')), json: values.booleans.has('--json') };
+}

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

@@ -153,6 +153,7 @@ export function parseBriefArgs(args) {
     };
 }
 const NOTES_ACTIONS = new Set([
+    "folders", "mkdir", "rmdir", "rename",
     "list",
     "show",
     "shelf",
@@ -162,6 +163,7 @@ const NOTES_ACTIONS = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 /** Actions whose first positional is the note it acts on. */
 const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
@@ -169,17 +171,21 @@ const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 export function parseNotesArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
+            "--wait",
             "--home",
             "--dashboard-url",
             "--file",
             "--name",
             "--exclude",
             "--to",
+            "--folder",
             "--clear-shelf",
+            "--apply",
             "--series",
             "--kind",
             "--since",
@@ -187,6 +193,7 @@ export function parseNotesArgs(args) {
             "--limit",
             "--yes",
             "--json",
+            "--tree",
         ],
         valueFlags: [
             "--home",
@@ -195,6 +202,7 @@ export function parseNotesArgs(args) {
             "--name",
             "--exclude",
             "--to",
+            "--folder",
             "--series",
             "--kind",
             "--since",
@@ -207,7 +215,7 @@ export function parseNotesArgs(args) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!NOTES_ACTIONS.has(action)) {
-        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, or move.`);
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, move, or place.`);
     }
     const rest = values.positionals.slice(first === undefined ? 0 : 1);
     const json = values.booleans.has("--json");
@@ -233,23 +241,33 @@ export function parseNotesArgs(args) {
         if (paths.length === 0)
             throw new Error("notes upload needs at least one file path.");
     }
+    else if (action === "mkdir" || action === "rmdir" || action === "rename") {
+        if (rest.length !== 1 || !rest[0]?.trim())
+            throw new Error(`notes ${action} needs one folder path.`);
+    }
     else if (action !== "paste" && !NOTES_ACTIONS_NEEDING_A_NOTE.has(action) && rest.length > 0) {
         throw new Error(`notes ${action} does not take "${rest[0]}".`);
     }
+    if (action === "rename" && !optionalNonEmpty(values.flags.get("--name")))
+        throw new Error("notes rename needs --name <name>.");
     const to = optionalNonEmpty(values.flags.get("--to"));
     const clearShelf = values.booleans.has("--clear-shelf");
     if (action === "move") {
         if (to && clearShelf) {
             throw new Error("notes move accepts either --to or --clear-shelf, not both.");
         }
-        if (!to && !clearShelf) {
-            throw new Error('notes move needs --to "<shelf>" or --clear-shelf.');
+        if (!to && !clearShelf && !values.flags.get("--folder")) {
+            throw new Error('notes move needs --to "<shelf>", --clear-shelf, or --folder "<path>".');
         }
     }
     const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
     return {
         kind: "notes",
+        ...(values.booleans.has("--wait") ? { wait: true } : {}),
         action,
+        ...(values.flags.has("--folder") ? { folder: values.flags.get("--folder") } : {}),
+        ...(action === "mkdir" || action === "rmdir" || action === "rename" ? { folder: rest[0] } : {}),
+        ...(values.booleans.has("--tree") ? { tree: true } : {}),
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         ...(noteId ? { noteId } : {}),
@@ -259,6 +277,8 @@ export function parseNotesArgs(args) {
         exclude: optionalNonEmpty(values.flags.get("--exclude")),
         ...(to ? { to } : {}),
         ...(clearShelf ? { clearShelf } : {}),
+        // BLI-4058. `place` says where a note belongs; only `--apply` moves it.
+        ...(values.booleans.has("--apply") ? { apply: true } : {}),
         series: optionalNonEmpty(values.flags.get("--series")),
         meetingKind: optionalNonEmpty(values.flags.get("--kind")),
         since: optionalNonEmpty(values.flags.get("--since")),

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

@@ -0,0 +1,8 @@
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export function parseUsageArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ["--since", "--until", "--include-automated", "--home", "--dashboard-url", "--json"], valueFlags: ["--since", "--until", "--home", "--dashboard-url"] });
+    const action = values.positionals[0] ?? "people";
+    if (action !== "people" || values.positionals.length > 1)
+        throw new Error("usage takes one verb: people.");
+    return { kind: "usage", action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
+}

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

@@ -35,4 +35,6 @@ export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-to
 export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
 export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
-export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseUsageArgs } from "./local-args-tower-usage.js";
+export { parseCareersArgs } from './local-args-tower-careers.js';

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseCareersArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -115,6 +115,10 @@ export function parseLocalArgs(argv) {
             return parseSearchArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
+        case "careers":
+            return parseCareersArgs(argv.slice(1));
+        case "usage":
+            return parseUsageArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

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

@@ -11,8 +11,18 @@
  * Every string moved verbatim. Help output is what an intern pastes back when
  * something breaks, so it is a user-visible contract like any other.
  */
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
+/**
+ * The corpora `cockpit search` can name, spelled the way `--kind` takes them.
+ * Read off `SEARCH_KINDS` rather than typed out: the help string said five for
+ * the two months `mail` and `cal` were searchable, so a person was told the
+ * door was narrower than it is (BLI-4048).
+ */
+const SEARCH_KIND_LIST = SEARCH_KINDS.join(",");
+const SEARCH_CORPORA_COUNT = SEARCH_KINDS.length;
 /** One entry per Tower noun, in the order `cockpit --help` lists them. */
 export const TOWER_COMMAND_HELP = [
+    ["careers", ["Usage: cockpit careers [list|show <id>|rescreen <id>] [--role <slug>] [--min-score <n>] [--since <date>] [--json]", "Super-admin application review. Lists at most 100 matches with total and has_more; use filters to narrow."]],
     [
         "docs",
         [
@@ -130,12 +140,27 @@ export const TOWER_COMMAND_HELP = [
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],
     ],
+    [
+        "usage",
+        [
+            "Usage: cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--json]",
+            "",
+            "Claude Code and Codex usage per person: sessions observed and extracted, tokens (total, output,",
+            "and the input / cache split when the row carries it), and an API list-price equivalent that is",
+            "labelled as such and is never actual spend. A super_admin sees everyone; a member sees their own row.",
+            "--since takes 7d, 30d, 90d or an ISO timestamp; --until an ISO timestamp (default now).",
+            "--include-automated adds harness, subagent and scheduled sessions, which are excluded by default.",
+            "It presses the same door as the /usage page and the usage_people MCP tool (GET /api/usage/people).",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+        ],
+    ],
     [
         "search",
         [
-            'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
+            `Usage: cockpit search "<words>" [--kind ${SEARCH_KIND_LIST}] [--limit <n>] [--json]`,
             "",
-            "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
+            `One bar over ${SEARCH_CORPORA_COUNT} corpora: documents, messages, issues, meeting notes, mail, calendar`,
+            "events and memory.",
             "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
             "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
             "",
@@ -144,12 +169,14 @@ export const TOWER_COMMAND_HELP = [
             "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
             "websearch parser, which shrugs at anything a person can type instead of raising.",
             "",
-            "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
+            `--kind narrows to one or more corpora, comma separated: ${SEARCH_KIND_LIST}.`,
+            `Omit it and all ${SEARCH_CORPORA_COUNT} are searched.`,
             "--limit caps the number of results (default 20, maximum 50).",
             "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
             "",
-            "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
-            "own database session, so a document or a channel you cannot open is not in the list.",
+            `Every result is scoped by what YOU may read: ${SEARCH_CORPORA_COUNT - 1} of the ${SEARCH_CORPORA_COUNT} corpora are`,
+            "searched on your own database session, so a document or a channel you cannot open is not in",
+            "the list; memory runs on the service role behind the memory doors' own gate.",
             "",
             "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
             "those are different facts and folding them together would let a broken search read as silence.",

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

@@ -305,12 +305,14 @@ export function localSubcommandHelp(command) {
         [
             "scout",
             [
-                "Usage: cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the same Scout board the Tower page shows, in the same words: the standing",
                 "watch line, the cards waiting on a decision, and the raw signal watch underneath.",
                 "This is the board itself. To ask a QUESTION about it — what it means, whether it is",
                 "worth doing here — use `cockpit jarvis`, whose readScout tool reads the same rows.",
+                "`cockpit scout board` and a bare `cockpit scout` are the same command; the MCP twin",
+                "is `scout_board` on the bli-tower server, over the same GET /api/cockpit/scout door.",
                 "--days <n> widens or narrows the window (1 to 90; the board defaults to 14).",
                 "Reading follows the Scout page audience setting, so whoever can open /scout can run this.",
                 "start, dismiss, and undo move one card and are super_admin actions on every surface;",
@@ -448,8 +450,14 @@ export function localSubcommandHelp(command) {
         [
             "notes",
             [
-                "Usage: cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [flags]",
+                "Usage: cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|move <id>] [flags]",
+                "Audio uploads: MP3, M4A, WAV, WebM and OGG, up to 4 MB. --wait polls transcription for at most 330 seconds.",
                 "",
+                "folders [--tree] [--json]: list folders and visible note counts.",
+                "mkdir <path> [--json]: create a folder and any missing ancestors.",
+                "rename <path> --name <name> [--json]: rename a folder and its descendant paths.",
+                "rmdir <path> [--json]: delete an empty folder; refuses notes or subfolders.",
+                "upload, paste and move accept --folder <path>; use / for Root. Shelf placement stays independent.",
                 "The /meeting-notes surface, typed. Bare `cockpit notes` lists the library.",
                 "list [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] — every note you may open, grouped by shelf, newest meeting first. Never a word of a note.",
                 "show <id> — one note with its text, its shelf, and why you are allowed to see it.",
@@ -461,6 +469,7 @@ export function localSubcommandHelp(command) {
                 "share <id> [--yes] — let everyone signed in read the statements that are safe to share. Asks first in a terminal; --yes is required without one, and --json implies --yes.",
                 "unshare <id> — take it back. Never asks: it only ever narrows who can read.",
                 "move <id> (--to \"<shelf>\"|--clear-shelf) — put it on a different shelf, or take the shelf off.",
+                "place <id> [--apply] — say which shelf this note belongs on and why, from the meeting it is part of, who was in the room and its own name. Moves nothing without --apply, and never overrules a shelf somebody typed.",
                 "A large note is read by a model on the server and can take a couple of minutes; the terminal says so before it waits.",
                 "--json writes one machine-readable object to stdout; every reason, receipt and progress line stays on stderr.",
                 "Sharing and moving need a signed-in session the database can see. If this deployment cannot mint one, they are refused as needs_signed_in_session rather than done with no permission check — and reads say when they came back narrower than the browser's.",

package/dist/commands/local-help.js

@@ -8,6 +8,7 @@
  * user-visible contract like any other.
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
 import { localSubcommandHelp } from "./local-help-commands.js";
 export const rootCommandNames = new Set([
     "onboard",
@@ -51,6 +52,8 @@ export const rootCommandNames = new Set([
     "project",
     "search",
     "release",
+    "careers",
+    "usage",
 ]);
 export function localCommandHelp(command) {
     if (command)
@@ -72,7 +75,7 @@ export function localCommandHelp(command) {
         "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
         "  cockpit model [show|set <provider:model>] [--json]",
         "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
-        "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
         "  cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] | read [--person <p>] [--channel <c>] [--query <text>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>]] [--json]",
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
@@ -81,7 +84,7 @@ export function localCommandHelp(command) {
         "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
         "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
-        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
+        "  cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|move <id>|place <id>] [--folder <path>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
@@ -96,8 +99,10 @@ export function localCommandHelp(command) {
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
-        "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
+        `  cockpit search "<words>" [--kind ${SEARCH_KINDS.join(",")}] [--limit <n>] [--dashboard-url <url>] [--json]`,
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+        "  cockpit careers [list|show <id>|rescreen <id>] [--role <slug>] [--min-score <n>] [--since <date>] [--json]",
+        "  cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");