@bli-cockpit/cli 0.2.109 → 0.2.111

package/dist/adapters/claude-attribution-score.js

@@ -88,7 +88,8 @@ export async function attributeOneSession(session, worktrees, collectionRoots) {
     }
     const primaryCwd = signals.cwds[0] ?? null;
     if (primaryCwd) {
-        base.cwd_basename = path.basename(primaryCwd) || null;
+        base.local_cwd = primaryCwd;
+        base.cwd_basename = (path.win32.isAbsolute(primaryCwd) ? path.win32 : path.posix).basename(primaryCwd) || null;
         base.cwd_hash = shortHash(primaryCwd);
     }
     if (signals.line_count === 0 || signals.parse_error_count === signals.line_count) {

package/dist/adapters/codex-attribution.js

@@ -199,7 +199,8 @@ async function attributeOneSession(file, worktrees, collectionRoots) {
     }
     const primaryCwd = signals.cwds[0] ?? null;
     if (primaryCwd) {
-        base.cwd_basename = path.basename(primaryCwd) || null;
+        base.local_cwd = primaryCwd;
+        base.cwd_basename = (path.win32.isAbsolute(primaryCwd) ? path.win32 : path.posix).basename(primaryCwd) || null;
         base.cwd_hash = shortHash(primaryCwd);
     }
     if (signals.line_count === 0 || signals.parse_error_count === signals.line_count) {

package/dist/commands/collection-roots.js

@@ -8,6 +8,7 @@
  * Split out of commands/local.ts (BLI-3104); moved verbatim.
  */
 import os from "node:os";
+import { scanWorkDirectories } from "./local-discovery.js";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
@@ -26,7 +27,10 @@ export async function resolveOnboardingRootsForCommand(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
     const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
     const interactive = !command.json && isInteractiveStdin(io);
+    const discovered = interactive && !command.collectionRoots?.length && !command.repoRoot && !existingConfig?.default_repo_paths.length
+        ? await scanWorkDirectories(command.homeDir ?? os.homedir()) : null;
     const rootsResult = await resolveOnboardingRoots({
+        suggestedRoots: discovered?.directories.map(entry => entry.directory),
         homeDir: command.homeDir,
         explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
         config: existingConfig,

package/dist/commands/doctor-access.js

@@ -1,3 +1,8 @@
+import os from "node:os";
+import { readRootWorkScan, outsideWorkDirectories, readRootApprovals, rootsAddCommand, rootPathApi } from "../root-work.js";
+import { writeJsonFile } from "../local-state-files.js";
+import { containsPath } from "../root-normalization.js";
+import { scanWorkDirectories } from "./local-discovery.js";
 import { sendCollectorHeartbeatBestEffort } from "./heartbeat.js";
 import { isInteractiveDoctorFix } from "./doctor-report.js";
 import { describeError } from "../health-detail.js";
@@ -150,4 +155,41 @@ function shellQuote(value) {
     if (value === "$PWD")
         return '"$PWD"';
     return `'${value.replace(/'/gu, "'\\''")}'`;
+}
+/** The last scan names work missed by the saved boundary. Diagnosis never grants consent. */
+export async function readRootsCoverWork(context) {
+    const homeDir = context.command.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    const scan = await readRootWorkScan(paths) ?? await scanWorkDirectories(homeDir, false);
+    const outside = outsideWorkDirectories(scan, (await readLocalCollectorConfig(paths))?.default_repo_paths ?? []);
+    const count = outside.reduce((sum, entry) => sum + entry.count, 0);
+    if (!count)
+        return ok("roots-cover-work", "work_covered", `${scan.observed} sessions seen; no known working directories outside approved roots.`);
+    return {
+        ...needsFix("roots-cover-work", "work_outside_roots", `${count} of ${scan.observed} sessions have working directories outside every approved root (scan ${scan.generated_at}):\n${outside.map(entry => `${entry.count}: ${entry.directory}\n  ${rootsAddCommand(entry.directory, process.platform, homeDir)}`).join("\n")}`),
+        nextAction: rootsAddCommand(outside[0].directory, process.platform, homeDir),
+    };
+}
+export async function fixRootsCoverWork(context) {
+    const homeDir = context.command.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    const config = await readLocalCollectorConfig(paths);
+    if (!config)
+        return readRootsCoverWork(context);
+    const scan = await readRootWorkScan(paths) ?? await scanWorkDirectories(homeDir);
+    const approvals = await readRootApprovals(paths);
+    const outside = outsideWorkDirectories(scan, config.default_repo_paths);
+    const additions = outside.filter(entry => approvals.some(root => containsPath(root, entry.directory, rootPathApi())));
+    if (additions.length) {
+        // Restore the precise approved directories, preserving every other config option.
+        const roots = normalizeCollectionRoots([...config.default_repo_paths, ...additions.map(entry => entry.directory)], rootPathApi());
+        await writeJsonFile(paths.config_file, { ...config, default_repo_paths: roots });
+        console.error("[doctor] roots-cover-work repaired", JSON.stringify({ added: additions.length }));
+        await scanWorkDirectories(homeDir);
+    }
+    else {
+        console.error("[doctor] roots-cover-work needs approval", JSON.stringify({ outside: outside.length, added: 0 }));
+    }
+    const checked = await readRootsCoverWork(context);
+    return { ...checked, fixed: additions.length > 0 && checked.status === "ok" };
 }

package/dist/commands/doctor-report.js

@@ -137,6 +137,7 @@ export function doctorNeedsPerson(rows, receipt) {
         "cli-latest": "npm i -g @bli-cockpit/cli && cockpit doctor",
         "authed": "cockpit doctor",
         "roots-ok": "cockpit doctor",
+        "roots-cover-work": "cockpit doctor",
         "single-install": "Run npm uninstall -g @bli-cockpit/cli with the Node installation that owns the extra CLI listed above.",
         "autostart-alive": "cockpit doctor",
         "memory-registered": "cockpit doctor",

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import { LOCAL_COLLECTOR_VERSION } from "../local-state.js";
 import { isSemverBelow } from "../scheduled-self-update.js";
 import { describeError } from "../health-detail.js";
 import { withStage } from "../crash-guard.js";
-import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
+import { checkSingleInstallState, readRootsCoverWork, fixRootsCoverWork, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.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";
@@ -119,6 +119,7 @@ function doctorInvariants() {
             fix: fixRootState,
             requiresInteractiveFix: true,
         },
+        { id: "roots-cover-work", check: context => context.deps.readRootsCoverWork(context), fix: context => context.deps.fixRootsCoverWork(context) },
         // Deliberately has NO fix: uninstalling software the operator did not ask
         // to have uninstalled is not a repair (BLI-3218/BLI-3553). Doctor names the
         // other install and the exact command; the person decides.
@@ -192,6 +193,8 @@ function defaultDoctorDeps(hooks) {
         readAuth: readAuthState,
         runLogin: (context) => hooks.runLogin(context.command, context.io),
         readRoots: readRootState,
+        readRootsCoverWork,
+        fixRootsCoverWork,
         resolveAndSaveRoots: (context) => hooks.resolveAndSaveRoots(context.command, context.io),
         checkSingleInstall: checkSingleInstallState,
         checkAutostart: checkAutostartState,

package/dist/commands/heartbeat.js

@@ -102,6 +102,7 @@ export function buildCollectorHeartbeat(options) {
         os_platform: platform,
         roots: collectionRootLabels(options.roots, platform),
         last_sync_status: options.facts.status,
+        ...(options.facts.outsideRootDirectories ? { outside_root_directories: options.facts.outsideRootDirectories } : {}),
         ...(options.facts.reason ? { last_sync_reason: options.facts.reason } : {}),
         ...(typeof options.facts.sessionsObserved === "number"
             ? { sessions_observed: options.facts.sessionsObserved }

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

@@ -1,13 +1,15 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
 export function parseUsageArgs(args) {
-    const values = parseNamedArgs(args, { allowedFlags: ["--min-confidence", "--by-topic", "--by-repo", "--person", "--all", "--since", "--until", "--include-automated", "--detail", "--home", "--dashboard-url", "--json"], valueFlags: ["--min-confidence", "--person", "--since", "--until", "--home", "--dashboard-url"] });
-    if (values.booleans.has("--by-repo") && values.booleans.has("--by-topic"))
-        throw new Error("--by-repo and --by-topic cannot be used together.");
+    const values = parseNamedArgs(args, { allowedFlags: ["--by-subject", "--subject", "--repo", "--session", "--from-window", "--min-confidence", "--by-topic", "--by-repo", "--person", "--all", "--since", "--until", "--include-automated", "--detail", "--home", "--dashboard-url", "--json"], valueFlags: ["--subject", "--repo", "--session", "--from-window", "--min-confidence", "--person", "--since", "--until", "--home", "--dashboard-url"] });
+    if (["--by-repo", "--by-topic", "--by-subject"].filter(flag => values.booleans.has(flag)).length > 1)
+        throw new Error("--by-repo and --by-topic cannot be used together or with --by-subject.");
     const minConfidence = values.flags.get("--min-confidence");
     if (minConfidence !== undefined && !["high", "medium", "low"].includes(minConfidence))
         throw new Error("--min-confidence accepts high, medium or low.");
     const action = values.positionals[0] ?? "people";
-    if (action !== "people" || values.positionals.length > 1)
-        throw new Error("usage takes one verb: people.");
-    return { kind: "usage", ...(minConfidence ? { minConfidence: minConfidence } : {}), byTopic: values.booleans.has("--by-topic"), byRepo: values.booleans.has("--by-repo"), person: optionalNonEmpty(values.flags.get("--person")), all: values.booleans.has("--all"), action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), detail: values.booleans.has("--detail"), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
+    if (!["people", "sessions"].includes(action) || values.positionals.length > 1)
+        throw new Error("usage takes people or sessions.");
+    if (action === "sessions" && !values.flags.get("--subject") && !values.flags.get("--session"))
+        throw new Error("usage sessions requires --subject or --session.");
+    return { bySubject: values.booleans.has("--by-subject"), subject: optionalNonEmpty(values.flags.get("--subject")), repo: optionalNonEmpty(values.flags.get("--repo")), session: optionalNonEmpty(values.flags.get("--session")), fromWindow: optionalNonEmpty(values.flags.get("--from-window")), kind: "usage", ...(minConfidence ? { minConfidence: minConfidence } : {}), byTopic: values.booleans.has("--by-topic"), byRepo: values.booleans.has("--by-repo"), person: optionalNonEmpty(values.flags.get("--person")), all: values.booleans.has("--all"), action: action, since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), detail: values.booleans.has("--detail"), 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.js

@@ -15,6 +15,7 @@
  * its own rate. Behavior-preserving extraction throughout: functions moved
  * verbatim, no logic change.
  */
+import { parseRootsArgs } from "./roots.js";
 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, parseUsageArgs, parseCareersArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
@@ -30,6 +31,7 @@ export { SCOUT_MIN_PREFIX_LENGTH, SLACK_WORKSPACE_KEYS, WORKBOOK_MIN_WIDTH, ISSU
 export function parseLocalArgs(argv) {
     const command = argv[0];
     switch (command) {
+        case "roots": return parseRootsArgs(argv.slice(1));
         case "onboard":
             return parseOnboardArgs(argv.slice(1));
         case "update":

package/dist/commands/local-discovery.js

@@ -112,4 +112,22 @@ function incompleteDiscoveryMessage(input) {
         "",
         "If the scan is still partial, raise the numbers again, or point --workspace at the specific project folders instead of a parent.",
     ].join("\n");
+}
+/** Reuse the session adapters for onboarding/doctor. No transcript bodies leave them. */
+export async function scanWorkDirectories(homeDir, persist = true) {
+    const [{ scanAndAttributeCodexSessions, defaultCodexSessionDirs }, { scanAndAttributeClaudeSessions }, { readLocalCollectorConfig, getCollectorRuntimePaths }, { saveRootWorkScan, workDirectories }] = await Promise.all([
+        import("../adapters/codex-attribution.js"), import("../adapters/claude-attribution.js"), import("../local-state.js"), import("../root-work.js"),
+    ]);
+    const paths = getCollectorRuntimePaths(homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(error => { if (error.code === "ENOENT")
+        return null; throw error; });
+    const now = new Date();
+    const options = { worktrees: [], collectionRoots: config?.default_repo_paths ?? [], now, sinceMinutes: 14 * 24 * 60, limit: Number.MAX_SAFE_INTEGER };
+    const codex = await scanAndAttributeCodexSessions({ ...options, sessionsDirs: defaultCodexSessionDirs(homeDir) });
+    const claude = config?.collect_claude_jsonl === false ? null : await scanAndAttributeClaudeSessions({ ...options, projectsDir: (await import("node:path")).default.join(homeDir, ".claude", "projects") });
+    if (codex.directory_read_failed_count || codex.stat_failed_count || claude?.project_dir_read_failed_count || claude?.session_stat_failed_count) {
+        throw new Error("work_directory_scan_incomplete");
+    }
+    const results = [...codex.results, ...(claude?.results ?? [])];
+    return persist ? saveRootWorkScan(paths, results, now) : { generated_at: now.toISOString(), observed: results.length, directories: workDirectories(results) };
 }

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

@@ -143,7 +143,10 @@ export const TOWER_COMMAND_HELP = [
     [
         "usage",
         [
-            "Usage: cockpit usage people [--by-repo | --by-topic] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--since <n>d|<n>h|<iso>] [--detail] [--until <iso>] [--include-automated] [--json]",
+            "Usage: cockpit usage people [--by-repo | --by-topic | --by-subject] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--since <n>d|<n>h|<iso>] [--detail] [--until <iso>] [--include-automated] [--json]",
+            "  cockpit usage sessions --subject <name> [--repo <label>] [--since <window>] [--json]",
+            "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
+            "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",
             "",
             "--by-topic adds topic rows, including (unlabelled). Choose only one grouping. --by-repo adds project rows under each person (top 10; --all shows every repo). --person me uses your signed-in email.",
             "Claude Code and Codex usage per person: sessions observed and extracted, tokens (total, output,",

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

@@ -21,6 +21,7 @@ import { localCommandHelp } from "./local-help.js";
 import { TOWER_COMMAND_HELP } from "./local-help-commands-tower.js";
 export function localSubcommandHelp(command) {
     const helpByCommand = new Map([
+        ["roots", ["Usage: cockpit roots add <dir> [--allow-home-root] [--json]", "Approves a work directory, saves an approval receipt, and adds it to collection. Run cockpit doctor afterward."]],
         // BLI-3709: the Tower nouns live next door, split along the same seam the
         // argument parsers already use — see `local-help-commands-tower.ts`.
         ...TOWER_COMMAND_HELP,
@@ -89,6 +90,7 @@ export function localSubcommandHelp(command) {
                 "",
                 "Diagnose, repair, and verify this machine.",
                 "Repairs CLI, background sync, sign-in, roots, memory and hooks, agent rules, catch-up, uploads, and cleanup.",
+                "roots-cover-work names sessions outside saved roots and gives cockpit roots add commands. Previously approved directories are restored automatically.",
                 "--check or --no-repair diagnoses without repairs. --dry-run previews repairs.",
                 "--backfill-budget defaults to 900 seconds; catch-up repeats chunks until complete, with progress every 30 seconds.",
                 "--lock-wait defaults to 600 seconds; progress prints every 30 seconds.",

package/dist/commands/local-help.js

@@ -11,6 +11,7 @@ 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([
+    "roots",
     "onboard",
     "update",
     "upgrade",
@@ -61,6 +62,7 @@ export function localCommandHelp(command) {
     if (command)
         return localSubcommandHelp(command);
     return [
+        "  cockpit roots add <dir> [--allow-home-root] [--json]",
         "  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]",
@@ -102,7 +104,10 @@ export function localCommandHelp(command) {
         `  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 [--by-repo | --by-topic] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
+        "  cockpit usage sessions --subject <name> [--repo <label>] [--since <window>] [--json]",
+        "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
+        "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",
+        "  cockpit usage people [--by-repo | --by-topic | --by-subject] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<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");

package/dist/commands/local.js

@@ -54,6 +54,7 @@ export { buildCollectorHeartbeat, collectionRootLabel, collectionRootLabels, sen
 export { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, SYNC_ERROR_DETAIL_MAX_CHARS, } from "./install-receipts.js";
 export { assertCollectionRootPersisted } from "./collection-roots.js";
 export { runSelfUpdate, SelfUpdateError, } from "./install-update.js";
+import { runRoots } from "./roots.js";
 export async function runLocalCockpitCli(argv, io = defaultIo()) {
     if (isLocalHelpRequest(argv)) {
         writeLine(io.stdout, localCommandHelp(argv[0]));
@@ -85,6 +86,7 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
     beginStage(`command:${command.kind}`);
     try {
         switch (command.kind) {
+            case "roots": return await runRoots(command, io);
             case "install":
                 return await runInstall(command, io);
             case "onboard":

package/dist/commands/public-root.js

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

package/dist/commands/roots.js

@@ -0,0 +1,41 @@
+import os from "node:os";
+import { stat } from "node:fs/promises";
+import { getCollectorRuntimePaths, ensureLocalCollectorConfig } from "../local-state.js";
+import { normalizeRootsDetailed } from "../onboarding-roots.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { recordRootApprovals } from "../root-work.js";
+import { writeJsonFile } from "../local-state-files.js";
+import { writeLine } from "./cli-io.js";
+export function parseRootsArgs(args) {
+    const [action, directory, ...flags] = args;
+    if (action !== "add" || !directory || directory.startsWith("--"))
+        throw new Error("Usage: cockpit roots add <dir> [--allow-home-root] [--json]");
+    let homeDir;
+    for (let index = 0; index < flags.length; index++) {
+        const flag = flags[index];
+        if (flag === "--home-dir" && flags[index + 1]) {
+            homeDir = flags[++index];
+            continue;
+        }
+        if (flag !== "--json" && flag !== "--allow-home-root")
+            throw new Error(`Unknown roots flag: ${flag}`);
+    }
+    return { kind: "roots", action, directory, homeDir, json: flags.includes("--json"), allowHomeRoot: flags.includes("--allow-home-root") };
+}
+export async function runRoots(command, io) {
+    const homeDir = command.homeDir ?? os.homedir();
+    const { roots, rejected } = normalizeRootsDetailed([command.directory], { homeDir, allowHomeRoot: command.allowHomeRoot });
+    if (!roots.length || rejected.length)
+        throw new Error("Choose a work directory, or pass --allow-home-root to approve your home folder.");
+    for (const root of roots)
+        if (!(await stat(root)).isDirectory())
+            throw new Error("Collection root must be a directory.");
+    const paths = getCollectorRuntimePaths(homeDir);
+    const config = (await ensureLocalCollectorConfig({ homeDir })).config;
+    const updated = { ...config, default_repo_paths: normalizeCollectionRoots([...config.default_repo_paths, ...roots]) };
+    await recordRootApprovals(paths, [...config.default_repo_paths, ...roots]);
+    await writeJsonFile(paths.config_file, updated);
+    console.error("[roots] added", JSON.stringify({ added: roots.length, roots: updated.default_repo_paths.length }));
+    writeLine(io.stdout, command.json ? JSON.stringify({ ok: true, roots: updated.default_repo_paths }) : `Approved roots: ${updated.default_repo_paths.join(", ")}. Run cockpit doctor to collect the work there.`);
+    return 0;
+}

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

@@ -9,6 +9,8 @@
  * that writes the closed-registry LABEL the health receipt is classified by.
  * Nothing here parses a rendered sentence back apart.
  */
+import { collectionRootLabel } from "./heartbeat.js";
+import { workDirectories } from "../root-work.js";
 import { createSyncFailureLedger, recordSourceScanFailures, recordUnexplainedFailure, recordUnpostedSessionReportFailure, recordWorktreeDeliveryFailures, } from "./session-sync-failures.js";
 import { countSessionsNewThisTick, countSessionsPendingUpload, } from "./session-sync-counters.js";
 import { logDeliveryHold, summarizeDeliveryHold } from "./session-sync-hold.js";
@@ -60,6 +62,9 @@ export function decideSyncHealth(options) {
         notice,
         hold,
         sessions_outside_root: sessionsOutsideRoot,
+        outside_root_directories: workDirectories([...(options.scan.codexAttribution.results ?? []), ...(options.scan.claudeAttribution.results ?? [])].filter(result => OUTSIDE_APPROVED_ROOT_REASONS.has(result.reason)))
+            .map(entry => ({ ...collectionRootLabel(entry.directory), count: entry.count }))
+            .filter(entry => entry.basename.length > 0 && !/[\\/]/u.test(entry.basename)).slice(0, 40),
         sessions_new_this_tick: countSessionsNewThisTick({
             sessions: options.sessions,
             codexCursorBefore: options.plan.codexCursorBefore,

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

@@ -8,6 +8,7 @@
  * `repo_not_on_disk` widens the next window and never fails a sync.
  */
 import path from "node:path";
+import { saveRootWorkScan } from "../root-work.js";
 import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions, } from "../adapters/claude-attribution.js";
 import { CLAUDE_CURSOR_FILENAME } from "../cursors/raw-evidence-cursor.js";
@@ -61,6 +62,7 @@ export async function scanAndAttributeBothSources(options) {
             reason: sourceScanRetryReason("claude_code", claudeAttribution),
         });
     }
+    await saveRootWorkScan(options.paths, [...codexAttribution.results, ...claudeAttribution.results], options.now);
     return { codexAttribution, claudeAttribution, firstRunBackfill };
 }
 /**

package/dist/commands/session-sync.js

@@ -133,6 +133,7 @@ export async function runAttributedWorktreeSync(options) {
         hold: health.hold,
         sessions_observed: sessions.length,
         sessions_outside_root: health.sessions_outside_root,
+        outside_root_directories: health.outside_root_directories,
         sessions_new_this_tick: health.sessions_new_this_tick,
         sessions_pending_upload: health.sessions_pending_upload,
         outcomes: worktreePass.outcomes,

package/dist/commands/sync-receipt.js

@@ -147,6 +147,7 @@ function heartbeatCounts(run) {
     return {
         sessionsObserved: run.sessionsObserved,
         sessionsOutsideRoot: run.sessionsOutsideRoot,
+        outsideRootDirectories: run.outsideRootDirectories,
         sessionsNewThisTick: run.sessionsNewThisTick,
         sessionsPendingUpload: run.sessionsPendingUpload,
     };

package/dist/commands/sync-report.js

@@ -155,6 +155,7 @@ function syncResult(run) {
         holdNotice: run.hold?.notice ?? null,
         sessionsObserved: run.sessions_observed,
         sessionsOutsideRoot: run.sessions_outside_root,
+        outsideRootDirectories: run.outside_root_directories,
         sessionsNewThisTick: run.sessions_new_this_tick,
         sessionsPendingUpload: run.sessions_pending_upload,
     };

package/dist/commands/usage.js

@@ -5,6 +5,8 @@ import { writeLine } from "./cli-io.js";
 export async function runUsage(command, io) {
     const door = await openAgentDoor("usage", command, io);
     const query = new URLSearchParams({ since: command.since });
+    if (command.bySubject)
+        query.set("groupBy", "topic");
     if (command.minConfidence)
         query.set("minConfidence", command.minConfidence);
     if (command.byTopic)
@@ -15,6 +17,21 @@ export async function runUsage(command, io) {
         query.set("until", command.until);
     if (command.includeAutomated)
         query.set("include_automated", "1");
+    if (command.action === "sessions") {
+        for (const [key, value] of [["subject", command.subject], ["repo", command.repo], ["session", command.session], ["fromWindow", command.fromWindow]])
+            if (value)
+                query.set(key, value);
+        const response = await askAgentDoor(door, { path: `/api/usage/sessions?${query}`, method: "GET", label: "usage sessions", timeoutMs: 30_000 });
+        if (!response.ok)
+            return failAgentDoor(door, "[usage]", response.reason, response.detail);
+        if (door.json || command.session)
+            return emitAgentDoor(door, response.body);
+        const sessions = response.body.sessions ?? [];
+        for (const session of sessions)
+            writeLine(io.stdout, `${session.session_id}  ${formatCount(session.tokens)}  ${session.task_type}  ${session.title}`);
+        writeLine(io.stdout, `${sessions.length} sessions`);
+        return 0;
+    }
     const answer = await askAgentDoor(door, { path: `/api/usage/people?${query}`, method: "GET", label: "usage people", timeoutMs: 30_000 });
     if (!answer.ok)
         return failAgentDoor(door, "[usage]", answer.reason, answer.detail);
@@ -31,6 +48,8 @@ export async function runUsage(command, io) {
     }
     if (command.byTopic && body.people?.some((person) => !Array.isArray(person.task_types)))
         return failAgentDoor(door, "[usage]", "topic_grouping_unavailable", "The dashboard returned person totals without topic rows. Deploy the dashboard topic split before using --by-topic.");
+    if (command.bySubject && body.people?.some(person => !Array.isArray(person.subjects)))
+        return failAgentDoor(door, "[usage]", "subject_grouping_unavailable", "Deploy the dashboard subject split before using --by-subject.");
     if (door.json)
         return emitAgentDoor(door, body);
     let nameWidth = 20;
@@ -41,6 +60,13 @@ export async function runUsage(command, io) {
                 nameWidth = Math.max(nameWidth, repo.repo_label.length + 2);
         }
     }
+    if (command.bySubject)
+        for (const person of body.people ?? [])
+            for (const subject of person.subjects ?? []) {
+                nameWidth = Math.max(nameWidth, subject.repo_label.length + subject.topic.length + 5);
+                for (const sub of subject.children ?? [])
+                    nameWidth = Math.max(nameWidth, sub.subtopic.length + 4);
+            }
     const widths = [nameWidth, 8, 15, 12, 10, 10, 12, 14];
     const printRow = (cells) => writeLine(io.stdout, cells.map((cell, index) => index === 0 ? cell.padEnd(widths[index]) : cell.padStart(widths[index])).join("  ").trimEnd());
     printRow(["Person", "Tokens", "List equivalent", "Coverage", ...(command.detail ? ["Output", "Input", "Cache read", "Cache creation"] : [])]);
@@ -52,6 +78,12 @@ export async function runUsage(command, io) {
             `${row.sessions_extracted}/${row.sessions_observed}`,
             ...(command.detail ? [row.output_tokens, row.input_tokens, row.cache_read_input_tokens, row.cache_creation_input_tokens].map(formatCount) : []),
         ]);
+        if (command.bySubject)
+            for (const subject of row.subjects ?? []) {
+                printRow([`  ${subject.repo_label} / ${subject.topic}`, formatCount(subject.tokens), formatUsageDollars(subject.api_list_price_equivalent_usd), `${subject.extracted_sessions}/${subject.sessions}`, ...(command.detail ? [subject.output, subject.input, subject.cache_read, subject.cache_creation].map(formatCount) : [])]);
+                for (const sub of subject.children ?? [])
+                    printRow([`    ${sub.subtopic}`, formatCount(sub.tokens), formatUsageDollars(sub.api_list_price_equivalent_usd), `${sub.extracted_sessions}/${sub.sessions}`, ...(command.detail ? [sub.output, sub.input, sub.cache_read, sub.cache_creation].map(formatCount) : [])]);
+            }
         if (command.byRepo || command.byTopic) {
             const repos = (command.byTopic ? row.task_types : row.repos) ?? [];
             for (const repo of command.all ? repos : repos.slice(0, 10)) {
@@ -66,6 +98,8 @@ export async function runUsage(command, io) {
     writeLine(io.stdout, "");
     writeLine(io.stdout, body.api_list_price_equivalent_label ?? "API list-price equivalent (not actual spend)");
     writeLine(io.stdout, `${body.coverage?.sessions_extracted ?? 0} of ${body.coverage?.sessions_observed ?? 0} sessions extracted`);
+    if (command.bySubject)
+        writeLine(io.stdout, `${(body.people ?? []).reduce((n, person) => n + (person.sessions_summarized ?? 0), 0)} of ${body.coverage?.sessions_observed ?? 0} sessions summarized`);
     if (command.byTopic)
         writeLine(io.stdout, `${body.coverage?.sessions_labelled ?? 0} of ${body.coverage?.sessions_observed ?? 0} sessions labelled by topic`);
     return 0;

package/dist/local-state-config.js

@@ -1,5 +1,6 @@
 import { LocalCollectorConfigSchema, } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
+import { recordRootApprovals } from "./root-work.js";
 import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -44,6 +45,7 @@ export async function installLocalCollector(options = {}) {
         session_file_path: paths.session_file,
         state_dir_path: paths.state_dir,
     });
+    await recordRootApprovals(paths, defaultRepoPaths, options.replaceRepoRoots);
     await writeJsonFile(paths.config_file, config);
     return {
         config,

package/dist/onboarding-roots.js

@@ -64,6 +64,10 @@ export async function resolveOnboardingRoots(options) {
         }
         return promptForRoots(options, "Collection root(s), comma-separated: ");
     }
+    const suggestions = normalizeRootsDetailed(options.suggestedRoots ?? [], { homeDir: options.homeDir, allowHomeRoot: options.allowHomeRoot }).roots;
+    if (options.interactive && suggestions.length > 0 && await requirePrompt(options).confirm(`Sessions were found in:\n${suggestions.join("\n")}\nCollect from these folders? [Y/n] `)) {
+        return resolvedRoots(options, suggestions, "prompt", true);
+    }
     const cwd = path.resolve(options.cwd ?? process.cwd());
     if (isHomeRoot(cwd, options.homeDir)) {
         const homeDir = path.resolve(options.homeDir ?? os.homedir());

package/dist/root-work.js

@@ -0,0 +1,70 @@
+/** Local directory evidence and explicit root approvals. Full paths stay here. */
+import path from "node:path";
+import { z } from "zod";
+import { readJsonFile, writeJsonFile, isMissingFileError } from "./local-state-files.js";
+import { containsPath, normalizeCollectionRoots } from "./root-normalization.js";
+const DirectorySchema = z.object({ directory: z.string(), count: z.number().int().nonnegative() });
+const ScanSchema = z.object({ generated_at: z.string(), observed: z.number(), directories: z.array(DirectorySchema) });
+export const rootPathApi = (platform = process.platform) => platform === "win32" ? path.win32 : path.posix;
+export function workDirectories(results, platform = process.platform) {
+    const api = rootPathApi(platform);
+    const counts = new Map();
+    for (const result of results) {
+        if (!result.local_cwd || !api.isAbsolute(result.local_cwd))
+            continue;
+        const directory = api.resolve(result.local_cwd);
+        const key = platform === "win32" ? directory.toLowerCase() : directory;
+        const entry = counts.get(key) ?? { directory, count: 0 };
+        entry.count += 1;
+        counts.set(key, entry);
+    }
+    return [...counts.values()].sort((a, b) => b.count - a.count || a.directory.localeCompare(b.directory));
+}
+export function outsideWorkDirectories(scan, roots, platform = process.platform) {
+    return scan.directories.filter(({ directory }) => !roots.some(root => containsPath(root, directory, rootPathApi(platform))));
+}
+export async function saveRootWorkScan(paths, results, now) {
+    const scan = { generated_at: now.toISOString(), observed: results.length, directories: workDirectories(results) };
+    try {
+        await writeJsonFile(path.join(paths.state_dir, "root-work-scan.json"), scan);
+    }
+    catch (error) {
+        console.error("[roots] work scan cache failed", JSON.stringify({ reason: "scan_cache_write_failed", error_name: error instanceof Error ? error.name : "unknown" }));
+        return scan;
+    }
+    console.error("[roots] work scan recorded", JSON.stringify({ observed: scan.observed, directories: scan.directories.length }));
+    return scan;
+}
+export async function readRootWorkScan(paths) {
+    try {
+        return ScanSchema.parse(await readJsonFile(path.join(paths.state_dir, "root-work-scan.json")));
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return null;
+        throw error;
+    }
+}
+const ApprovalsSchema = z.object({ approved_at: z.string(), roots: z.array(z.string()) });
+export async function readRootApprovals(paths) {
+    try {
+        return ApprovalsSchema.parse(await readJsonFile(path.join(paths.config_dir, "root-approvals.json"))).roots;
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return [];
+        throw error;
+    }
+}
+export async function recordRootApprovals(paths, roots, replace = false) {
+    const previous = replace ? [] : await readRootApprovals(paths);
+    const approved = normalizeCollectionRoots([...previous, ...roots]);
+    await writeJsonFile(path.join(paths.config_dir, "root-approvals.json"), { approved_at: new Date().toISOString(), roots: approved });
+    console.error("[roots] approval recorded", JSON.stringify({ roots: approved.length, replaced: replace }));
+}
+export function rootsAddCommand(directory, platform = process.platform, homeDir) {
+    // Native Windows command is for PowerShell; POSIX quoting is for zsh/bash.
+    const escaped = platform === "win32" ? directory.replace(/'/gu, "''") : directory.replace(/'/gu, "'\\''");
+    const homeFlag = homeDir && rootPathApi(platform).relative(homeDir, directory) === "" ? " --allow-home-root" : "";
+    return `cockpit roots add '${escaped}'${homeFlag}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.109",
+  "version": "0.2.111",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.28",
-    "@bli-cockpit/mcp": "0.1.37",
-    "@bli-cockpit/telemetry-core": "0.1.44"
+    "@bli-cockpit/memory-mcp": "0.1.29",
+    "@bli-cockpit/mcp": "0.1.39",
+    "@bli-cockpit/telemetry-core": "0.1.45"
   }
 }