@indigoai-us/hq-cli 5.214.0 → 5.216.0

package/CHANGELOG.md

@@ -2,10 +2,35 @@
 
 ## [Unreleased]
 
+## [5.216.0] — 2026-09-26
+
+### Fixed
+
+- Lane watchers keep valid questions from a malformed `ask` envelope when
+  repair is skipped, cannot start, or still produces invalid output. The lane
+  stores the validation errors, and recovered question context includes them.
+  Repair spawns ignore unknown profile metadata and log the field names.
+  `hq lanes create` and `hq lanes resume --worker` keep strict validation.
+
+- `hq lanes` stops sending status updates for stories missing from the project
+  board. The watcher reports the refusal once per lane run and keeps appending
+  lane events.
+
+## [5.215.0] — 2026-09-26
+
+### Fixed
+
+- hq-cli 5.211.0 could resume a retired lead from its worker profile's
+  `keep_alive` value. Reconcile now requires an explicit lane opt-in written
+  after the latest envelope, and skips retired or superseded leads.
+
 ## [5.214.0] — 2026-09-26
 
 ### Added
 
+- `hq lanes keep-alive <lane-id> --on|--off` lets a lane's senior opt in on
+  the host that owns the lane.
+
 - `hq doctor` now checks the last hour of the sync runner log for stuck
   realtime lag, cloud permission refusals, runner restart loops, device-limit
   backoff, and repeated conflicts. Client health reports send these to Sentry

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

@@ -7399,6 +7399,28 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "keep-alive";
+        readonly description: "Opt a lane into or out of automatic lead-lane resumes";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <lane-id>";
+        readonly arguments: readonly [{
+            readonly name: "lane-id";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--on";
+            readonly description: "Enable explicit keep-alive for this lane";
+        }, {
+            readonly flags: "--off";
+            readonly description: "Disable keep-alive for this lane";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Emit JSON on stdout (default)";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "grant";
         readonly description: "Set a lane's alive child-lane grant as its senior";

package/dist/command-catalog.generated.js

@@ -9566,6 +9566,35 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "keep-alive",
+                "description": "Opt a lane into or out of automatic lead-lane resumes",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <lane-id>",
+                "arguments": [
+                    {
+                        "name": "lane-id",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--on",
+                        "description": "Enable explicit keep-alive for this lane"
+                    },
+                    {
+                        "flags": "--off",
+                        "description": "Disable keep-alive for this lane"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Emit JSON on stdout (default)"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "grant",
                 "description": "Set a lane's alive child-lane grant as its senior",

package/dist/commands/lanes.js

@@ -36,9 +36,10 @@ import { CompanySelectionError } from "../utils/company-selection-error.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshEventIdentity, } from "../lib/lanes/mesh-events.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { effectiveAccountHome } from "../lib/lanes/account-home.js";
-import { AccountResolutionError, compareLaneQueueOrder, coveredLaneIds, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, createQuestion, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseLivenessState, parseQuestionRecord, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, runReconcilePass, wakeAnsweredLaneNow, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withLaneHireLocks, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
+import { AccountResolutionError, compareLaneQueueOrder, coveredLaneIds, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, createQuestion, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseLivenessState, parseQuestionRecord, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, runReconcilePass, wakeAnsweredLaneNow, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, withLaneHireLocks, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
 import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
+import { keepAliveExclusion, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
@@ -896,41 +897,6 @@ async function withResumeHireAdmission(ctx, lane, fn) {
         return fn();
     });
 }
-function hireGrantCapacityError(parent, children) {
-    const grant = parent.hire_grant ?? 0;
-    const grantor = (parent.senior.kind === "lane" || parent.senior.kind === "session") &&
-        parent.senior.id
-        ? { kind: parent.senior.kind, id: parent.senior.id }
-        : null;
-    const grantorReason = grantor
-        ? undefined
-        : parent.senior.kind === "user"
-            ? "senior_is_user"
-            : "parent_senior_missing_id";
-    const capacity = children.length === grant
-        ? `is at its hire grant (${children.length} of ${grant} alive children)`
-        : `has exhausted its hire grant (${children.length} alive children; grant ${grant})`;
-    const grantCommand = `hq lanes grant ${parent.lane_id} --hire <n>`;
-    const authorityGuidance = grantor
-        ? `Its senior ${grantor.kind} ${grantor.id} can raise it with: ${grantCommand}`
-        : parent.senior.kind === "user"
-            ? `Its senior is the user and can raise it with: ${grantCommand}`
-            : `No senior is recorded, so an operator must resolve ownership before running: ${grantCommand}`;
-    const message = `Lane ${parent.lane_id} ${capacity}. ${authorityGuidance}`;
-    return new LanesError("hire_grant_exhausted", message, {
-        senior_lane_id: parent.lane_id,
-        parent_grant: grant,
-        alive_children: children.map((child) => child.lane_id),
-        alive_child_count: children.length,
-        grantor,
-        ...(grantorReason ? { grantor_reason: grantorReason } : {}),
-        message,
-        ask_guidance: {
-            envelope: "decision=ask; include the desired total grant and the reason",
-            senior_command: `hq lanes grant ${parent.lane_id} --hire <n>`,
-        },
-    });
-}
 const CAPACITY_PROBE_TIMEOUT_MS = 15_000;
 const MAX_PLACEMENT_OUTPOSTS = 16;
 function outpostIdentityUnknownError(message, expectedId, details = {}) {
@@ -2071,7 +2037,7 @@ async function emitLaneTerminalStateSoft(ctx, lane) {
         process.stderr.write(`hq lanes: terminal mesh update failed for ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}\n`);
     }
 }
-async function emitLaneStartedForStories(ctx, company, lane, threadId) {
+async function emitLaneStartedForStories(ctx, company, lane, threadId, knownAbsentStories = new Set()) {
     let ready = lane;
     if (ctx.mesh.ensureLaneThread) {
         try {
@@ -2107,6 +2073,8 @@ async function emitLaneStartedForStories(ctx, company, lane, threadId) {
             failures.push(err);
             continue;
         }
+        if (knownAbsentStories.has(storyBoardStoryKey(story.project_id, story.story_id)))
+            continue;
         try {
             await ctx.mesh.patchStoryStatus(company, story.project_id, story.story_id, "in_progress");
         }
@@ -2134,20 +2102,30 @@ function storyNotOnBoardWarning(err) {
         ? err.message
         : undefined;
 }
+function storyBoardStoryKey(projectId, storyId) {
+    return JSON.stringify([projectId, storyId]);
+}
 function combinedStoryWarning(lane, additional = []) {
     const warnings = [storyWarning(lane), ...additional]
         .filter((warning) => warning !== undefined && warning.trim().length > 0);
     return [...new Set(warnings)].join(" ") || null;
 }
-async function storyBoardWarning(ctx, company, projectId, storyIds) {
+async function storyBoardCheck(ctx, company, projectId, storyIds) {
     try {
         await assertStoriesOnBoard(ctx, company, projectId, storyIds);
-        return undefined;
+        return { absentStoryIds: new Set() };
     }
     catch (err) {
         const warning = storyNotOnBoardWarning(err);
-        if (warning !== undefined)
-            return warning;
+        if (warning !== undefined) {
+            const storyId = isLanesError(err) && typeof err.details.story_id === "string"
+                ? err.details.story_id
+                : undefined;
+            return {
+                warning,
+                absentStoryIds: new Set(storyId ? [storyId] : []),
+            };
+        }
         throw err;
     }
 }
@@ -2450,10 +2428,14 @@ async function runCreate(ctx, opts) {
     const seniorCompany = companyOfSenior(hqRoot, senior, ctx);
     assertSameTenant(company, senior, seniorCompany);
     const createStoryWarnings = [];
+    const knownAbsentStories = new Set();
     if (meshCompany && storyIds.length > 0) {
-        const warning = await storyBoardWarning(ctx, meshCompany, project, storyIds);
-        if (warning !== undefined)
-            createStoryWarnings.push(warning);
+        const boardCheck = await storyBoardCheck(ctx, meshCompany, project, storyIds);
+        if (boardCheck.warning !== undefined)
+            createStoryWarnings.push(boardCheck.warning);
+        for (const storyId of boardCheck.absentStoryIds) {
+            knownAbsentStories.add(storyBoardStoryKey(project, storyId));
+        }
     }
     let resolvedWorker;
     if (opts.worker) {
@@ -2935,6 +2917,7 @@ async function runCreate(ctx, opts) {
                 }
                 : {}),
             keep_alive: keepAlive,
+            ...(keepAlive ? { keep_alive_opted_in_at: createdAt } : {}),
             provider,
             account: pinnedAccount,
             ...(accountSelection !== undefined ? { account_selection: accountSelection } : {}),
@@ -3065,7 +3048,7 @@ async function runCreate(ctx, opts) {
             locateTranscript: ctx.locateTranscript,
         });
         if (meshCompany) {
-            createStoryWarnings.push(...await emitLaneStartedForStories(ctx, meshCompany, started, started.thread_id));
+            createStoryWarnings.push(...await emitLaneStartedForStories(ctx, meshCompany, started, started.thread_id, knownAbsentStories));
         }
     }
     else if (outpostId) {
@@ -4493,15 +4476,7 @@ async function runShow(ctx, laneId) {
         ? { ...storedLane, state: "remote", remote_state: storedLane.state, queued_reason: undefined }
         : storedLane;
     const askDeliveryFailed = readJsonFile(askDeliveryFailedPath(hqRoot, laneId));
-    let keepAliveState;
-    try {
-        keepAliveState = resolveLaneKeepAlive(hqRoot, storedLane);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`hq lanes show: keep-alive profile could not be loaded for ${laneId}: ${message}\n`);
-        keepAliveState = { enabled: false, source: "none" };
-    }
+    const keepAliveState = resolveLaneKeepAlive(hqRoot, storedLane);
     printJson({
         ok: true,
         action: "show",
@@ -4516,6 +4491,7 @@ async function runShow(ctx, laneId) {
         provider_session_id: lane.provider_session_id ?? null,
         provider_session_id_absent: lane.provider_session_id_absent ?? null,
         envelope_repair_mode: lane.envelope_repair?.mode ?? null,
+        envelope_validation_errors: lane.envelope_validation_errors ?? [],
         last_resume: lane.last_resume ?? null,
         account: lane.account ?? null,
         account_history: lane.account_history ?? [],
@@ -4529,6 +4505,9 @@ async function runShow(ctx, laneId) {
         keep_alive_state: {
             enabled: keepAliveState.enabled,
             source: keepAliveState.source,
+            opted_in_at: storedLane.keep_alive_opted_in_at ?? null,
+            blocked_reason: storedLane.keep_alive_blocked_reason ??
+                (storedLane.keep_alive === true ? null : "not_opted_in"),
             consecutive_auto_resumes: lane.keep_alive_resume_count ?? 0,
             last_auto_resume_at: lane.keep_alive_last_resume_at ?? null,
             next_eligible_at: lane.keep_alive_next_eligible_at ?? null,
@@ -4658,6 +4637,45 @@ function printGrantResult(hqRoot, updated, hierarchy) {
     const fields = laneHireFields(updated, hierarchy ?? loadAllLanes(hqRoot));
     printJson({ ok: true, action: "grant", lane_id: updated.lane_id, lane: updated, ...fields });
 }
+async function runKeepAlive(ctx, laneId, opts) {
+    if (Boolean(opts.on) === Boolean(opts.off)) {
+        throw new LanesError("keep_alive_mode_invalid", "Pass exactly one of --on or --off", { lane_id: laneId });
+    }
+    const hqRoot = ctx.hqRoot();
+    const updated = await withAllLaneAdmissionLocks(hqRoot, async () => {
+        const lane = readLane(hqRoot, laneId);
+        if (!callerMatchesSenior(ctx, lane.senior)) {
+            throw new LanesError("keep_alive_unauthorized", `Only senior ${seniorKey(lane.senior)} may change lane ${laneId}'s keep-alive setting`, { lane_id: laneId, senior: lane.senior });
+        }
+        if (!laneRunsHere(lane, reconcileHostFromCtx(ctx))) {
+            throw new LanesError("keep_alive_owner_host_required", `Run hq lanes keep-alive ${laneId} on its owner host ${lane.host.kind}:${lane.host.id}`, { lane_id: laneId, host: lane.host });
+        }
+        if (lane.state === "killed" || lane.state === "cancelled" || lane.state === "failed") {
+            throw new LanesError("keep_alive_terminal_lane", `Cannot change keep-alive for lane ${laneId} in terminal state ${lane.state}`, { lane_id: laneId, state: lane.state });
+        }
+        let optedInAt;
+        if (opts.on) {
+            const retiredLaneIds = loadRetiredLaneIds(hqRoot);
+            const exclusion = keepAliveExclusion(lane, loadAllLanes(hqRoot), retiredLaneIds);
+            if (exclusion !== undefined) {
+                throw new LanesError("keep_alive_lane_excluded", `Cannot opt in lane ${laneId}: it is ${exclusion}`, { lane_id: laneId, blocked_reason: exclusion });
+            }
+            optedInAt = ctx.now().toISOString();
+        }
+        return updateLane(hqRoot, laneId, lane.version, "command", (current) => ({
+            ...current,
+            keep_alive: Boolean(opts.on),
+            keep_alive_opted_in_at: optedInAt,
+            keep_alive_blocked_reason: undefined,
+        }));
+    });
+    printJson({
+        ok: true,
+        action: "keep-alive",
+        lane_id: updated.lane_id,
+        lane: updated,
+    });
+}
 async function runGrant(ctx, laneId, opts) {
     if (opts.hire === undefined) {
         throw new LanesError("missing_hire_grant", "--hire is required", {});
@@ -4950,6 +4968,10 @@ function applyResumeProfileAndEffort(current, next, input) {
         next.worker_policy_delivery = undefined;
         if (profile.meta.keep_alive !== undefined) {
             next.keep_alive = profile.meta.keep_alive;
+            next.keep_alive_opted_in_at = profile.meta.keep_alive
+                ? input.at ?? new Date().toISOString()
+                : undefined;
+            next.keep_alive_blocked_reason = undefined;
         }
         if (next.model_source !== "cli") {
             if (profile.meta.provider === current.provider && profile.meta.model !== undefined) {
@@ -4966,8 +4988,13 @@ function applyResumeProfileAndEffort(current, next, input) {
         next.effort = input.effort.effort;
         next.effort_source = input.effort.source;
     }
-    if (input.keepAlive !== undefined)
+    if (input.keepAlive !== undefined) {
         next.keep_alive = input.keepAlive;
+        next.keep_alive_opted_in_at = input.keepAlive
+            ? input.at ?? new Date().toISOString()
+            : undefined;
+        next.keep_alive_blocked_reason = undefined;
+    }
 }
 function recordResumeSetup(ctx, lane, input) {
     if (input.cliModel !== undefined) {
@@ -4998,7 +5025,7 @@ function recordResumeSetup(ctx, lane, input) {
             throw new LanesError("lane_resume_setup_conflict", `Lane ${lane.lane_id} changed while resume settings were prepared; run the resume again`, { lane_id: lane.lane_id, prepared_version: lane.version, version: current.version });
         }
         const next = { ...current };
-        applyResumeProfileAndEffort(current, next, input);
+        applyResumeProfileAndEffort(current, next, { ...input, at: ctx.now().toISOString() });
         if (input.cliModel !== undefined) {
             next.model = input.cliModel.trim();
             next.model_source = "cli";
@@ -5237,6 +5264,7 @@ async function prepareAccountMove(ctx, lane, input) {
             applyResumeProfileAndEffort(current, next, {
                 ...(input.workerProfile !== undefined ? { profile: input.workerProfile } : {}),
                 ...(input.effort !== undefined ? { effort: input.effort } : {}),
+                at,
             });
             if (input.deferTurnStart) {
                 next.state = current.state;
@@ -6281,7 +6309,7 @@ async function ensureLaneThreadRecord(ctx, lane, projectId = lane.project_id, st
     }
     return updated;
 }
-async function emitStoryTransition(ctx, lane, projectId, storyId, event, status, payload = {}) {
+async function emitStoryTransition(ctx, lane, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
     const company = lane.mesh_company ?? lane.company;
     if (!company)
         return;
@@ -6295,7 +6323,9 @@ async function emitStoryTransition(ctx, lane, projectId, storyId, event, status,
         ...payload,
         lane_status: lane.state,
     });
-    await ctx.mesh.patchStoryStatus(company, projectId, storyId, status === "blocked" ? "in_progress" : status);
+    if (!skipStoryStatusPatch) {
+        await ctx.mesh.patchStoryStatus(company, projectId, storyId, status === "blocked" ? "in_progress" : status);
+    }
 }
 function sameCommittedStory(current, expected, projectId, storyId) {
     const currentStory = laneStory(current, projectId, storyId);
@@ -6304,9 +6334,9 @@ function sameCommittedStory(current, expected, projectId, storyId) {
         current.story_id === expected.story_id &&
         JSON.stringify(currentStory) === JSON.stringify(expectedStory));
 }
-async function commitStoryTransition(ctx, before, next, projectId, storyId, event, status, payload = {}) {
+async function commitStoryTransition(ctx, before, next, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
     try {
-        await emitStoryTransition(ctx, next, projectId, storyId, event, status, payload);
+        await emitStoryTransition(ctx, next, projectId, storyId, event, status, payload, skipStoryStatusPatch);
         return undefined;
     }
     catch (err) {
@@ -6362,10 +6392,12 @@ async function runStoryAdd(ctx, laneId, storyId, opts) {
     }
     const company = lane.mesh_company ?? lane.company;
     const warnings = [];
+    let storyKnownAbsent = false;
     if (company) {
-        const warning = await storyBoardWarning(ctx, company, projectId, [normalizedStoryId]);
-        if (warning !== undefined)
-            warnings.push(warning);
+        const boardCheck = await storyBoardCheck(ctx, company, projectId, [normalizedStoryId]);
+        if (boardCheck.warning !== undefined)
+            warnings.push(boardCheck.warning);
+        storyKnownAbsent = boardCheck.absentStoryIds.has(normalizedStoryId);
     }
     const at = ctx.now().toISOString();
     const thread = await ensureStoryThreadForTransition(ctx, lane, projectId, normalizedStoryId);
@@ -6381,7 +6413,7 @@ async function runStoryAdd(ctx, laneId, storyId, opts) {
             no_story_reason: undefined,
         };
     });
-    const transitionWarning = await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress");
+    const transitionWarning = await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress", {}, storyKnownAbsent);
     if (transitionWarning !== undefined)
         warnings.push(transitionWarning);
     const finalLane = readLane(hqRoot, laneId);
@@ -8388,6 +8420,16 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (laneId, opts) => {
         await runGrantOwnerTarget(ctx, laneId, opts);
     }));
+    lanes
+        .command("keep-alive")
+        .description("Opt a lane into or out of automatic lead-lane resumes")
+        .argument("<lane-id>", "Lane id")
+        .option("--on", "Enable explicit keep-alive for this lane")
+        .option("--off", "Disable keep-alive for this lane")
+        .option("--json", "Emit JSON on stdout (default)")
+        .action(wrap(async (laneId, opts) => {
+        await runKeepAlive(ctx, laneId, opts);
+    }));
     lanes
         .command("grant")
         .description("Set a lane's alive child-lane grant as its senior")

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

@@ -3,7 +3,7 @@
  */
 export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
 export { MAX_LANE_DEPTH } from "./constants.js";
-export { assignedChildHireGrants, aliveDirectChildren, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
+export { assignedChildHireGrants, aliveDirectChildren, hireGrantCapacityError, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
 export type { HireGrantBackfillRow } from "./hire-grants.js";
 export { compareLaneQueueOrder, hasActiveAdmissionReservation, hasActivePendingResume, hasEarlierEligibleQueuedLane, laneOccupiesRunningSlot, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, withLaneAdmissionLock, } from "./admission.js";
 export type { AdmissionCapReason, AdmissionHost } from "./admission.js";

package/dist/lib/lanes/index.js

@@ -3,7 +3,7 @@
  */
 export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
 export { MAX_LANE_DEPTH } from "./constants.js";
-export { assignedChildHireGrants, aliveDirectChildren, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
+export { assignedChildHireGrants, aliveDirectChildren, hireGrantCapacityError, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
 export { compareLaneQueueOrder, hasActiveAdmissionReservation, hasActivePendingResume, hasEarlierEligibleQueuedLane, laneOccupiesRunningSlot, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, withLaneAdmissionLock, } from "./admission.js";
 export { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "./host-capacity.js";
 export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STORY_STATUSES, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";

package/dist/lib/lanes/keep-alive.d.ts

@@ -1,8 +1,17 @@
+import type { LaneRecord } from "./types.js";
 export declare const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
 export declare const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export declare const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS: number;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS: number;
 export declare const LEAD_LANE_KEEP_ALIVE_RESUME_TEXT = "Automatic keep-alive resume: your last turn ended with decision done and story_complete false. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
+export type KeepAliveBlockedReason = NonNullable<LaneRecord["keep_alive_blocked_reason"]>;
+export declare function retiredLaneRegistryPath(hqRoot: string): string;
+/** Missing registry means no retired lanes; every present invalid file fails closed. */
+export declare function loadRetiredLaneIds(hqRoot: string): ReadonlySet<string>;
+/** IDs may be stored bare or with an owner-host suffix after an underscore. */
+export declare function isRetiredLaneId(laneId: string, retiredLaneIds: ReadonlySet<string>): boolean;
+export declare function keepAliveSupersededBy(lane: LaneRecord, lanes: readonly LaneRecord[]): LaneRecord | undefined;
+export declare function keepAliveExclusion(lane: LaneRecord, lanes: readonly LaneRecord[], retiredLaneIds: ReadonlySet<string>): "retired" | "superseded" | undefined;
 export declare function leadLaneKeepAliveBackoffMs(attempt: number): number;
 //# sourceMappingURL=keep-alive.d.ts.map

package/dist/lib/lanes/keep-alive.js

@@ -1,9 +1,110 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
 export const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
 export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 export const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS = 5 * 60 * 1000;
 export const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS = 60 * 60 * 1000;
 export const LEAD_LANE_KEEP_ALIVE_RESUME_TEXT = "Automatic keep-alive resume: your last turn ended with decision done and story_complete false. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
+export function retiredLaneRegistryPath(hqRoot) {
+    return path.join(hqRoot, "workspace", "lane-briefs", "juniors.json");
+}
+/** Missing registry means no retired lanes; every present invalid file fails closed. */
+export function loadRetiredLaneIds(hqRoot) {
+    const filePath = retiredLaneRegistryPath(hqRoot);
+    let text;
+    try {
+        const stat = fs.lstatSync(filePath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error("expected a regular file");
+        }
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return new Set();
+        throw new LanesError("keep_alive_retired_list_invalid", `Cannot read retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesError("keep_alive_retired_list_invalid", `Cannot parse retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw invalidRetiredList(filePath, "root must be an object");
+    }
+    const retired = parsed.retired;
+    if (retired === undefined)
+        return new Set();
+    if (!Array.isArray(retired))
+        throw invalidRetiredList(filePath, "retired must be an array");
+    const laneIds = new Set();
+    for (const [index, entry] of retired.entries()) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw invalidRetiredList(filePath, `retired[${index}] must be an object with a lane id`);
+        }
+        const laneId = entry.lane;
+        if (typeof laneId !== "string" || laneId.trim() === "") {
+            throw invalidRetiredList(filePath, `retired[${index}].lane must be a non-empty string`);
+        }
+        laneIds.add(laneId.trim());
+    }
+    return laneIds;
+}
+function invalidRetiredList(filePath, message) {
+    return new LanesError("keep_alive_retired_list_invalid", `Invalid retired lane list ${filePath}: ${message}`, { path: filePath });
+}
+/** IDs may be stored bare or with an owner-host suffix after an underscore. */
+export function isRetiredLaneId(laneId, retiredLaneIds) {
+    for (const retiredId of retiredLaneIds) {
+        if (retiredId === laneId ||
+            retiredId.startsWith(`${laneId}_`) ||
+            laneId.startsWith(`${retiredId}_`))
+            return true;
+    }
+    return false;
+}
+export function keepAliveSupersededBy(lane, lanes) {
+    const createdAt = Date.parse(lane.created_at);
+    if (!Number.isFinite(createdAt))
+        return undefined;
+    const lanesById = new Map(lanes.map((candidate) => [candidate.lane_id, candidate]));
+    return lanes.find((candidate) => {
+        if (candidate.lane_id === lane.lane_id || Date.parse(candidate.created_at) <= createdAt)
+            return false;
+        const sameCompany = lane.company === null
+            ? candidate.company === null
+            : candidate.company?.uid === lane.company.uid;
+        if (!sameCompany)
+            return false;
+        // Any descendant is part of this lead's work tree, not a replacement lead.
+        let parentLaneId = candidate.senior.kind === "lane" ? candidate.senior.id : undefined;
+        const visitedLaneIds = new Set();
+        while (parentLaneId) {
+            if (parentLaneId === lane.lane_id)
+                return false;
+            if (visitedLaneIds.has(parentLaneId))
+                break;
+            visitedLaneIds.add(parentLaneId);
+            const parent = lanesById.get(parentLaneId);
+            parentLaneId = parent?.senior.kind === "lane" ? parent.senior.id : undefined;
+        }
+        const sameProfile = lane.worker_profile !== undefined &&
+            candidate.worker_profile === lane.worker_profile;
+        const projectLead = lane.project_id !== undefined &&
+            candidate.project_id === lane.project_id &&
+            (candidate.hire_grant ?? 0) > 0;
+        return sameProfile || projectLead;
+    });
+}
+export function keepAliveExclusion(lane, lanes, retiredLaneIds) {
+    if (isRetiredLaneId(lane.lane_id, retiredLaneIds))
+        return "retired";
+    return keepAliveSupersededBy(lane, lanes) === undefined ? undefined : "superseded";
+}
 export function leadLaneKeepAliveBackoffMs(attempt) {
     if (!Number.isSafeInteger(attempt) || attempt < 1) {
         throw new RangeError("keep-alive attempt must be a positive safe integer");

package/dist/lib/lanes/mesh-events.d.ts

@@ -92,6 +92,7 @@ export interface CreateLaneMeshOptions {
     }) => Promise<void>;
 }
 export declare function storyNotOnBoardError(company: LaneCompanyRef, projectId: string, storyId: string): LanesError;
+export declare function laneStoryStatusSuppressionKey(company: LaneCompanyRef, projectId: string, storyId: string): string;
 export declare function createLaneMesh(opts?: CreateLaneMeshOptions): LaneMesh;
 /** Resolve the explicit mesh attribution before falling back to the lane tenant. */
 export declare function laneMeshCompany(lane: Pick<LaneRecord, "company" | "mesh_company">): LaneCompanyRef | undefined;
@@ -106,6 +107,8 @@ export declare function laneMeshEventIdentity(lane: LaneRecord): Record<string,
 export declare function emitLaneDecisionEvents(mesh: LaneMesh, lane: LaneRecord, envelope: Pick<LaneEnvelope, "decision" | "summary" | "blocked_reason">, opts?: {
     questionIds?: string[];
     signal?: AbortSignal;
+    /** Per-watcher-run cache for story_not_on_board refusals. */
+    storyStatusSuppressions?: Set<string>;
 }): Promise<void>;
 /** Emit an abnormal terminal state even when the worker produced no envelope. */
 export declare function emitLaneTerminalStateEvent(mesh: LaneMesh, lane: LaneRecord, state: Exclude<TerminalLaneState, "done">, summary?: string, signal?: AbortSignal): Promise<void>;