@indigoai-us/hq-cli 5.345.61 → 5.345.63

package/dist/commands/core-hq-session-native.js

@@ -657,8 +657,12 @@ export function executeHqSession(argv, context, overrides = {}) {
                 const oldText = existed ? deps.readFile(target, "utf8") : `session_id: ${sessionId}\nstarted_at: "${timestamp(deps.now())}"\nsenior: user\n`;
                 const rawCompanies = metaCompanySlugs(oldText);
                 const companies = rawCompanies.filter((company) => company === "personal" || exactCompanyDir(root, company, deps));
-                if (subcommand === "add" && companies.includes(slug))
+                if (subcommand === "add" && companies.includes(slug)) {
+                    if (!mintScopeCapability(root, sessionId, companies, deps, true)) {
+                        return { code: 1, stdout: "", stderr: `hq-session: failed to repair scope-capability for session ${sessionId}; metadata was unchanged\n` };
+                    }
                     return { code: 0, stdout: "", stderr: "" };
+                }
                 const next = subcommand === "add"
                     ? [...(companies[0] === "personal" ? [] : companies), slug]
                     : companies.filter((value) => value !== slug);

package/dist/commands/daemon.js

@@ -24,7 +24,7 @@ import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/d
 import { ROOT_REFUSAL, SYSTEM_UNIT_DIR, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, } from "../lib/daemon/install.js";
 import { describeLegacyUnit, findLegacyUnits } from "../lib/daemon/legacy.js";
 import { isDaemonProcess, runningDaemonPid } from "../lib/daemon/lock.js";
-import { bundledHqCloud, managedHqCloud, managedHqCloudRoot, readHqCloudCopy } from "../lib/daemon/hq-cloud.js";
+import { bundledHqCloud, managedHqCloud, managedHqCloudRoot, readHqCloudCopy, readHqCloudUpdateState } from "../lib/daemon/hq-cloud.js";
 import { MACHINE_TYPE_MARKER_PATH, detectMachineType, homeFromPasswd, } from "../lib/daemon/machine-type.js";
 import { daemonPaths } from "../lib/daemon/paths.js";
 import { processCommandLine } from "../lib/daemon/lock.js";
@@ -510,6 +510,7 @@ function daemonSyncStatus(d) {
     const runnerSource = syncRunnerSource(runnerPath, paths.root, d.platform);
     const managedCopy = managedHqCloud(paths.root);
     const managedVersion = managedCopy?.version ?? null;
+    const hqCloudUpdate = readHqCloudUpdateState(paths.root);
     let hqCloudVersion = ownerStatus?.version ?? null;
     let hqCloudVersionSource = hqCloudVersion ? "owner-status" : "unknown";
     if (!hqCloudVersion && runnerPath) {
@@ -547,6 +548,10 @@ function daemonSyncStatus(d) {
         runnerSource,
         managedHqCloudVersion: managedVersion,
         pinnedHqCloudVersion: config.hqCloudVersion ?? null,
+        hqCloudUpdateLastCheckAt: hqCloudUpdate?.lastCheckAt ?? null,
+        hqCloudUpdateOutcome: hqCloudUpdate?.outcome ?? null,
+        hqCloudUpdateTarget: hqCloudUpdate?.target ?? null,
+        hqCloudUpdateErrorClass: hqCloudUpdate?.errorClass ?? null,
         lastHeartbeat: syncUnit?.lastHeartbeatAt ?? ownerStatus?.heartbeatAt ?? null,
         lastPassResult: syncUnit?.lastPassResult ?? null,
         unitStatus: syncUnit?.status ?? "not-running",

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

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerLanesLinkCommand(lanes: Command): void;
+//# sourceMappingURL=lanes-link.d.ts.map

package/dist/commands/lanes-link.js

@@ -0,0 +1,83 @@
+import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
+import { isLinkedSession, linkedSessionIdFromHookInput, LANE_SESSION_LINKS_FLAG, LaneLinkError, runLaneLinkWithFlag } from "../lib/lanes/links.js";
+function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function addLinkOptions(command) {
+    return command
+        .option("--json", "Print JSON output (the default)")
+        .option("--session-id <id>", "Act as this session")
+        .option("--link <id>", "Conduct link id")
+        .option("--child <name|all>", "Child name or all children")
+        .option("--name <name>", "Child name")
+        .option("--engine <engine>", "Session engine")
+        .option("--title <title>", "Session title")
+        .option("--host-session <id>", "Host session id")
+        .option("--text <message>", "Message text")
+        .option("--text-file <path>", "Read message text from a file")
+        .option("--state <state>", "Child state")
+        .option("--note <note>", "State note")
+        .option("--timeout <seconds>", "Wait timeout in seconds", (value) => Number(value));
+}
+async function readHookInput() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function commandError(error) {
+    const code = error instanceof LaneLinkError ? error.code : "internal";
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`hq lanes link: ${message}\n`);
+    writeJson({ error: code, message });
+    process.exitCode = 1;
+}
+export function registerLanesLinkCommand(lanes) {
+    const link = lanes.command("link").description("Link live sessions to a conductor through session inboxes");
+    const commands = ["open", "join", "send", "report", "status", "inbox", "read", "wait", "list", "leave", "close"];
+    for (const subcommand of commands) {
+        addLinkOptions(link.command(subcommand)).action(async (options) => {
+            try {
+                const root = resolveLanesHqRoot(process.env);
+                const enabled = await readLanesRegistryFlagFailOpen(LANE_SESSION_LINKS_FLAG, {
+                    env: process.env,
+                    defaultValue: true,
+                });
+                const result = await runLaneLinkWithFlag(subcommand, { ...options, hqRoot: root, env: process.env }, enabled);
+                writeJson(result.output ?? {});
+                if (result.exitCode !== undefined)
+                    process.exitCode = result.exitCode;
+            }
+            catch (error) {
+                commandError(error);
+            }
+        });
+    }
+    const deliver = link.command("_deliver", { hidden: true })
+        .description("Internal linked-session hook delivery")
+        .requiredOption("--event <event>", "Hook event");
+    deliver.action(async (options) => {
+        // Hook commands must not update/re-exec the CLI inside the provider's time budget.
+        process.env.HQ_NO_UPDATE_CHECK = "1";
+        try {
+            const root = resolveLanesHqRoot(process.env);
+            const input = await readHookInput();
+            const sid = linkedSessionIdFromHookInput(input);
+            if (!sid || !isLinkedSession(root, sid))
+                return;
+            const enabled = await readLanesRegistryFlagFailOpen(LANE_SESSION_LINKS_FLAG, {
+                env: process.env,
+                defaultValue: true,
+            });
+            const result = await runLaneLinkWithFlag("_deliver", { hqRoot: root, env: process.env, event: options.event, input }, enabled);
+            if (result.output)
+                writeJson(result.output);
+        }
+        catch (error) {
+            process.stderr.write(`hq lanes link _deliver: ${error instanceof Error ? error.message : String(error)}\n`);
+            // Hook failures are fail-open; queued messages remain available if delivery failed.
+        }
+    });
+}
+//# sourceMappingURL=lanes-link.js.map

package/dist/commands/lanes-loop.js

@@ -17,12 +17,11 @@ export function startLaneLoopController(ctx, laneId, initialAdmission = false) {
     const entry = process.argv[1];
     if (!entry)
         throw new LanesError("loop_controller_entry_missing", "Cannot resolve the hq CLI entry point for the loop controller", { lane_id: laneId });
-    const child = spawn(process.execPath, [entry, "lanes", "_loop-worker", laneId], {
-        cwd: ctx.hqRoot(),
-        detached: true,
-        stdio: "ignore",
-        env: { ...ctx.env, HQ_LANE_LOOP_CONTROLLER: "1", ...(initialAdmission ? { HQ_LANE_LOOP_INITIAL: "1" } : {}) },
-    });
+    const args = [entry, "lanes", "_loop-worker", laneId];
+    const env = { ...ctx.env, HQ_LANE_LOOP_CONTROLLER: "1", ...(initialAdmission ? { HQ_LANE_LOOP_INITIAL: "1" } : {}) };
+    const child = ctx.spawnProcess
+        ? ctx.spawnProcess(process.execPath, args, { cwd: ctx.hqRoot(), detached: true, windowsHide: true, stdio: ["ignore", 1, 2], env })
+        : spawn(process.execPath, args, { cwd: ctx.hqRoot(), detached: true, stdio: "ignore", env });
     child.unref();
     if (child.pid === undefined)
         throw new LanesError("loop_controller_spawn_failed", "Loop controller did not start", { lane_id: laneId });

package/dist/commands/lanes-questions.js

@@ -5,7 +5,7 @@ import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { appendCappedHistory, createQuestion, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
 import { resolveQuestionCompanyWithFallback } from "../lib/lanes/questions.js";
 import { LanesError } from "../lib/lanes/errors.js";
-import { applyLoopStallAnswer } from "../lib/lanes/loop.js";
+import { applyLoopStallAnswer, findLoopStallResult } from "../lib/lanes/loop.js";
 export function resolveAnswerChoice(choice, options, freeform) {
     const trimmed = choice.trim();
     if (/^[0-9]+$/.test(trimmed)) {
@@ -801,7 +801,6 @@ export function createLaneQuestionsHandlers(deps) {
             });
             return;
         }
-        throwIfQuestionNotPending(question);
         if (askingLane.state === "awaiting_input") {
             assertLaneRunsHereForOperatorMutation(ctx, askingLane, "wake after answering");
         }
@@ -819,11 +818,27 @@ export function createLaneQuestionsHandlers(deps) {
             throw new LanesError("missing_choice", "--choice or --freeform is required", {});
         }
         const choice = freeform ?? resolveAnswerChoice(opts.choice, body.options, false);
+        const isLoopStallQuestion = body.loop_stall?.lane_id === askingLane.lane_id && askingLane.loop_mode === true;
+        const incomingAnswerKind = freeform ? "freeform" : "option";
+        const incomingNotesMatch = opts.notes
+            ? question.answer?.notes_ref !== undefined && body.notes === opts.notes
+            : question.answer?.notes_ref === undefined;
+        const retryingSameLoopAnswer = isLoopStallQuestion && question.status === "answered" && question.answer?.choice === choice &&
+            question.answer.answer_kind === incomingAnswerKind && incomingNotesMatch &&
+            deps.sameQuestionAnswer(question.answer, { ...question.answer });
+        if (question.status !== "pending" && !retryingSameLoopAnswer)
+            throwIfQuestionNotPending(question);
+        const loopStallResult = isLoopStallQuestion
+            ? findLoopStallResult(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id), questionId)
+            : undefined;
         const at = ctx.now().toISOString();
         const answeredBy = sessionIdFromEnv(ctx.env)
             ? `session:${sessionIdFromEnv(ctx.env)}`
             : "user";
         const updated = casUpdateQuestion(hqRoot, questionId, (current) => {
+            if (retryingSameLoopAnswer && current.status === "answered" && current.answer?.choice === choice &&
+                deps.sameQuestionAnswer(current.answer, question.answer))
+                return current;
             throwIfQuestionNotPending(current);
             assertQuestionCompanyAccess(current, askingLane, requestedCompany, hqRoot);
             const recordedCompany = current.company ?? questionCompany;
@@ -856,7 +871,12 @@ export function createLaneQuestionsHandlers(deps) {
                 },
             };
         });
-        if (body.loop_stall?.lane_id === askingLane.lane_id && askingLane.loop_mode === true) {
+        if (isLoopStallQuestion) {
+            if (!loopStallResult && !retryingSameLoopAnswer) {
+                process.stderr.write(`hq lanes: loop phase for question ${questionId} was already re-enqueued; recording answer as superseded\n`);
+                printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: "superseded" });
+                return;
+            }
             const resolved = applyLoopStallAnswer({
                 runDir: path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id),
                 questionId,
@@ -866,6 +886,10 @@ export function createLaneQuestionsHandlers(deps) {
             });
             if (!resolved)
                 throw new LanesError("loop_stall_result_missing", `Loop stall result for question ${questionId} is missing`, { question_id: questionId, lane_id: askingLane.lane_id });
+            if (resolved.action === "already_applied") {
+                printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action });
+                return;
+            }
             const controllerPid = await deps.restartLoopController(ctx, askingLane.lane_id);
             printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action, controller_pid: controllerPid });
             return;

package/dist/commands/lanes.js

@@ -34,6 +34,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { registerLaneSessionStartCommand } from "./lanes-session-start.js";
+import { registerLanesLinkCommand } from "./lanes-link.js";
 import { laneDepthCap } from "../lib/lanes/depth-cap.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { runResidentCommandWithPackageLease } from "../utils/resident-package-preload.js";
@@ -9431,10 +9432,30 @@ export function registerLanesCommand(parent, deps = {}) {
             }
             const runDirPath = runDir(handlerCtx.hqRoot(), laneId);
             if (loopControllerIsAlive(runDirPath)) {
-                const pid = loopStatus(runDirPath, laneId).pid;
-                if (pid === undefined)
-                    throw new LanesError("loop_controller_pid_missing", `Loop controller for ${laneId} is alive without a recorded pid`, { lane_id: laneId });
-                return pid;
+                let status = loopStatus(runDirPath, laneId);
+                if (status.state === "parked") {
+                    const deadline = Date.now() + 10_000;
+                    while (Date.now() < deadline) {
+                        await new Promise((resolve) => setTimeout(resolve, 100));
+                        status = loopStatus(runDirPath, laneId);
+                        if (status.state !== "parked") {
+                            if (status.pid === undefined)
+                                throw new LanesError("loop_controller_pid_missing", `Loop controller for ${laneId} left parked without a recorded pid`, { lane_id: laneId });
+                            return status.pid;
+                        }
+                        if (!loopControllerIsAlive(runDirPath))
+                            break;
+                    }
+                    if (loopControllerIsAlive(runDirPath) && loopStatus(runDirPath, laneId).state === "parked") {
+                        throw new LanesError("loop_controller_winding_down", `Loop controller for ${laneId} stayed parked while winding down`, { lane_id: laneId });
+                    }
+                }
+                else {
+                    const pid = status.pid;
+                    if (pid === undefined)
+                        throw new LanesError("loop_controller_pid_missing", `Loop controller for ${laneId} is alive without a recorded pid`, { lane_id: laneId });
+                    return pid;
+                }
             }
             return startLaneLoopController(handlerCtx, laneId);
         },
@@ -9534,6 +9555,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .command("lanes")
         .description("Create, supervise, and steer worker lanes; routed decision queue");
     registerLaneSessionStartCommand(lanes);
+    registerLanesLinkCommand(lanes);
     registerLaneChecksCommand(lanes, {
         hqRoot: ctx.hqRoot,
         resolveCompany: ctx.resolveCompany,

package/dist/lib/daemon/hq-cloud.d.ts

@@ -71,8 +71,19 @@ export interface HqCloudUpdateOutcome {
     ok: boolean;
     from: string | null;
     to: string | null;
+    outcome?: HqCloudUpdateState["outcome"];
+    target?: string | null;
+    errorClass?: HqCloudUpdateState["errorClass"];
+    lastCheckAt?: string;
     detail?: string;
 }
+export interface HqCloudUpdateState {
+    lastCheckAt: string;
+    outcome: "updated" | "up_to_date" | "pinned" | "failed";
+    target: string | null;
+    errorClass: "registry" | "install" | "convergence" | "filesystem" | "unknown" | null;
+}
+export declare function readHqCloudUpdateState(daemonRoot: string): HqCloudUpdateState | null;
 interface NpmRunResult {
     status: number | null;
     stdout?: string | null;
@@ -80,11 +91,12 @@ interface NpmRunResult {
     error?: Error;
 }
 export interface UpdateHqCloudDeps {
-    run?: (file: string, args: string[], shell: boolean, env: NodeJS.ProcessEnv) => NpmRunResult;
+    run?: (file: string, args: string[], shell: boolean, env: NodeJS.ProcessEnv, timeoutMs: number) => NpmRunResult;
     bundled?: HqCloudCopy | null;
     platform?: NodeJS.Platform;
     /** Test seam for bounded install retry delays. */
     sleep?: (ms: number) => void;
+    now?: () => Date;
 }
 /** Install or update the updater's copy, as this (the login) user. */
 export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv, deps?: UpdateHqCloudDeps): HqCloudUpdateOutcome;

package/dist/lib/daemon/hq-cloud.js

@@ -161,6 +161,47 @@ export function currentHqCloudAfterLeaseRelease(daemonRoot, expectedVersion) {
         return null;
     return { ...managed, source: "managed" };
 }
+const HQ_CLOUD_UPDATE_STATE_FILE = "hq-cloud-update-state.json";
+const HQ_CLOUD_UPDATE_STATE_MAX_BYTES = 4_096;
+const HQ_CLOUD_UPDATE_OUTCOMES = new Set(["updated", "up_to_date", "pinned", "failed"]);
+const HQ_CLOUD_UPDATE_ERROR_CLASSES = new Set([
+    "registry", "install", "convergence", "filesystem", "unknown",
+]);
+export function readHqCloudUpdateState(daemonRoot) {
+    try {
+        const file = path.join(daemonRoot, HQ_CLOUD_UPDATE_STATE_FILE);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.size > HQ_CLOUD_UPDATE_STATE_MAX_BYTES) {
+            throw new Error("updater state is not a small regular file");
+        }
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.lastCheckAt !== "string"
+            || !HQ_CLOUD_UPDATE_OUTCOMES.has(raw.outcome)
+            || !(raw.target === null || typeof raw.target === "string")
+            || !(raw.errorClass === null || HQ_CLOUD_UPDATE_ERROR_CLASSES.has(raw.errorClass)))
+            return null;
+        return raw;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            console.warn("Could not read daemon hq-cloud updater state; status will omit it:", error instanceof Error ? error.message : String(error));
+        }
+        return null;
+    }
+}
+function writeHqCloudUpdateState(daemonRoot, state) {
+    const file = path.join(daemonRoot, HQ_CLOUD_UPDATE_STATE_FILE);
+    const temporary = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(temporary, JSON.stringify(state) + "\n", { mode: 0o600 });
+    fs.renameSync(temporary, file);
+}
+function updateErrorClass(detail, fallback) {
+    if (/could not look up|npm listed no/i.test(detail))
+        return "registry";
+    return fallback;
+}
+const HQ_CLOUD_REGISTRY_TIMEOUT_MS = 15_000;
+const HQ_CLOUD_INSTALL_TIMEOUT_MS = 120_000;
 function isTransientNpmFailure(result) {
     // spawnSync's ETIMEDOUT means this attempt hit our full 10-minute process
     // timeout. Retrying that result would multiply one stall across every attempt.
@@ -172,11 +213,11 @@ function isTransientNpmFailure(result) {
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-function runNpm(file, args, shell, env) {
+function runNpm(file, args, shell, env, timeoutMs) {
     return spawnSync(file, args, {
         encoding: "utf8",
         env,
-        timeout: 10 * 60_000,
+        timeout: timeoutMs,
         stdio: ["ignore", "pipe", "pipe"],
         windowsHide: true,
         shell,
@@ -193,24 +234,40 @@ export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
     const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
     const bundled = deps.bundled !== undefined ? deps.bundled : bundledHqCloud();
     const from = managedHqCloud(daemonRoot)?.version ?? bundled?.version ?? null;
+    const checkedAt = (deps.now ?? (() => new Date()))().toISOString();
+    const finish = (result, outcome, target, errorClass) => {
+        const state = { lastCheckAt: checkedAt, outcome, target, errorClass };
+        try {
+            fs.mkdirSync(daemonRoot, { recursive: true, mode: 0o700 });
+            writeHqCloudUpdateState(daemonRoot, state);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.warn("Could not persist daemon hq-cloud updater state; preserving update result:", detail);
+        }
+        return { ...result, outcome, target, errorClass, lastCheckAt: checkedAt };
+    };
     if (!bundled)
-        return { ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" };
+        return finish({ ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" }, "failed", pinnedVersion ?? null, "unknown");
     const prefix = managedHqCloudDir(daemonRoot);
     try {
         fs.mkdirSync(prefix, { recursive: true, mode: 0o700 });
     }
     catch (err) {
-        return { ok: false, from, to: null, detail: `could not create ${prefix}: ${err instanceof Error ? err.message : String(err)}` };
+        return finish({ ok: false, from, to: null, detail: `could not create ${prefix}: ${err instanceof Error ? err.message : String(err)}` }, "failed", pinnedVersion ?? null, "filesystem");
     }
     let version = pinnedVersion;
     if (!version) {
         const view = hqCloudLatestCommand(bundled.version, platform);
-        const r = run(view.file, view.args, view.shell, env);
-        if (r.status !== 0)
-            return { ok: false, from, to: null, detail: `could not look up the newest hq-cloud: ${npmFailure(r)}` };
+        const r = run(view.file, view.args, view.shell, env, HQ_CLOUD_REGISTRY_TIMEOUT_MS);
+        if (r.status !== 0) {
+            const detail = `could not look up the newest hq-cloud: ${npmFailure(r)}`;
+            return finish({ ok: false, from, to: null, detail }, "failed", null, updateErrorClass(detail, "registry"));
+        }
         const latest = latestSameMajor(r.stdout ?? "", bundled.version);
         if (!latest) {
-            return { ok: false, from, to: null, detail: `npm listed no hq-cloud release at or above ${bundled.version} in the same major version` };
+            const detail = `npm listed no hq-cloud release at or above ${bundled.version} in the same major version`;
+            return finish({ ok: false, from, to: null, detail }, "failed", null, "registry");
         }
         version = latest;
     }
@@ -219,22 +276,28 @@ export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
     const sleep = deps.sleep ?? sleepSync;
     let r;
     for (let attempt = 0;; attempt++) {
-        r = run(cmd.file, cmd.args, cmd.shell, env);
+        r = run(cmd.file, cmd.args, cmd.shell, env, HQ_CLOUD_INSTALL_TIMEOUT_MS);
         if (r.status === 0)
             break;
         const retryable = pinnedVersion !== undefined && pinnedVersion !== null && isTransientNpmFailure(r);
         const delay = retryDelays[attempt];
         if (!retryable || delay === undefined) {
             const retries = retryable ? attempt : 0;
-            return {
-                ok: false,
-                from,
-                to: null,
-                detail: retries > 0 ? `pinned hq-cloud install failed after ${retries + 1} attempts: ${npmFailure(r)}` : npmFailure(r),
-            };
+            const detail = retries > 0 ? `pinned hq-cloud install failed after ${retries + 1} attempts: ${npmFailure(r)}` : npmFailure(r);
+            return finish({ ok: false, from, to: null, detail }, "failed", version, retryable ? "registry" : "install");
         }
         sleep(delay);
     }
-    return { ok: true, from, to: managedHqCloud(daemonRoot)?.version ?? null };
+    const installedPackage = managedHqCloud(daemonRoot);
+    const installedVersion = installedPackage?.version ?? null;
+    const syncRunner = installedPackage ? hqCloudRunners(installedPackage.root).syncRunner : null;
+    if (installedVersion !== version || !syncRunner) {
+        const detail = installedVersion !== version
+            ? `hq-cloud install exited successfully but installed ${installedVersion ?? "no readable package"}, expected ${version}`
+            : `hq-cloud install exited successfully at ${version} but has no dist/bin/sync-runner.js`;
+        return finish({ ok: false, from, to: installedVersion, detail }, "failed", version, "convergence");
+    }
+    const outcome = pinnedVersion ? "pinned" : installedVersion === from ? "up_to_date" : "updated";
+    return finish({ ok: true, from, to: installedVersion }, outcome, version, null);
 }
 //# sourceMappingURL=hq-cloud.js.map

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

@@ -0,0 +1,39 @@
+export declare const LANE_SESSION_LINKS_FLAG = "lanes.session-links";
+export declare class LaneLinkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface LinkOptions {
+    hqRoot: string;
+    sessionId?: string;
+    env?: NodeJS.ProcessEnv;
+    link?: string;
+    child?: string;
+    name?: string;
+    engine?: string;
+    title?: string;
+    hostSession?: string;
+    text?: string;
+    textFile?: string;
+    state?: string;
+    note?: string;
+    timeout?: number;
+    event?: string;
+    input?: string;
+    now?: () => Date;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+export interface LinkResult {
+    output?: Record<string, unknown>;
+    exitCode?: number;
+}
+export declare function resolveLinkSessionId(root: string, explicit: string | undefined, env?: NodeJS.ProcessEnv): string;
+/** Cheap hook guard used before remote flag lookup or queue access. */
+export declare function linkedSessionIdFromHookInput(input: string): string;
+export declare function isLinkedSession(root: string, sid: string): boolean;
+/** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
+export declare function drainLinkQueue(inbox: string): string;
+export declare function runLaneLink(subcommand: string, options: LinkOptions): Promise<LinkResult>;
+/** Apply the default-on feature gate contract at the command boundary. */
+export declare function runLaneLinkWithFlag(subcommand: string, options: LinkOptions, enabled: boolean): Promise<LinkResult>;
+//# sourceMappingURL=links.d.ts.map