@indigoai-us/hq-cli 5.345.54 → 5.345.56

package/dist/commands/cloud.js

@@ -139,6 +139,9 @@ export async function withSyncHealthReport(run) {
  * nothing was scope-excluded. Keeping this pure makes the "never silently
  * succeed when files were dropped" guarantee unit-testable.
  */
+export function scopeExcludedExitCode(count) {
+    return count > 0 ? 1 : 0;
+}
 export function scopeExcludedWarning(count) {
     if (count <= 0)
         return null;
@@ -147,6 +150,19 @@ export function scopeExcludedWarning(count) {
         `They were skipped, not synced. Re-run with --json to list them, or ` +
         `ask an admin to grant you write on those paths.`);
 }
+/** Actionable recovery for files refused because the vault baseline is stale. */
+export function staleUploadRefusalLines(count, paths = []) {
+    if (count <= 0)
+        return [];
+    const lines = [
+        `⚠ ${count} file(s) were NOT uploaded because the vault copy changed after your edit. ` +
+            `Pull the current vault copy, merge your edit, and push again.`,
+    ];
+    if (paths.length > 0) {
+        lines.push("  Not uploaded:", ...paths.map((filePath) => `  - ${filePath}`));
+    }
+    return lines;
+}
 /**
  * Optional detail line listing the effective write prefixes when a push
  * dropped files — helps debug ACL vs scope-excluded mismatches (feedback_7e9c535e).
@@ -176,7 +192,7 @@ export function scopeExcludedLines(count, prefixSet) {
             `⚠ ${count} file(s) were NOT uploaded — the server refused them. ` +
                 `A common cause is a file someone else created in a private folder ` +
                 `(foo/): only its creator can change it. They were skipped, not ` +
-                `synced. Re-run with --json to list them.`,
+                `synced. Re-run with --json to list them, or ask its creator to grant access.`,
         ];
     }
     const lines = [scopeExcludedWarning(count)];
@@ -527,6 +543,12 @@ export async function pushAll(options, deps) {
             result.bytesUploaded += r.bytesUploaded;
             result.filesDeleted += r.filesDeleted;
             result.filesExcludedByScope += r.filesExcludedByScope;
+            if ((r.filesRefusedStale ?? 0) > 0) {
+                result.filesRefusedStale =
+                    (result.filesRefusedStale ?? 0) + (r.filesRefusedStale ?? 0);
+                result.filesRefusedStalePaths ??= [];
+                result.filesRefusedStalePaths.push(...(r.filesRefusedStalePaths ?? []));
+            }
             result.perCompany.push({
                 slug: entry.slug,
                 result: r,
@@ -977,6 +999,17 @@ export function registerCloudCommands(program) {
                 ...(pushPrefixSet !== undefined ? { prefixSet: pushPrefixSet } : {}),
             });
             const planLimitRefused = planLimitTracker.summary();
+            const staleRefusalCount = result.filesRefusedStale ?? 0;
+            const refusalRecovery = [
+                result.filesExcludedByScope > 0
+                    ? "Check write access for the refused path; ask its creator or a company admin to grant access."
+                    : null,
+                staleRefusalCount > 0
+                    ? "Pull the current vault copy, merge your edit, and push again."
+                    : null,
+            ]
+                .filter((message) => message !== null)
+                .join(" ");
             if (jsonMode) {
                 // Synthetic terminal event so subprocess consumers can read final
                 // counts without summing per-file events. Distinguished from
@@ -991,6 +1024,10 @@ export function registerCloudCommands(program) {
                     filesSkipped: result.filesSkipped,
                     conflictPaths: result.conflictPaths,
                     aborted: result.aborted,
+                    filesExcludedByScope: result.filesExcludedByScope,
+                    filesRefusedStale: staleRefusalCount,
+                    filesRefusedStalePaths: result.filesRefusedStalePaths ?? [],
+                    ...(refusalRecovery ? { refusalRecovery } : {}),
                     ...(planLimitRefused ? { planLimitRefused } : {}),
                 });
             }
@@ -1019,22 +1056,32 @@ export function registerCloudCommands(program) {
                 for (const line of scopeExcludedLines(result.filesExcludedByScope, pushPrefixSet)) {
                     log(chalk.yellow(line));
                 }
+                for (const line of staleUploadRefusalLines(result.filesRefusedStale ?? 0, result.filesRefusedStalePaths)) {
+                    log(chalk.yellow(line));
+                }
                 await syncHealth.succeeded();
-                if (!jsonMode)
-                    process.exit(1);
+                process.exit(1);
                 return;
             }
-            if (result.filesExcludedByScope > 0) {
+            if (result.filesExcludedByScope > 0 || staleRefusalCount > 0) {
                 log(chalk.yellow(`\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
-                    `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`));
+                    `${result.filesSkipped} skipped, ${result.filesExcludedByScope + staleRefusalCount} files not uploaded)`));
                 for (const line of scopeExcludedLines(result.filesExcludedByScope, pushPrefixSet)) {
                     log(chalk.yellow(line));
                 }
+                for (const line of staleUploadRefusalLines(staleRefusalCount, result.filesRefusedStalePaths)) {
+                    log(chalk.yellow(line));
+                }
             }
             else {
                 log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
             }
             await syncHealth.succeeded();
+            const exitCode = scopeExcludedExitCode(result.filesExcludedByScope + staleRefusalCount);
+            if (exitCode !== 0) {
+                process.exit(exitCode);
+                return;
+            }
         }
         catch (err) {
             if (syncHealth)
@@ -1630,13 +1677,13 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         else if (row.result) {
             const r = row.result;
             const legRefused = r.planLimit ?? null;
-            const status = r.aborted || r.filesExcludedByScope > 0 || legRefused
+            const status = r.aborted || r.filesExcludedByScope > 0 || (r.filesRefusedStale ?? 0) > 0 || legRefused
                 ? chalk.yellow("⚠")
                 : chalk.green("✓");
             console.log(`  ${status} ${row.slug}: ${r.filesUploaded} file(s), ` +
                 `${formatBytes(r.bytesUploaded)}, ${r.filesSkipped} skipped, ` +
                 `${r.filesDeleted} deleted, ${r.filesExcludedByScope} scope-excluded, ` +
-                `${r.conflictPaths.length} conflict(s)` +
+                `${r.filesRefusedStale ?? 0} stale-refused, ${r.conflictPaths.length} conflict(s)` +
                 (r.aborted ? " — aborted" : "") +
                 (legRefused
                     ? ` — ${describeRefusedCount(legRefused)} refused by plan limit`
@@ -1652,7 +1699,8 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     const summary = `\nPushed ${result.filesUploaded} file(s) ` +
         `(${formatBytes(result.bytesUploaded)}) across ${result.attempted} ` +
         `target(s); ${result.filesDeleted} deleted; ${errored} error(s); ` +
-        `${result.filesExcludedByScope} scope-excluded` +
+        `${result.filesExcludedByScope} scope-excluded; ` +
+        `${result.filesRefusedStale ?? 0} stale-refused` +
         (refusedTargets > 0
             ? `; new files refused by a plan limit on ${refusedTargets} target(s)`
             : "");
@@ -1673,10 +1721,24 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         for (const line of scopeExcludedLines(excluded, row.prefixSet)) {
             console.log(chalk.yellow(`${row.slug}: ${line}`));
         }
+        const staleCount = row.result?.filesRefusedStale ?? 0;
+        for (const line of staleUploadRefusalLines(staleCount, row.result?.filesRefusedStalePaths)) {
+            console.log(chalk.yellow(`${row.slug}: ${line}`));
+        }
     }
     if (errored > 0)
         throw new SyncExitError(1);
-    return refused;
+    const refusalSummary = {
+        planLimitRefused: refused,
+        filesExcludedByScope: result.filesExcludedByScope,
+        filesRefusedStale: result.filesRefusedStale ?? 0,
+        filesRefusedStalePaths: [...new Set(result.filesRefusedStalePaths ?? [])],
+    };
+    return (refusalSummary.planLimitRefused ||
+        refusalSummary.filesExcludedByScope > 0 ||
+        refusalSummary.filesRefusedStale > 0
+        ? refusalSummary
+        : null);
 }
 async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Now"));
@@ -1763,7 +1825,10 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             ...(nowPushPrefixSet !== undefined ? { prefixSet: nowPushPrefixSet } : {}),
         });
         const pushRefused = planLimitTracker.summary();
-        const pushStatus = pushResult.aborted || pushResult.filesExcludedByScope > 0 || pushRefused
+        const pushStatus = pushResult.aborted ||
+            pushResult.filesExcludedByScope > 0 ||
+            (pushResult.filesRefusedStale ?? 0) > 0 ||
+            pushRefused
             ? chalk.yellow("⚠")
             : chalk.green("✓");
         console.log(`    ${pushStatus} ` +
@@ -1780,6 +1845,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 console.log(chalk.yellow(line));
             }
         }
+        for (const line of staleUploadRefusalLines(pushResult.filesRefusedStale ?? 0, pushResult.filesRefusedStalePaths)) {
+            console.log(chalk.yellow(line));
+        }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             throw new SyncExitError(1);
@@ -1900,6 +1968,11 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 "refused by your plan limit (listed above)."));
             throw new SyncExitError(1, { health: "succeeded" });
         }
+        if (pushResult.filesExcludedByScope > 0 ||
+            (pushResult.filesRefusedStale ?? 0) > 0) {
+            console.log(chalk.yellow("\n⚠ Sync now finished, but one or more requested uploads were refused."));
+            throw new SyncExitError(1, { health: "succeeded" });
+        }
         console.log(chalk.green("\n✓ Sync now complete"));
         if (!personalMode &&
             nudgeResolvedCompanyUid &&
@@ -1943,13 +2016,16 @@ async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPerso
     // pull-side).
     await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, forceScopeShrink);
     if (refused) {
-        // A plan-limit refusal does not stop the pull, but the run must not end
-        // looking like a clean sync: say so last and exit non-zero.
-        console.log(chalk.yellow(`\n⚠ Sync finished, but ${describeRefusedFiles(refused)} refused ` +
-            "by your plan limit (listed under push --all above)."));
-        if (refused.upgradeUrl) {
-            console.log(chalk.yellow(`  Upgrade: ${refused.upgradeUrl}`));
+        // A refused push does not stop the pull, but the run must not end looking
+        // like a clean sync. Its per-target details were printed above.
+        if (refused.planLimitRefused) {
+            console.log(chalk.yellow(`\n⚠ Sync finished, but ${describeRefusedFiles(refused.planLimitRefused)} refused ` +
+                "by your plan limit (listed under push --all above)."));
+            if (refused.planLimitRefused.upgradeUrl) {
+                console.log(chalk.yellow(`  Upgrade: ${refused.planLimitRefused.upgradeUrl}`));
+            }
         }
+        console.log(chalk.yellow("\n⚠ Sync finished, but one or more requested uploads were refused."));
         throw new SyncExitError(1, { health: "succeeded" });
     }
 }

package/dist/commands/core-delegate-w1b.js

@@ -11,6 +11,8 @@ import { commandExists, delegateDiagnosticPath, isRecord, jsonAt, jqFallback, jq
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { ACL_SOURCE_DISPLAY_LABELS } from "../utils/files-browse-acl.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
+import { resolveWindowsBash } from "../utils/windows-bash.js";
+import { createShellCompatibleJqInvoker } from "../utils/jq-windows-compat.js";
 const FLAG = "core-native-delegate";
 const ASSETS = {
     bundle: "core/scripts/hq-delegate-bundle.sh",
@@ -367,6 +369,13 @@ function runBundle(args, context, onMalformedWhoami) {
 function runHq(args, context, stdout = "capture") {
     return subprocess("hq", args, context.cwd, { stdout });
 }
+const runJq = createShellCompatibleJqInvoker((args, input, cwd, options) => subprocess("jq", args, cwd, { input, ...options }), process.platform, process.env, (cwd) => {
+    const bash = resolveWindowsBash(process.env).executable;
+    if (!bash)
+        return undefined;
+    const result = subprocess(bash, ["-c", "printf '%s' \"$OSTYPE\""], cwd, { stderr: "ignore" });
+    return result.code === 0 ? result.stdout?.trim() : undefined;
+});
 function commandSubstitutionBytes(value) {
     const bytes = value.stdoutBytes ?? Buffer.from(value.stdout ?? "");
     let end = bytes.length;
@@ -377,11 +386,15 @@ function commandSubstitutionBytes(value) {
 function emitJqParseDiagnostic(input, args, context) {
     if (!commandExists("jq", context.cwd))
         return;
-    const result = subprocess("jq", args, context.cwd, { input, stdout: "ignore", stderr: "pipe" });
-    const rawDiagnostic = result.stderrBytes ?? Buffer.from(result.stderr ?? "");
-    const diagnostic = process.platform === "win32"
-        ? Buffer.from(rawDiagnostic.toString("latin1").replace(/\r(?=\n|$)/g, ""), "latin1")
-        : rawDiagnostic;
+    // cmd.exe cannot pass CR, LF, or NUL inside an argument. jq treats line
+    // breaks between tokens as whitespace, and these fixed filters contain no
+    // multiline string literals, so send the program as one argument on Windows.
+    const jqArgs = [...args];
+    const programIndex = jqArgs.length - 1;
+    if (programIndex >= 0)
+        jqArgs[programIndex] = (jqArgs[programIndex] ?? "").replace(/[\r\n\0]+/gu, " ");
+    const result = runJq(jqArgs, input, context.cwd, { stdout: "ignore", stderr: "pipe" });
+    const diagnostic = result.stderrBytes ?? Buffer.from(result.stderr ?? "");
     if (diagnostic.length)
         err(diagnostic);
 }

package/dist/commands/core-derive-trigger-facts-command.js

@@ -13,6 +13,20 @@ export function registerCoreDeriveTriggerFactsCommand(core) {
         .helpOption(false)
         .argument("[args...]")
         .action(async (args = [], _options, commandContext) => {
+        if (process.env.HQ_CORE_STDIN_CLOSED === "1") {
+            const root = liveRoot();
+            const result = runBundledScript({
+                asset: DERIVE_TRIGGER_FACTS_ASSET,
+                args: commandContext.args.length ? commandContext.args : args,
+                cwd: root,
+                hqRoot: root,
+                msysScriptPath: process.platform === "win32",
+                closeStdin: true,
+            });
+            if (result.code !== 0)
+                process.exit(result.code);
+            return;
+        }
         if (!await coreNativeHookHelpersEnabled()) {
             const root = liveRoot();
             const stdin = process.platform === "win32" ? await readStdin() : undefined;

package/dist/commands/core-derive-trigger-facts-native.d.ts

@@ -20,4 +20,5 @@ export declare function commandOnPath(command: string, env: Record<string, strin
 /** Run the native handler contract, retaining exact bytes for differential tests. */
 export declare function runDeriveTriggerFacts(options: DeriveTriggerRunOptions): DeriveTriggerRunResult;
 export declare function runDeriveTriggerFactsFast(argv: readonly string[], stdin: string, cwd: string, hqRoot: string | undefined): number;
+export declare function runDeriveTriggerFactsFastResult(argv: readonly string[], stdin: string, cwd: string, hqRoot: string | undefined): DeriveTriggerRunResult;
 //# sourceMappingURL=core-derive-trigger-facts-native.d.ts.map

package/dist/commands/core-derive-trigger-facts-native.js

@@ -583,11 +583,30 @@ export function runDeriveTriggerFacts(options) {
     }
 }
 export function runDeriveTriggerFactsFast(argv, stdin, cwd, hqRoot) {
-    const result = runDeriveTriggerFacts({ argv, stdin, cwd, hqRoot: hqRoot ?? cwd });
+    const result = runDeriveTriggerFactsFastResult(argv, stdin, cwd, hqRoot);
     if (result.stdout.length)
         process.stdout.write(result.stdout);
     if (result.stderr.length)
         process.stderr.write(result.stderr);
     return result.code;
 }
+export function runDeriveTriggerFactsFastResult(argv, stdin, cwd, hqRoot) {
+    if (process.env.HQ_CORE_STDIN_CLOSED === "1") {
+        const result = runBundledScript({
+            asset: DERIVE_TRIGGER_FACTS_ASSET,
+            args: [...argv],
+            cwd,
+            hqRoot: hqRoot ?? cwd,
+            msysScriptPath: process.platform === "win32",
+            closeStdin: true,
+            captureOutput: true,
+        });
+        return {
+            code: result.code,
+            stdout: result.stdout ?? Buffer.alloc(0),
+            stderr: result.stderr ?? Buffer.alloc(0),
+        };
+    }
+    return runDeriveTriggerFacts({ argv, stdin, cwd, hqRoot: hqRoot ?? cwd });
+}
 //# sourceMappingURL=core-derive-trigger-facts-native.js.map

package/dist/commands/daemon.js

@@ -30,6 +30,7 @@ import { daemonPaths } from "../lib/daemon/paths.js";
 import { processCommandLine } from "../lib/daemon/lock.js";
 import { writeControlRequest } from "../lib/daemon/requests.js";
 import { runDaemonCall } from "../lib/daemon/command-call.js";
+import { acknowledgeConflictNotice, conflictNoticeStateDir } from "../lib/daemon/conflict-notices.js";
 import { isSyncRunnerCommandLine, readWatchRunnerOwnerStatus, syncRunnerPathFromCommandLine, watchRunnerOwnerStatusPath } from "../lib/daemon/sync-runner.js";
 import { stagedSyncRunnerVersion, syncRunnerBundleStageRoot } from "../lib/daemon/sync-runner-bundle.js";
 import { getSyncModeForCompany, setSyncMode } from "./sync-mode.js";
@@ -959,6 +960,21 @@ export function registerDaemonCommand(program, over = {}) {
     const sync = daemon
         .command("sync")
         .description("Inspect and control the daemon's company sync runner");
+    sync
+        .command("conflicts")
+        .description("Manage parked conflict copy notices")
+        .command("acknowledge <noticeId>")
+        .description("Acknowledge a parked conflict copy notice")
+        .action(wrap(async (d, noticeId) => {
+        const host = currentHost(d);
+        const managedHome = host.runAsUser ? d.userHome(host.runAsUser) : d.home;
+        const stateDir = conflictNoticeStateDir(d.env, managedHome);
+        acknowledgeConflictNotice(noticeId, stateDir);
+        if (host.runAsUser && d.isRoot) {
+            d.run("chown", [`${host.runAsUser}:`, path.join(stateDir, "conflict-notice-acks.jsonl")]);
+        }
+        d.out("Conflict notice acknowledged.");
+    }));
     sync
         .command("status")
         .description("Show sync ownership, heartbeat, last pass and log path")

package/dist/commands/doctor.d.ts

@@ -119,6 +119,7 @@ export interface RunDoctorResult {
  * read; all other default tiers remain local unless explicitly opted in.
  */
 export declare function runDoctor(options?: RunDoctorOptions): Promise<RunDoctorResult>;
+export declare function createClientHealthReasonCodeCompanyResolver(hqRoot: string): (companySlug: string | null) => Promise<boolean>;
 export declare function createClientHealthCheckStatusCompanyResolver(hqRoot: string): (companySlug: string | null) => Promise<boolean>;
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -207,7 +207,14 @@ async function resolveClientHealthReasonCodesCheckIds(families, resolveForCompan
                 continue;
             }
             const scoped = /^sync\.(?:journal|manifest)\.(.+)$/.exec(result.checkId);
-            const companySlug = scoped && isCompanyJournalSlug(scoped[1]) ? scoped[1] : null;
+            const companyUidScope = scoped
+                ? /^company:(cmp_[A-Za-z0-9]{3,128})$/.exec(scoped[1])
+                : null;
+            const companySlug = companyUidScope
+                ? `company:${companyUidScope[1]}`
+                : scoped && isCompanyJournalSlug(scoped[1])
+                    ? scoped[1]
+                    : null;
             const checkIds = checksByCompany.get(companySlug) ?? [];
             checkIds.push(result.checkId);
             checksByCompany.set(companySlug, checkIds);
@@ -254,12 +261,18 @@ async function resolveClientHealthCheckStatusCheckIds(families, resolveForCompan
     }
     return enabledChecks;
 }
-function createClientHealthReasonCodeCompanyResolver(hqRoot) {
+export function createClientHealthReasonCodeCompanyResolver(hqRoot) {
     const companies = readCompaniesManifestMap(hqRoot);
     return async (companySlug) => {
         if (companySlug === null) {
             return isActiveCompanyClientHealthReasonCodesEnabled();
         }
+        const scopedCompanyUid = /^company:(cmp_[A-Za-z0-9]{3,128})$/.exec(companySlug);
+        if (scopedCompanyUid) {
+            return clientHealthReasonCodesEnabledForCompany({
+                companyUid: scopedCompanyUid[1],
+            });
+        }
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(companySlug)) {
             return false;
         }

package/dist/commands/import-scan.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `hq import` command group.
+ *
+ *   hq import scan                  human-readable scan summary
+ *   hq import scan --json           only the final `done` event (one JSON line)
+ *   hq import scan --json --stream  every scan event as JSON Lines
+ *
+ * Runs the HQ tree's import-context scanner with `--progress-json` (local
+ * only, read-only apart from report.json). The HQ tree is `--hq-root`, else
+ * the one the HQ installer recorded in ~/.hq/menubar.json; this command does
+ * not guess from the current folder or $HQ_ROOT. Event contract and types:
+ * src/lib/import-scan/events.ts and docs/import-scan-stream.md.
+ */
+import { Command, type CommanderError } from "commander";
+/** Exit code for every usage error of `hq import scan` (contract). */
+export declare const IMPORT_SCAN_USAGE_EXIT_CODE = 2;
+/** Exit code for a Commander error raised while parsing `hq import scan`. */
+export declare function importScanExitCode(err: CommanderError): number;
+export interface RegisterImportCommandDeps {
+    /** Ends the process (default process.exit). Tests pass one that throws. */
+    exit?: (code: number, err: CommanderError) => never;
+}
+export declare function registerImportCommand(program: Command, deps?: RegisterImportCommandDeps): Command;
+//# sourceMappingURL=import-scan.d.ts.map

package/dist/commands/import-scan.js

@@ -0,0 +1,75 @@
+/**
+ * `hq import` command group.
+ *
+ *   hq import scan                  human-readable scan summary
+ *   hq import scan --json           only the final `done` event (one JSON line)
+ *   hq import scan --json --stream  every scan event as JSON Lines
+ *
+ * Runs the HQ tree's import-context scanner with `--progress-json` (local
+ * only, read-only apart from report.json). The HQ tree is `--hq-root`, else
+ * the one the HQ installer recorded in ~/.hq/menubar.json; this command does
+ * not guess from the current folder or $HQ_ROOT. Event contract and types:
+ * src/lib/import-scan/events.ts and docs/import-scan-stream.md.
+ */
+import { runImportScan } from "../lib/import-scan/run.js";
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+/** Exit code for every usage error of `hq import scan` (contract). */
+export const IMPORT_SCAN_USAGE_EXIT_CODE = 2;
+/** Commander error codes that mean "the command line was wrong". */
+const COMMANDER_USAGE_ERROR_CODES = new Set([
+    "commander.unknownOption",
+    "commander.unknownCommand",
+    "commander.missingArgument",
+    "commander.optionMissingArgument",
+    "commander.missingMandatoryOptionValue",
+    "commander.conflictingOption",
+    "commander.excessArguments",
+    "commander.invalidArgument",
+]);
+/** Exit code for a Commander error raised while parsing `hq import scan`. */
+export function importScanExitCode(err) {
+    if (err.exitCode !== 0 && COMMANDER_USAGE_ERROR_CODES.has(err.code))
+        return IMPORT_SCAN_USAGE_EXIT_CODE;
+    return err.exitCode;
+}
+export function registerImportCommand(program, deps = {}) {
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const importCmd = program
+        .command("import")
+        .description("Import existing AI context (Claude Code, Codex, repos) into HQ");
+    importCmd
+        .command("scan")
+        .description("Scan this machine for AI context (sessions, repos, companies, projects); local only")
+        .option("--json", "Print only the final done event as JSON")
+        .option("--stream", "With --json, print every scan event as JSON Lines while scanning")
+        .option("--hq-root <path>", "HQ folder (default: the folder the HQ installer recorded)")
+        .option("--output <path>", "Where to write report.json (default: <hq>/workspace/imports/<scan id>/report.json)")
+        .option("--scope <dir>", "Also scan this folder (repeatable)", collect, [])
+        .option("--claude-export <path>", "Include a claude.ai data export (unzipped folder or conversations.json)")
+        .option("--no-default-scopes", "Scan only --scope folders, not the default code folders")
+        .addHelpText("after", "\nThe desktop app runs: hq import scan --json --stream\n" +
+        "Events (v1): start, source, count, company, project, error, done. See docs/import-scan-stream.md.")
+        // Usage errors (unknown option, missing value, --stream without --json)
+        // exit 2 per the scan contract. Scoped to this command only; Commander
+        // would otherwise exit 1 for most of them.
+        .exitOverride((err) => exit(importScanExitCode(err), err))
+        .action(async (opts, cmd) => {
+        if (opts.stream && !opts.json) {
+            cmd.error("error: --stream requires --json", { exitCode: 2 });
+        }
+        const mode = opts.json ? (opts.stream ? "stream" : "final") : "human";
+        const code = await runImportScan({
+            mode,
+            hqRoot: opts.hqRoot,
+            output: opts.output,
+            scopes: opts.scope,
+            claudeExport: opts.claudeExport,
+            noDefaultScopes: opts.defaultScopes === false,
+        }, { stdout: process.stdout, stderr: process.stderr });
+        process.exitCode = code;
+    });
+    return importCmd;
+}
+//# sourceMappingURL=import-scan.js.map

package/dist/commands/lanes-checks.d.ts

@@ -2,12 +2,15 @@ import type { Command } from "commander";
 import { type TrackerCheckTeam } from "../lib/lanes/tracker-checks.js";
 import { type TrackerKind, type TrackerRecord } from "../lib/lanes/tracker-store.js";
 import type { LaneRecord, LaneCompanyRef, QuestionRecord } from "../lib/lanes/types.js";
+import { type ReapDeps } from "../lib/lanes/reaper.js";
 export interface LaneChecksDeps {
     hqRoot: () => string;
     resolveCompany: (company?: string) => Promise<LaneCompanyRef>;
     now: () => Date;
     stopLane?: (laneId: string, reason: string) => Promise<void>;
     sessionState?: (root: string, sessionId: string, now: Date) => string | null;
+    stopEnabled?: (lane: LaneRecord) => Promise<boolean> | boolean;
+    reaperDeps?: Partial<ReapDeps>;
 }
 type WrapHandler = <Args extends unknown[]>(action: (...args: Args) => Promise<void>) => (...args: Args) => Promise<void>;
 export interface ProjectMapping {

package/dist/commands/lanes-checks.js

@@ -13,6 +13,7 @@ import { LANES_RUNS_REL } from "../lib/lanes/spawn.js";
 import { assertNoSecretText } from "../lib/lanes/text-scan.js";
 import { checkCompanyPath } from "../lib/lanes/checked-company-path.js";
 import { findOrphanedBareIdDropboxes } from "../lib/lanes/orphaned-dropbox.js";
+import { parseReapMinAge, reapLocalLanes } from "../lib/lanes/reaper.js";
 export function mappingIncludesStory(mapping, storyId) {
     return (mapping.storyPrefix === undefined || storyId.startsWith(mapping.storyPrefix))
         && (mapping.excludePrefix === undefined || !storyId.startsWith(mapping.excludePrefix));
@@ -905,6 +906,39 @@ async function orphanReport(root, company, now, minAgeMinutes, userIdleHours, de
     output("orphans.stop", stopped);
 }
 export function registerLaneChecksCommand(parent, deps, wrap) {
+    parent.command("reap")
+        // CL-5's SessionStart hook launches this alias detached and does not wait for it.
+        .alias("_reap")
+        .description("Classify local lanes whose session senior has ended; report only by default")
+        .option("--min-age <minutes>", "Minimum lane age in minutes (default: 120)")
+        .option("--apply-stale-state", "Remove stale worker and watcher pid markers")
+        .option("--stop", "Stop candidate process trees when the hq-flags stop key is enabled")
+        .option("--reason <text>", "Required audit reason when --stop is set")
+        .option("--json", "Print machine-readable JSON (default)")
+        .action(wrap(async (options) => {
+        const reason = options.reason?.trim();
+        if (options.stop && !reason)
+            fail("lane_reap_reason_required", "--stop requires a non-empty --reason", {});
+        if (!options.stop && options.reason !== undefined)
+            fail("lane_reap_reason_requires_stop", "--reason can only be used with --stop", {});
+        if (reason)
+            assertNoSecretText("stop reason", reason);
+        const minAgeMinutes = parseReapMinAge(options.minAge);
+        const report = await reapLocalLanes(deps.hqRoot(), {
+            minAgeMinutes,
+            stop: options.stop === true,
+            applyStaleState: options.applyStaleState === true,
+            reason: reason ?? "Orphaned lane: owning session is confirmed ended",
+            json: true,
+        }, {
+            ...deps.reaperDeps,
+            now: deps.now,
+            sessionState: deps.sessionState,
+            stopEnabled: deps.stopEnabled,
+            stopLane: deps.stopLane,
+        });
+        console.log(JSON.stringify(report, null, 2));
+    }));
     parent.command("checks")
         .description("Evaluate tracker and lane health checks")
         .option("--company <slug>", "Select the company by slug")

package/dist/commands/lanes-session-start.d.ts

@@ -0,0 +1,17 @@
+import { spawn } from "node:child_process";
+import type { Command } from "commander";
+export interface SessionStartOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: Pick<NodeJS.WriteStream, "write">;
+    stderr?: Pick<NodeJS.WriteStream, "write">;
+    resolveRoot?: (env: NodeJS.ProcessEnv, cwd?: string) => string;
+    startSweep?: (root: string, env: NodeJS.ProcessEnv) => void;
+}
+/** Starts the CL-4 read-only orphan report once per host, without holding SessionStart open. */
+export declare function startSessionStartOrphanSweep(root: string, env?: NodeJS.ProcessEnv, spawnDetached?: typeof spawn): void;
+/** SessionStart-compatible, fail-open conduct bootstrap. */
+export declare function runLaneSessionStart(options?: SessionStartOptions): Promise<void>;
+export declare function registerLaneSessionStartCommand(lanes: Command): void;
+//# sourceMappingURL=lanes-session-start.d.ts.map