@indigoai-us/hq-cli 5.345.134 → 5.345.136

package/dist/commands/integrations.d.ts

@@ -21,6 +21,7 @@
  *   hq integrations show [app]               One app in full.
  *   hq integrations tools --provider <p>     What the connected app can do.
  *   hq integrations call <tool> --provider <p> --args '<json>'
+ *   hq integrations call <tool> --provider <p> --args-file args.json
  *   hq integrations pending                  Calls awaiting approval.
  *   hq integrations pending --history        Recently decided calls, including status.
  *   hq integrations approve|reject <queueId> Decide a queued call.
@@ -51,6 +52,16 @@
  */
 import { Command } from "commander";
 import { type PendingApproval } from "./integrations-api.js";
+/**
+ * Resolve `hq integrations call` tool arguments from `--args <json>`,
+ * `--args -` (stdin), or `--args-file <path>` (`-` also reads stdin). A file or
+ * stdin avoids shell quoting: zsh breaks inline JSON that contains apostrophes
+ * or parentheses. The result must be a JSON object.
+ */
+export declare function resolveCallArgs(opts: {
+    args?: string;
+    argsFile?: string;
+}, stdin?: NodeJS.ReadableStream): Promise<Record<string, unknown>>;
 export { IntegrationsCliError, callGateway, fetchConnections, fetchUsableApps, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
 export type { AdminConnection, UsableApp, UsableAppsResult } from "./integrations-core.js";
 /** Wait for a decided queue item without resending the approve request. */

package/dist/commands/integrations.js

@@ -21,6 +21,7 @@
  *   hq integrations show [app]               One app in full.
  *   hq integrations tools --provider <p>     What the connected app can do.
  *   hq integrations call <tool> --provider <p> --args '<json>'
+ *   hq integrations call <tool> --provider <p> --args-file args.json
  *   hq integrations pending                  Calls awaiting approval.
  *   hq integrations pending --history        Recently decided calls, including status.
  *   hq integrations approve|reject <queueId> Decide a queued call.
@@ -50,6 +51,7 @@
  * `integrations-manage.ts`.
  */
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
@@ -60,6 +62,69 @@ import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
 import { registerSlackCommands } from "./integrations-slack.js";
 import { fetchPendingApprovals } from "./integrations-api.js";
+const CALL_ARGS_EXAMPLE = `--args '{"assignee":"me"}' or --args-file args.json`;
+function readStream(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.on("end", () => resolve(data));
+        stream.on("error", reject);
+    });
+}
+/**
+ * Resolve `hq integrations call` tool arguments from `--args <json>`,
+ * `--args -` (stdin), or `--args-file <path>` (`-` also reads stdin). A file or
+ * stdin avoids shell quoting: zsh breaks inline JSON that contains apostrophes
+ * or parentheses. The result must be a JSON object.
+ */
+export async function resolveCallArgs(opts, stdin = process.stdin) {
+    if (opts.args !== undefined && opts.argsFile !== undefined) {
+        throw new IntegrationsCliError("Use either --args or --args-file, not both.", { expected: true });
+    }
+    let text;
+    let source;
+    const fromStdin = opts.args === "-" || opts.argsFile === "-";
+    if (fromStdin) {
+        if (stdin.isTTY) {
+            throw new IntegrationsCliError("Reading tool arguments from stdin needs piped input, e.g. `hq integrations call <tool> --args - < args.json`.", { expected: true });
+        }
+        text = await readStream(stdin);
+        source = "stdin";
+    }
+    else if (opts.argsFile !== undefined) {
+        source = `--args-file ${opts.argsFile}`;
+        try {
+            text = await readFile(opts.argsFile, "utf8");
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new IntegrationsCliError(`Could not read --args-file ${opts.argsFile}: ${reason}`, { expected: true });
+        }
+    }
+    else {
+        text = opts.args ?? "{}";
+        source = "--args";
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new IntegrationsCliError(source === "--args"
+            ? `--args must be a JSON object, e.g. ${CALL_ARGS_EXAMPLE}`
+            : `Tool arguments from ${source} are not valid JSON (${reason}). They must be a JSON object, e.g. {"assignee":"me"}.`, { expected: true });
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new IntegrationsCliError(source === "--args"
+            ? `--args must be a JSON object, e.g. ${CALL_ARGS_EXAMPLE}`
+            : `Tool arguments from ${source} must be a JSON object, e.g. {"assignee":"me"}.`, { expected: true });
+    }
+    return raw;
+}
 /** Routing ids hq sets on a built-in tool call; never accepted from --args. */
 const BUILT_IN_ROUTING_ARGS = ["companyUid", "connectionId", "idempotencyKey"];
 /**
@@ -382,7 +447,7 @@ export function registerIntegrationsCommand(program) {
         const selector = sharedProvider
             ? `--connection ${connection.id}`
             : `--provider ${bareProvider(connection.provider)}`;
-        console.log(chalk.dim(`\n${tools.length} tools. Describe inputs: hq integrations tools ${selector} --describe <tool>\nCall one with: hq integrations call <tool> ${selector} --args '<json>'`));
+        console.log(chalk.dim(`\n${tools.length} tools. Describe inputs: hq integrations tools ${selector} --describe <tool>\nCall one with: hq integrations call <tool> ${selector} --args '<json>'\nIf the JSON has apostrophes or parentheses, put it in a file: --args-file args.json (or --args - to read stdin)`));
     });
     integrations
         .command("call <tool>")
@@ -390,21 +455,12 @@ export function registerIntegrationsCommand(program) {
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
         .option("--company <slug>", "Company slug, e.g. indigo")
-        .option("--args <json>", "Tool arguments as JSON", "{}")
+        .option("--args <json>", "Tool arguments as a JSON object (default {}); use - to read the JSON from stdin")
+        .option("--args-file <path>", "Read tool arguments from a JSON file (use - for stdin); avoids shell quoting of apostrophes and parentheses")
         .option("--idempotency-key <key>", "Stable key so retries execute at most once (default: generated)")
         .option("--json", "Machine-readable output")
         .action(async (tool, opts) => {
-        let parsedArgs;
-        try {
-            const raw = JSON.parse(opts.args);
-            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-                throw new Error("not an object");
-            }
-            parsedArgs = raw;
-        }
-        catch {
-            throw new IntegrationsCliError(`--args must be a JSON object, e.g. --args '{"assignee":"me"}'`, { expected: true });
-        }
+        const parsedArgs = await resolveCallArgs(opts);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = selectConnection(await fetchConnections(token, companyUid), opts);
@@ -417,7 +473,7 @@ export function registerIntegrationsCommand(program) {
             // arg with a routing name would redirect the call; refuse it.
             const reserved = BUILT_IN_ROUTING_ARGS.filter((key) => key in parsedArgs);
             if (reserved.length) {
-                throw new IntegrationsCliError(`--args cannot include ${reserved.join(", ")}: it is set by hq from the selected connection.`, { expected: true });
+                throw new IntegrationsCliError(`Tool arguments cannot include ${reserved.join(", ")}: it is set by hq from the selected connection.`, { expected: true });
             }
             gatewayParams = {
                 companyUid,
@@ -525,16 +581,41 @@ export function registerIntegrationsCommand(program) {
                     process.exitCode = 1;
                 return;
             }
+            if (decision === "reject") {
+                if (opts.json)
+                    printJson(body);
+                else
+                    console.log(chalk.yellow(`Rejected (status: ${body.status ?? "rejected"}).`));
+                return;
+            }
+            // A synchronous approve runs the call inline. The gateway answers a
+            // provider-side tool error with { status: "rejected", outcome:
+            // "failed", rejectionReason: "provider_tool_error" }; an older
+            // gateway reports "resumed" with an isError result. Classify both as
+            // failures, the same way the polling path does.
+            const result = body.result === undefined ? undefined : unwrapGatewayResult(body.result);
+            const toolError = body.result !== undefined &&
+                (gatewayResultIsError(result) || gatewayResultIsError(body.result));
+            const failed = approvalOutcomeFailed(body) || toolError;
+            if (failed)
+                process.exitCode = 1;
             if (opts.json) {
                 printJson(body);
                 return;
             }
-            console.log(decision === "approve"
-                ? chalk.green(`Approved — the call ran (status: ${body.status ?? "resumed"}).`)
-                : chalk.yellow(`Rejected (status: ${body.status ?? "rejected"}).`));
-            if (decision === "approve" && body.result !== undefined) {
-                printJson(unwrapGatewayResult(body.result));
+            if (failed) {
+                const reason = body.rejectionReason ??
+                    (toolError ? "provider_tool_error" : body.outcome ?? body.status ?? "failed");
+                console.log(chalk.red(`The approved call failed at the provider (${reason}).`));
             }
+            else if (body.status === "resumed" || body.status === "completed" || body.outcome === "ran") {
+                console.log(chalk.green(`Approved — the call ran (status: ${body.status ?? body.outcome}).`));
+            }
+            else {
+                console.log(chalk.yellow(`Approval ended with status ${body.status ?? "unknown"}.`));
+            }
+            if (result !== undefined)
+                printJson(result);
         });
     }
     registerConnectCommands(integrations);

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

@@ -18,9 +18,18 @@ export interface LoopControllerDeps {
     resumeLane(laneId: string, options: LaneResumeOptions): Promise<unknown>;
     interruptLane(laneId: string, reason: string, options: {
         preserveLoopQueue: boolean;
+        terminalReason?: string;
     }): Promise<void>;
     emitTerminal(lane: LaneRecord): Promise<void>;
 }
+/**
+ * terminal_reason values for interrupts HQ issues itself. An operator
+ * interrupt (`hq lanes interrupt`) records `operator_interrupt`; these keep a
+ * system recovery from looking like an operator action in the lane record.
+ */
+export declare const LOOP_CONTROLLER_RECOVERY_REASON = "loop_controller_recovery";
+export declare const LOOP_STALL_RESTART_REASON = "loop_stall_restart";
+export declare const LOOP_PHASE_DEADLINE_REASON = "loop_phase_deadline";
 export declare function startLaneLoopController(ctx: Ctx, laneId: string, initialAdmission?: boolean): number;
 export declare function runLaneLoopController(ctx: Ctx, laneId: string, deps: LoopControllerDeps): Promise<void>;
 //# sourceMappingURL=lanes-loop.d.ts.map

package/dist/commands/lanes-loop.js

@@ -52,6 +52,14 @@ function casLoopLaneState(hqRoot, laneId, from, to) {
         }
     }
 }
+/**
+ * terminal_reason values for interrupts HQ issues itself. An operator
+ * interrupt (`hq lanes interrupt`) records `operator_interrupt`; these keep a
+ * system recovery from looking like an operator action in the lane record.
+ */
+export const LOOP_CONTROLLER_RECOVERY_REASON = "loop_controller_recovery";
+export const LOOP_STALL_RESTART_REASON = "loop_stall_restart";
+export const LOOP_PHASE_DEADLINE_REASON = "loop_phase_deadline";
 export function startLaneLoopController(ctx, laneId, initialAdmission = false) {
     const entry = process.argv[1];
     if (!entry)
@@ -202,7 +210,7 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                 }
                 let interruptPromise;
                 const abortPhase = () => {
-                    interruptPromise = deps.interruptLane(laneId, "loop phase deadline exceeded", { preserveLoopQueue: true }).catch((error) => {
+                    interruptPromise = deps.interruptLane(laneId, "loop phase deadline exceeded", { preserveLoopQueue: true, terminalReason: LOOP_PHASE_DEADLINE_REASON }).catch((error) => {
                         process.stderr.write(`hq lanes: could not interrupt stalled loop phase ${laneId}: ${error instanceof Error ? error.message : String(error)}\n`);
                     });
                 };

package/dist/commands/lanes.js

@@ -48,7 +48,7 @@ import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } fr
 import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "../lib/lanes/flag-keys.js";
 import { applyContinuitySettings, findWorkerContinuityLane, sameLaneHost, workerContinuityPrompt } from "../lib/lanes/worker-continuity.js";
 import { commitIdleLoopStop, enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopLaneIsIdle, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
-import { runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
+import { LOOP_CONTROLLER_RECOVERY_REASON, LOOP_STALL_RESTART_REASON, runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
 import { configuredCodexRolloutHomes, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
 import { runLeadAutopilotPass } from "../lib/lanes/autopilot.js";
@@ -494,6 +494,41 @@ function livenessDepsFromCtx(ctx) {
         hostname: ctx.hostname,
     };
 }
+/**
+ * Start a lane that admission just let through. A queued loop lane is marked
+ * running and gets its loop controller, which works through the queued phase
+ * envelopes; every other lane spawns its worker directly. Every admission path
+ * (reconcile, in-process queue drain, hq lanes admit) goes through here so a
+ * loop lane never runs its brief without a controller.
+ */
+function startAdmittedLane(ctx, root, candidate) {
+    if (candidate.loop_mode !== true || candidate.state !== "queued") {
+        const admissionHost = reconcileHostFromCtx(ctx);
+        return spawnLaneWorker(root, candidate, {
+            env: ctx.env,
+            hostname: admissionHost.hostname,
+            admissionHost,
+            modelDeps: { readFileSync: ctx.readFileSync, probe: ctx.probeProvider, env: ctx.env },
+            existsSync: ctx.existsSync,
+            spawnProcess: ctx.spawnProcess,
+            proveDetached: ctx.proveDetached,
+            killProcess: ctx.killProcess,
+            now: ctx.now,
+            resolveMachineIdentity: ctx.resolveMachineIdentity,
+            runCompaction: ctx.runCompaction,
+            locateTranscript: ctx.locateTranscript,
+        });
+    }
+    const admitted = casUpdateLane(root, candidate.lane_id, (current) => ({
+        ...current,
+        state: "running",
+        queued_reason: undefined,
+        queued_details: undefined,
+        admission_reserved_at: undefined,
+    }));
+    startLaneLoopController(ctx, candidate.lane_id, true);
+    return admitted;
+}
 /**
  * Admit queued lanes in-process after a command frees or adds capacity, so
  * the queue drains without `hq daemon`. Best effort: an admission failure is
@@ -516,6 +551,7 @@ async function admitQueuedFromCtx(ctx) {
                 runCompaction: ctx.runCompaction,
                 locateTranscript: ctx.locateTranscript,
             },
+            spawn: (root, candidate) => startAdmittedLane(ctx, root, candidate),
             throttleDeps: ctx.throttleDeps,
             livenessDeps: livenessDepsFromCtx(ctx),
             presenceConnected: ctx.presenceConnected,
@@ -2432,11 +2468,18 @@ function autopilotWorkerStarter(ctx) {
         return { lane_id: started.lane_id };
     };
 }
+/**
+ * The senior for a lane created without `--senior`. Inside a lane worker
+ * (HQ_LANE_ID set) the worker's own session wins, because HQ_PARENT_SESSION_ID
+ * there names the session that started the worker, one level too high.
+ */
 function defaultSenior(ctx) {
+    const sessionId = sessionIdFromEnv(ctx.env);
+    if (ctx.env.HQ_LANE_ID?.trim() && sessionId)
+        return { kind: "session", id: sessionId };
     const parent = ctx.env.HQ_PARENT_SESSION_ID?.trim();
     if (parent)
         return { kind: "session", id: parent };
-    const sessionId = sessionIdFromEnv(ctx.env);
     if (sessionId)
         return { kind: "session", id: sessionId };
     return { kind: "user" };
@@ -3348,7 +3391,7 @@ async function runCreate(ctx, opts) {
     const requestedHireGrant = opts.hireGrant === undefined
         ? undefined
         : parseHireGrant(opts.hireGrant);
-    const requestedPlacement = opts.placement !== undefined
+    let requestedPlacement = opts.placement !== undefined
         ? parsePlacementPolicy(opts.placement)
         : undefined;
     const defaultPlacement = opts.defaultPlacement !== undefined
@@ -3568,6 +3611,13 @@ async function runCreate(ctx, opts) {
         placementGate ??= readLanePlacementEnabled(ctx, resolvePlacementCompany());
         return placementGate;
     };
+    if (requestedPlacement?.kind === "local" &&
+        defaultPlacement === undefined &&
+        !(await placementEnabled())) {
+        // With placement off every lane already runs here, so --placement local
+        // asks for the default. Treat it as omitted instead of refusing.
+        requestedPlacement = undefined;
+    }
     if (requestedPlacement !== undefined || defaultPlacement !== undefined) {
         await assertPlacementEnabled(ctx, resolvePlacementCompany(), placementEnabled);
     }
@@ -6305,6 +6355,7 @@ async function runShow(ctx, laneId, hasPendingQuestionForLane, resolveLaneTarget
         ...(showRefresh.remoteRefresh === undefined ? {} : { remote_refresh: showRefresh.remoteRefresh }),
         provider_session_id: lane.provider_session_id ?? null,
         provider_session_id_absent: lane.provider_session_id_absent ?? null,
+        fingerprint: lane.fingerprint ?? null,
         envelope_repair_mode: lane.envelope_repair?.mode ?? null,
         envelope_validation_errors: lane.envelope_validation_errors ?? [],
         last_resume: lane.last_resume ?? null,
@@ -7151,22 +7202,7 @@ async function runAdmit(ctx, laneId, opts) {
             });
             return;
         }
-        const started = spawnLaneWorker(hqRoot, lane, {
-            env: ctx.env,
-            modelDeps: {
-                readFileSync: ctx.readFileSync,
-                probe: ctx.probeProvider,
-                env: ctx.env,
-            },
-            existsSync: ctx.existsSync,
-            spawnProcess: ctx.spawnProcess,
-            proveDetached: ctx.proveDetached,
-            killProcess: ctx.killProcess,
-            now: ctx.now,
-            resolveMachineIdentity: ctx.resolveMachineIdentity,
-            runCompaction: ctx.runCompaction,
-            locateTranscript: ctx.locateTranscript,
-        });
+        const started = startAdmittedLane(ctx, hqRoot, lane);
         const admitted = opts.force && started.state === "running"
             ? casUpdateLane(hqRoot, laneId, (current) => ({ ...current, admitted_reason: "operator_force" }))
             : started;
@@ -8803,7 +8839,7 @@ async function runStop(ctx, laneId, reason, quiet = false) {
         }
         const controllerAlive = loopControllerIsAlive(runDirPath);
         if (!controllerAlive && lane.state === "running") {
-            await runInterrupt(ctx, lane.lane_id, "loop controller exited; recovering queued work before stop", { preserveLoopQueue: true, quiet: true });
+            await runInterrupt(ctx, lane.lane_id, "loop controller exited; recovering queued work before stop", { preserveLoopQueue: true, quiet: true, terminalReason: LOOP_CONTROLLER_RECOVERY_REASON });
         }
         const queued = enqueueLoopEnvelope({ runDir: runDirPath, laneId: lane.lane_id, envelope: { kind: "stop" }, now: ctx.now });
         if (!controllerAlive && lane.state !== "queued")
@@ -8879,6 +8915,13 @@ function stopTerminalWarning(laneId) {
  * session so `hq lanes resume` continues it. Keep-alive resumes only
  * `exited_with_partial_output` interruptions, so it leaves this lane alone.
  */
+/** Stop-history text for an operator interrupt given without --reason. */
+function defaultOperatorInterruptReason(ctx) {
+    const sessionId = sessionIdFromEnv(ctx.env);
+    const laneId = ctx.env.HQ_LANE_ID?.trim();
+    const caller = laneId ? ` by lane ${laneId}` : sessionId ? ` by session ${sessionId}` : "";
+    return `hq lanes interrupt${caller} (no reason given)`;
+}
 async function runInterrupt(ctx, laneId, reason, options = {}) {
     const operatorReason = reason?.trim();
     if (reason !== undefined && !operatorReason) {
@@ -8886,6 +8929,11 @@ async function runInterrupt(ctx, laneId, reason, options = {}) {
     }
     if (operatorReason !== undefined)
         assertNoSecretText("interrupt reason", operatorReason);
+    const terminalReason = options.terminalReason ?? "operator_interrupt";
+    // Every interrupt leaves a stop-history entry, so an operator interrupt
+    // given without --reason is still distinguishable from a system one.
+    const historyReason = operatorReason ??
+        (terminalReason === "operator_interrupt" ? defaultOperatorInterruptReason(ctx) : terminalReason);
     const hqRoot = ctx.hqRoot();
     const lane = readLane(hqRoot, laneId);
     if (lane.host.kind === "outpost" && !laneRunsHereForOperatorMutation(ctx, lane)) {
@@ -8910,7 +8958,7 @@ async function runInterrupt(ctx, laneId, reason, options = {}) {
         if (!reason)
             reason = "story-scoped loop phase interrupt";
         const remaining = scoped;
-        await runInterrupt(ctx, laneId, reason, { preserveLoopQueue: true, quiet: true });
+        await runInterrupt(ctx, laneId, reason, { preserveLoopQueue: true, quiet: true, terminalReason: options.terminalReason });
         if (!options.quiet)
             printJson({ ok: true, action: "interrupt", lane_id: lane.lane_id, terminal: false, resumable: true, ...remaining });
         return;
@@ -8945,13 +8993,11 @@ async function runInterrupt(ctx, laneId, reason, options = {}) {
                 queued_reason: undefined,
                 queued_details: undefined,
                 interrupted_at: at,
-                terminal_reason: "operator_interrupt",
-                ...(operatorReason === undefined ? {} : {
-                    stop_history: [
-                        ...(current.stop_history ?? []),
-                        { at, reason: operatorReason },
-                    ],
-                }),
+                terminal_reason: terminalReason,
+                stop_history: [
+                    ...(current.stop_history ?? []),
+                    { at, reason: historyReason },
+                ],
             };
         });
         stopLaneProcesses(hqRoot, laneId, {
@@ -9307,31 +9353,7 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
             runCompaction: ctx.runCompaction,
             locateTranscript: ctx.locateTranscript,
         },
-        spawn: (root, candidate) => {
-            if (candidate.loop_mode !== true || candidate.state !== "queued") {
-                return spawnLaneWorker(root, candidate, {
-                    env: ctx.env,
-                    modelDeps: { readFileSync: ctx.readFileSync, probe: ctx.probeProvider, env: ctx.env },
-                    existsSync: ctx.existsSync,
-                    spawnProcess: ctx.spawnProcess,
-                    proveDetached: ctx.proveDetached,
-                    killProcess: ctx.killProcess,
-                    now: ctx.now,
-                    resolveMachineIdentity: ctx.resolveMachineIdentity,
-                    runCompaction: ctx.runCompaction,
-                    locateTranscript: ctx.locateTranscript,
-                });
-            }
-            const admitted = casUpdateLane(root, candidate.lane_id, (current) => ({
-                ...current,
-                state: "running",
-                queued_reason: undefined,
-                queued_details: undefined,
-                admission_reserved_at: undefined,
-            }));
-            startLaneLoopController(ctx, candidate.lane_id, true);
-            return admitted;
-        },
+        spawn: (root, candidate) => startAdmittedLane(ctx, root, candidate),
         throttleDeps: ctx.throttleDeps,
         livenessDeps: livenessDepsFromCtx(ctx),
         presenceConnected: ctx.presenceConnected,
@@ -9693,7 +9715,7 @@ export function registerLanesCommand(parent, deps = {}) {
                 return deps.restartLoopController(handlerCtx, laneId);
             const current = readLane(handlerCtx.hqRoot(), laneId);
             if (current.state === "running") {
-                await runInterrupt(handlerCtx, laneId, "loop stall question answered; restarting controller", { preserveLoopQueue: true, quiet: true });
+                await runInterrupt(handlerCtx, laneId, "loop stall question answered; restarting controller", { preserveLoopQueue: true, quiet: true, terminalReason: LOOP_STALL_RESTART_REASON });
             }
             const runDirPath = runDir(handlerCtx.hqRoot(), laneId);
             if (loopControllerIsAlive(runDirPath)) {
@@ -9983,7 +10005,7 @@ export function registerLanesCommand(parent, deps = {}) {
         const controllerAlive = loopControllerIsAlive(runDirPath);
         const result = enqueueLoopEnvelope({ runDir: runDirPath, laneId: lane.lane_id, envelope, now: ctx.now });
         if (!controllerAlive && lane.state === "running") {
-            await runInterrupt(ctx, lane.lane_id, "loop controller exited; recovering the queued phase", { preserveLoopQueue: true, quiet: true });
+            await runInterrupt(ctx, lane.lane_id, "loop controller exited; recovering the queued phase", { preserveLoopQueue: true, quiet: true, terminalReason: LOOP_CONTROLLER_RECOVERY_REASON });
         }
         const shouldRestart = !controllerAlive && lane.state !== "queued";
         const controllerPid = shouldRestart ? startLaneLoopController(ctx, lane.lane_id) : undefined;
@@ -10378,6 +10400,7 @@ export function registerLanesCommand(parent, deps = {}) {
     }));
     lanes
         .command("stop")
+        .alias("cancel")
         .description("Cancel a queued lane or kill a running one (terminal; use interrupt to keep it resumable)")
         .argument("<lane-id>", "Lane id")
         .option("--reason <text>", "Record the reason in the lane's terminal history")

package/dist/commands/meetings.d.ts

@@ -1,3 +1,5 @@
 import { Command } from "commander";
+/** Upper bound on list pages one short-id lookup reads (per cursor chain). */
+export declare const SHORT_ID_MAX_PAGES = 50;
 export declare function registerMeetingsCommand(program: Command): void;
 //# sourceMappingURL=meetings.d.ts.map

package/dist/commands/meetings.js

@@ -251,26 +251,69 @@ function renderSignals(signals) {
     }
     console.log();
 }
+/** The server caps one `/v1/meetings` page at this many rows. */
+const MEETINGS_PAGE_SIZE = "100";
+/** Upper bound on list pages one short-id lookup reads (per cursor chain). */
+export const SHORT_ID_MAX_PAGES = 50;
+/**
+ * Resolve the 8-character id `hq meetings list` prints to a full meeting id.
+ *
+ * `/v1/meetings` is paged: the server caps a page at 100 rows (it ignores a
+ * larger `limit`) and may end a page early, even empty, with
+ * `truncated: true` when it runs out of time. Reading only the first page
+ * missed any meeting past it, so follow `nextToken` (and `nativeNextToken`
+ * for HQ Meet calls) until the prefix is found or the list ends. A full
+ * 8-character prefix stops at the first page with a match; a shorter prefix
+ * reads every page so ambiguity is still reported.
+ */
 async function resolveShortId(token, prefix, query) {
     if (prefix.includes("-") && prefix.length > 8)
         return prefix;
-    const res = await vaultApiFetch({
-        token,
-        path: "/v1/meetings",
-        query: { ...query, limit: "500" },
-    });
-    if (!res.ok) {
-        throw new Error(`Could not resolve meeting ID "${prefix}" — failed to list meetings (${res.status}). Pass the full meeting id.`);
+    const stopOnFirstMatch = prefix.length >= 8;
+    const matches = new Map();
+    let capped = false;
+    const fetchPage = async (extra) => {
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/meetings",
+            query: { ...query, limit: MEETINGS_PAGE_SIZE, ...extra },
+        });
+        if (!res.ok) {
+            throw new Error(`Could not resolve meeting ID "${prefix}" — failed to list meetings (${res.status}). Pass the full meeting id.`);
+        }
+        const data = (await res.json());
+        for (const m of data.meetings ?? []) {
+            if (typeof m.meetingId === "string" && m.meetingId.startsWith(prefix))
+                matches.set(m.meetingId, m);
+        }
+        return data;
+    };
+    const first = await fetchPage({});
+    let nextToken = first.nextToken;
+    for (let page = 1; nextToken && !(stopOnFirstMatch && matches.size > 0); page += 1) {
+        if (page >= SHORT_ID_MAX_PAGES) {
+            capped = true;
+            break;
+        }
+        nextToken = (await fetchPage({ nextToken })).nextToken;
+    }
+    let nativeCursor = first.nativeNextToken;
+    for (let page = 1; nativeCursor && !(stopOnFirstMatch && matches.size > 0); page += 1) {
+        if (page >= SHORT_ID_MAX_PAGES) {
+            capped = true;
+            break;
+        }
+        nativeCursor = (await fetchPage({ nativeCursor })).nativeNextToken;
     }
-    const data = (await res.json());
-    const matches = data.meetings.filter((m) => m.meetingId.startsWith(prefix));
-    if (matches.length === 1)
-        return matches[0].meetingId;
-    if (matches.length > 1) {
-        console.error(chalk.red(`Ambiguous ID prefix "${prefix}" — matches ${matches.length} meetings. Use a longer prefix.`));
+    if (matches.size === 1)
+        return [...matches.keys()][0];
+    if (matches.size > 1) {
+        console.error(chalk.red(`Ambiguous ID prefix "${prefix}" — matches ${matches.size} meetings. Use a longer prefix.`));
         process.exit(1);
     }
-    console.error(chalk.red(`No meeting matches ID "${prefix}". It may be older than the meetings shown by \`hq meetings list\`, still processing, or attributed to a different company. Pass the full meeting id, add --company <slug>, or widen the list with \`hq meetings list --limit <n>\`.`));
+    console.error(chalk.red(capped
+        ? `No meeting matches ID "${prefix}" in the newest ${SHORT_ID_MAX_PAGES * Number(MEETINGS_PAGE_SIZE)} meetings. Pass the full meeting id (shown by \`hq meetings list --json\`).`
+        : `No meeting matches ID "${prefix}". It may still be processing or attributed to a different company. Pass the full meeting id, or add --company <slug>.`));
     process.exit(1);
 }
 async function handleApiError(res, json = false) {

package/dist/commands/mesh.d.ts

@@ -6,10 +6,27 @@
  * Distinct from `hq doctor` (hook guardrails).
  */
 import { Command } from "commander";
-import { type MeshCompany, type MeshThread } from "../lib/mesh/api.js";
+import { type MeshCompany, type MeshProjectRepo, type MeshProjectStoryInput, type MeshThread } from "../lib/mesh/api.js";
+import { UnknownProjectStoryStateError } from "../lib/mesh/story-status.js";
 import { type DaemonInstallPlatform, type InstallPaths } from "../lib/mesh/live/daemon/install.js";
 import { type RunCommand } from "../lib/service-manager/launchd.js";
 export declare function formatCheckLines(threads: MeshThread[], company: MeshCompany, projectId?: string): string[];
+/** 400 PROJECT_VIEW_INVALID "Unknown story ..." from a story PATCH. */
+export declare function isUnknownBoardStory(error: unknown): boolean;
+/** The local PRD for this project when it lists `storyId`; null otherwise. */
+export declare function localPrdWithStory(company: {
+    companySlug?: string;
+}, projectId: string, storyId: string, hqRoot?: string | undefined): {
+    prdPath: string;
+    source: ProjectPlanSource;
+} | null;
+type ProjectPlanSource = {
+    name?: string;
+    description?: string;
+    stories: MeshProjectStoryInput[];
+    repos?: MeshProjectRepo[];
+    rejectedStories: UnknownProjectStoryStateError[];
+};
 /** Test seam for the usage-attribution question asked by `default set`. */
 export interface DefaultCompanyPromptDeps {
     /** True when stdin and stdout are a terminal (a person can answer). */
@@ -61,4 +78,5 @@ export declare function runDaemonStatus(opts: {
     run?: RunCommand;
     uid?: number;
 }): Promise<void>;
+export {};
 //# sourceMappingURL=mesh.d.ts.map