@indigoai-us/hq-cli 5.257.0 → 5.259.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [5.259.0] — 2026-09-28
+
+### Fixed
+
+- The checkpoint stop gate now recognizes path-qualified `hq core checkpoint`
+  commands without treating lookalike text as a checkpoint.
+- `hq doctor --live-runtimes` now invokes Windows npm shims through their `.cmd`
+  entry points.
+
+## [5.258.0] — 2026-09-28
+
+### Fixed
+
+- Envelope repair runs through the currently installed CLI so a long-lived
+  watcher cannot use stale worker-profile validation.
+- Updated the external-agent CLI guide to match the kit services, probe checks,
+  shipped skills, and MCP tools.
+- Fixed the Docker agent-kit launcher to supervise configured services through
+  `hq agent kit run all`.
+- `hq packages list` and `hq packs list` return an error when run outside an HQ tree.
+- `hq index collections` prints a summary when no collections are expected or registered.
+
 ## [5.257.0] — 2026-09-28
 
 ### Added

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -350,7 +350,11 @@ exec 3>&2
       else ""
       end;
     def checkpoint_command:
-      test("(^|[;&|(\\s])(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint(\\s|$)");
+      # Match the actual command at a shell command boundary. A whitespace
+      # boundary alone would accept `echo hq core checkpoint`; allow only the
+      # shell wrappers and environment assignments that can invoke hq itself.
+      # Quoted assignment values and executable paths may contain spaces.
+      test("(^\\s*|[;&|()]\\s*|\\n\\s*)(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?(\"[^\"]*[/\\\\]hq\"|[^\\s;&|()]*[/\\\\]hq|hq)\\s+core\\s+checkpoint(\\s|$)");
     def strip_quoted:
       # Remove quoted spans so flag text inside a --summary value (e.g.
       # --summary "investigated --gate-probe behavior") is never mistaken for
@@ -362,12 +366,21 @@ exec 3>&2
     def checkpoint_flag($flag):
       strip_quoted | test("(^|\\s)" + $flag + "(\\s|$)");
     def pure_checkpoint:
-      # The command is ONLY a checkpoint invocation (optional env-assignment
-      # prefix, no other command joined by a separator). A compound call like
-      # `git status; hq core checkpoint --idle` did other work in the same
-      # tool call, so its exemptions must not apply.
-      strip_quoted
-      | test("^\\s*(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$");
+      # The command is ONLY a checkpoint invocation (recognized wrappers and
+      # env assignments are allowed, but no other command may be joined by a
+      # separator). A compound call like `git status; hq core checkpoint
+      # --idle` did other work in the same tool call, so its exemptions do not
+      # apply.
+      # Normalize a quoted or path-qualified executable to hq before
+      # stripping quoted argument values, so a path with spaces still gets
+      # the same --idle exemptions.
+      (capture("^(?<prefix>\\s*(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?)(?<executable>\"[^\"]*[/\\\\]hq\"|[^\\s;&|()]*[/\\\\]hq|hq)(?<tail>\\s+core\\s+checkpoint(?:\\s+[^;&|\n]*)?)$")? // false) as $parts
+      | if $parts == false then false
+        else
+          ($parts.prefix + "hq" + $parts.tail)
+          | strip_quoted
+          | test("^\\s*(?:(?:command|exec)\\s+)?(?:env\\s+)?([A-Za-z_][A-Za-z0-9_]*=(?:\"(?:\\\\.|[^\"\\\\])*\"|\\u0027[^\\u0027]*\\u0027|[^\\s;&|()]*)\\s+)*(?:(?:command|exec|env)\\s+)?hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$")
+        end;
     def gate_feedback_user:
       # This gate surfaces its own Stop feedback as a synthetic user row. That
       # row is a turn boundary for the checkpoint requirement, but NOT for

package/dist/command-catalog.generated.d.ts

@@ -8180,6 +8180,18 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "_spawn-envelope-repair";
+        readonly description: "";
+        readonly aliases: readonly [];
+        readonly hidden: true;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "_monitor-message";
         readonly description: "";

package/dist/command-catalog.generated.js

@@ -10581,6 +10581,21 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "_spawn-envelope-repair",
+                "description": "",
+                "aliases": [],
+                "hidden": true,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "_monitor-message",
                 "description": "",

package/dist/commands/agent-kit.d.ts

@@ -4,13 +4,15 @@
  *
  *   sync       company vault pull loop            → component-sync
  *   inbox      inbox poller (mirror + optional ack) → component-inbox
- *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
+ *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with enabled component status
  *
- * `install` renders one user-level unit per service (LaunchAgent on macOS,
- * systemd --user on Linux), each of which just runs
- * `node hq agent kit run <service>`; the Docker image runs the same four
- * commands. Hosts where the service manager is unusable (no systemd user
- * session bus, permission refused, launchd unavailable) fall back to one
+ * `install` renders one user-level unit per enabled service (LaunchAgent on
+ * macOS, systemd --user on Linux), each of which just runs
+ * `node hq agent kit run <service>`. The Docker entrypoint runs
+ * `hq agent kit run all`, which supervises the services enabled in kit.json,
+ * including sync only when file mirroring is configured. Hosts where the
+ * service manager is unusable, such as a missing systemd user session bus or
+ * unavailable launchd, fall back to one
  * detached `hq agent kit run all` supervisor (pid in ~/.hq-agent/kit.pid,
  * output in ~/.hq-agent/logs/kit.log). Logs: ~/.hq-agent/logs/<service>.log. Skills:
  * ~/.hq-agent/skills/<name>/SKILL.md.

package/dist/commands/agent-kit.js

@@ -4,13 +4,15 @@
  *
  *   sync       company vault pull loop            → component-sync
  *   inbox      inbox poller (mirror + optional ack) → component-inbox
- *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
+ *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with enabled component status
  *
- * `install` renders one user-level unit per service (LaunchAgent on macOS,
- * systemd --user on Linux), each of which just runs
- * `node hq agent kit run <service>`; the Docker image runs the same four
- * commands. Hosts where the service manager is unusable (no systemd user
- * session bus, permission refused, launchd unavailable) fall back to one
+ * `install` renders one user-level unit per enabled service (LaunchAgent on
+ * macOS, systemd --user on Linux), each of which just runs
+ * `node hq agent kit run <service>`. The Docker entrypoint runs
+ * `hq agent kit run all`, which supervises the services enabled in kit.json,
+ * including sync only when file mirroring is configured. Hosts where the
+ * service manager is unusable, such as a missing systemd user session bus or
+ * unavailable launchd, fall back to one
  * detached `hq agent kit run all` supervisor (pid in ~/.hq-agent/kit.pid,
  * output in ~/.hq-agent/logs/kit.log). Logs: ~/.hq-agent/logs/<service>.log. Skills:
  * ~/.hq-agent/skills/<name>/SKILL.md.

package/dist/commands/index-cmd.js

@@ -131,7 +131,11 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const registered = dependencies.listRegisteredCollections(hqRoot);
-        for (const line of collectionStatusLines(dependencies.deriveCollections(hqRoot), registered))
+        const expected = dependencies.deriveCollections(hqRoot);
+        const lines = collectionStatusLines(expected, registered);
+        if (lines.length === 0)
+            console.log(collectionSummary(expected, registered));
+        for (const line of lines)
             console.log(line);
     });
     index

package/dist/commands/lanes.js

@@ -61,7 +61,7 @@ import { SESSION_MOVE_REASON } from "../lib/lanes/move-account.js";
 import { managerStatusGateEnabledForLane, resolveManagerStatusGateForLane, } from "../lib/lanes/manager-status-gate.js";
 import { ensureSessionHome } from "../lib/lanes/session-relink.js";
 import { defaultProbe, validateProfileLaneModel, validateLaneModel, } from "../lib/lanes/models.js";
-import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, spawnLaneWorker, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
+import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
 import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export { spawnLaneWorker };
 export { questionBodyAbsPath };
@@ -7155,6 +7155,28 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (laneId) => {
         printJson(await messageHandlers.recoverQueuedMessages(ctx, laneId));
     }));
+    lanes
+        .command("_spawn-envelope-repair", { hidden: true })
+        .action(wrap(async () => {
+        let payload;
+        try {
+            payload = JSON.parse(ctx.readStdin());
+        }
+        catch (err) {
+            throw new LanesError("repair_request_invalid", `Envelope repair request is invalid JSON: ${err instanceof Error ? err.message : String(err)}`, {});
+        }
+        printJson(spawnEnvelopeRepairRequest(ctx.hqRoot(), payload, {
+            env: ctx.env,
+            hostname: ctx.hostname(),
+            existsSync: ctx.existsSync,
+            spawnProcess: ctx.spawnProcess,
+            proveDetached: ctx.proveDetached,
+            killProcess: ctx.killProcess,
+            resolveMachineIdentity: ctx.resolveMachineIdentity,
+            runCompaction: ctx.runCompaction,
+            locateTranscript: ctx.locateTranscript,
+        }));
+    }));
     lanes
         .command("_monitor-message", { hidden: true })
         .argument("<lane-id>", "Lane id")

package/dist/commands/packs.js

@@ -23,11 +23,21 @@ import { spawnSync } from 'child_process';
 import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import { findHqRoot } from '../utils/manifest.js';
+import { resolveHqRoot as resolveDetectedHqRoot } from './doctor.js';
 import { classify, resolveLatest, resolveLatestMarketplace, runScanPackages, installPack, } from './pack-install.js';
 import { contributionLinks, linkStatus, listInstalledPacks, findDependentPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
 function resolveRoot(opts) {
     return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
 }
+function resolvePackListRoot(opts) {
+    if (opts.hqRoot)
+        return path.resolve(opts.hqRoot);
+    const hqRoot = resolveDetectedHqRoot(process.cwd());
+    if (!hqRoot) {
+        throw new Error('hq packages: not inside an HQ tree. Run this command from inside your HQ root or pass --hq-root <path>.');
+    }
+    return hqRoot;
+}
 /** JSON when --json or when piped (non-TTY); human-readable on a terminal. */
 function wantsJson(opts) {
     return opts.json === true || !process.stdout.isTTY;
@@ -377,7 +387,7 @@ export function registerPacksListCommand(parent) {
         .option('--eval-conditionals', 'Evaluate catalog conditional predicates (runs bash)')
         .action(async (opts) => {
         try {
-            const view = await buildListView(resolveRoot(opts), !!opts.checkUpdates, !!opts.evalConditionals, !!opts.refresh);
+            const view = await buildListView(resolvePackListRoot(opts), !!opts.checkUpdates, !!opts.evalConditionals, !!opts.refresh);
             if (wantsJson(opts))
                 emitJson(view);
             else

package/dist/commands/reindex.js

@@ -1,10 +1,11 @@
 /**
- * hq reindex — surface namespaced skills, mirror the personal overlay into
- * core/, regenerate the workers registry, and converge HQ-owned hook trust for
- * Codex, Grok, and Claude Code.
+ * hq reindex — surface namespaced skills and commands, clean up retired
+ * personal-overlay mirror links, capture coding-harness session logs, regenerate
+ * the workers registry, and converge HQ-owned hook trust for Codex, Grok, and
+ * Claude Code.
  *
- * Thin wrapper over @indigoai-us/hq-cloud's reindex(), which execs the bundled
- * scripts/reindex.sh against the HQ root. This command is what the hq-core
+ * Thin wrapper over @indigoai-us/hq-cloud's native TypeScript reindex(), which
+ * runs against the HQ root. This command is what the hq-core
  * reindex hook shim calls on Stop / PostToolUse, and what sync()/rescue() call
  * after they change on-disk sources.
  *

package/dist/lib/agent-kit/paths.d.ts

@@ -5,7 +5,7 @@
  *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
  *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
- *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/state/               component-{sync,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
  *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service

package/dist/lib/agent-kit/paths.js

@@ -5,7 +5,7 @@
  *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
  *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
- *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/state/               component-{sync,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
  *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service

package/dist/lib/agent-kit/run/heartbeat.d.ts

@@ -1,12 +1,10 @@
 /**
  * Kit service: heartbeat reporter.
  *
- * Every 60 s POST /v1/agents/{uid}/heartbeat with
- * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
- * external-agent body from api-contract v1, mirroring the hosted box's
- * hq-agent-heartbeat.sh (which folds per-component stamp files into one
- * beat). Component values are read from the stamps the other three services
- * write; a missing or stale stamp reports `error`, never silence.
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with the enabled component status
+ * values (`sync` and `inbox`), plus cliVersion and hostInfo. The external-agent
+ * body mirrors the hosted box's hq-agent-heartbeat.sh, which folds per-component
+ * stamp files into one beat. A missing or stale enabled stamp reports `error`.
  *
  * The last successful beat is recorded at state/last-heartbeat.json so
  * `hq agent probe` can report its age.

package/dist/lib/agent-kit/run/heartbeat.js

@@ -1,12 +1,10 @@
 /**
  * Kit service: heartbeat reporter.
  *
- * Every 60 s POST /v1/agents/{uid}/heartbeat with
- * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
- * external-agent body from api-contract v1, mirroring the hosted box's
- * hq-agent-heartbeat.sh (which folds per-component stamp files into one
- * beat). Component values are read from the stamps the other three services
- * write; a missing or stale stamp reports `error`, never silence.
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with the enabled component status
+ * values (`sync` and `inbox`), plus cliVersion and hostInfo. The external-agent
+ * body mirrors the hosted box's hq-agent-heartbeat.sh, which folds per-component
+ * stamp files into one beat. A missing or stale enabled stamp reports `error`.
  *
  * The last successful beat is recorded at state/last-heartbeat.json so
  * `hq agent probe` can report its age.

package/dist/lib/doctor/checks/runtime-health.d.ts

@@ -80,6 +80,8 @@ export interface RuntimeHealthDeps {
     execProbe?: (file: string, args: string[], timeoutMs: number) => Promise<ProbeOutcome>;
     /** Per-probe timeout. Default {@link DEFAULT_PROBE_TIMEOUT_MS}. */
     probeTimeoutMs?: number;
+    /** Runtime platform override for the spawn plan (normally process.platform). */
+    platform?: NodeJS.Platform;
 }
 /**
  * The AI-runtime-health check family entry. Presence checks always run; the

package/dist/lib/doctor/checks/runtime-health.js

@@ -29,6 +29,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { planCommandSpawn } from "../../../utils/windows-spawn.js";
 /** The id of the AI-runtime-health family. */
 export const RUNTIMES_FAMILY_ID = "runtimes";
 /** Common id prefix for every result this family emits. */
@@ -101,7 +102,8 @@ export async function checkRuntimeHealth(context, deps = {}) {
 async function runRuntimeChecks(context, deps) {
     const resolved = {
         resolveBinary: deps.resolveBinary ?? resolveOnPath,
-        execProbe: deps.execProbe ?? defaultExecProbe,
+        execProbe: deps.execProbe ??
+            ((file, args, timeoutMs) => defaultExecProbe(file, args, timeoutMs, deps.platform ?? process.platform)),
         timeoutMs: deps.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
         live: context.liveRuntimes === true,
     };
@@ -268,11 +270,19 @@ export function resolveOnPath(binary) {
  * CLI that reads piped stdin in non-TTY mode — blocks forever on a pipe that
  * never reaches EOF, which turns every probe into a timeout.
  */
-function defaultExecProbe(file, args, timeoutMs) {
+function defaultExecProbe(file, args, timeoutMs, platform) {
     return new Promise((resolve) => {
-        const child = spawn(file, args, {
+        const command = platform === "win32" && !/\.(?:cmd|bat|exe|com)$/i.test(file)
+            ? `${file}.cmd`
+            : file;
+        const plan = planCommandSpawn(command, args, platform);
+        const child = spawn(plan.cmd, plan.args, {
             cwd: os.tmpdir(),
             stdio: ["ignore", "pipe", "pipe"],
+            shell: plan.shell,
+            ...(plan.windowsVerbatimArguments === undefined
+                ? {}
+                : { windowsVerbatimArguments: plan.windowsVerbatimArguments }),
         });
         const cap = 1024 * 1024;
         let stdout = "";

package/dist/lib/lanes/envelope-repair-dispatch.d.ts

@@ -0,0 +1,26 @@
+import type { LaneRecord } from "./types.js";
+import type { EnvelopeRepairSpawnInput } from "./spawn.js";
+interface EnvelopeRepairDispatchResult {
+    error?: Error;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+interface EnvelopeRepairDispatchOptions {
+    encoding: "utf8";
+    timeout: number;
+    input: string;
+    env: NodeJS.ProcessEnv;
+}
+export interface EnvelopeRepairDispatchDeps {
+    env?: NodeJS.ProcessEnv;
+    spawnSync?: (command: string, args: string[], options: EnvelopeRepairDispatchOptions) => EnvelopeRepairDispatchResult;
+}
+/**
+ * Dispatch repair into the currently installed CLI. A watcher can stay alive
+ * across upgrades, so repair must not call its in-memory spawn implementation.
+ */
+export declare function spawnEnvelopeRepairViaCurrentCli(hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput, deps?: EnvelopeRepairDispatchDeps): number;
+export {};
+//# sourceMappingURL=envelope-repair-dispatch.d.ts.map

package/dist/lib/lanes/envelope-repair-dispatch.js

@@ -0,0 +1,74 @@
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+/**
+ * Dispatch repair into the currently installed CLI. A watcher can stay alive
+ * across upgrades, so repair must not call its in-memory spawn implementation.
+ */
+export function spawnEnvelopeRepairViaCurrentCli(hqRoot, lane, input, deps = {}) {
+    const request = {
+        lane_id: lane.lane_id,
+        input: {
+            ...(input.session_id !== undefined ? { session_id: input.session_id } : {}),
+            envelopePath: input.envelopePath,
+            error: input.error,
+            rawText: input.rawText,
+            ...(input.missing !== undefined ? { missing: input.missing } : {}),
+        },
+    };
+    const run = deps.spawnSync ?? ((command, args, options) => {
+        const result = nodeSpawnSync(command, args, options);
+        return {
+            ...(result.error !== undefined ? { error: result.error } : {}),
+            status: result.status,
+            signal: result.signal,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    });
+    const env = deps.env ?? process.env;
+    const cliEntry = env.HQ_LANE_CLI_ENTRY?.trim();
+    if (!cliEntry || !path.isAbsolute(cliEntry) || path.resolve(cliEntry) !== cliEntry) {
+        throw new LanesError("repair_cli_entry_invalid", "Lane watcher has no valid absolute hq CLI entrypoint for envelope repair", { lane_id: lane.lane_id });
+    }
+    const result = run(process.execPath, [cliEntry, "lanes", "_spawn-envelope-repair"], {
+        encoding: "utf8",
+        timeout: 120_000,
+        input: JSON.stringify(request),
+        env: {
+            ...env,
+            HQ_ROOT: hqRoot,
+            HQ_NO_UPDATE_CHECK: "1",
+            HQ_TELEMETRY: "0",
+        },
+    });
+    if (result.error) {
+        throw new LanesError("repair_cli_spawn_failed", `Current hq CLI could not start the envelope repair: ${result.error.message}`, { lane_id: lane.lane_id });
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || `exit ${result.status ?? result.signal ?? "without status"}`;
+        throw new LanesError("repair_cli_failed", `Current hq CLI envelope repair failed: ${detail}`, { lane_id: lane.lane_id, status: result.status, signal: result.signal });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch (err) {
+        throw new LanesError("repair_cli_result_invalid", `Current hq CLI returned invalid envelope repair JSON: ${err instanceof Error ? err.message : String(err)}`, { lane_id: lane.lane_id });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("repair_cli_result_invalid", "Current hq CLI returned an invalid envelope repair result", { lane_id: lane.lane_id });
+    }
+    const response = parsed;
+    if (!Number.isInteger(response.pid) ||
+        Number(response.pid) <= 0 ||
+        !Array.isArray(response.profile_warnings) ||
+        !response.profile_warnings.every((warning) => Array.isArray(warning) && warning.every((field) => typeof field === "string"))) {
+        throw new LanesError("repair_cli_result_invalid", "Current hq CLI returned an invalid envelope repair result", { lane_id: lane.lane_id });
+    }
+    for (const warning of response.profile_warnings) {
+        input.onProfileWarning?.(warning);
+    }
+    return Number(response.pid);
+}
+//# sourceMappingURL=envelope-repair-dispatch.js.map

package/dist/lib/lanes/spawn.d.ts

@@ -68,6 +68,8 @@ export type ProveDetachedFn = (pid: number) => DetachProof;
 export type KillProcessFn = (pid: number, signal?: NodeJS.Signals) => void;
 export interface SpawnLaneDeps {
     env?: NodeJS.ProcessEnv;
+    /** Absolute CLI entry captured when the watcher is armed; tests may inject it. */
+    hqCliEntry?: string;
     hostname?: string;
     /** The caller's host scope for admission checks; reconcile supplies its resolved host. */
     admissionHost?: AdmissionHost;
@@ -311,6 +313,16 @@ export interface EnvelopeRepairSpawnInput {
     /** Repair-only warning hook for profile metadata ignored during recovery. */
     onProfileWarning?: (fields: readonly string[]) => void;
 }
+/**
+ * Handle the private request sent by an older, long-running watcher to the
+ * currently installed `hq` executable. The persisted repair attempt is the
+ * authorization for this one-shot spawn; the request cannot select an
+ * arbitrary lane or write outside that lane's envelope directory.
+ */
+export declare function spawnEnvelopeRepairRequest(hqRoot: string, rawRequest: unknown, deps?: SpawnLaneDeps): {
+    pid: number;
+    profile_warnings: string[][];
+};
 /** How the spec §4 repair turn reaches the provider (recorded as `envelope_repair.mode`). */
 export type EnvelopeRepairMode = "resume" | "fresh_turn";
 /**

package/dist/lib/lanes/spawn.js

@@ -1508,10 +1508,15 @@ export function armLaneWatcher(hqRoot, laneId, deps = {}) {
     const runDir = laneRunDir(hqRoot, laneId);
     const logsDir = path.join(runDir, "logs");
     ensureDir(logsDir);
+    const cliEntry = deps.hqCliEntry?.trim() || process.argv[1]?.trim();
+    if (!cliEntry) {
+        throw new LanesError("watcher_cli_entry_unavailable", "Cannot arm the lane watcher without the current hq CLI entrypoint", { lane_id: laneId });
+    }
     const watcherPid = spawnDetached(spawnProcess, process.execPath, [watcherMainPath(), laneId], {
         ...env,
         HQ_ROOT: hqRoot,
         HQ_LANE_ID: laneId,
+        HQ_LANE_CLI_ENTRY: path.resolve(cliEntry),
     }, hqRoot, path.join(logsDir, "watcher.out"), path.join(logsDir, "watcher.err"));
     writePidRecord(path.join(runDir, "watcher.pid"), {
         pid: watcherPid,
@@ -2228,6 +2233,88 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     }
     return laneLaunchResult(readLane(hqRoot, lane.lane_id));
 }
+/**
+ * Handle the private request sent by an older, long-running watcher to the
+ * currently installed `hq` executable. The persisted repair attempt is the
+ * authorization for this one-shot spawn; the request cannot select an
+ * arbitrary lane or write outside that lane's envelope directory.
+ */
+export function spawnEnvelopeRepairRequest(hqRoot, rawRequest, deps = {}) {
+    const invalid = (message) => {
+        throw new LanesError("repair_request_invalid", message, {});
+    };
+    if (!rawRequest || typeof rawRequest !== "object" || Array.isArray(rawRequest)) {
+        return invalid("Envelope repair request must be an object");
+    }
+    const request = rawRequest;
+    if (Object.keys(request).some((key) => key !== "lane_id" && key !== "input")) {
+        return invalid("Envelope repair request has unknown fields");
+    }
+    if (typeof request.lane_id !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(request.lane_id)) {
+        return invalid("Envelope repair request must include a lane_id");
+    }
+    if (!request.input || typeof request.input !== "object" || Array.isArray(request.input)) {
+        return invalid("Envelope repair request input must be an object");
+    }
+    const rawInput = request.input;
+    const allowedInputFields = new Set([
+        "session_id",
+        "envelopePath",
+        "error",
+        "rawText",
+        "missing",
+    ]);
+    if (Object.keys(rawInput).some((key) => !allowedInputFields.has(key))) {
+        return invalid("Envelope repair request input has unknown fields");
+    }
+    if (typeof rawInput.envelopePath !== "string" ||
+        !path.isAbsolute(rawInput.envelopePath) ||
+        path.resolve(rawInput.envelopePath) !== rawInput.envelopePath ||
+        typeof rawInput.error !== "string" ||
+        !rawInput.error.trim() ||
+        typeof rawInput.rawText !== "string" ||
+        (rawInput.session_id !== undefined &&
+            rawInput.session_id !== null &&
+            (typeof rawInput.session_id !== "string" || !rawInput.session_id.trim())) ||
+        (rawInput.missing !== undefined && typeof rawInput.missing !== "boolean")) {
+        return invalid("Envelope repair request input has invalid fields");
+    }
+    const lane = readLane(hqRoot, request.lane_id);
+    const repair = lane.envelope_repair;
+    if (lane.state !== "running" || !repair?.attempted || repair.succeeded) {
+        throw new LanesError("repair_request_not_authorized", `Lane ${lane.lane_id} has no pending envelope repair attempt`, { lane_id: lane.lane_id });
+    }
+    if (repair.first_error !== rawInput.error) {
+        throw new LanesError("repair_request_stale", `Lane ${lane.lane_id} envelope repair request no longer matches its recorded error`, { lane_id: lane.lane_id });
+    }
+    const envelopeDir = path.resolve(laneRunDir(hqRoot, lane.lane_id), "envelopes");
+    const envelopePath = path.resolve(rawInput.envelopePath);
+    if (path.dirname(envelopePath) !== envelopeDir ||
+        !path.basename(envelopePath).endsWith(".json") ||
+        typeof repair.envelope_ref !== "string" ||
+        path.posix.dirname(repair.envelope_ref) !== "envelopes" ||
+        !path.posix.basename(repair.envelope_ref).endsWith(".json")) {
+        throw new LanesError("repair_request_path_invalid", `Lane ${lane.lane_id} envelope repair request does not name a lane envelope`, { lane_id: lane.lane_id });
+    }
+    const recordedEnvelopePath = path.resolve(laneRunDir(hqRoot, lane.lane_id), repair.envelope_ref);
+    if (envelopePath !== recordedEnvelopePath) {
+        throw new LanesError("repair_request_envelope_mismatch", `Lane ${lane.lane_id} envelope repair request does not match the recorded repair slot`, { lane_id: lane.lane_id, envelope_ref: repair.envelope_ref });
+    }
+    const warnings = [];
+    const input = {
+        envelopePath,
+        error: rawInput.error,
+        rawText: rawInput.rawText,
+        ...(typeof rawInput.session_id === "string" || rawInput.session_id === null
+            ? { session_id: rawInput.session_id }
+            : {}),
+        ...(typeof rawInput.missing === "boolean" ? { missing: rawInput.missing } : {}),
+        onProfileWarning: (fields) => warnings.push([...fields]),
+    };
+    const pid = spawnEnvelopeRepair(hqRoot, lane, input, deps);
+    return { pid, profile_warnings: warnings };
+}
 /**
  * `resume`: claude and codex continue the recorded session with the repair
  * prompt. `fresh_turn`: grok gets a new single-turn invocation on the same

package/dist/lib/lanes/watcher-main.d.ts

@@ -5,5 +5,7 @@
  * Usage: node watcher-main.js <lane-id>
  * Requires HQ_ROOT in the environment.
  */
-export {};
+import { type EnvelopeRepairDispatchDeps } from "./envelope-repair-dispatch.js";
+import type { WatcherLoopDeps } from "./watcher.js";
+export declare function watcherMainDeps(hqRoot: string, laneId: string, env?: NodeJS.ProcessEnv, repairDispatchDeps?: Pick<EnvelopeRepairDispatchDeps, "spawnSync">): WatcherLoopDeps;
 //# sourceMappingURL=watcher-main.d.ts.map

package/dist/lib/lanes/watcher-main.js

@@ -6,12 +6,33 @@
  * Requires HQ_ROOT in the environment.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runWatcherLoop } from "./watcher.js";
+import { spawnEnvelopeRepairViaCurrentCli, } from "./envelope-repair-dispatch.js";
 import { LanesError } from "./errors.js";
 import { openMeshTransport } from "../mesh/client.js";
 import { CompanySelectionError } from "../../utils/company-selection-error.js";
+export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatchDeps = {}) {
+    const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
+    return {
+        resolveQuestionActiveCompany,
+        spawnRepair: (root, lane, input) => spawnEnvelopeRepairViaCurrentCli(root, lane, input, { ...repairDispatchDeps, env }),
+        recoverQueuedMessages: async () => {
+            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
+                env,
+                encoding: "utf8",
+                timeout: 120_000,
+            });
+            if (result.error)
+                throw result.error;
+            if (result.status !== 0) {
+                throw new Error(`recovery command exited ${result.status ?? result.signal ?? "without status"}: ${(result.stderr ?? "").trim()}`);
+            }
+        },
+    };
+}
 async function resolveQuestionActiveCompany() {
     try {
         const { company } = await openMeshTransport({});
@@ -30,25 +51,14 @@ function main() {
         process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
         process.exit(1);
     }
-    const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
-    void runWatcherLoop(hqRoot, laneId, {
-        resolveQuestionActiveCompany,
-        recoverQueuedMessages: async () => {
-            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
-                env: process.env,
-                encoding: "utf8",
-                timeout: 120_000,
-            });
-            if (result.error)
-                throw result.error;
-            if (result.status !== 0) {
-                throw new Error(`recovery command exited ${result.status ?? result.signal ?? "without status"}: ${(result.stderr ?? "").trim()}`);
-            }
-        },
-    }).catch((err) => {
+    void runWatcherLoop(hqRoot, laneId, watcherMainDeps(hqRoot, laneId, process.env)).catch((err) => {
         process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
         process.exit(1);
     });
 }
-main();
+const invokedEntryPath = process.argv[1] ? path.resolve(process.argv[1]) : undefined;
+const currentModule = realpathSync(fileURLToPath(import.meta.url));
+if (invokedEntryPath && existsSync(invokedEntryPath) && realpathSync(invokedEntryPath) === currentModule) {
+    main();
+}
 //# sourceMappingURL=watcher-main.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.257.0",
+  "version": "5.259.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {