@indigoai-us/hq-cli 5.232.0 → 5.234.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.234.0] — 2026-09-27
+
+### Added
+
+- A lane's senior can explicitly resume a failed lane's recorded provider
+  session with `hq lanes resume --from-failed --reason`; the secret-scanned
+  reason and recovered failure are recorded in lane history. Failed lanes
+  continue to refuse ordinary messages. (#927)
+
+### Fixed
+
+- `hq agents stop` says the stop was accepted and shows the status the API returns, instead of saying the agent has already stopped. (#922)
+
+## [5.233.0] — 2026-09-27
+
+### Added
+
+- `hq lanes wait` exits on the first selected envelope, pending-question, or
+  state change across the requested lanes. It uses a startup baseline and a
+  bounded two-second poll interval.
+
 ## [5.232.0] — 2026-09-27
 
 ### Added

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

@@ -7773,6 +7773,27 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "wait";
+        readonly description: "Wait for the first requested change across lanes";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--any <lane-id...>";
+            readonly description: "Lane ids to monitor";
+        }, {
+            readonly flags: "--for <change-type>";
+            readonly description: "envelope | question | state";
+        }, {
+            readonly flags: "--timeout <seconds>";
+            readonly description: "Positive timeout in seconds";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON output";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "watch";
         readonly description: "Watch lane state and question changes until all lanes are terminal";
@@ -8026,7 +8047,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "resume";
-        readonly description: "Resume an interrupted, done or blocked lane on its recorded provider session";
+        readonly description: "Resume an interrupted, done or blocked lane on its recorded provider session; recover failed lanes with the senior-only --from-failed option";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] <lane-id>";
@@ -8038,6 +8059,12 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly options: readonly [{
             readonly flags: "--text <msg>";
             readonly description: "Operator message for the resumed turn";
+        }, {
+            readonly flags: "--from-failed";
+            readonly description: "Explicitly resume a failed lane as its senior";
+        }, {
+            readonly flags: "--reason <text>";
+            readonly description: "Required explanation for resuming from failed";
         }, {
             readonly flags: "--project <slug>";
             readonly description: "Re-point project attribution from this resume";
@@ -8059,6 +8086,9 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--grant-context <base64url>";
             readonly description: "";
+        }, {
+            readonly flags: "--failed-resume-context <base64url>";
+            readonly description: "";
         }, {
             readonly flags: "--keep-alive";
             readonly description: "Automatically resume done lead lanes while their story remains open";

package/dist/command-catalog.generated.js

@@ -10051,6 +10051,33 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "wait",
+                "description": "Wait for the first requested change across lanes",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--any <lane-id...>",
+                        "description": "Lane ids to monitor"
+                    },
+                    {
+                        "flags": "--for <change-type>",
+                        "description": "envelope | question | state"
+                    },
+                    {
+                        "flags": "--timeout <seconds>",
+                        "description": "Positive timeout in seconds"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON output"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "watch",
                 "description": "Watch lane state and question changes until all lanes are terminal",
@@ -10381,7 +10408,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "resume",
-                "description": "Resume an interrupted, done or blocked lane on its recorded provider session",
+                "description": "Resume an interrupted, done or blocked lane on its recorded provider session; recover failed lanes with the senior-only --from-failed option",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] <lane-id>",
@@ -10397,6 +10424,14 @@ export const COMMAND_CATALOG = [
                         "flags": "--text <msg>",
                         "description": "Operator message for the resumed turn"
                     },
+                    {
+                        "flags": "--from-failed",
+                        "description": "Explicitly resume a failed lane as its senior"
+                    },
+                    {
+                        "flags": "--reason <text>",
+                        "description": "Required explanation for resuming from failed"
+                    },
                     {
                         "flags": "--project <slug>",
                         "description": "Re-point project attribution from this resume"
@@ -10425,6 +10460,10 @@ export const COMMAND_CATALOG = [
                         "flags": "--grant-context <base64url>",
                         "description": ""
                     },
+                    {
+                        "flags": "--failed-resume-context <base64url>",
+                        "description": ""
+                    },
                     {
                         "flags": "--keep-alive",
                         "description": "Automatically resume done lead lanes while their story remains open"

package/dist/commands/agents.js

@@ -1819,8 +1819,16 @@ export function registerAgentsCommand(program) {
             .action(async function (agentUid) {
             try {
                 const token = (await resolveVaultCredential()).token;
-                await startStopAgent(token, agentUid, action);
-                console.log(chalk.green(`${action === "start" ? "Started" : "Stopped"} agent ${agentUid}.`));
+                const result = await startStopAgent(token, agentUid, action);
+                const runtimeStatus = result.runtime?.status;
+                const successMessage = action === "start"
+                    ? `Started agent ${agentUid}.`
+                    : runtimeStatus === "terminated"
+                        ? `Stopped agent ${agentUid}.`
+                        : typeof runtimeStatus === "string"
+                            ? `Stop accepted for agent ${agentUid} (status: ${runtimeStatus}).`
+                            : `Stop accepted for agent ${agentUid}.`;
+                console.log(chalk.green(successMessage));
             }
             catch (err) {
                 fail(err);

package/dist/commands/lanes.js

@@ -52,6 +52,7 @@ import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
 import { parseCliEffort, resolveLaneEffort, } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
+import { LANE_WAIT_INVALID_INPUT_EXIT_CODE, LANE_WAIT_TIMEOUT_EXIT_CODE, runLaneWait, } from "../lib/lanes/wait.js";
 import { dispatchLaneDelivery } from "../lib/lanes/delivery-core.js";
 import { dropboxInboxHasMessages, drainDropbox, formatDropboxMessages, formatMonitorEvent, requeueDropboxMessages, } from "../lib/lanes/dropbox.js";
 import { isPidAlive, runWatcherLoop, WATCHER_OUT_MAX_BYTES, watcherOutLogPath, writeWatcherDecision, } from "../lib/lanes/watcher.js";
@@ -2127,6 +2128,37 @@ function yieldEventLoop() {
         setImmediate(resolve);
     });
 }
+function laneWaitHumanLine(result) {
+    const details = Object.entries(result.change)
+        .filter(([key]) => key !== "type")
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(" ");
+    return `lane=${result.lane_id} change=${result.change.type}${details ? ` ${details}` : ""} at=${result.at}`;
+}
+async function runWait(ctx, opts) {
+    const timeoutSeconds = opts.timeout === undefined ? Number.NaN : Number(opts.timeout);
+    try {
+        const result = await runLaneWait(ctx.hqRoot(), opts.any ?? [], opts.for ?? [], timeoutSeconds * 1000, { now: ctx.now, sleep: ctx.sleep });
+        if (result) {
+            console.log(opts.json ? JSON.stringify(result) : laneWaitHumanLine(result));
+            return 0;
+        }
+        console.log(opts.json
+            ? JSON.stringify({ ok: false, error: "wait_timeout" })
+            : "wait_timeout");
+        return LANE_WAIT_TIMEOUT_EXIT_CODE;
+    }
+    catch (err) {
+        if (!isLanesError(err) || err.error !== "wait_invalid_input")
+            throw err;
+        const output = { ok: false, error: err.error, message: err.message };
+        if (opts.json)
+            console.log(JSON.stringify(output));
+        else
+            process.stderr.write(`${err.message}\n`);
+        return LANE_WAIT_INVALID_INPUT_EXIT_CODE;
+    }
+}
 function withCasRetry(fn, attempts = 5) {
     let last;
     for (let i = 0; i < attempts; i += 1) {
@@ -3594,6 +3626,10 @@ function outpostRejectedGrantContextOption(result) {
     return result.exitCode !== 0 &&
         /unknown option\s+(?:['"])?--grant-context(?:['"])?(?:\s|$)/i.test(`${result.stderr}\n${result.stdout}`);
 }
+function outpostRejectedFailedResumeOption(result) {
+    return result.exitCode !== 0 &&
+        /unknown option\s+(?:['"])?--(?:from-failed|failed-resume-context)(?:['"])?(?:\s|$)/i.test(`${result.stderr}\n${result.stdout}`);
+}
 function verifyOutpostProfileContent(hqRoot, lane) {
     if (lane.host.kind !== "outpost" || lane.worker_profile === undefined)
         return;
@@ -3616,6 +3652,70 @@ function resumeProfileRepinActor(ctx) {
     const sessionId = sessionIdFromEnv(ctx.env);
     return sessionId ? `session:${sessionId}` : "ssm-owner-dispatch";
 }
+function createOutpostFailedResumeContext(ctx, lane) {
+    return Buffer.from(JSON.stringify({
+        version: 1,
+        lane_id: lane.lane_id,
+        expected_senior: lane.senior,
+        actor: resumeProfileRepinActor(ctx),
+    })).toString("base64url");
+}
+function parseOutpostFailedResumeContext(encoded, laneId) {
+    try {
+        if (!/^[A-Za-z0-9_-]{1,4096}$/.test(encoded))
+            throw new Error("invalid encoding");
+        const value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("invalid payload");
+        const payload = value;
+        const seniorValue = payload.expected_senior;
+        if (seniorValue === null || typeof seniorValue !== "object" || Array.isArray(seniorValue))
+            throw new Error("invalid senior");
+        const senior = seniorValue;
+        let expectedSenior;
+        if (senior.kind === "user") {
+            expectedSenior = { kind: "user" };
+        }
+        else if ((senior.kind === "lane" || senior.kind === "session") &&
+            typeof senior.id === "string" && senior.id.trim().length > 0) {
+            expectedSenior = { kind: senior.kind, id: senior.id };
+        }
+        else {
+            throw new Error("invalid senior");
+        }
+        if (payload.version !== 1 ||
+            payload.lane_id !== laneId ||
+            typeof payload.actor !== "string" ||
+            payload.actor.trim().length === 0) {
+            throw new Error("invalid payload");
+        }
+        return { expectedSenior, actor: payload.actor };
+    }
+    catch {
+        throw new LanesError("failed_resume_authorization_invalid", "Failed-resume authorization context is invalid", { lane_id: laneId });
+    }
+}
+function authorizeFailedResume(ctx, lane, encodedContext) {
+    if (encodedContext !== undefined) {
+        if (!ctx.isSsmOwnerDispatch()) {
+            throw new LanesError("failed_resume_authorization_invalid", "Failed-resume authorization context is only valid on an Outpost owner dispatch", { lane_id: lane.lane_id });
+        }
+        const context = parseOutpostFailedResumeContext(encodedContext, lane.lane_id);
+        if (lane.host.kind !== "outpost" ||
+            !sameHireGrantSenior(lane.senior, context.expectedSenior)) {
+            throw new LanesError("failed_resume_senior_changed", `Lane ${lane.lane_id}'s senior changed after its failed-resume request was authorized`, {
+                lane_id: lane.lane_id,
+                expected_senior: context.expectedSenior,
+                current_senior: lane.senior,
+            });
+        }
+        return context.actor;
+    }
+    if (!callerMatchesSenior(ctx, lane.senior)) {
+        throw new LanesError("failed_resume_unauthorized", "Only the lane's senior may resume a failed lane with --from-failed", { lane_id: lane.lane_id });
+    }
+    return resumeProfileRepinActor(ctx);
+}
 function workerProfileHashMismatch(lane, profile) {
     return new LanesError("worker_profile_hash_mismatch", `Worker profile ${JSON.stringify(profile.id)} on Outpost ${lane.host.id} does not match the hash recorded by the lane`, {
         lane_id: lane.lane_id,
@@ -3725,6 +3825,9 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
             actor: resumeProfileRepinActor(ctx),
         })
         : undefined;
+    const failedResumeContext = action === "resume" && options.fromFailed === true
+        ? createOutpostFailedResumeContext(ctx, lane)
+        : undefined;
     let grantContext;
     let grantHierarchy;
     if (action === "grant") {
@@ -3744,6 +3847,7 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
     }
     let dispatched;
     let grantContextRejected = false;
+    let failedResumeOptionRejected = false;
     try {
         const dispatchCommand = (contexts) => ctx.dispatchOutpostExec({
             outpostId,
@@ -3765,15 +3869,17 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
                 effort: options.effort,
                 worker: options.worker,
                 keepAlive: options.keepAlive,
+                fromFailed: options.fromFailed,
                 hire: options.hire,
                 senior: options.senior,
                 reason: options.reason,
                 grantContext: contexts.grantContext,
                 profileRepinContext: contexts.profileRepinContext,
+                failedResumeContext: contexts.failedResumeContext,
                 compact: options.compact,
             }),
         });
-        let contexts = { grantContext, profileRepinContext };
+        let contexts = { grantContext, profileRepinContext, failedResumeContext };
         dispatched = await dispatchCommand(contexts);
         for (let retry = 0; action === "resume" && retry < 2; retry += 1) {
             if (contexts.grantContext !== undefined && outpostRejectedGrantContextOption(dispatched)) {
@@ -3784,6 +3890,10 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
                 outpostRejectedProfileRepinOption(dispatched)) {
                 contexts = { ...contexts, profileRepinContext: undefined };
             }
+            else if (options.fromFailed === true && outpostRejectedFailedResumeOption(dispatched)) {
+                failedResumeOptionRejected = true;
+                break;
+            }
             else {
                 break;
             }
@@ -3800,6 +3910,13 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
             required_option: "--grant-context",
         });
     }
+    if (failedResumeOptionRejected) {
+        throw new LanesError("outpost_cli_upgrade_required", `Outpost ${outpostId} needs an hq-cli release containing failed-lane resume support before it can resume lane ${lane.lane_id}`, {
+            lane_id: lane.lane_id,
+            outpost_id: outpostId,
+            required_option: "--from-failed",
+        });
+    }
     const ownerError = ownerErrorFromOutput(dispatched.stdout);
     if (options.effort !== undefined && outpostRejectedEffortOption(dispatched)) {
         throw new LanesError("outpost_effort_unsupported", `Outpost ${outpostId} rejected --effort; update hq-cli on that Outpost before changing a lane's effort remotely`, {
@@ -3816,6 +3933,7 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options) {
     if (ownerError) {
         if (action === "resume" &&
             (ownerError.error === "worker_profile_hash_mismatch" ||
+                ownerError.error.startsWith("failed_resume_") ||
                 ownerError.error.startsWith("hire_grant_"))) {
             throw new LanesError(ownerError.error, ownerError.message, {
                 ...ownerError.details,
@@ -5015,6 +5133,7 @@ async function runShow(ctx, laneId) {
         last_resume: lane.last_resume ?? null,
         account: lane.account ?? null,
         account_history: lane.account_history ?? [],
+        failed_resume_history: lane.failed_resume_history ?? [],
         pending_resume: lane.pending_resume ?? null,
         last_run_usage: lane.last_run_usage ?? null,
         model: lane.model ?? null,
@@ -6599,6 +6718,30 @@ function laneWithRecoveredProviderSession(hqRoot, lane) {
 async function runResume(ctx, laneId, opts) {
     const hqRoot = ctx.hqRoot();
     let lane = readLane(hqRoot, laneId);
+    const failedResumeReason = opts.reason?.trim();
+    if (opts.reason !== undefined && opts.fromFailed !== true) {
+        throw new LanesError("failed_resume_reason_requires_flag", "--reason on hq lanes resume requires --from-failed", { lane_id: laneId });
+    }
+    if (opts.fromFailed === true && !failedResumeReason) {
+        throw new LanesError("failed_resume_reason_required", "--from-failed requires a non-empty --reason", { lane_id: laneId });
+    }
+    if (opts.reason !== undefined)
+        assertNoSecretText("resume reason", opts.reason);
+    if (opts.failedResumeContext !== undefined && opts.fromFailed !== true) {
+        throw new LanesError("failed_resume_authorization_invalid", "Failed-resume authorization context requires --from-failed", { lane_id: laneId });
+    }
+    const failedResumeActor = opts.fromFailed === true
+        ? authorizeFailedResume(ctx, lane, opts.failedResumeContext)
+        : undefined;
+    if (opts.fromFailed === true && lane.state !== "failed") {
+        throw new LanesError("lane_not_failed", `Lane ${laneId} is ${lane.state}; --from-failed only applies to a failed lane`, { lane_id: laneId, state: lane.state });
+    }
+    const failedResumeExpectedSenior = opts.fromFailed === true
+        ? { ...lane.senior }
+        : undefined;
+    const recoveredFailure = opts.fromFailed === true
+        ? lane.terminal_reason ?? "failure_reason_unavailable"
+        : undefined;
     const hireGrantContext = opts.grantContext === undefined
         ? undefined
         : (() => {
@@ -6639,7 +6782,7 @@ async function runResume(ctx, laneId, opts) {
     if (lane.state === "queued") {
         throw new LanesError("lane_not_resumable", `Lane ${laneId} is queued; use hq lanes admit ${laneId} to request admission`, { lane_id: laneId, state: lane.state, admission_command: `hq lanes admit ${laneId}` });
     }
-    const refusal = resumeCommandRefusal(lane);
+    const refusal = resumeCommandRefusal(lane, { allowFailed: opts.fromFailed === true });
     if (refusal !== null) {
         throw new LanesError(refusal.error, refusal.message, {
             lane_id: laneId,
@@ -6709,6 +6852,10 @@ async function runResume(ctx, laneId, opts) {
             pending: {
                 trigger: "resume",
                 resumed_from: resumedFrom,
+                ...(opts.fromFailed === true ? { from_failed: true } : {}),
+                ...(failedResumeExpectedSenior !== undefined
+                    ? { expected_senior: failedResumeExpectedSenior }
+                    : {}),
                 ...(text !== undefined ? { text } : {}),
                 ...(messageId !== undefined ? { message_id: messageId } : {}),
                 compact: opts.compact !== false,
@@ -6734,6 +6881,10 @@ async function runResume(ctx, laneId, opts) {
                 pending: {
                     trigger: "resume",
                     resumed_from: resumedFrom,
+                    ...(opts.fromFailed === true ? { from_failed: true } : {}),
+                    ...(failedResumeExpectedSenior !== undefined
+                        ? { expected_senior: failedResumeExpectedSenior }
+                        : {}),
                     ...(text !== undefined ? { text } : {}),
                     ...(messageId !== undefined ? { message_id: messageId } : {}),
                     compact: opts.compact !== false,
@@ -6794,6 +6945,10 @@ async function runResume(ctx, laneId, opts) {
                                 session_id: sessionId,
                                 trigger: "resume",
                                 resumed_from: resumedFrom,
+                                ...(opts.fromFailed === true ? { from_failed: true } : {}),
+                                ...(failedResumeExpectedSenior !== undefined
+                                    ? { expected_senior: failedResumeExpectedSenior }
+                                    : {}),
                                 ...(text !== undefined ? { text } : {}),
                                 ...(messageId !== undefined ? { message_id: messageId } : {}),
                                 compact: opts.compact !== false,
@@ -6821,6 +6976,10 @@ async function runResume(ctx, laneId, opts) {
                     trigger: {
                         kind: "resume",
                         from: resumedFrom,
+                        ...(opts.fromFailed === true ? { fromFailed: true } : {}),
+                        ...(failedResumeExpectedSenior !== undefined
+                            ? { expectedSenior: failedResumeExpectedSenior }
+                            : {}),
                         ...(text !== undefined ? { text } : {}),
                         ...(messageId !== undefined ? { message_id: messageId } : {}),
                     },
@@ -6843,6 +7002,19 @@ async function runResume(ctx, laneId, opts) {
         });
     }
     let next = resumed;
+    if (failedResumeActor !== undefined &&
+        failedResumeReason !== undefined &&
+        recoveredFailure !== undefined) {
+        next = casUpdateLane(hqRoot, laneId, (current) => ({
+            ...current,
+            failed_resume_history: appendCappedHistory(current.failed_resume_history ?? [], {
+                at,
+                actor: failedResumeActor,
+                reason: failedResumeReason,
+                failure: recoveredFailure,
+            }),
+        }));
+    }
     if (text !== undefined) {
         // An operator text moves the compaction reference forward, as a message does.
         next = casUpdateLane(hqRoot, laneId, (current) => ({
@@ -9492,6 +9664,14 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (laneId, opts) => {
         await runAdmit(ctx, laneId, opts);
     }));
+    lanes
+        .command("wait")
+        .description("Wait for the first requested change across lanes")
+        .option("--any <lane-id...>", "Lane ids to monitor")
+        .option("--for <change-type>", "envelope | question | state", collectRepeatable, [])
+        .option("--timeout <seconds>", "Positive timeout in seconds")
+        .option("--json", "JSON output")
+        .action(wrapText(async (opts) => runWait(ctx, opts)));
     lanes
         .command("watch")
         .description("Watch lane state and question changes until all lanes are terminal")
@@ -9616,9 +9796,11 @@ export function registerLanesCommand(parent, deps = {}) {
     }));
     lanes
         .command("resume")
-        .description("Resume an interrupted, done or blocked lane on its recorded provider session")
+        .description("Resume an interrupted, done or blocked lane on its recorded provider session; recover failed lanes with the senior-only --from-failed option")
         .argument("<lane-id>", "Lane id")
         .option("--text <msg>", "Operator message for the resumed turn")
+        .option("--from-failed", "Explicitly resume a failed lane as its senior")
+        .option("--reason <text>", "Required explanation for resuming from failed")
         .option("--project <slug>", "Re-point project attribution from this resume")
         .option("--story <id>", "Re-point story attribution from this resume")
         .option("--account <id>", "Move the lane's session to this account of its provider before resuming")
@@ -9627,6 +9809,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--worker <profile>", "Attach a personal worker profile for the resumed turn")
         .addOption(new Option("--profile-repin-context <base64url>").hideHelp())
         .addOption(new Option("--grant-context <base64url>").hideHelp())
+        .addOption(new Option("--failed-resume-context <base64url>").hideHelp())
         .option("--keep-alive", "Automatically resume done lead lanes while their story remains open")
         .option("--mesh-company <slug>", "Attach Work Mesh attribution after verifying company membership")
         .option("--no-compact", "Skip the resume-time compaction check for this resume")

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

@@ -17,7 +17,7 @@
  * module rather than testing provider or state inline. A guard bound at one
  * site and not another is the defect class this branch has already shipped.
  */
-import { type LaneProvider, type LaneRecord, type LaneState } from "./types.js";
+import { type LaneProvider, type LaneRecord, type LaneState, type SeniorRef } from "./types.js";
 /** Which providers can continue an exited worker from a recorded session id. */
 export declare const PROVIDER_SESSION_RESUME: Record<LaneProvider, boolean>;
 export declare function providerSupportsSessionResume(provider: LaneProvider): boolean;
@@ -45,7 +45,8 @@ export declare function sessionNotPortableMessage(provider: LaneProvider): strin
  * reconcile pass resumes it once every question is answered. `killed` and
  * `cancelled` were stopped on purpose by the operator; a message must not
  * silently restart them. `failed` means the run ended without an envelope or
- * never started; the operator has not seen why. `interrupted` exited with
+ * never started; only the lane's senior can explicitly recover it with
+ * `hq lanes resume <lane-id> --from-failed --reason <text>`. `interrupted` exited with
  * partial output and no envelope, so the lane's state was never closed
  * cleanly; only the explicit `hq lanes resume` opt-in continues it
  * (RESUME_COMMAND_STATES). `queued` and `running` take the drop box, not a
@@ -139,6 +140,9 @@ export type LaunchTrigger = {
     kind: "resume";
     /** Lane state at the moment of the command; recorded as `last_resume.resumed_from`. */
     from: ResumeCommandState | "failed";
+    fromFailed?: true;
+    /** Senior that authorized a failed-lane resume, rechecked at the claim CAS. */
+    expectedSenior?: SeniorRef;
     text?: string;
     message_id?: string;
 };
@@ -152,7 +156,9 @@ export type LaunchPlan = {
  * Refusal for `hq lanes resume`, in precedence order: wrong state, provider
  * without a resume path, no recorded session. Null when the resume can go.
  */
-export declare function resumeCommandRefusal(lane: DeliveryLane): {
+export declare function resumeCommandRefusal(lane: DeliveryLane, options?: {
+    allowFailed?: boolean;
+}): {
     error: "lane_not_resumable" | "resume_unsupported" | "no_provider_session";
     message: string;
 } | null;

package/dist/lib/lanes/delivery.js

@@ -65,7 +65,8 @@ export function sessionNotPortableMessage(provider) {
  * reconcile pass resumes it once every question is answered. `killed` and
  * `cancelled` were stopped on purpose by the operator; a message must not
  * silently restart them. `failed` means the run ended without an envelope or
- * never started; the operator has not seen why. `interrupted` exited with
+ * never started; only the lane's senior can explicitly recover it with
+ * `hq lanes resume <lane-id> --from-failed --reason <text>`. `interrupted` exited with
  * partial output and no envelope, so the lane's state was never closed
  * cleanly; only the explicit `hq lanes resume` opt-in continues it
  * (RESUME_COMMAND_STATES). `queued` and `running` take the drop box, not a
@@ -137,7 +138,7 @@ export function deliveryRefusalReason(lane) {
         case "interrupted":
             return `Lane is ${state}. The run did not close cleanly and the operator has not decided what to do with it. Resuming from ${state} needs an explicit opt-in: hq lanes resume <lane-id> [--text <message>].`;
         case "failed":
-            return `Lane is ${state}. The run did not close cleanly and the operator has not decided what to do with it. Resuming from ${state} needs an explicit opt-in, which does not exist yet.`;
+            return `Lane is ${state}. A plain message does not restart it. Its senior can resume the recorded session with: hq lanes resume <lane-id> --from-failed --reason <text>.`;
         default: {
             const _exhaustive = state;
             return _exhaustive;
@@ -345,8 +346,10 @@ export const LAUNCH_TRIGGERS = ["admit", "answered_questions", "message", "resum
  * Refusal for `hq lanes resume`, in precedence order: wrong state, provider
  * without a resume path, no recorded session. Null when the resume can go.
  */
-export function resumeCommandRefusal(lane) {
-    if (!isResumeCommandState(lane.state) && !isFailedEnvelopeRepairLane(lane)) {
+export function resumeCommandRefusal(lane, options = {}) {
+    if (!isResumeCommandState(lane.state) &&
+        !isFailedEnvelopeRepairLane(lane) &&
+        !(options.allowFailed === true && lane.state === "failed")) {
         return {
             error: "lane_not_resumable",
             message: `Lane is ${lane.state}. hq lanes resume continues a lane in ${RESUME_COMMAND_STATES.join(", ")}; ${lane.state === "awaiting_input"
@@ -395,7 +398,7 @@ export function planLaneLaunch(lane, trigger) {
             return { mode: "resume", session_id: lane.provider_session_id };
         }
         case "resume": {
-            const refusal = resumeCommandRefusal(lane);
+            const refusal = resumeCommandRefusal(lane, { allowFailed: trigger.fromFailed === true });
             if (refusal !== null || !hasRecordedSessionId(lane)) {
                 throw new LanesError(refusal?.error ?? "no_provider_session", refusal?.message ?? `Lane is ${lane.state} and has no recorded provider session`, { state: lane.state, provider: lane.provider });
             }
@@ -418,7 +421,9 @@ export function claimableStatesFor(trigger, lane) {
         case "message":
             return envelopeRepairFailed ? [...RESUMABLE_LANE_STATES, "failed"] : RESUMABLE_LANE_STATES;
         case "resume":
-            return envelopeRepairFailed ? [...RESUME_COMMAND_STATES, "failed"] : RESUME_COMMAND_STATES;
+            return trigger.fromFailed === true || envelopeRepairFailed
+                ? [...RESUME_COMMAND_STATES, "failed"]
+                : RESUME_COMMAND_STATES;
         default: {
             const _exhaustive = trigger;
             return _exhaustive;

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -37,6 +37,8 @@ export interface OutpostLaneCommand {
     model?: string;
     effort?: string;
     worker?: string;
+    fromFailed?: boolean;
+    failedResumeContext?: string;
     keepAlive?: boolean;
     hire?: string;
     grantContext?: string;

package/dist/lib/lanes/outpost-dispatch.js

@@ -151,12 +151,15 @@ export function buildOutpostLaneCommand(input) {
         ["--hire", input.hire],
         ["--grant-context", input.grantContext],
         ["--profile-repin-context", input.profileRepinContext],
+        ["--failed-resume-context", input.failedResumeContext],
         ["--senior", input.senior],
         ["--reason", input.reason],
     ]) {
         if (value !== undefined)
             args.push(flag, value);
     }
+    if (input.action === "resume" && input.fromFailed === true)
+        args.push("--from-failed");
     if (input.action === "resume" && input.keepAlive === true)
         args.push("--keep-alive");
     if (input.compact === false)

package/dist/lib/lanes/spawn.js

@@ -1576,6 +1576,9 @@ function laneLaunchResult(lane) {
     const { provider_home_at_spawn: _providerHomeAtSpawn, ...safe } = lane;
     return safe;
 }
+function sameSeniorRef(a, b) {
+    return a.kind === b.kind && a.id === b.id;
+}
 function inferTrigger(lane) {
     if (lane.state === "awaiting_input")
         return { kind: "answered_questions" };
@@ -1631,6 +1634,12 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     // starting fresh from the brief.
     const pendingResume = launch.trigger === undefined && existing.state === "queued" ? existing.pending_resume : undefined;
     const trigger = launch.trigger ?? inferTrigger(existing);
+    const failedResumeClaim = (trigger.kind === "resume" && trigger.fromFailed === true) || pendingResume?.from_failed === true;
+    const failedResumeExpectedSenior = trigger.kind === "resume" && trigger.fromFailed === true
+        ? trigger.expectedSenior
+        : pendingResume?.from_failed === true
+            ? pendingResume.expected_senior
+            : undefined;
     // A message into a finished lane must not turn that lane `failed` when the
     // account cannot be bound: nothing has started yet, so the record keeps its
     // state and the caller sees the error. Admission and question resume keep
@@ -1971,6 +1980,15 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         if (!claimableStatesFor(trigger, current).includes(current.state)) {
             throw new LanesError("spawn_state_mismatch", `Cannot mark ${current.lane_id} running from ${current.state}`, { lane_id: current.lane_id, state: current.state, trigger: trigger.kind });
         }
+        if (failedResumeClaim &&
+            (failedResumeExpectedSenior === undefined ||
+                !sameSeniorRef(current.senior, failedResumeExpectedSenior))) {
+            throw new LanesError("failed_resume_senior_changed", `Lane ${current.lane_id}'s senior changed after its failed-resume request was authorized`, {
+                lane_id: current.lane_id,
+                expected_senior: failedResumeExpectedSenior ?? null,
+                current_senior: current.senior,
+            });
+        }
         claimed = true;
         const next = {
             ...current,
@@ -2044,6 +2062,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(pendingResume.message_id !== undefined ? { message_id: pendingResume.message_id } : {}),
                 ...(pendingResume.monitor_event === true ? { monitor_event: true } : {}),
                 ...(pendingResume.resumed_from !== undefined ? { resumed_from: pendingResume.resumed_from } : {}),
+                ...(pendingResume.from_failed === true ? { from_failed: true } : {}),
                 ...(pendingResume.text !== undefined ? { text: pendingResume.text } : {}),
                 ...(pendingResume.compact !== undefined ? { compact: pendingResume.compact } : {}),
             };
@@ -2065,6 +2084,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(trigger.kind === "resume"
                     ? {
                         resumed_from: trigger.from,
+                        ...(trigger.fromFailed === true ? { from_failed: true } : {}),
                         ...(trigger.text !== undefined ? { text: trigger.text } : {}),
                         ...(trigger.message_id !== undefined ? { message_id: trigger.message_id } : {}),
                     }

package/dist/lib/lanes/store.js

@@ -888,6 +888,11 @@ export function mergeLaneRecords(live, sidecars) {
                 worker_profile_repin_history: unionHistory(all.map((record) => record.worker_profile_repin_history ?? []), entryIdentity, base.worker_profile_repin_history ?? []),
             }
             : {}),
+        ...(all.some((record) => record.failed_resume_history !== undefined)
+            ? {
+                failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),
+            }
+            : {}),
         stories: mergeLaneStories(all, base),
     };
 }

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

@@ -400,6 +400,8 @@ export interface LaneRecord {
      * like the other histories.
      */
     account_history?: AccountHistoryEntry[];
+    /** Bounded audit history for explicitly authorized resumes from failed. */
+    failed_resume_history?: FailedResumeHistoryEntry[];
     /**
      * Set by an account move (`--account`) until the spawn claims the lane:
      * the turn the move was asked to run. While set it reserves a slot on the
@@ -537,11 +539,20 @@ export interface AccountHistoryEntry {
     at: string;
     reason: "first_assignment" | "model_change" | "usage_limit" | "account_unavailable" | "recorded_account_logged_out" | "load_balance" | "operator_move";
 }
+export interface FailedResumeHistoryEntry {
+    at: string;
+    actor: string;
+    reason: string;
+    failure: string;
+}
 export interface PendingResume {
     /** Fresh answered-question launches need no previous session id. */
     session_id?: string;
     trigger: "answered_questions" | "message" | "resume";
     resumed_from?: "interrupted" | "done" | "blocked" | "failed";
+    from_failed?: true;
+    /** Senior that authorized a failed-lane resume, rechecked at the claim CAS. */
+    expected_senior?: SeniorRef;
     text?: string;
     message_id?: string;
     /** The text is already framed as untrusted monitor data, not an operator instruction. */
@@ -572,6 +583,7 @@ export interface LaneResumeRecord {
      * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
      */
     resumed_from?: "interrupted" | "done" | "blocked" | "failed";
+    from_failed?: true;
     text?: string;
     /** False when the continued turn explicitly skipped compaction. */
     compact?: boolean;

package/dist/lib/lanes/types.js

@@ -225,7 +225,7 @@ export const LANE_FIELD_WRITERS = {
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
-    provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
+    provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],

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

@@ -0,0 +1,39 @@
+import type { LaneRecord, QuestionRecord } from "./types.js";
+export declare const LANE_WAIT_POLL_INTERVAL_MS = 2000;
+export declare const LANE_WAIT_MAX_LANES = 64;
+export declare const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
+export declare const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
+export declare const LANE_WAIT_CHANGE_TYPES: readonly ["envelope", "question", "state"];
+export type LaneWaitChangeType = (typeof LANE_WAIT_CHANGE_TYPES)[number];
+export type LaneWaitChange = {
+    type: "envelope";
+    ref: string;
+    decision: "done" | "ask" | "blocked";
+} | {
+    type: "question";
+    question_id: string;
+} | {
+    type: "state";
+    from: string;
+    to: string;
+};
+export interface LaneWaitResult {
+    ok: true;
+    lane_id: string;
+    change: LaneWaitChange;
+    at: string;
+}
+export interface LaneWaitDeps {
+    readLane?: (hqRoot: string, laneId: string) => LaneRecord | null;
+    listQuestionIds?: (hqRoot: string) => string[];
+    readQuestion?: (hqRoot: string, questionId: string) => QuestionRecord | null;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wait for the first requested change after taking a read-only baseline.
+ * Each poll reads every selected lane once and runs no lane-store mutation or
+ * lock. Question records are scanned in one pass when question changes matter.
+ */
+export declare function runLaneWait(hqRoot: string, laneIds: readonly string[], changeTypes: readonly string[], timeoutMs: number, deps?: LaneWaitDeps): Promise<LaneWaitResult | null>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/lib/lanes/wait.js

@@ -0,0 +1,159 @@
+import { listQuestionIds, readLane, readQuestion } from "./store.js";
+import { LanesError } from "./errors.js";
+export const LANE_WAIT_POLL_INTERVAL_MS = 2_000;
+export const LANE_WAIT_MAX_LANES = 64;
+export const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
+export const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
+export const LANE_WAIT_CHANGE_TYPES = ["envelope", "question", "state"];
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function invalidInput(message, details = {}) {
+    throw new LanesError("wait_invalid_input", message, details);
+}
+function validateInput(laneIds, changeTypes, timeoutMs) {
+    const normalizedLaneIds = laneIds.map((laneId) => laneId.trim());
+    if (normalizedLaneIds.length === 0 || normalizedLaneIds.some((laneId) => laneId.length === 0)) {
+        invalidInput("hq lanes wait requires at least one non-empty lane id", { lane_ids: laneIds });
+    }
+    if (normalizedLaneIds.some((laneId) => laneId === "." || laneId === ".." || /[\\/]/.test(laneId))) {
+        invalidInput("Lane ids must not contain path separators", { lane_ids: laneIds });
+    }
+    const uniqueLaneIds = [...new Set(normalizedLaneIds)];
+    if (uniqueLaneIds.length > LANE_WAIT_MAX_LANES) {
+        invalidInput(`hq lanes wait accepts at most ${LANE_WAIT_MAX_LANES} lane ids`, {
+            max: LANE_WAIT_MAX_LANES,
+        });
+    }
+    if (changeTypes.length === 0 || changeTypes.some((kind) => !LANE_WAIT_CHANGE_TYPES.includes(kind))) {
+        invalidInput(`hq lanes wait requires one or more --for values: ${LANE_WAIT_CHANGE_TYPES.join(", ")}`, { accepted: [...LANE_WAIT_CHANGE_TYPES], values: changeTypes });
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isSafeInteger(Math.ceil(timeoutMs))) {
+        invalidInput("hq lanes wait requires a positive finite timeout", { timeout_ms: timeoutMs });
+    }
+    return {
+        laneIds: uniqueLaneIds,
+        changeTypes: [...new Set(changeTypes)],
+    };
+}
+function snapshotLanes(hqRoot, laneIds, changeTypes, deps) {
+    const readLaneRecord = deps.readLane ?? readLane;
+    const lanes = new Map();
+    for (const laneId of laneIds) {
+        const lane = readLaneRecord(hqRoot, laneId);
+        if (!lane) {
+            throw new LanesError("wait_lane_unreadable", `Lane ${laneId} could not be read while waiting`, { lane_id: laneId });
+        }
+        lanes.set(laneId, lane);
+    }
+    const pendingQuestions = new Map();
+    if (changeTypes.includes("question")) {
+        const listIds = deps.listQuestionIds ?? listQuestionIds;
+        const readQuestionRecord = deps.readQuestion ?? readQuestion;
+        for (const questionId of new Set(listIds(hqRoot))) {
+            const question = readQuestionRecord(hqRoot, questionId);
+            if (!question) {
+                throw new LanesError("wait_question_unreadable", `Question ${questionId} disappeared while waiting`, { question_id: questionId });
+            }
+            if (question.status === "pending" && lanes.has(question.lane_id)) {
+                pendingQuestions.set(questionId, question);
+            }
+        }
+    }
+    return { lanes, pendingQuestions };
+}
+function timestamp(value, fallbackMs) {
+    const parsed = value === undefined ? Number.NaN : Date.parse(value);
+    const atMs = Number.isFinite(parsed) ? parsed : fallbackMs;
+    return { at: new Date(atMs).toISOString(), atMs };
+}
+function envelopeSignature(lane) {
+    const envelope = lane.last_envelope;
+    return envelope === undefined
+        ? undefined
+        : `${envelope.ref}\0${envelope.decision}\0${envelope.at}`;
+}
+function candidatesForSnapshot(previous, current, laneIds, changeTypes, observedAtMs) {
+    const candidates = [];
+    laneIds.forEach((laneId, laneOrder) => {
+        const before = previous.lanes.get(laneId);
+        const after = current.lanes.get(laneId);
+        if (!before || !after)
+            return;
+        changeTypes.forEach((type, typeOrder) => {
+            if (type === "envelope" && envelopeSignature(before) !== envelopeSignature(after)) {
+                const envelope = after.last_envelope;
+                if (envelope) {
+                    const when = timestamp(envelope.at, observedAtMs);
+                    candidates.push({
+                        laneId,
+                        change: { type, ref: envelope.ref, decision: envelope.decision },
+                        ...when,
+                        laneOrder,
+                        typeOrder,
+                    });
+                }
+            }
+            if (type === "state" && before.state !== after.state) {
+                const when = timestamp(after.updated_at, observedAtMs);
+                candidates.push({
+                    laneId,
+                    change: { type, from: before.state, to: after.state },
+                    ...when,
+                    laneOrder,
+                    typeOrder,
+                });
+            }
+            if (type === "question") {
+                for (const [questionId, question] of current.pendingQuestions) {
+                    if (question.lane_id !== laneId || previous.pendingQuestions.has(questionId))
+                        continue;
+                    const when = timestamp(question.asked_at, observedAtMs);
+                    candidates.push({
+                        laneId,
+                        change: { type, question_id: questionId },
+                        ...when,
+                        laneOrder,
+                        typeOrder,
+                    });
+                }
+            }
+        });
+    });
+    return candidates.sort((a, b) => a.atMs - b.atMs || a.laneOrder - b.laneOrder || a.typeOrder - b.typeOrder);
+}
+/**
+ * Wait for the first requested change after taking a read-only baseline.
+ * Each poll reads every selected lane once and runs no lane-store mutation or
+ * lock. Question records are scanned in one pass when question changes matter.
+ */
+export async function runLaneWait(hqRoot, laneIds, changeTypes, timeoutMs, deps = {}) {
+    const input = validateInput(laneIds, changeTypes, timeoutMs);
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? defaultSleep;
+    const startedAtMs = now().getTime();
+    const deadlineMs = startedAtMs + timeoutMs;
+    let previous = snapshotLanes(hqRoot, input.laneIds, input.changeTypes, deps);
+    while (true) {
+        const remainingMs = deadlineMs - now().getTime();
+        if (remainingMs <= 0)
+            return null;
+        await sleep(Math.min(LANE_WAIT_POLL_INTERVAL_MS, remainingMs));
+        const observedAtMs = now().getTime();
+        const current = snapshotLanes(hqRoot, input.laneIds, input.changeTypes, deps);
+        const candidates = candidatesForSnapshot(previous, current, input.laneIds, input.changeTypes, observedAtMs);
+        const first = candidates.find((candidate) => candidate.atMs <= deadlineMs);
+        if (first) {
+            return {
+                ok: true,
+                lane_id: first.laneId,
+                change: first.change,
+                at: first.at,
+            };
+        }
+        if (observedAtMs >= deadlineMs)
+            return null;
+        previous = current;
+    }
+}
+//# sourceMappingURL=wait.js.map

package/package.json

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