@indigoai-us/hq-cli 5.273.0-alpha.0 → 5.274.0

package/dist/lib/daemon/supervisor.d.ts

@@ -20,16 +20,12 @@
 import type { UnitPlan } from "./catalog.js";
 import type { MachineType } from "./machine-type.js";
 import type { ControlRequest } from "./requests.js";
-import { syncPassResult } from "./sync-runner.js";
 export declare const BACKOFF_BASE_MS = 1000;
 export declare const BACKOFF_MAX_MS = 60000;
 export declare const HEALTHY_RUN_MS = 60000;
 export declare const STOP_ESCALATION_MS = 10000;
 export interface SupervisedChild {
     pid?: number;
-    stdout?: {
-        on(event: "data" | "end", handler: (chunk?: Buffer | string) => void): unknown;
-    };
     on(event: "exit", handler: (code: number | null, signal: string | null) => void): unknown;
     on(event: "error", handler: (err: Error) => void): unknown;
     kill(signal?: NodeJS.Signals | number): boolean;
@@ -53,8 +49,6 @@ export interface UnitState {
     lastRunAt?: number;
     nextRunAt?: number;
     lastResult?: "ok" | "failed";
-    lastHeartbeatAt?: string;
-    lastPassResult?: ReturnType<typeof syncPassResult>;
 }
 /** An app that runs the daemon as its own child process instead of an OS unit. */
 export type HostApp = "desktop";
@@ -85,8 +79,6 @@ export interface SupervisorDeps {
     clearTimeout?: (handle: unknown) => void;
     reconcileMs?: number;
     requestPollMs?: number;
-    /** Read hq-cloud's lease status after it exits with the lease-conflict code. */
-    syncOwnerBlockReason?: () => string | undefined;
 }
 export interface Supervisor {
     start(): void;

package/dist/lib/daemon/supervisor.js

@@ -17,8 +17,6 @@
  *
  * Processes, time, and state output are injected; `run.ts` wires the real ones.
  */
-import { StringDecoder } from "node:string_decoder";
-import { SYNC_RUNNER_LEASE_CONFLICT_EXIT, SYNC_RUNNER_LEASE_RETRY_MS, parseSyncRunnerProtocolLine, syncPassResult, } from "./sync-runner.js";
 export const BACKOFF_BASE_MS = 1_000;
 export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
@@ -27,15 +25,7 @@ export function backoffMs(attempt) {
     return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
 }
 function planKey(plan) {
-    return JSON.stringify([
-        plan.kind,
-        plan.restart,
-        plan.intervalSec,
-        plan.initialDelaySec,
-        plan.heartbeatTimeoutMs,
-        plan.command,
-        plan.env,
-    ]);
+    return JSON.stringify([plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env]);
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -78,11 +68,6 @@ export function createSupervisor(deps) {
             clearT(slot.timer);
         slot.timer = undefined;
     };
-    const clearHeartbeatTimer = (slot) => {
-        if (slot.heartbeatTimer !== undefined)
-            clearT(slot.heartbeatTimer);
-        slot.heartbeatTimer = undefined;
-    };
     const setBlocked = (slot) => {
         const block = slot.plan.blocked;
         slot.state.status = block.state;
@@ -93,7 +78,6 @@ export function createSupervisor(deps) {
     /** Stop the slot's child (if any), then run `then` once it has exited. */
     const terminate = (slot, then) => {
         clearTimer(slot);
-        clearHeartbeatTimer(slot);
         const child = slot.child;
         if (!child) {
             then?.();
@@ -138,69 +122,6 @@ export function createSupervisor(deps) {
     const watch = (slot, child) => {
         live.add(child);
         let ended = false;
-        const timeoutMs = slot.plan.heartbeatTimeoutMs;
-        const decoder = timeoutMs ? new StringDecoder("utf8") : null;
-        let stdoutRemainder = "";
-        let lastHeartbeatPersistedAt = now() - 15_000;
-        const armHeartbeatWatchdog = () => {
-            if (!timeoutMs)
-                return;
-            clearHeartbeatTimer(slot);
-            slot.heartbeatTimer = setT(() => {
-                slot.heartbeatTimer = undefined;
-                if (stopped || slot.child !== child || slot.expectingExit)
-                    return;
-                deps.log("warn", `${slot.plan.id} emitted no sync protocol heartbeat for ${timeoutMs}ms; restarting it`);
-                terminate(slot, () => scheduleRestart(slot));
-                emit();
-            }, timeoutMs);
-        };
-        const acceptProtocolLine = (line) => {
-            let event;
-            try {
-                event = parseSyncRunnerProtocolLine(line);
-            }
-            catch (err) {
-                deps.log("error", `${slot.plan.id} emitted invalid sync protocol output (${Buffer.byteLength(line)} bytes): ${errorMessage(err)}`);
-                return;
-            }
-            if (!event)
-                return;
-            const at = now();
-            slot.state.lastHeartbeatAt = new Date(at).toISOString();
-            const pass = syncPassResult(event, slot.state.lastHeartbeatAt);
-            if (pass)
-                slot.state.lastPassResult = pass;
-            armHeartbeatWatchdog();
-            if (pass || at - lastHeartbeatPersistedAt >= 15_000) {
-                lastHeartbeatPersistedAt = at;
-                emit();
-            }
-        };
-        if (decoder && child.stdout) {
-            child.stdout.on("data", (chunk) => {
-                if (chunk === undefined)
-                    return;
-                stdoutRemainder += decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-                let newline = stdoutRemainder.indexOf("\n");
-                while (newline >= 0) {
-                    acceptProtocolLine(stdoutRemainder.slice(0, newline).trim());
-                    stdoutRemainder = stdoutRemainder.slice(newline + 1);
-                    newline = stdoutRemainder.indexOf("\n");
-                }
-                // A malformed or unexpectedly large line is not a heartbeat. Bound
-                // retained data so a broken child cannot grow daemon memory forever.
-                if (Buffer.byteLength(stdoutRemainder) > 1024 * 1024)
-                    stdoutRemainder = "";
-            });
-            child.stdout.on("end", () => {
-                stdoutRemainder += decoder.end();
-                if (stdoutRemainder)
-                    acceptProtocolLine(stdoutRemainder.trim());
-                stdoutRemainder = "";
-            });
-        }
-        armHeartbeatWatchdog();
         const onEnd = (code, signal) => {
             if (ended)
                 return;
@@ -211,7 +132,6 @@ export function createSupervisor(deps) {
             if (slot.child !== child)
                 return;
             slot.child = undefined;
-            clearHeartbeatTimer(slot);
             if (slot.killTimer !== undefined) {
                 clearT(slot.killTimer);
                 slot.killTimer = undefined;
@@ -239,20 +159,6 @@ export function createSupervisor(deps) {
                 emit();
                 return;
             }
-            if (slot.plan.service === "sync" && code === SYNC_RUNNER_LEASE_CONFLICT_EXIT) {
-                const reason = deps.syncOwnerBlockReason?.() ?? "sync owned by another runner";
-                slot.state.status = "waiting";
-                slot.state.reason = reason;
-                slot.state.nextRunAt = now() + SYNC_RUNNER_LEASE_RETRY_MS;
-                deps.log("info", `${reason}; retrying in ${SYNC_RUNNER_LEASE_RETRY_MS}ms`);
-                slot.timer = setT(() => {
-                    slot.timer = undefined;
-                    startLong(slot);
-                    emit();
-                }, SYNC_RUNNER_LEASE_RETRY_MS);
-                emit();
-                return;
-            }
             deps.log("warn", `${slot.plan.id} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
             if (ranFor >= HEALTHY_RUN_MS)
                 slot.attempts = 0;
@@ -463,11 +369,6 @@ export function createSupervisor(deps) {
         emit();
     };
     const handleRequest = (req) => {
-        if (req.action === "reconcile") {
-            deps.log("info", "reconciling daemon configuration (requested)");
-            reconcile();
-            return;
-        }
         if (req.action === "restart-daemon") {
             deps.log("info", "restarting the daemon (requested)");
             if (deps.restartDaemon)
@@ -574,7 +475,6 @@ export function createSupervisor(deps) {
                 clearT(requestTimer);
             for (const slot of slots.values()) {
                 clearTimer(slot);
-                clearHeartbeatTimer(slot);
                 slot.child = undefined;
                 if (slot.killTimer !== undefined)
                     clearT(slot.killTimer);

package/dist/lib/deploy-api.d.ts

@@ -0,0 +1,6 @@
+/** Shared authenticated request path for the hq-deploy control plane. */
+export declare const DEPLOY_API_URL: string;
+export declare function deployHeaders(token: string, json?: boolean, extra?: Record<string, string>): Record<string, string>;
+export declare function deployApiUrl(route: string): string;
+export declare function deployApiRequest(token: string, route: string, method: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<Response>;
+//# sourceMappingURL=deploy-api.d.ts.map

package/dist/lib/deploy-api.js

@@ -0,0 +1,21 @@
+/** Shared authenticated request path for the hq-deploy control plane. */
+export const DEPLOY_API_URL = process.env.HQ_DEPLOY_API_URL?.trim() || "https://api.indigo-hq.com";
+export function deployHeaders(token, json = true, extra = {}) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        ...(json ? { "Content-Type": "application/json" } : {}),
+        ...extra,
+    };
+}
+export function deployApiUrl(route) {
+    return `${DEPLOY_API_URL.replace(/\/+$/, "")}${route}`;
+}
+export async function deployApiRequest(token, route, method, body, extraHeaders = {}) {
+    return fetch(deployApiUrl(route), {
+        method,
+        headers: deployHeaders(token, body !== undefined, extraHeaders),
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+}
+//# sourceMappingURL=deploy-api.js.map

package/dist/lib/doctor/checks/scaffold-cli-floor.d.ts

@@ -0,0 +1,7 @@
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const SCAFFOLD_CLI_FLOOR_FAMILY_ID = "scaffold-cli-floor";
+export declare const SCAFFOLD_CLI_FLOOR_FAMILY_TITLE = "Scaffold CLI compatibility";
+export declare const SCAFFOLD_CLI_FLOOR_CHECK_ID = "scaffold-cli-floor.requires-hq-cli";
+export declare const scaffoldCliFloorFamily: CheckFamily;
+export declare function checkScaffoldCliFloor(context: CheckContext): CheckResult[];
+//# sourceMappingURL=scaffold-cli-floor.d.ts.map

package/dist/lib/doctor/checks/scaffold-cli-floor.js

@@ -0,0 +1,73 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { CLI_VERSION } from "../../../cli-version.js";
+import { compareScaffoldCliFloor } from "../../scaffold-cli-floor.js";
+export const SCAFFOLD_CLI_FLOOR_FAMILY_ID = "scaffold-cli-floor";
+export const SCAFFOLD_CLI_FLOOR_FAMILY_TITLE = "Scaffold CLI compatibility";
+export const SCAFFOLD_CLI_FLOOR_CHECK_ID = "scaffold-cli-floor.requires-hq-cli";
+export const scaffoldCliFloorFamily = {
+    id: SCAFFOLD_CLI_FLOOR_FAMILY_ID,
+    title: SCAFFOLD_CLI_FLOOR_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkScaffoldCliFloor(context)),
+};
+export function checkScaffoldCliFloor(context) {
+    const coreYamlPath = path.join(context.hqRoot, "core", "core.yaml");
+    if (!fs.existsSync(coreYamlPath)) {
+        return [skipped(coreYamlPath, "core/core.yaml is missing")];
+    }
+    let document;
+    try {
+        document = yaml.load(fs.readFileSync(coreYamlPath, "utf8"));
+    }
+    catch {
+        return [
+            {
+                status: "WARN",
+                checkId: SCAFFOLD_CLI_FLOOR_CHECK_ID,
+                target: coreYamlPath,
+                message: "core/core.yaml could not be parsed, so the hq-cli floor was not checked.",
+            },
+        ];
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        if (document === undefined || document === null) {
+            return [skipped(coreYamlPath, "core/core.yaml does not declare requiresHqCli")];
+        }
+        return [
+            {
+                status: "WARN",
+                checkId: SCAFFOLD_CLI_FLOOR_CHECK_ID,
+                target: coreYamlPath,
+                message: "core/core.yaml is not a mapping, so the hq-cli floor was not checked.",
+            },
+        ];
+    }
+    const required = document.requiresHqCli;
+    const comparison = compareScaffoldCliFloor(required, CLI_VERSION);
+    if (comparison.status === "skip") {
+        return [skipped(coreYamlPath, "core/core.yaml does not declare requiresHqCli")];
+    }
+    return [
+        {
+            status: comparison.status === "pass"
+                ? "PASS"
+                : comparison.status === "fail"
+                    ? "FAIL"
+                    : "WARN",
+            checkId: SCAFFOLD_CLI_FLOOR_CHECK_ID,
+            target: coreYamlPath,
+            message: comparison.message,
+            ...(comparison.remediation ? { remediation: comparison.remediation } : {}),
+        },
+    ];
+}
+function skipped(target, reason) {
+    return {
+        status: "NA",
+        checkId: SCAFFOLD_CLI_FLOOR_CHECK_ID,
+        target,
+        message: `Skipped: ${reason}; no hq-cli floor was checked.`,
+    };
+}
+//# sourceMappingURL=scaffold-cli-floor.js.map

package/dist/lib/doctor/fix/apply.d.ts

@@ -101,6 +101,8 @@ export interface RefreshSyncResult {
 export declare const REFRESH_SYNC_TIMEOUT_MS = 90000;
 /** One applied (or attempted) repair, with its post-fix re-check status. */
 export interface AppliedFix {
+    /** One-based repair pass in this `hq doctor --fix` invocation. */
+    pass: number;
     /** The check id of the finding that was repaired. */
     checkId: string;
     /** The safe class applied. */
@@ -114,13 +116,24 @@ export interface AppliedFix {
     /** Present for refresh-sync plans; contains no command output or path data. */
     refreshSyncOutcome?: RefreshSyncOutcome;
 }
+/** Backup and restore information for one pass that wrote files. */
+export interface AppliedFixBackup {
+    /** One-based repair pass that created this backup. */
+    pass: number;
+    /** Absolute path of the backup directory. */
+    backupDir: string;
+    /** Command that restores this pass's pre-write files. */
+    restoreCommand: string;
+}
+/** A newly unlocked safe repair can be picked up for at most this many passes. */
+export declare const MAX_FIX_PASSES = 3;
 /** The outcome of an {@link applyFixes} run. */
 export interface ApplyFixesResult {
-    /** 0 on success or a clean no-op; 1 when the run was refused. */
+    /** 0 on success, decline, or a clean no-op; 1 when a dirty tree is refused. */
     exitCode: number;
     /** Whether any file was written. */
     wrote: boolean;
-    /** Why the run wrote nothing, when it did not: refusal reason or null. */
+    /** Why no further repairs were applied, when the run stopped early. */
     refused: "dirty-tree" | "declined" | null;
     /** How many findings were auto-fixable. */
     fixableCount: number;
@@ -128,6 +141,8 @@ export interface ApplyFixesResult {
     backupDir: string | null;
     /** The restore command, or null when nothing was written. */
     restoreCommand: string | null;
+    /** Every backup made, in pass order. */
+    backups: AppliedFixBackup[];
     /** The applied repairs with their post-fix status. */
     applied: AppliedFix[];
 }

package/dist/lib/doctor/fix/apply.js

@@ -45,6 +45,8 @@ import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
 /** Per-company bound for the default `hq sync pull` repair. */
 export const REFRESH_SYNC_TIMEOUT_MS = 90_000;
+/** A newly unlocked safe repair can be picked up for at most this many passes. */
+export const MAX_FIX_PASSES = 3;
 /**
  * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
  * preview/confirmation gate, the pre-write backup, and the post-fix re-check.
@@ -62,6 +64,7 @@ export async function applyFixes(options) {
         fixableCount: 0,
         backupDir: null,
         restoreCommand: null,
+        backups: [],
         applied: [],
         ...over,
     });
@@ -80,72 +83,123 @@ export async function applyFixes(options) {
     const collect = options.runChecks ?? defaultRunChecks;
     const refreshSync = options.refreshSync ?? defaultRefreshSync;
     const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
-    // 2. Collect findings and keep only the allowlisted auto-fixable ones.
-    const findings = await collect(hqRoot);
-    const fixable = [];
-    for (const result of findings) {
-        const rem = deriveRemediation(result);
-        if (rem && rem.autoFixable)
-            fixable.push({ result, rem });
-    }
-    if (fixable.length === 0) {
-        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
-        return empty();
-    }
-    const plans = fixable
-        .map(({ result, rem }) => planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath))
-        .filter((plan) => plan !== null);
-    if (plans.length === 0) {
-        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
-        return empty();
-    }
-    // 3. Diff-style preview + confirmation (AC5).
-    write(`hq doctor --fix will apply ${plans.length} repair${plans.length === 1 ? "" : "s"}:\n\n`);
-    for (const plan of plans)
-        write(plan.preview + "\n");
-    if (!options.yes) {
-        const confirmed = await Promise.resolve((options.confirm ?? declineByDefault)());
-        if (!confirmed) {
-            write("Aborted — no changes written.\n");
-            return empty({ refused: "declined" });
+    // 2. Collect findings, then plan each newly unlocked allowlisted repair.
+    //    Identity is deliberately the check id + target pair: an unsuccessful
+    //    repair must not be applied repeatedly in one invocation.
+    let findings = await collect(hqRoot);
+    const appliedKeys = new Set();
+    const planned = [];
+    const backups = [];
+    let fixableCount = 0;
+    let refused = null;
+    let lastBackupMs = Number.NEGATIVE_INFINITY;
+    const backupClock = () => {
+        const suppliedMs = (options.now ?? (() => new Date()))().getTime();
+        lastBackupMs = Math.max(suppliedMs, lastBackupMs + 1);
+        return new Date(lastBackupMs);
+    };
+    const buildPlans = (results) => {
+        const keysThisPass = new Set();
+        const plans = [];
+        for (const result of results) {
+            const rem = deriveRemediation(result);
+            if (!rem?.autoFixable)
+                continue;
+            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath);
+            if (!plan)
+                continue;
+            const key = JSON.stringify([plan.checkId, plan.target]);
+            if (appliedKeys.has(key) || keysThisPass.has(key))
+                continue;
+            keysThisPass.add(key);
+            plans.push(plan);
+        }
+        return plans;
+    };
+    for (let pass = 1; pass <= MAX_FIX_PASSES; pass += 1) {
+        const plans = buildPlans(findings);
+        if (plans.length === 0)
+            break;
+        fixableCount += plans.length;
+        // 3. Preview and require confirmation for every pass unless --yes is set.
+        write(`Pass ${pass}/${MAX_FIX_PASSES}: hq doctor --fix will apply ${plans.length} repair${plans.length === 1 ? "" : "s"}:\n\n`);
+        for (const plan of plans)
+            write(plan.preview + "\n");
+        if (!options.yes) {
+            const confirmed = await Promise.resolve((options.confirm ?? declineByDefault)());
+            if (!confirmed) {
+                refused = "declined";
+                if (planned.length === 0) {
+                    write("Aborted — no changes written.\n");
+                    return empty({ refused, fixableCount });
+                }
+                write(`Pass ${pass} declined — no further changes written.\n`);
+                break;
+            }
+        }
+        // 4. Back up this pass's files before its first write. The clock advances
+        //    at least one millisecond per backup so fast consecutive passes cannot
+        //    overwrite an earlier pass's restore point.
+        const affected = unique(plans.map((plan) => plan.relpath).filter((rel) => rel.length > 0));
+        const backup = affected.length > 0 ? createBackup(hqRoot, affected, backupClock) : null;
+        if (backup) {
+            backups.push({
+                pass,
+                backupDir: backup.dir,
+                restoreCommand: backup.restoreCommand,
+            });
+            write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} for pass ${pass} to ${backup.dir}\n`);
+            write(`To restore: ${backup.restoreCommand}\n`);
         }
+        // 5. Apply each plan once. Later findings with this check id + target are
+        //    excluded even if this repair did not make its check pass.
+        for (const plan of plans) {
+            appliedKeys.add(JSON.stringify([plan.checkId, plan.target]));
+            planned.push({ plan, pass });
+            await plan.apply();
+        }
+        // 6. Re-run checks. Newly surfaced repairs are considered by the next loop.
+        findings = await collect(hqRoot);
     }
-    // 4. Back up every file about to change BEFORE the first write (AC6).
-    //    refresh-sync plans have no hook file; skip the backup pass when nothing
-    //    in the tree is about to be copied.
-    const affected = unique(plans.map((plan) => plan.relpath).filter((rel) => rel.length > 0));
-    const backup = affected.length > 0 ? createBackup(hqRoot, affected, options.now) : null;
-    // 5. Apply. Each plan reads the current on-disk state, so multiple plans that
-    //    touch the same file (two gate ids) compose correctly.
-    for (const plan of plans)
-        await plan.apply();
-    if (backup) {
-        write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} to ${backup.dir}\n`);
-        write(`To restore: ${backup.restoreCommand}\n`);
+    if (planned.length === 0) {
+        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
+        return empty({ refused, fixableCount });
     }
-    // 6. Re-run the checks and report the post-fix status of each repair (AC7).
-    const after = await collect(hqRoot);
-    const applied = plans.map((plan) => ({
-        checkId: plan.checkId,
-        fixClass: plan.fixClass,
-        target: plan.target,
-        summary: plan.summary,
-        postStatus: plan.postStatus(after),
-        ...(plan.refreshSyncOutcome?.()
-            ? { refreshSyncOutcome: plan.refreshSyncOutcome() }
-            : {}),
-    }));
+    // Show each repair's final post-fix status, including work from earlier passes.
+    const applied = planned.map(({ plan, pass }) => {
+        const refreshSyncOutcome = plan.refreshSyncOutcome?.();
+        return {
+            pass,
+            checkId: plan.checkId,
+            fixClass: plan.fixClass,
+            target: plan.target,
+            summary: plan.summary,
+            postStatus: plan.postStatus(findings),
+            ...(refreshSyncOutcome ? { refreshSyncOutcome } : {}),
+        };
+    });
     write("\nPost-fix status:\n");
     for (const fix of applied) {
-        write(`  ${fix.postStatus ?? "UNKNOWN"}  ${fix.checkId} [${fix.target}]\n`);
+        write(`  ${fix.postStatus ?? "UNKNOWN"}  ${fix.checkId} [${fix.target}] (pass ${fix.pass})\n`);
+    }
+    // Restore later pass snapshots first. This also returns every file to its
+    // pre-run state when multiple passes touched the same path.
+    const restoreCommand = backups.length > 0
+        ? [...backups].reverse().map(({ restoreCommand: command }) => command).join(" && ")
+        : null;
+    if (restoreCommand)
+        write(`To restore all changes: ${restoreCommand}\n`);
+    if (planned.at(-1)?.pass === MAX_FIX_PASSES && buildPlans(findings).length > 0) {
+        write(`Stopped after ${MAX_FIX_PASSES} repair passes; new auto-fixable findings remain.\n`);
     }
     return {
         exitCode: 0,
         wrote: true,
-        refused: null,
-        fixableCount: fixable.length,
-        backupDir: backup?.dir ?? null,
-        restoreCommand: backup?.restoreCommand ?? null,
+        refused,
+        fixableCount,
+        backupDir: backups[0]?.backupDir ?? null,
+        restoreCommand,
+        backups,
         applied,
     };
 }

package/dist/lib/doctor/fix/json-output.d.ts

@@ -1,9 +1,16 @@
-import type { AppliedFix, ApplyFixesResult } from "./apply.js";
+import type { AppliedFix, AppliedFixBackup, ApplyFixesResult } from "./apply.js";
 export declare const DOCTOR_FIX_JSON_SCHEMA_VERSION = 1;
 export interface DoctorFixJsonResult {
     schemaVersion: number;
     exitCode: number;
     refused: ApplyFixesResult["refused"] | "outside-hq-tree";
+    applied: {
+        checkId: string;
+        fixClass: AppliedFix["fixClass"];
+        pass: number;
+        postStatus: AppliedFix["postStatus"];
+    }[];
+    backups: Pick<AppliedFixBackup, "pass" | "backupDir" | "restoreCommand">[];
     refreshSync: {
         checkId: string;
         outcome: NonNullable<AppliedFix["refreshSyncOutcome"]>;
@@ -15,6 +22,7 @@ export declare function buildDoctorFixJson(input: {
     exitCode: number;
     refused: ApplyFixesResult["refused"] | "outside-hq-tree";
     applied: readonly AppliedFix[];
+    backups?: readonly AppliedFixBackup[];
 }): DoctorFixJsonResult;
 export declare function renderDoctorFixJson(input: Parameters<typeof buildDoctorFixJson>[0]): string;
 //# sourceMappingURL=json-output.d.ts.map

package/dist/lib/doctor/fix/json-output.js

@@ -5,6 +5,17 @@ export function buildDoctorFixJson(input) {
         schemaVersion: DOCTOR_FIX_JSON_SCHEMA_VERSION,
         exitCode: input.exitCode,
         refused: input.refused,
+        applied: input.applied.map(({ checkId, fixClass, pass, postStatus }) => ({
+            checkId,
+            fixClass,
+            pass,
+            postStatus,
+        })),
+        backups: (input.backups ?? []).map(({ pass, backupDir, restoreCommand }) => ({
+            pass,
+            backupDir,
+            restoreCommand,
+        })),
         refreshSync: input.applied.flatMap((fix) => fix.fixClass === "refresh-sync" && fix.refreshSyncOutcome
             ? [
                 {

package/dist/lib/doctor/registry.js

@@ -23,6 +23,7 @@ import { integrationsFamily } from "./checks/integrations.js";
 import { syncHealthFamily } from "./checks/sync-health.js";
 import { workContextFamily } from "./checks/work-context.js";
 import { botsFamily } from "./checks/bots.js";
+import { scaffoldCliFloorFamily } from "./checks/scaffold-cli-floor.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -236,6 +237,7 @@ function hasCommandHook(settings, event) {
 export function createDefaultRegistry() {
     const registry = new DoctorRegistry();
     registry.register(hooksFamily);
+    registry.register(scaffoldCliFloorFamily);
     // Fixture coverage (US-007): reports UNTESTED for every registered hook with
     // no fixture and prints the tested/total coverage line. A separate family so
     // it needs no change to the hooks tier, per the registry's extensibility

package/dist/lib/first-sync-next-step.d.ts

@@ -0,0 +1,37 @@
+export declare const CLI_FIRST_SYNC_NEXT_STEP_FLAG = "cli.first-sync-next-step";
+export declare const FIRST_SYNC_NEXT_STEP_COPY = "Save a file in your HQ folder, then run `hq sync push`.";
+export declare const FIRST_SYNC_CONFIRMATION_COPY = "Your first work sync is complete.";
+export type FirstSyncStepOutcome = "shown" | "followed";
+export declare function shouldShowFirstSyncNextStep(input: {
+    flagEnabled: boolean;
+    interactive: boolean;
+    alreadyShown: boolean;
+    alreadyCompleted: boolean;
+}): boolean;
+export declare function shouldConfirmFirstWorkBearingSync(input: {
+    flagEnabled: boolean;
+    interactive: boolean;
+    alreadyCompleted: boolean;
+    workBearing: boolean;
+}): boolean;
+export declare function isWorkBearingSyncResult(result: Record<string, unknown>): boolean;
+export declare function isHumanInteractiveCliSession(input: {
+    stdoutIsTTY: boolean;
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    machineIdentity: boolean;
+}): boolean;
+export declare function firstSyncStepMarkerPaths(identity: string, home?: string): {
+    shown: string;
+    completed: string;
+};
+export declare function claimFirstSyncStepMarker(kind: "shown" | "completed", identity: string, home?: string): boolean;
+export declare function firstSyncStepTelemetryProperties(outcome: FirstSyncStepOutcome): Record<string, unknown>;
+export declare function isFirstSyncNextStepEnabled(): boolean;
+/** Called once after the first completed CLI action, before process finalization. */
+export declare function maybeShowFirstSyncNextStep(): boolean;
+/** Capture the first positive CLI sync result without changing transfer logic. */
+export declare function recordFirstWorkBearingSync(result: Record<string, unknown>): boolean;
+/** Drain outcomes once so each shown/followed event is sent at most once per run. */
+export declare function takeFirstSyncStepOutcomes(): FirstSyncStepOutcome[];
+//# sourceMappingURL=first-sync-next-step.d.ts.map