@bli-cockpit/cli 0.2.2 → 0.2.4

package/README.md

@@ -45,16 +45,16 @@ The OTP proves you own an approved BLI mailbox. The JWT is used once to register
 
 ## Every command, what it does, and why it's called that
 
-You only need `onboard` once and `do-everything` whenever Edward asks the fleet to converge. The rest exist for
-recovery and maintenance.
+On a blank Mac, `npm i -g @bli-cockpit/cli && cockpit do-everything` is enough to sign in, choose roots, and converge the machine. `onboard` remains the named setup subset, and the rest exist for recovery and maintenance.
 
 | Command | What it does | Why it exists / why this name |
 |---|---|---|
 | `cockpit onboard` | The everything-command: signs you in (email code), registers this Mac, starts capture, uploads once, installs the 15-min background sync, and prints proof you're live. | You are boarding the crew. Run it once per machine; rerunning is always safe. |
-| `cockpit do-everything` / `cockpit fix` | Converges an already-onboarded Mac: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess. |
+| `cockpit do-everything` / `cockpit fix` | Converges a Mac from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/`--json` runs explain and exit instead of blocking. `--dry-run` previews without writing. | Edward can post one line and every intern machine should end green. `fix` is the alias people guess. |
 | `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
 | `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this Mac). | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
 | `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |
+| `cockpit analyze` | Runs a fresh sync, then queues batch analysis of your latest uploaded sessions. It returns immediately; status and results appear in My Work. | One command when you want newly finished work uploaded and judged now. |
 | `cockpit start --ticket <id>` | Tags your CURRENT work with a Linear ticket so sessions attribute to it. `--clear-ticket` returns to general capture. | "Start (working on) X." Agents usually run this for you per the agent rules. |
 | `cockpit login` / `cockpit pair` | Just the sign-in + device-registration step, standalone (onboard already includes it). Two names, one command: `login` is what humans guess, `pair` is what the dashboard's device screen calls it. | Recovery path when a session expires or you switch accounts. |
 | `cockpit logout` | Deletes this machine's session. | The undo of login. |
@@ -83,16 +83,34 @@ cockpit onboard --no-auth
 
 - `--email` skips the email prompt.
 - `--workspace` pins one collection root; repeat it for multiple unrelated roots.
-- `--allow-home-root` deliberately collects your whole home folder. Use it only on a company machine where that is intended.
+- Interactive onboarding from your home folder asks whether to sync all projects on the machine. Answer `y` only on a company machine where collecting every current and future repo under `$HOME` is intended. `n` or Enter asks for the actual work folder; if no valid non-home folder is chosen, Cockpit captures nothing and tells you to rerun with `--workspace <path-to-your-work-folder>`.
+- `--allow-home-root` is the headless/scripted form of that full-home opt-in.
 - `--device-name` changes only the human label shown in Cockpit.
 - `--dashboard-url` is for staging/custom dashboards only. Production is the default.
 - `--no-auth` forces the old manual approval queue.
 - `--repo` still works as a legacy alias for `--workspace`.
 
-`cockpit do-everything` is the normal fleet convergence command after onboarding. It exits non-zero only when a checked invariant remains red after its fix runs, or when a human action such as login/onboard-rerun is required.
+`cockpit do-everything` is the normal fleet convergence command. On an interactive first run it uses the same email OTP login and root-picker flow as onboarding, then re-checks the machine. In headless, launchd, `--json`, or no-TTY runs it never prompts; missing auth or roots stay red with the repair text. `--dry-run` previews without writing auth or config.
 
 `cockpit update` installs the latest public CLI and reruns onboarding checks against saved roots. `cockpit upgrade` is the same command.
 
+## Analyze latest work
+
+```bash
+cockpit analyze --workspace "$PWD"
+```
+
+`cockpit analyze` first performs the same durable upload as `cockpit sync`. It
+queues the analysis only after that upload succeeds, then exits without waiting
+for the Fireworks batch. Use `--json` for a single machine-readable object that
+contains both the sync receipt and queued job status. The dashboard button
+analyzes the latest upload already stored by the background collector; run the
+CLI command when the work ended too recently for the 15-minute background sync.
+Each person can queue analysis once every three hours, subject to the team's
+shared `$2` UTC-day judge cap. Completion can take several minutes plus the wait
+for the next 15-minute collector poll; My Work shows queued, running, done, or
+failed status while you wait.
+
 ## Parent Mode
 
 Use a parent folder such as `~/BLI` when it contains multiple repos. Cockpit scans child git repos/worktrees, creates one stable work context per worktree, and rolls them up under repo rows in the dashboard.

package/dist/commands/doctor.js

@@ -22,20 +22,28 @@ export async function runDoctorWithDeps(command, io, deps) {
             rows.push(checked);
             continue;
         }
-        if (checked.hardStop) {
-            rows.push(checked);
-            break;
+        if (command.dryRun && invariant.fix) {
+            rows.push(dryRunPreview(checked));
+            continue;
+        }
+        const canFix = Boolean(invariant.fix) &&
+            (!invariant.requiresInteractiveFix || isInteractiveDoctorFix(context));
+        if (!canFix) {
+            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
+            if (checked.hardStop)
+                break;
+            continue;
         }
-        if (command.dryRun || !invariant.fix) {
-            rows.push({
-                ...checked,
-                status: "needs_fix",
-                message: `would fix: ${checked.message}`,
-            });
+        if (!invariant.fix) {
+            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
+            if (checked.hardStop)
+                break;
             continue;
         }
         const fixed = await invariant.fix(context, checked);
         rows.push({ ...fixed, fixed: fixed.status !== "fail" });
+        if (fixed.hardStop)
+            break;
         if (fixed.reexecExitCode !== undefined) {
             await maybeReportDoctorEvents(context, rows);
             writeDoctorOutput(command, io, rows);
@@ -49,8 +57,18 @@ export async function runDoctorWithDeps(command, io, deps) {
 function doctorInvariants() {
     return [
         { id: "cli-latest", check: checkCliLatest, fix: fixCliLatest },
-        { id: "authed", check: (context) => context.deps.readAuth(context) },
-        { id: "roots-ok", check: (context) => context.deps.readRoots(context) },
+        {
+            id: "authed",
+            check: (context) => context.deps.readAuth(context),
+            fix: fixAuthState,
+            requiresInteractiveFix: true,
+        },
+        {
+            id: "roots-ok",
+            check: (context) => context.deps.readRoots(context),
+            fix: fixRootState,
+            requiresInteractiveFix: true,
+        },
         {
             id: "autostart-alive",
             check: (context) => context.deps.checkAutostart(context),
@@ -80,7 +98,9 @@ function defaultDoctorDeps(hooks) {
         reexecDoctor: reexecDoctor,
         reportInstallEvents: hooks.reportInstallEvents,
         readAuth: readAuthState,
+        runLogin: (context) => hooks.runLogin(context.command, context.io),
         readRoots: readRootState,
+        resolveAndSaveRoots: (context) => hooks.resolveAndSaveRoots(context.command, context.io),
         checkAutostart: checkAutostartState,
         fixAutostart: fixAutostartState,
         checkBackfill: checkBackfillState,
@@ -120,6 +140,18 @@ async function fixCliLatest(context, state) {
         reexecExitCode: code,
     };
 }
+async function fixAuthState(context, state) {
+    const code = await context.deps.runLogin(context).catch(() => 1);
+    if (code !== 0)
+        return state;
+    const checked = await context.deps.readAuth(context);
+    return checked.status === "ok" ? checked : state;
+}
+async function fixRootState(context, state) {
+    await context.deps.resolveAndSaveRoots(context).catch(() => undefined);
+    const checked = await context.deps.readRoots(context);
+    return checked.status === "ok" ? checked : state;
+}
 async function latestCliVersionFromNpm(context) {
     const exec = context.io.exec;
     if (!exec)
@@ -350,6 +382,18 @@ function fail(id, code, message) {
 function hardStop(id, code, message) {
     return { id, status: "fail", code, message, hardStop: true };
 }
+function dryRunPreview(state) {
+    const preview = { ...state };
+    delete preview.hardStop;
+    return {
+        ...preview,
+        status: "needs_fix",
+        message: `would fix: ${oneLine(state.message)}`,
+    };
+}
+function isInteractiveDoctorFix(context) {
+    return !context.command.json && Boolean(context.io.stdin.isTTY);
+}
 async function savedRoots() {
     const config = await readLocalCollectorConfig(getCollectorRuntimePaths()).catch(() => null);
     return normalizeCollectionRoots(config?.default_repo_paths ?? []);

package/dist/commands/local-args.js

@@ -29,6 +29,8 @@ export function parseLocalArgs(argv) {
             return parseStartArgs(argv.slice(1));
         case "sync":
             return parseSyncArgs(argv.slice(1));
+        case "analyze":
+            return parseAnalyzeArgs(argv.slice(1));
         case "backfill":
             return parseBackfillArgs(argv.slice(1));
         case "status":
@@ -302,6 +304,12 @@ function parseStartArgs(args) {
     };
 }
 function parseSyncArgs(args) {
+    return parseSyncLikeArgs(args, "sync");
+}
+function parseAnalyzeArgs(args) {
+    return parseSyncLikeArgs(args, "analyze");
+}
+function parseSyncLikeArgs(args, command) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
             "--home",
@@ -321,9 +329,9 @@ function parseSyncArgs(args) {
             "--max-repos",
         ],
     });
-    assertNoPositionals(values.positionals, "sync");
+    assertNoPositionals(values.positionals, command);
     return {
-        kind: "sync",
+        kind: command,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),

package/dist/commands/local.js

@@ -30,6 +30,7 @@ export const rootCommandNames = new Set([
     "logout",
     "start",
     "sync",
+    "analyze",
     "backfill",
     "status",
     "sessions",
@@ -65,6 +66,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runDoctor(command, io, {
                     reportInstallEvents: reportInstallEventsBestEffort,
                     selfUpdate: runSelfUpdate,
+                    runLogin: runDoctorLogin,
+                    resolveAndSaveRoots: resolveAndSaveDoctorRoots,
                 });
             case "login":
                 return await runLogin(command, io);
@@ -74,6 +77,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runStart(command, io);
             case "sync":
                 return await runSync(command, io);
+            case "analyze":
+                return await runAnalyze(command, io);
             case "backfill":
                 return await runBackfillCommand(command, io);
             case "status":
@@ -110,6 +115,7 @@ export function localCommandHelp(command) {
         "  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>] [--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]",
@@ -234,6 +240,17 @@ function localSubcommandHelp(command) {
                 "--max-depth and --max-repos.",
             ],
         ],
+        [
+            "analyze",
+            [
+                "Usage: cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads the latest local ambient evidence, then queues one analysis job.",
+                "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",
             [
@@ -1053,6 +1070,64 @@ function backgroundSyncLine(result) {
     }
     return result.status;
 }
+async function resolveOnboardingRootsForCommand(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
+    const interactive = !command.json && isInteractiveStdin(io);
+    const rootsResult = await resolveOnboardingRoots({
+        homeDir: command.homeDir,
+        explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
+        config: existingConfig,
+        interactive,
+        allowHomeRoot: command.allowHomeRoot,
+        prompt: interactive ? onboardingRootPrompt(io) : undefined,
+    });
+    const collectionRoots = rootsResult.roots;
+    const primaryRoot = collectionRoots[0];
+    if (!primaryRoot) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
+    }
+    const replaceRepoRoots = rootsResult.source === "prompt" &&
+        !command.collectionRoots?.length &&
+        (existingConfig?.default_repo_paths.length ?? 0) > 0;
+    return {
+        existingConfig,
+        rootsResult,
+        collectionRoots,
+        primaryRoot,
+        replaceRepoRoots,
+    };
+}
+async function persistOnboardingRootConfig(command, resolution) {
+    return installLocalCollector({
+        homeDir: command.homeDir,
+        repoRoot: resolution.primaryRoot,
+        repoRoots: resolution.collectionRoots,
+        replaceRepoRoots: resolution.replaceRepoRoots,
+        dashboardUrl: command.dashboardUrl,
+        deviceName: command.deviceName,
+    });
+}
+async function runDoctorLogin(command, io) {
+    return runLogin({
+        kind: "login",
+        dashboardUrl: command.dashboardUrl,
+        json: command.json,
+        noAuth: false,
+    }, io);
+}
+async function resolveAndSaveDoctorRoots(command, io) {
+    const rootCommand = {
+        repoRoot: command.repoRoot,
+        dashboardUrl: command.dashboardUrl,
+        json: command.json,
+    };
+    const resolution = await resolveOnboardingRootsForCommand(rootCommand, io);
+    await persistOnboardingRootConfig(rootCommand, resolution);
+    if (!command.json) {
+        writeLine(io.stdout, `Saved collection roots: ${resolution.collectionRoots.join(", ")}`);
+    }
+}
 async function runOnboard(command, io) {
     const installEvents = [];
     const finish = async (code) => {
@@ -1080,31 +1155,17 @@ async function runOnboard(command, io) {
             writeLine(io.stdout, `Dashboard: ${command.dashboardUrl}`);
             writeLine(io.stdout, `Ticket: ${command.activeTicketId ?? "general ambient"}`);
         }
-        const paths = getCollectorRuntimePaths(command.homeDir);
         backfillHint = await onboardBackfillHint(command.homeDir);
-        const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
-        const interactive = !command.json && isInteractiveStdin(io);
-        rootsResult = await resolveOnboardingRoots({
-            homeDir: command.homeDir,
-            explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
-            config: existingConfig,
-            interactive,
-            allowHomeRoot: command.allowHomeRoot,
-            prompt: interactive ? onboardingRootPrompt(io) : undefined,
-        });
+        const resolvedRoots = await resolveOnboardingRootsForCommand(command, io);
+        const existingConfig = resolvedRoots.existingConfig;
+        rootsResult = resolvedRoots.rootsResult;
         const collectionRoots = rootsResult.roots;
-        const primaryRoot = collectionRoots[0];
-        if (!primaryRoot) {
-            throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
-        }
+        const primaryRoot = resolvedRoots.primaryRoot;
         const resolvedCommand = {
             ...command,
             repoRoot: primaryRoot,
             collectionRoots,
         };
-        const replaceRepoRoots = rootsResult.source === "prompt" &&
-            !command.collectionRoots?.length &&
-            (existingConfig?.default_repo_paths.length ?? 0) > 0;
         if (!command.json) {
             writeLine(io.stdout, `Collecting from: ${collectionRoots.join(", ")}`);
         }
@@ -1112,14 +1173,7 @@ async function runOnboard(command, io) {
             addInstallEvent(installEvents, "home_root_optin", "ok");
         }
         const claimedOwnerEmail = await resolveOnboardEmail(resolvedCommand, collectionRoots, existingConfig, io);
-        install = await installLocalCollector({
-            homeDir: command.homeDir,
-            repoRoot: primaryRoot,
-            repoRoots: collectionRoots,
-            replaceRepoRoots,
-            dashboardUrl: command.dashboardUrl,
-            deviceName: command.deviceName,
-        });
+        install = await persistOnboardingRootConfig(command, resolvedRoots);
         addInstallEvent(installEvents, "install", "ok");
         if (!command.json) {
             writeLine(io.stdout, "1/5 Installed local collector.");
@@ -1786,6 +1840,137 @@ async function runSyncLocked(command, io) {
     writeLine(io.stderr, `Retry: ${result.retry_command}`);
     return 1;
 }
+async function runAnalyze(command, io) {
+    const syncStdout = [];
+    const syncStderr = [];
+    const syncIo = {
+        ...io,
+        stdout: bufferedWritable(syncStdout),
+        stderr: bufferedWritable(syncStderr),
+    };
+    const syncCommand = {
+        ...command,
+        kind: "sync",
+        json: true,
+    };
+    const syncExitCode = await runSync(syncCommand, syncIo);
+    const syncOutput = parseCapturedJson(syncStdout);
+    if (syncExitCode !== 0 || !isUploadedSyncResult(syncOutput)) {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: syncExitCode === 0 ? "sync_not_completed" : "sync_failed",
+                sync: syncOutput,
+                error: syncStderr.join("").trim()
+                    || (syncExitCode === 0
+                        ? "Cockpit sync did not upload fresh evidence."
+                        : "Cockpit sync failed."),
+            }, null, 2));
+        }
+        else {
+            replayCaptured(io.stderr, syncStderr);
+            writeLine(io.stderr, syncExitCode === 0
+                ? "Analysis was not queued because a fresh upload did not complete."
+                : "Analysis was not queued because the latest upload failed.");
+        }
+        return syncExitCode === 0 ? 1 : syncExitCode;
+    }
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => {
+        throw new Error("Cockpit is not signed in. Run `cockpit onboard` or `cockpit login` first.");
+    });
+    const dashboardUrl = normalizeUrl(command.dashboardUrl ?? session.dashboard_url ?? DEFAULT_DASHBOARD_URL);
+    const response = await io.fetch(`${dashboardUrl}/api/ambient/analyze`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${session.device_token}`,
+            "content-type": "application/json",
+        },
+        body: "{}",
+    });
+    const body = await readAnalyzeApiResponse(response);
+    if (!response.ok) {
+        const message = typeof body.message === "string"
+            ? body.message
+            : `Analysis request failed with HTTP ${response.status}.`;
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: "analyze_failed",
+                sync: syncOutput,
+                http_status: response.status,
+                code: typeof body.code === "string" ? body.code : null,
+                message,
+                retry_after_seconds: typeof body.retry_after_seconds === "number"
+                    ? body.retry_after_seconds
+                    : null,
+            }, null, 2));
+        }
+        else {
+            replayCaptured(io.stderr, syncStderr);
+            writeLine(io.stderr, `Analysis was not queued: ${message}`);
+        }
+        return 1;
+    }
+    const jobId = typeof body.job?.id === "string" ? body.job.id : null;
+    const jobStatus = typeof body.job?.status === "string" ? body.job.status : "pending";
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "queued",
+            sync: syncOutput,
+            job: body.job ?? null,
+            dashboard_url: `${dashboardUrl}/my-work`,
+        }, null, 2));
+        return 0;
+    }
+    replayCaptured(io.stderr, syncStderr);
+    writeLine(io.stdout, "Cockpit latest evidence uploaded.");
+    writeLine(io.stdout, "Cockpit analysis queued.");
+    if (jobId)
+        writeLine(io.stdout, `Job: ${jobId}`);
+    writeLine(io.stdout, `Status: ${jobStatus === "pending" ? "queued" : jobStatus}`);
+    writeLine(io.stdout, `Results: ${dashboardUrl}/my-work`);
+    return 0;
+}
+async function readAnalyzeApiResponse(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseCapturedJson(chunks) {
+    const text = chunks.join("").trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isUploadedSyncResult(value) {
+    return Boolean(value
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && value["status"] === "uploaded");
+}
+function bufferedWritable(chunks) {
+    return {
+        write(chunk) {
+            chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+            return true;
+        },
+    };
+}
+function replayCaptured(stream, chunks) {
+    for (const chunk of chunks)
+        stream.write(chunk);
+}
 async function runSyncRawEvidenceGc(command, io) {
     return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
 }

package/dist/onboarding-roots.js

@@ -1,10 +1,15 @@
 import fs from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { discoverGitWorktrees } from "./repo-identity.js";
 import { normalizeCollectionRoots } from "./root-normalization.js";
 export const COLLECTION_ROOT_REQUIRED = "collection_root_required";
-export const HOME_ROOT_CONSENT_PROMPT = "Collect your ENTIRE home folder? Any git repo you ever create under it will be collected automatically. Type 'everything' to confirm: ";
+export function homeRootConsentPrompt(homeDirInput) {
+    const homeDir = path.resolve(homeDirInput ?? os.homedir());
+    return `You're in your home folder (${homeDir}).\n  Sync ALL projects on this machine? Every git repo under here gets captured now and in the future.\n  This is a work machine — exclude personal projects yourself if needed.  [y/N]: `;
+}
+export const HOME_ROOT_DECLINE_PATH_PROMPT = "Okay — which folder should I sync? Enter the full path to your work directory: ";
+export const HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE = "No folder chosen. Re-run: cockpit onboard --workspace <path-to-your-work-folder>";
 export async function resolveOnboardingRoots(options) {
     const explicitInput = options.explicitRoots ?? [];
     const explicit = normalizeRootsDetailed(explicitInput, {
@@ -19,10 +24,7 @@ export async function resolveOnboardingRoots(options) {
         if (!options.interactive) {
             throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(explicit.rejected[0], options)}`);
         }
-        explainRejectedRoots(options, explicit.rejected);
-        const homeOffer = await counterOfferHomeDirectoryRepos(options, explicit.rejected);
-        if (homeOffer)
-            return homeOffer;
+        explainRejectedRoots(options, withoutHomeRejections(explicit.rejected));
         const homeOptIn = await promptForHomeRootOptIn(options, explicit.rejected);
         if (homeOptIn)
             return homeOptIn;
@@ -45,10 +47,24 @@ export async function resolveOnboardingRoots(options) {
         }
         return promptForRoots(options, "Collection root(s), comma-separated: ");
     }
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    if (isHomeRoot(cwd, options.homeDir)) {
+        const homeDir = path.resolve(options.homeDir ?? os.homedir());
+        if (options.allowHomeRoot) {
+            return resolvedRoots(options, [homeDir], "cwd_likely_root", true);
+        }
+        if (!options.interactive) {
+            throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${homeRootTutorial(homeDir)}`);
+        }
+        const homeOptIn = await promptForHomeRootOptIn(options, [
+            { input: homeDir, reason: "home_dir" },
+        ]);
+        if (homeOptIn)
+            return homeOptIn;
+    }
     if (!options.interactive) {
         throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(options)}`);
     }
-    const cwd = path.resolve(options.cwd ?? process.cwd());
     const cwdRoot = likelyBliRootFromCwd(cwd);
     if (cwdRoot) {
         const confirmed = await requirePrompt(options).confirm(`Collect from ${cwdRoot}? [Y/n] `);
@@ -115,10 +131,7 @@ async function promptForRoots(options, message) {
             return resolvedRoots(options, detailed.roots, "prompt", true);
         }
         if (detailed.rejected.length > 0) {
-            explainRejectedRoots(options, detailed.rejected);
-            const homeOffer = await counterOfferHomeDirectoryRepos(options, detailed.rejected);
-            if (homeOffer)
-                return homeOffer;
+            explainRejectedRoots(options, withoutHomeRejections(detailed.rejected));
             const homeOptIn = await promptForHomeRootOptIn(options, detailed.rejected);
             if (homeOptIn)
                 return homeOptIn;
@@ -164,6 +177,9 @@ export function rootRejectionExplanation(rejection, options = {}) {
             return filesystemRootTutorial(options.homeDir);
     }
 }
+function withoutHomeRejections(rejections) {
+    return rejections.filter((rejection) => rejection.reason !== "home_dir");
+}
 function rootRejectionPromptHint(rejection, options = {}) {
     switch (rejection.reason) {
         case "home_dir":
@@ -172,45 +188,63 @@ function rootRejectionPromptHint(rejection, options = {}) {
             return filesystemRootTutorial(options.homeDir);
     }
 }
-async function counterOfferHomeDirectoryRepos(options, rejections) {
-    const homeRejection = rejections.find((rejection) => rejection.reason === "home_dir");
-    if (!homeRejection)
-        return null;
-    const prompt = requirePrompt(options);
-    const homeDir = path.resolve(options.homeDir ?? os.homedir());
-    const discover = options.discoverGitWorktrees ?? discoverGitWorktrees;
-    const worktrees = await discover(homeDir, {
-        maxDepth: 3,
-        maxWorktrees: 50,
-    }).catch(() => []);
-    const roots = normalizeCollectionRoots([...new Set(worktrees.map((worktree) => path.resolve(worktree.repo_root)))]);
-    if (roots.length === 0)
-        return null;
-    const confirmed = await prompt.confirm([
-        "Your home folder can't be a collection root by default:",
-        `  I found ${roots.length} git repos under ${homeDir} that are safer to collect.`,
-        "Discovered repos:",
-        ...roots.map((root) => `- ${root}`),
-        "What you can do:",
-        "  1) Use these repos: answer y",
-        "  2) Pick different folders: answer n, then paste specific paths",
-        "  3) Collect everything anyway: answer n, then type everything at the next prompt",
-        "Collect from these? [Y/n] ",
-    ].join("\n"));
-    return confirmed ? resolvedRoots(options, roots, "prompt", true) : null;
-}
 async function promptForHomeRootOptIn(options, rejections) {
     if (!rejections.some((rejection) => rejection.reason === "home_dir"))
         return null;
-    const answer = await requirePrompt(options).input(HOME_ROOT_CONSENT_PROMPT);
-    if (answer.trim().toLowerCase() !== "everything")
-        return null;
-    return {
-        roots: [path.resolve(options.homeDir ?? os.homedir())],
-        source: "prompt",
-        confirmed: true,
-        homeRootOptIn: true,
-    };
+    const homeDir = path.resolve(options.homeDir ?? os.homedir());
+    const answer = await requirePrompt(options).input(homeRootConsentPrompt(homeDir));
+    if (isHomeRootYes(answer)) {
+        return {
+            roots: [homeDir],
+            source: "prompt",
+            confirmed: true,
+            homeRootOptIn: true,
+        };
+    }
+    return promptForDeclinedHomeRoot(options, homeDir);
+}
+function isHomeRootYes(raw) {
+    const answer = raw.trim().split(/\s+/u)[0]?.toLowerCase() ?? "";
+    return answer === "y" || answer === "yes";
+}
+async function promptForDeclinedHomeRoot(options, homeDir) {
+    const prompt = requirePrompt(options);
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+        const answer = await prompt.input(HOME_ROOT_DECLINE_PATH_PROMPT);
+        const requestedRoot = answer.trim();
+        if (!requestedRoot) {
+            if (attempt < 2)
+                continue;
+            break;
+        }
+        const resolvedRoot = resolveRootInputPath(requestedRoot, homeDir, cwd);
+        if (isHomeRoot(resolvedRoot, homeDir))
+            break;
+        if (!(await directoryExists(resolvedRoot))) {
+            prompt.message?.(`That folder doesn't exist: ${resolvedRoot}`);
+            if (attempt < 2)
+                continue;
+            break;
+        }
+        const detailed = normalizeRootsDetailed([resolvedRoot], {
+            homeDir,
+            allowHomeRoot: options.allowHomeRoot,
+        });
+        if (detailed.roots.length > 0) {
+            return resolvedRoots(options, detailed.roots, "prompt", true);
+        }
+        explainRejectedRoots(options, withoutHomeRejections(detailed.rejected));
+        break;
+    }
+    prompt.message?.(HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE);
+    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE}`);
+}
+function resolveRootInputPath(input, homeDir, cwd) {
+    const expanded = input === "~" || input.startsWith("~/")
+        ? path.join(homeDir, input.slice(2))
+        : input;
+    return path.resolve(cwd, expanded);
 }
 function resolvedRoots(options, roots, source, confirmed) {
     const result = { roots, source, confirmed };
@@ -219,8 +253,21 @@ function resolvedRoots(options, roots, source, confirmed) {
     }
     return result;
 }
+// Canonicalize through realpath so a symlink pointing at $HOME can't slip past
+// the home-root guard on the decline path (e.g. `~/home-link -> /Users/me`).
+// Non-existent paths (or realpath errors) fall back to the lexical resolve so
+// behavior is unchanged for the retry branch and for tests using fake homedirs.
+function canonicalPath(input) {
+    const resolved = path.resolve(input);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
 function isHomeRoot(root, homeDir) {
-    return path.resolve(root) === path.resolve(homeDir ?? os.homedir());
+    return canonicalPath(root) === canonicalPath(homeDir ?? os.homedir());
 }
 function homeRootTutorial(homeDirInput) {
     const homeDir = path.resolve(homeDirInput ?? os.homedir());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
   "type": "module",
   "bin": {