@indigoai-us/hq-cli 5.273.0 → 5.274.0

package/dist/commands/report.js

@@ -5,9 +5,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { ensureCognitoToken, } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { DEPLOY_API_URL, deployApiRequest, deployHeaders } from "../lib/deploy-api.js";
 import { listReportTemplates } from "../lib/report-templates.js";
 import { adoptReport, buildReportTarball, conventionReportDir, deployOrgContext, ReportPublishError, plainFailureReason, publishReport, } from "../lib/report-publish.js";
-const DEPLOY_API_URL = process.env.HQ_DEPLOY_API_URL ?? "https://api.indigo-hq.com";
 const REPORT_CHANNEL_STATE_FILE = "report-channels.json";
 const MAX_REPORT_DISCOVERY_CHANNELS = 50;
 const JOB_EXECUTION_DISABLED_MESSAGE = "Scheduled jobs are turned off for this company. A company owner can turn them back on.";
@@ -214,22 +214,10 @@ export async function patchReport(token, report, patch) {
         throw new ReportPublishError("Report update response was incomplete.");
     return body.report;
 }
-function deployHeaders(token, json = true, extra = {}) {
-    return {
-        Authorization: `Bearer ${token}`,
-        Accept: "application/json",
-        ...(json ? { "Content-Type": "application/json" } : {}),
-        ...extra,
-    };
-}
 async function deployJson(token, route, method, body, extraHeaders = {}) {
     let res;
     try {
-        res = await fetch(`${DEPLOY_API_URL.replace(/\/+$/, "")}${route}`, {
-            method,
-            headers: deployHeaders(token, body !== undefined, extraHeaders),
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-        });
+        res = await deployApiRequest(token, route, method, body, extraHeaders);
     }
     catch {
         throw new ReportPublishError("Could not reach hq-deploy.");

package/dist/fast-core.js

@@ -9,7 +9,7 @@
  */
 import { resolveLiveRoot } from "./utils/hq-roots.js";
 import { runBundledScript } from "./utils/run-bundled-script.js";
-import { parseFastCore } from "./commands/scaffold-fast.js";
+import { parseFastCore } from "./fast-scaffold.js";
 /**
  * Run the fast-path scaffold script named in `argv` and exit with its code.
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without

package/dist/{commands/scaffold-fast.d.ts → fast-scaffold.d.ts}

@@ -38,4 +38,4 @@ export type ParsedFastCore = {
 export declare function parseFastCore(argv: readonly string[]): ParsedFastCore | null;
 /** Whether this invocation is a fast-path scaffold dispatch. */
 export declare function isFastCoreRequest(argv: readonly string[]): boolean;
-//# sourceMappingURL=scaffold-fast.d.ts.map
+//# sourceMappingURL=fast-scaffold.d.ts.map

package/dist/{commands/scaffold-fast.js → fast-scaffold.js}

@@ -54,4 +54,4 @@ export function parseFastCore(argv) {
 export function isFastCoreRequest(argv) {
     return parseFastCore(argv) !== null;
 }
-//# sourceMappingURL=scaffold-fast.js.map
+//# sourceMappingURL=fast-scaffold.js.map

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { isVersionRequest } from "./version-request.js";
-import { isFastCoreRequest } from "./commands/scaffold-fast.js";
+import { isFastCoreRequest } from "./fast-scaffold.js";
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;

package/dist/index.js

@@ -6,7 +6,7 @@ import "./node-network-compat.js";
 import { isVersionRequest, wantsLabelledVersionReport } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
-import { isFastCoreRequest } from "./commands/scaffold-fast.js";
+import { isFastCoreRequest } from "./fast-scaffold.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
@@ -33,7 +33,7 @@ if (isVersionRequest(process.argv)) {
 else if (isFastCoreRequest(process.argv)) {
     // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
     // dispatches straight to the bundled-script runner, so it never pays for the
-    // ~60-module command graph main.ts imports. See src/commands/scaffold-fast.ts.
+    // ~60-module command graph main.ts imports. See src/fast-scaffold.ts.
     void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
 }
 else {

package/dist/lib/checkpoint-ontology/apply.d.ts

@@ -105,6 +105,14 @@ export declare class ApplyError extends Error {
 }
 /** Validate one raw candidate. Returns the candidate or a rejection reason. */
 export declare function parseCandidate(raw: unknown): Candidate | string;
+/**
+ * checkpoint.ontology.named-evidence: true when `evidence` holds one of
+ * `names` as a word, matching case. A name inside a path, domain, handle, tag
+ * or identifier does not count: `indigoai-us/hq`, `getindigo.ai`,
+ * `C:\\Indigo\\hq`, `scope: company:indigo`, `Indigo:internal`, `@indigo`,
+ * `` `indigo` ``.
+ */
+export declare function evidenceNames(evidence: string, names: string[]): boolean;
 type Resolution = {
     tier: 1;
     target: string;

package/dist/lib/checkpoint-ontology/apply.js

@@ -63,6 +63,25 @@ export function parseCandidate(raw) {
         evidence: typeof c.evidence === "string" ? c.evidence : "",
     };
 }
+/**
+ * checkpoint.ontology.named-evidence: true when `evidence` holds one of
+ * `names` as a word, matching case. A name inside a path, domain, handle, tag
+ * or identifier does not count: `indigoai-us/hq`, `getindigo.ai`,
+ * `C:\\Indigo\\hq`, `scope: company:indigo`, `Indigo:internal`, `@indigo`,
+ * `` `indigo` ``.
+ */
+export function evidenceNames(evidence, names) {
+    for (const raw of names) {
+        const name = raw.trim();
+        if (!name || !evidence)
+            continue;
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const word = new RegExp(`(?<![\\p{L}\\p{N}_\\-./\\\\@:\`#])${escaped}(?![\\p{L}\\p{N}_\\-/\\\\@\`]|[.:#][\\p{L}\\p{N}])`, "u");
+        if (word.test(evidence))
+            return true;
+    }
+    return false;
+}
 /** Design section 5.3, tiers 1 to 4. */
 export function resolveCandidate(index, type, canonical) {
     const normalized = normalizeEntityName(canonical, type);
@@ -281,6 +300,9 @@ export function applyOntologyRun(options) {
             if (types.size > 1)
                 crossTypeNames.add(name);
     }
+    // checkpoint.ontology.named-evidence: the company's own company entity.
+    const ownCompanyRel = `ontology/entities/company/${company.slug}.md`;
+    const isOwnCompany = (entity, rel) => entity.type === "company" && (rel === ownCompanyRel || crossTypeKey(entity.canonical_name) === crossTypeKey(company.slug));
     const inputs = liveInputs(options.hqRoot, company, plan);
     const blocked = new Set();
     const updates = new Map();
@@ -339,6 +361,13 @@ export function applyOntologyRun(options) {
                 note(report.rejected, "ambiguous_type");
                 continue;
             }
+            if (plan.named_evidence === true &&
+                input.kind === "knowledge" &&
+                isOwnCompany(linked, resolved.target) &&
+                !evidenceNames(candidate.evidence, [candidate.name, ...candidate.aliases])) {
+                note(report.rejected, "unnamed_in_evidence");
+                continue;
+            }
             report.matched += 1;
             report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: resolved.target });
             if (resolved.tier === 1 && resolved.duplicates.length > 0) {
@@ -379,6 +408,10 @@ export function applyOntologyRun(options) {
                 ? [...(index.canonical.get(entityKey("project", normalizeEntityName(canonical, "project"))) ?? [])]
                 : [];
             if (projects.length === 1) {
+                if (plan.named_evidence === true && !evidenceNames(candidate.evidence, [candidate.name, ...candidate.aliases])) {
+                    note(report.rejected, "unnamed_in_evidence");
+                    continue;
+                }
                 const linked = index.byRel.get(projects[0]);
                 report.matched += 1;
                 report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: projects[0] });

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -81,6 +81,19 @@ export declare const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.sk
  * to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
  */
 export declare const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-link";
+/**
+ * A knowledge link to the company's own company entity, or a
+ * concept-project-link redirect, needs evidence that names the entity as a
+ * word: the candidate name or one of its aliases, not inside a path, domain,
+ * handle, tag or identifier (`indigoai-us/hq`, `getindigo.ai`,
+ * `scope: company:indigo`). The plan carries `named_evidence: true`, and apply
+ * rejects such a link as `unnamed_in_evidence`. CO-57: on the six CO-52 runs,
+ * 67 of 143 false positives were links to company/indigo and project/HQ, most
+ * on evidence that only held the name inside an identifier; a replay of this
+ * rule raised precision on the concept-project-link arm from 0.705 to 0.750
+ * and lost no gold link.
+ */
+export declare const NAMED_EVIDENCE_FLAG = "checkpoint.ontology.named-evidence";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -153,6 +166,8 @@ export interface OntologyPlan {
     skip_ambiguous_concept_links?: true;
     /** Set by checkpoint.ontology.concept-project-link: apply links a knowledge concept with an ambiguous alias to the one project of that canonical name. */
     concept_project_link?: true;
+    /** Set by checkpoint.ontology.named-evidence: apply rejects a knowledge link to the company's own entity, or a concept-project-link redirect, whose evidence does not name it as a word. */
+    named_evidence?: true;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;

package/dist/lib/checkpoint-ontology/plan.js

@@ -85,6 +85,19 @@ export const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambig
  * to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
  */
 export const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-link";
+/**
+ * A knowledge link to the company's own company entity, or a
+ * concept-project-link redirect, needs evidence that names the entity as a
+ * word: the candidate name or one of its aliases, not inside a path, domain,
+ * handle, tag or identifier (`indigoai-us/hq`, `getindigo.ai`,
+ * `scope: company:indigo`). The plan carries `named_evidence: true`, and apply
+ * rejects such a link as `unnamed_in_evidence`. CO-57: on the six CO-52 runs,
+ * 67 of 143 false positives were links to company/indigo and project/HQ, most
+ * on evidence that only held the name inside an identifier; a replay of this
+ * rule raised precision on the concept-project-link arm from 0.705 to 0.750
+ * and lost no gold link.
+ */
+export const NAMED_EVIDENCE_FLAG = "checkpoint.ontology.named-evidence";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -264,6 +277,7 @@ export async function planOntologyRun(options) {
     const firstNamePeople = await options.readFlag(FIRST_NAME_PEOPLE_FLAG, company);
     const skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG, company);
     const conceptProjectLink = await options.readFlag(CONCEPT_PROJECT_LINK_FLAG, company);
+    const namedEvidence = await options.readFlag(NAMED_EVIDENCE_FLAG, company);
     const touched = sessionTouched(hqRoot, company, payload.files);
     // A first run takes its boundary from the entity tree, so the ledger is
     // refreshed before merge-back moves any `last_updated` forward.
@@ -366,6 +380,7 @@ export async function planOntologyRun(options) {
         ...(firstNamePeople ? { first_name_people: true } : {}),
         ...(skipAmbiguousConceptLinks ? { skip_ambiguous_concept_links: true } : {}),
         ...(conceptProjectLink ? { concept_project_link: true } : {}),
+        ...(namedEvidence ? { named_evidence: true } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,

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/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/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