@bli-cockpit/cli 0.2.28 → 0.2.30

package/dist/commands/local-auth.js

@@ -0,0 +1,268 @@
+/**
+ * Signing this machine in: which email to pair as, the email-OTP exchange that
+ * gets a short-lived access token, and pairing itself with a manual-approval
+ * fallback when the authenticated route is refused.
+ *
+ * Every failure here degrades to manual dashboard approval rather than
+ * stopping — a person who cannot receive the code must still be able to
+ * onboard. Split out of commands/local.ts (BLI-3104); moved verbatim.
+ */
+import { execFile } from "node:child_process";
+import { errorMessage, isInteractiveStdin, readLine, writeLine, yesByDefault, } from "./cli-io.js";
+import { normalizeUrl } from "./local-args.js";
+import { getCollectorRuntimePaths, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, } from "../local-state.js";
+const OTP_CODE_PROMPT = [
+    "Email code needed:",
+    "  Check your latest Cockpit email for a 6- to 10-digit code.",
+    "What you can do:",
+    "  1) Paste the code here.",
+    "  2) No code yet: wait for the resend window, then rerun this command.",
+    "  3) Can't use email: rerun with --no-auth for manual approval.",
+    "Code: ",
+].join("\n");
+const OTP_INVALID_MESSAGE = [
+    "Email code was not accepted:",
+    "  Cockpit expects digits only, length 6 to 10.",
+    "What you can do:",
+    "  1) Rerun and paste the latest email code.",
+    "  2) Use manual approval: rerun this command with --no-auth --email <you@buildlaunchiterate.ca>",
+].join("\n");
+/**
+ * Asks for the dashboard email so `cockpit onboard` (no flags) need not force a
+ * `--email`. Only called when stdin is a TTY and not in --json mode. An empty
+ * answer or a non-email skips rather than failing, matching `optionalEmail`'s
+ * leniency (the approving admin's account then owns the device).
+ */
+export async function promptOnboardEmail(io) {
+    const raw = await readLine(io, "What's your @buildlaunchiterate.ca email? (press enter to skip): ");
+    const answer = raw.trim().toLowerCase();
+    if (!answer)
+        return undefined;
+    if (!answer.includes("@")) {
+        writeLine(io.stderr, `"${answer}" is not an email; continuing without one — the approving admin's account will own this device.`);
+        return undefined;
+    }
+    return answer;
+}
+export async function resolveOnboardEmail(command, roots, config, io) {
+    if (command.claimedOwnerEmail)
+        return command.claimedOwnerEmail;
+    const inferred = await inferOnboardEmail(command.homeDir, roots, config);
+    const interactive = !command.json && isInteractiveStdin(io);
+    if (!inferred) {
+        return interactive ? promptOnboardEmail(io) : undefined;
+    }
+    if (inferred.source === "session") {
+        if (!command.json)
+            writeLine(io.stdout, `Dashboard email: ${inferred.email}`);
+        return inferred.email;
+    }
+    if (!interactive)
+        return inferred.email;
+    const answer = (await readLine(io, `Use ${inferred.email} for Cockpit pairing? [Y/n] `)).trim().toLowerCase();
+    const typedEmail = answer.split(/\s+/u).find((part) => part.includes("@"));
+    if (typedEmail)
+        return typedEmail;
+    if (yesByDefault(answer)) {
+        return inferred.email;
+    }
+    return promptOnboardEmail(io);
+}
+export async function resolveInteractiveLoginEmail(command, io) {
+    if (command.claimedOwnerEmail)
+        return command.claimedOwnerEmail;
+    if (command.noAuth || command.json || !isInteractiveStdin(io)) {
+        return undefined;
+    }
+    return promptOnboardEmail(io);
+}
+export async function requestPairingAccessToken(input, io) {
+    return (await requestPairingAccessTokenDetailed(input, io)).accessToken;
+}
+export async function requestPairingAccessTokenDetailed(input, io) {
+    if (!input.email ||
+        input.noAuth ||
+        input.json ||
+        !isInteractiveStdin(io)) {
+        return {
+            status: "skipped",
+            errorCode: authSkippedReason(input, io),
+        };
+    }
+    try {
+        const fetchImpl = io.fetch;
+        writeLine(io.stdout, `Signing in as ${input.email}.`);
+        const start = await postOtpStart(fetchImpl, input.dashboardUrl, input.email);
+        const resendAfter = typeof start.resend_after_seconds === "number"
+            ? start.resend_after_seconds
+            : 60;
+        writeLine(io.stdout, `Code sent; valid 1h, resend in ${resendAfter}s by rerunning this command.`);
+        const code = (await readLine(io, OTP_CODE_PROMPT)).trim();
+        if (!/^\d{6,10}$/.test(code)) {
+            throw new Error(OTP_INVALID_MESSAGE);
+        }
+        const verified = await postOtpVerify(fetchImpl, input.dashboardUrl, input.email, code);
+        if (typeof verified.access_token !== "string" || !verified.access_token) {
+            throw new Error("OTP verified but dashboard returned no access token.");
+        }
+        writeLine(io.stdout, `Signed in as ${input.email}.`);
+        return { status: "ok", accessToken: verified.access_token };
+    }
+    catch (error) {
+        writeLine(io.stderr, `Auth step skipped: ${errorMessage(error)}`);
+        writeLine(io.stderr, "Continuing with manual dashboard approval.");
+        return { status: "fail", errorCode: classifyAuthError(error) };
+    }
+}
+function authSkippedReason(input, io) {
+    if (!input.email)
+        return "email_missing";
+    if (input.noAuth)
+        return "no_auth";
+    if (input.json)
+        return "json_mode";
+    if (!isInteractiveStdin(io))
+        return "non_interactive";
+    return "auth_skipped";
+}
+function classifyAuthError(error) {
+    const message = errorMessage(error);
+    if (/\b(otp|code|digit|invalid)\b/i.test(message))
+        return "otp_invalid";
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED|HTTP/i.test(message)) {
+        return "network_or_auth";
+    }
+    return "auth_failed";
+}
+export async function pairLocalCollectorWithAuthFallback(options, io) {
+    try {
+        return await pairLocalCollector(options);
+    }
+    catch (error) {
+        if (!options.pairingAccessToken || !isPairingAuthFailure(error)) {
+            throw error;
+        }
+        writeLine(io.stderr, `Authenticated pairing failed: ${errorMessage(error)}`);
+        writeLine(io.stderr, "Continuing with manual dashboard approval.");
+        return pairLocalCollector({
+            ...options,
+            pairingAccessToken: undefined,
+        });
+    }
+}
+function isPairingAuthFailure(error) {
+    return /\b(auth|authorization|bearer|token|jwt|otp)\b/i.test(errorMessage(error));
+}
+async function postOtpStart(fetchImpl, dashboardUrl, email) {
+    const response = await fetchImpl(`${dashboardUrl}/api/auth/otp/start`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email }),
+    });
+    const parsed = await readJsonResponse(response);
+    if (!response.ok) {
+        throw new Error(responseErrorMessage(parsed, "OTP start failed"));
+    }
+    return parsed;
+}
+async function postOtpVerify(fetchImpl, dashboardUrl, email, code) {
+    const response = await fetchImpl(`${dashboardUrl}/api/auth/otp/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email, code }),
+    });
+    const parsed = await readJsonResponse(response);
+    if (!response.ok) {
+        throw new Error(responseErrorMessage(parsed, "OTP verify failed"));
+    }
+    return parsed;
+}
+async function readJsonResponse(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function responseErrorMessage(parsed, fallback) {
+    if (parsed && typeof parsed === "object") {
+        const record = parsed;
+        if (typeof record["message"] === "string" && record["message"].trim()) {
+            return record["message"];
+        }
+        if (typeof record["error"] === "string" && record["error"].trim()) {
+            return record["error"];
+        }
+    }
+    return fallback;
+}
+/** Best guess at who this machine belongs to: paired session, then saved config, then git. */
+async function inferOnboardEmail(homeDir, roots, config) {
+    const session = await readOnboardSessionReuseCandidate(homeDir).catch(() => null);
+    const sessionEmail = normalizeEmailForComparison(session?.email);
+    if (session?.session_state === "valid" && sessionEmail) {
+        return { email: sessionEmail, source: "session" };
+    }
+    const configEmail = normalizeEmailForComparison(config?.claimed_owner_email);
+    if (configEmail)
+        return { email: configEmail, source: "config" };
+    const gitEmail = await inferUniqueGitEmail(roots);
+    return gitEmail ? { email: gitEmail, source: "git" } : null;
+}
+/** Two roots disagreeing about `user.email` is no answer at all, so neither is used. */
+async function inferUniqueGitEmail(roots) {
+    const emails = new Set();
+    for (const root of roots) {
+        const email = await readGitConfigEmail(root);
+        if (email)
+            emails.add(email);
+    }
+    return emails.size === 1 ? [...emails][0] ?? null : null;
+}
+async function readGitConfigEmail(root) {
+    return new Promise((resolve) => {
+        execFile("git", ["config", "user.email"], { cwd: root, encoding: "utf8" }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const email = normalizeEmailForComparison(stdout);
+            resolve(email?.includes("@") ? email : null);
+        });
+    });
+}
+/** Reuse the paired session only when it is the same person on the same dashboard. */
+export function canReuseOnboardSession(session, claimedOwnerEmail, dashboardUrl) {
+    if (session.session_state !== "valid")
+        return false;
+    const expectedEmail = normalizeEmailForComparison(claimedOwnerEmail);
+    if (expectedEmail && normalizeEmailForComparison(session.email) !== expectedEmail) {
+        return false;
+    }
+    const expectedDashboardUrl = normalizeUrlForComparison(dashboardUrl);
+    if (expectedDashboardUrl &&
+        normalizeUrlForComparison(session.dashboard_url) !== expectedDashboardUrl) {
+        return false;
+    }
+    return true;
+}
+function normalizeEmailForComparison(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized ? normalized : null;
+}
+export async function readOnboardSessionReuseCandidate(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    try {
+        return await readLocalCollectorSessionFile(paths);
+    }
+    catch {
+        return readLocalSessionReference(paths);
+    }
+}
+function normalizeUrlForComparison(value) {
+    return value ? normalizeUrl(value) : null;
+}

package/dist/commands/local-discovery.js

@@ -0,0 +1,100 @@
+import { writeLine } from "./cli-io.js";
+import { resolveDiscoveryLimits, saveDiscoveryLimits, } from "../discovery-limits.js";
+import { discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
+export async function discoverCommandWorktrees(repoRoot, discovery = {}, io) {
+    // What the operator typed this run, else what they typed some previous run,
+    // else the built-in defaults (BLI-2362).
+    const limits = await resolveDiscoveryLimits(discovery, discovery.homeDir);
+    const maxWorktrees = limits.maxRepos;
+    const roots = Array.isArray(repoRoot)
+        ? repoRoot
+        : [repoRoot ?? process.cwd()];
+    const result = await discoverGitWorktreesInRootsWithStatus(roots, {
+        maxDepth: limits.maxDepth,
+        maxWorktrees,
+    });
+    if (io && result.unreadable_dirs.length > 0) {
+        // Never silently dropped: anything under these folders is missing from the
+        // scan, so say so even when the run otherwise succeeds.
+        writeLine(io.stderr, unreadableDirectoriesMessage(result.unreadable_dirs));
+    }
+    const worktrees = result.worktrees;
+    if (!result.complete) {
+        // Sync fails closed here ON PURPOSE, and that is not the bug. Advancing a
+        // cursor after a partial scan would mark the run as covering repos it
+        // never saw, permanently skipping their sessions — backfill can tolerate
+        // partial only because it keeps per-scope completion markers, and sync
+        // does not. The bug (BLI-2362) was that the refusal named no roots and
+        // gave no runnable command, so a big workspace just stayed red forever.
+        const message = incompleteDiscoveryMessage({
+            result,
+            roots,
+            maxDepth: limits.maxDepth,
+            maxRepos: maxWorktrees,
+            found: worktrees.length,
+        });
+        if (io)
+            writeLine(io.stderr, message);
+        throw new Error(message);
+    }
+    if (worktrees.length === 0 && !discovery.allowEmpty) {
+        throw new Error("No git repos found. Run from a git repo, or from a parent folder containing git repos.");
+    }
+    return worktrees;
+}
+/**
+ * Persists `--max-depth` / `--max-repos` when a command carried them, so the
+ * number survives into the background sync and the doctor's own sync — neither
+ * of which has anywhere to type one (BLI-2362). Best-effort: failing to record
+ * a preference must never fail the command the operator actually asked for.
+ */
+export async function rememberDiscoveryLimits(command) {
+    const limits = command;
+    if (limits.maxDepth === undefined && limits.maxRepos === undefined)
+        return;
+    await saveDiscoveryLimits({ maxDepth: limits.maxDepth, maxRepos: limits.maxRepos }, limits.homeDir).catch(() => undefined);
+}
+/**
+ * Says which folders could not be opened, and therefore what the scan could not
+ * see. Reported without failing the run — an unreadable folder cannot be fixed
+ * by retrying, so blocking on one would strand the machine (BLI-2362).
+ */
+function unreadableDirectoriesMessage(unreadable) {
+    return [
+        `WARNING: ${unreadable.length} folder(s) could not be opened, so anything inside them was not scanned:`,
+        ...unreadable.map((dir) => `  ${dir.path} (${dir.code})`),
+        "Collection continued for everything else. If a repo is missing from Cockpit,",
+        "check the permissions on the folders above.",
+    ].join("\n");
+}
+/**
+ * Names the roots that could not be covered and hands back a command that
+ * actually fixes it, with this machine's numbers already filled in.
+ */
+function incompleteDiscoveryMessage(input) {
+    const { result, roots, maxDepth, maxRepos, found } = input;
+    const blocked = result.incomplete_roots.length > 0 ? result.incomplete_roots : roots;
+    const hitRepoCap = result.incomplete_reasons.includes("max_worktrees_reached");
+    const nextDepth = maxDepth + 3;
+    const nextRepos = Math.max(maxRepos * 2, found + 50);
+    const retry = [
+        "cockpit do-everything",
+        ...roots.map((root) => `--workspace ${root}`),
+        `--max-depth ${hitRepoCap ? maxDepth : nextDepth}`,
+        `--max-repos ${nextRepos}`,
+    ].join(" ");
+    return [
+        `Cockpit could not finish scanning for repos, so it stopped instead of collecting a partial picture (${result.incomplete_reasons.join(", ")}).`,
+        "It stops rather than continuing because a partial scan would mark these repos as already checked and skip them from now on.",
+        "",
+        "Could not fully scan:",
+        ...blocked.map((root) => `  ${root}`),
+        "",
+        `Found ${found} repo(s) before stopping, with --max-depth ${maxDepth} and --max-repos ${maxRepos}.`,
+        "",
+        "Run this to raise the limits and try again:",
+        `  ${retry}`,
+        "",
+        "If that still stops, the folder is deeper or larger than expected — raise the numbers again, or point --workspace at the specific project folders instead of a parent.",
+    ].join("\n");
+}

package/dist/commands/local-help.js

@@ -0,0 +1,281 @@
+/**
+ * What `cockpit --help` and `cockpit <command> --help` print, plus the set of
+ * command names the top-level router recognises.
+ *
+ * Pure text and one lookup table — no filesystem, no network, no process. Split
+ * out of commands/local.ts (BLI-3104) with 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 { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+export const rootCommandNames = new Set([
+    "onboard",
+    "update",
+    "upgrade",
+    "do-everything",
+    "fix",
+    "install",
+    "login",
+    "pair",
+    "logout",
+    "start",
+    "sync",
+    "analyze",
+    "backfill",
+    "status",
+    "sessions",
+    "serve",
+    "autostart",
+    "agent-rules",
+    "release",
+]);
+export function localCommandHelp(command) {
+    if (command)
+        return localSubcommandHelp(command);
+    return [
+        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
+        "  cockpit upgrade [same flags as update]",
+        "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
+        "  cockpit fix [same flags as do-everything]",
+        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
+        "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+        "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+        "  cockpit logout",
+        "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--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]",
+        "  cockpit serve [--port <port>] [--workspace <path>]",
+        "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+        "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
+        "  cockpit release [--dry-run] [--skip-checks] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+        "",
+        `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");
+}
+function localSubcommandHelp(command) {
+    const helpByCommand = new Map([
+        [
+            "onboard",
+            [
+                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+                "",
+                "Installs, pairs, starts work context(s), syncs once, completes all-history",
+                "Codex and Claude backfill for the saved roots, and then tells you it is working.",
+                "If --workspace is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                `Omit --dashboard-url for normal production setup (${DEFAULT_DASHBOARD_URL}).`,
+                "Pass --dashboard-url only for staging/custom dashboards or to force a different pairing.",
+                "Run with no flags in a terminal and it prompts for the dashboard email and OTP code; pass --email to skip the email prompt. Use --no-auth to force the manual approval fallback.",
+                "Interactive runs also offer to add Cockpit ticket-binding rules to AGENTS.md and CLAUDE.md after readiness proof.",
+            ],
+        ],
+        [
+            "install",
+            [
+                "Usage: cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
+                "",
+                "Writes local collector config. Pair with `cockpit login`, then run `cockpit start` when work begins.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
+            ],
+        ],
+        [
+            "update",
+            [
+                "Usage: cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
+                "",
+                "Updates the global public CLI from npm, then reruns `cockpit onboard`",
+                "with the same setup flags so pairing, saved roots, all-history backfill,",
+                "agent rules, autostart, and the initial sync are refreshed in one command.",
+                "`cockpit upgrade` is an alias.",
+            ],
+        ],
+        [
+            "upgrade",
+            [
+                "Usage: cockpit upgrade [same flags as cockpit update]",
+                "",
+                "Alias for `cockpit update`.",
+            ],
+        ],
+        [
+            "do-everything",
+            [
+                "Usage: cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
+                "",
+                "Gets this machine fully set up, whether it is brand new, already set up, or handed down: latest CLI, sign-in and collection-root recovery when needed, saved folders, background sync, catching up on old sessions, cleaning up old files, and one fresh upload.",
+                "`cockpit fix` is an alias.",
+                "Maintainers only: use `--update-tag next` so self-update and re-exec stay on the prerelease candidate.",
+                "--dry-run shows what it would do without changing anything.",
+            ],
+        ],
+        [
+            "fix",
+            [
+                "Usage: cockpit fix [same flags as cockpit do-everything]",
+                "",
+                "Alias for `cockpit do-everything`.",
+            ],
+        ],
+        [
+            "login",
+            [
+                "Usage: cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+                "",
+                "Signs in with an email OTP when interactive, starts dashboard device pairing, and stores the approved local session.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
+            ],
+        ],
+        [
+            "pair",
+            [
+                "Usage: cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+                "",
+                "Alias for `cockpit login`.",
+            ],
+        ],
+        ["logout", ["Usage: cockpit logout [--json]", "", "Removes the local device session."]],
+        [
+            "start",
+            [
+                "Usage: cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--topic-summary <summary>] [--intent <intent>] [--phase <phase>] [--intent-confidence <0..1>] [--workspace <path>] [--branch <name>] [--json]",
+                "",
+                "Starts collecting your work in the background. If you point it at a parent folder it covers every repo inside.",
+                "Add --ticket only when the work already has a visible ticket; omit it to preserve an existing binding.",
+                "Use --clear-ticket to go back to collecting general work with no ticket attached.",
+                "Use --topic/--intent/--phase for planning, discovery, and learning work that has no ticket yet.",
+                "Supported intents: implementation, bug_fix, root_cause_analysis, planning, discovery, review, testing, documentation, release, learning, coordination, maintenance, analysis, unknown, other.",
+                "Supported phases: planning, discovery, implementation, debugging, review, testing, documentation, release, handoff, analysis, unknown, other.",
+                "`--repo <path>` remains supported as a backward-compatible alias; use --workspace in agent guidance.",
+            ],
+        ],
+        [
+            "sync",
+            [
+                "Usage: cockpit sync [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads your latest collected work. If it cannot reach Cockpit it saves a retry and tries again later.",
+                "Omit --dashboard-url for normal production sync; pass it only for staging/custom dashboards or forced re-pairing.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Parent folders sync each child git worktree; Codex AND Claude Code JSONL",
+                "transcripts (and Claude subagent sidecars) are attributed to repos",
+                "deterministically and ambiguous transcripts are retained as unattributed",
+                "instead of being duplicated across repos. Use `cockpit sessions` to see why",
+                "a session is or is not collected.",
+                "New repos start being collected automatically, with no ticket attached.",
+                "Discovery scans 3 folder levels and up to 50 repos by default; tune with",
+                "--max-depth and --max-repos.",
+                "Also self-updates the CLI from npm latest once per day, strictly after",
+                "collection finishes; set COCKPIT_DISABLE_AUTO_UPDATE=1 to freeze the",
+                "installed version during incident triage.",
+            ],
+        ],
+        [
+            "analyze",
+            [
+                "Usage: cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads your latest collected work, then asks Cockpit to analyse it.",
+                "The command returns after the batch is queued; view status and results in My Work.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "backfill",
+            [
+                "Usage: cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
+                "",
+                "Backfills historical Codex and Claude Code session evidence using the saved collection roots from local config when --workspace is omitted.",
+                "Omit --source to scan both sources; there is no --source all literal.",
+                "The non-all window is capped at the collector session paired_at timestamp.",
+                "--all requires a dry-run review and TTY confirmation; pass --yes for headless agent runs.",
+                "Repo discovery scans 3 folder levels and up to 50 repos by default.",
+                "Raise --max-depth or --max-repos when a partial result reports a discovery cap.",
+                "--dry-run validates the paired collector and dashboard reachability, prints the same summary tables, and writes nothing.",
+            ],
+        ],
+        [
+            "status",
+            [
+                "Usage: cockpit status [--workspace <path>] [--json]",
+                "",
+                "Prints install, pairing, active work, upload, and retry state.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "sessions",
+            [
+                "Usage: cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--json]",
+                "",
+                "Read-only: re-runs Codex + Claude session attribution and prints each",
+                "session's id, source, state, reason, scores, signals, and per-sidecar",
+                "skip reasons. No upload, no cursor writes. Answers \"why is session X",
+                "missing?\" locally — counts and labels only, never paths or content.",
+                "--since-days uses the same paired_at cap as `cockpit backfill`; --all scans the full local history.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "serve",
+            [
+                "Usage: cockpit serve [--port <port>] [--workspace <path>]",
+                "",
+                "Starts the local collector HTTP status server.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "autostart",
+            [
+                "Usage: cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+                "",
+                "Installs background sync through launchd on Apple Silicon macOS or a",
+                "per-user Task Scheduler task on native Windows.",
+                "Runs `cockpit sync` every 15 min by default and survives reboots;",
+                "the Windows task runs while the user is signed in.",
+                "Action defaults to `install`. `--workspace` is the parent work folder to sync.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
+                "See docs/runbooks/cockpit-launchd-sync.md and",
+                "docs/runbooks/cockpit-windows-task-scheduler-sync.md.",
+            ],
+        ],
+        [
+            "agent-rules",
+            [
+                "Usage: cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
+                "",
+                "Installs a managed Cockpit Ticket Binding block into ~/.codex/AGENTS.md",
+                "and ~/.claude/CLAUDE.md by default. Pass --host to manage only one.",
+                "The block is scoped to --workspace, or the current directory when omitted,",
+                "so Codex and Claude only run Cockpit ticket binding inside that onboarded folder.",
+                "Action defaults to `install`.",
+            ],
+        ],
+        [
+            "release",
+            [
+                "Usage: cockpit release [--dry-run] [--skip-checks] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+                "",
+                "Maintainer-only helper. Run from inside the bli-cockpit repo checkout.",
+                "Requires a clean `main` branch and runs `git pull --ff-only` before publishing.",
+                "Delegates to `npm run publish:public -- ...` so public packages are",
+                "built, checked, and published in the safe telemetry-core then CLI order.",
+            ],
+        ],
+    ]);
+    return (helpByCommand.get(command) ?? [localCommandHelp()]).join("\n");
+}
+/** `cockpit <command> --help` — the command name alone, with only the help flag. */
+export function isLocalHelpRequest(argv) {
+    const command = argv[0];
+    if (!command || !rootCommandNames.has(command))
+        return false;
+    return argv.length === 2 && (argv[1] === "--help" || argv[1] === "-h");
+}