@indigoai-us/hq-cli 5.214.0 → 5.215.0

package/CHANGELOG.md

@@ -2,10 +2,20 @@
 
 ## [Unreleased]
 
+## [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, 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";
@@ -2935,6 +2936,7 @@ async function runCreate(ctx, opts) {
                 }
                 : {}),
             keep_alive: keepAlive,
+            ...(keepAlive ? { keep_alive_opted_in_at: createdAt } : {}),
             provider,
             account: pinnedAccount,
             ...(accountSelection !== undefined ? { account_selection: accountSelection } : {}),
@@ -4493,15 +4495,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",
@@ -4529,6 +4523,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 +4655,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 +4986,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 +5006,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 +5043,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 +5282,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;
@@ -8388,6 +8434,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/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/profile.d.ts

@@ -39,10 +39,10 @@ export declare function workerProfileMarker(hqRoot: string, id: string): "absent
 export declare function loadWorkerProfile(hqRoot: string, id: string): WorkerProfile;
 export interface EffectiveLaneKeepAlive {
     enabled: boolean;
-    source: "lane" | "profile" | "none";
+    source: "lane" | "none";
 }
-/** Resolve the keep-alive opt-in recorded on a lane or its attached profile. */
-export declare function resolveLaneKeepAlive(hqRoot: string, lane: Pick<LaneRecord, "keep_alive" | "worker_profile">): EffectiveLaneKeepAlive;
+/** Resolve keep-alive from the lane record; profile metadata only seeds new spawns. */
+export declare function resolveLaneKeepAlive(_hqRoot: string, lane: Pick<LaneRecord, "keep_alive">): EffectiveLaneKeepAlive;
 export declare function workerProfilePrompt(profile: WorkerProfile, delivery?: "hook" | "prompt"): string;
 export declare function ignoredWorkerProfileFields(provider: LaneProvider): string[];
 /**

package/dist/lib/lanes/profile.js

@@ -370,18 +370,11 @@ export function loadWorkerProfile(hqRoot, id) {
         contentHash: hashProfileFiles(dir, hashFiles),
     };
 }
-/** Resolve the keep-alive opt-in recorded on a lane or its attached profile. */
-export function resolveLaneKeepAlive(hqRoot, lane) {
-    if (lane.keep_alive !== undefined) {
-        return { enabled: lane.keep_alive, source: "lane" };
-    }
-    if (lane.worker_profile === undefined) {
-        return { enabled: false, source: "none" };
-    }
-    const profileKeepAlive = loadWorkerProfile(hqRoot, lane.worker_profile).meta.keep_alive;
-    return profileKeepAlive === undefined
+/** Resolve keep-alive from the lane record; profile metadata only seeds new spawns. */
+export function resolveLaneKeepAlive(_hqRoot, lane) {
+    return lane.keep_alive === undefined
         ? { enabled: false, source: "none" }
-        : { enabled: profileKeepAlive, source: "profile" };
+        : { enabled: lane.keep_alive, source: "lane" };
 }
 export function workerProfilePrompt(profile, delivery = "prompt") {
     const parts = [profile.systemPrompt.trimEnd()];

package/dist/lib/lanes/reconcile.js

@@ -14,14 +14,14 @@ import { effectiveAccountHome } from "./account-home.js";
 import { loadLanesConfig, providerQuotaDefaultHoldMs } from "./config.js";
 import { MAX_LANE_DEPTH } from "./constants.js";
 import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./errors.js";
+import { loadWorkerProfile } from "./profile.js";
 import { LANE_HIRE_GRANTS_FLAG, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
-import { loadWorkerProfile, resolveLaneKeepAlive } from "./profile.js";
 import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, unindexedClaudeSessionLiveness, } from "./liveness.js";
 import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
-import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, leadLaneKeepAliveBackoffMs, } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
 import { answeredQuestionEntries, raiseEnvelopeQuestions } from "./questions.js";
@@ -800,18 +800,19 @@ export async function runPassBody(hqRoot, deps) {
     const keepAliveFlagCompanies = new Map();
     const keepAliveHireGrantFlagCompanies = new Map();
     for (const lane of lanes) {
-        if (lane.state !== "done" ||
-            (lane.keep_alive !== true &&
-                !(lane.keep_alive === undefined && lane.worker_profile !== undefined)) ||
+        if (!(lane.state === "done" || lane.state === "killed" || lane.state === "cancelled" || lane.state === "failed") ||
+            (lane.keep_alive !== true && lane.worker_profile === undefined) ||
             !laneRunsHere(lane, deps.host) ||
-            lane.terminal_reason === PROVIDER_REJECTED_REASON ||
-            lane.terminal_reason === "account_not_logged_in" ||
-            !providerSupportsSessionResume(lane.provider) ||
-            !(lane.provider_session_id ?? lane.last_resume?.session_id))
-            continue;
-        const envelope = readLatestEnvelopeRecord(hqRoot, lane.lane_id)?.envelope;
-        if (!envelope || envelope.decision !== "done" || envelope.story_complete === true)
+            (lane.state === "done" && (lane.terminal_reason === PROVIDER_REJECTED_REASON ||
+                lane.terminal_reason === "account_not_logged_in" ||
+                !providerSupportsSessionResume(lane.provider) ||
+                !(lane.provider_session_id ?? lane.last_resume?.session_id))))
             continue;
+        if (lane.state === "done") {
+            const envelope = readLatestEnvelopeRecord(hqRoot, lane.lane_id)?.envelope;
+            if (!envelope || envelope.decision !== "done" || envelope.story_complete === true)
+                continue;
+        }
         const key = keepAliveCompanyKey(lane.company);
         keepAliveFlagCompanies.set(key, lane.company);
         if (lane.senior.kind === "lane" && lane.senior.id) {
@@ -1413,80 +1414,164 @@ function recordKeepAliveEvent(hqRoot, laneId, summary, event) {
         });
     }
 }
+function recordKeepAliveSkip(hqRoot, lane, reason, summary, deps, detail) {
+    summary.skipped.push({
+        kind: "lane",
+        id: lane.lane_id,
+        why: `keep_alive_${reason}${detail ? `: ${detail}` : ""}`,
+    });
+    if (deps.dryRun || lane.keep_alive_blocked_reason === reason)
+        return;
+    try {
+        casLaneIf(hqRoot, lane.lane_id, (current) => current.version === lane.version && current.state === lane.state, (current) => ({ ...current, keep_alive_blocked_reason: reason }), false);
+    }
+    catch (err) {
+        markDirty(summary, {
+            kind: "lane",
+            id: lane.lane_id,
+            why: `keep-alive skip state write failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+}
+function latestEnvelopeMtimeMs(hqRoot, lane, ref) {
+    const filePath = path.join(laneRunDir(hqRoot, lane.lane_id), ref);
+    try {
+        return fs.statSync(filePath).mtimeMs;
+    }
+    catch (err) {
+        throw new LanesError("keep_alive_envelope_timestamp_unavailable", `Cannot stat latest envelope for lane ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: lane.lane_id, path: filePath });
+    }
+}
 function resumeDoneKeepAlive(hqRoot, lanes, summary, deps, now, flagByCompany, hireGrantFlagByCompany) {
     const nowMs = now.getTime();
     const nowIso = now.toISOString();
     const config = loadLanesConfig(hqRoot);
+    const keepAliveEnabled = [...flagByCompany.values()].some((enabled) => enabled);
+    let retiredLaneIds = null;
+    if (keepAliveEnabled) {
+        try {
+            retiredLaneIds = loadRetiredLaneIds(hqRoot);
+        }
+        catch (err) {
+            markError(summary, err);
+        }
+    }
     for (const lane of lanes) {
-        const hasRecordedProfileFallback = lane.keep_alive === undefined && lane.worker_profile !== undefined;
+        if (!laneRunsHere(lane, deps.host))
+            continue;
+        if (lane.state === "killed" || lane.state === "cancelled" || lane.state === "failed") {
+            if (lane.keep_alive === true &&
+                flagByCompany.get(keepAliveCompanyKey(lane.company)) === true)
+                recordKeepAliveSkip(hqRoot, lane, "terminal_state", summary, deps);
+            continue;
+        }
         if (lane.state !== "done" ||
-            lane.keep_alive === false ||
-            (lane.keep_alive !== true && !hasRecordedProfileFallback) ||
-            !laneRunsHere(lane, deps.host))
+            (lane.keep_alive !== true && lane.worker_profile === undefined))
             continue;
         const latest = readLatestEnvelopeRecord(hqRoot, lane.lane_id);
         const envelope = latest?.envelope;
         if (!envelope || envelope.decision !== "done")
             continue;
-        const keepAliveConfigurationUnchanged = (candidate) => lane.keep_alive === true
-            ? candidate.keep_alive === true
-            : lane.keep_alive === undefined &&
-                lane.worker_profile !== undefined &&
-                candidate.keep_alive === undefined &&
-                candidate.worker_profile === lane.worker_profile;
         if (envelope.story_complete === true) {
             if (hasKeepAliveProgress(lane)) {
                 casLaneIf(hqRoot, lane.lane_id, (current) => current.version === lane.version &&
                     current.state === "done" &&
-                    keepAliveConfigurationUnchanged(current), (current) => clearedKeepAliveProgress(current), deps.dryRun);
+                    current.keep_alive === lane.keep_alive, (current) => ({ ...clearedKeepAliveProgress(current), keep_alive_blocked_reason: undefined }), deps.dryRun);
             }
             continue;
         }
+        if (flagByCompany.get(keepAliveCompanyKey(lane.company)) !== true)
+            continue;
         if (lane.terminal_reason === PROVIDER_REJECTED_REASON ||
-            lane.terminal_reason === "account_not_logged_in" ||
-            !providerSupportsSessionResume(lane.provider) ||
-            !(lane.provider_session_id ?? lane.last_resume?.session_id))
+            lane.terminal_reason === "account_not_logged_in") {
+            recordKeepAliveSkip(hqRoot, lane, "terminal_state", summary, deps, lane.terminal_reason);
             continue;
-        if (flagByCompany.get(keepAliveCompanyKey(lane.company)) !== true)
+        }
+        if (lane.keep_alive !== true) {
+            recordKeepAliveSkip(hqRoot, lane, "not_opted_in", summary, deps);
             continue;
-        let keepAlive;
+        }
+        const optedInAtMs = Date.parse(lane.keep_alive_opted_in_at ?? "");
+        if (!Number.isFinite(optedInAtMs)) {
+            recordKeepAliveSkip(hqRoot, lane, "missing_opt_in_time", summary, deps);
+            continue;
+        }
+        let envelopeAtMs;
         try {
-            keepAlive = resolveLaneKeepAlive(hqRoot, lane);
+            envelopeAtMs = latestEnvelopeMtimeMs(hqRoot, lane, latest.ref);
         }
         catch (err) {
-            const message = err instanceof LanesError
-                ? `${err.error}: ${err.message}`
-                : err instanceof Error ? err.message : String(err);
             markDirty(summary, {
                 kind: "lane",
                 id: lane.lane_id,
-                why: `keep-alive worker profile could not be loaded: ${message}`,
+                why: `keep-alive envelope timestamp unavailable: ${err instanceof Error ? err.message : String(err)}`,
             });
             continue;
         }
-        if (!keepAlive.enabled)
+        if (envelopeAtMs <= optedInAtMs) {
+            recordKeepAliveSkip(hqRoot, lane, "envelope_before_opt_in", summary, deps);
+            continue;
+        }
+        if (retiredLaneIds === null) {
+            recordKeepAliveSkip(hqRoot, lane, "retired_list_invalid", summary, deps);
+            continue;
+        }
+        const exclusion = keepAliveExclusion(lane, lanes, retiredLaneIds);
+        if (exclusion !== undefined) {
+            recordKeepAliveSkip(hqRoot, lane, exclusion, summary, deps);
+            continue;
+        }
+        if (!providerSupportsSessionResume(lane.provider) ||
+            !(lane.provider_session_id ?? lane.last_resume?.session_id))
             continue;
-        const keepAliveStillEnabled = (candidate) => keepAlive.source === "lane"
-            ? candidate.keep_alive === true
-            : candidate.keep_alive === undefined &&
-                candidate.worker_profile === lane.worker_profile;
+        const keepAliveStillEnabled = (candidate) => candidate.keep_alive === true &&
+            candidate.keep_alive_opted_in_at === lane.keep_alive_opted_in_at;
         const current = readLane(hqRoot, lane.lane_id);
         if (current.version !== lane.version ||
             current.state !== "done" ||
             !keepAliveStillEnabled(current) ||
             !laneRunsHere(current, deps.host))
             continue;
-        const currentEnvelope = readLatestEnvelopeRecord(hqRoot, current.lane_id)?.envelope;
+        const currentEnvelopeRecord = readLatestEnvelopeRecord(hqRoot, current.lane_id);
+        const currentEnvelope = currentEnvelopeRecord?.envelope;
         if (!currentEnvelope || currentEnvelope.decision !== "done")
             continue;
         if (currentEnvelope.story_complete === true) {
             if (hasKeepAliveProgress(current)) {
                 casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
                     latestLane.state === "done" &&
-                    keepAliveStillEnabled(latestLane), (latestLane) => clearedKeepAliveProgress(latestLane), deps.dryRun);
+                    keepAliveStillEnabled(latestLane), (latestLane) => ({ ...clearedKeepAliveProgress(latestLane), keep_alive_blocked_reason: undefined }), deps.dryRun);
             }
             continue;
         }
+        if (currentEnvelopeRecord !== null) {
+            let currentEnvelopeAtMs;
+            try {
+                currentEnvelopeAtMs = latestEnvelopeMtimeMs(hqRoot, current, currentEnvelopeRecord.ref);
+            }
+            catch (err) {
+                markDirty(summary, {
+                    kind: "lane",
+                    id: current.lane_id,
+                    why: `keep-alive envelope timestamp unavailable: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            if (currentEnvelopeAtMs <= Date.parse(current.keep_alive_opted_in_at ?? "")) {
+                recordKeepAliveSkip(hqRoot, current, "envelope_before_opt_in", summary, deps);
+                continue;
+            }
+        }
+        if (retiredLaneIds === null) {
+            recordKeepAliveSkip(hqRoot, current, "retired_list_invalid", summary, deps);
+            continue;
+        }
+        const currentLanes = loadLaneRecords(hqRoot, summary);
+        const currentExclusion = keepAliveExclusion(current, currentLanes, retiredLaneIds);
+        if (currentExclusion !== undefined) {
+            recordKeepAliveSkip(hqRoot, current, currentExclusion, summary, deps);
+            continue;
+        }
         const providerSessionId = current.provider_session_id ?? current.last_resume?.session_id;
         if (current.terminal_reason === PROVIDER_REJECTED_REASON ||
             current.terminal_reason === "account_not_logged_in" ||
@@ -1567,6 +1652,7 @@ function resumeDoneKeepAlive(hqRoot, lanes, summary, deps, now, flagByCompany, h
             keep_alive_last_resume_at: nowIso,
             keep_alive_next_eligible_at: nextEligibleAt,
             keep_alive_exhausted_at: undefined,
+            keep_alive_blocked_reason: undefined,
         }), deps.dryRun);
         const seniorId = current.senior.kind === "lane" ? current.senior.id : undefined;
         let queued;

package/dist/lib/lanes/store.js

@@ -409,6 +409,25 @@ export function parseLaneRecord(raw, filePath) {
             value: raw.keep_alive,
         });
     }
+    const keepAliveBlockedReason = raw.keep_alive_blocked_reason;
+    const validKeepAliveBlockedReasons = [
+        "not_opted_in",
+        "missing_opt_in_time",
+        "envelope_before_opt_in",
+        "retired",
+        "superseded",
+        "retired_list_invalid",
+        "terminal_state",
+    ];
+    if (keepAliveBlockedReason !== undefined &&
+        (typeof keepAliveBlockedReason !== "string" ||
+            !validKeepAliveBlockedReasons.includes(keepAliveBlockedReason))) {
+        throw new LaneSchemaError("keep_alive_blocked_reason is invalid", {
+            path: filePath,
+            field: "keep_alive_blocked_reason",
+            value: keepAliveBlockedReason,
+        });
+    }
     if (raw.keep_alive_resume_count !== undefined &&
         (typeof raw.keep_alive_resume_count !== "number" ||
             !Number.isSafeInteger(raw.keep_alive_resume_count) ||
@@ -420,6 +439,7 @@ export function parseLaneRecord(raw, filePath) {
         });
     }
     for (const field of [
+        "keep_alive_opted_in_at",
         "keep_alive_last_resume_at",
         "keep_alive_next_eligible_at",
         "keep_alive_exhausted_at",

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

@@ -356,6 +356,10 @@ export interface LaneRecord {
     worker_profile?: string;
     /** Whether this lead lane should resume completed turns while its story is open. */
     keep_alive?: boolean;
+    /** Time this lane most recently explicitly opted into keep-alive. */
+    keep_alive_opted_in_at?: string;
+    /** Why reconcile declined to resume this lane most recently. */
+    keep_alive_blocked_reason?: "not_opted_in" | "missing_opt_in_time" | "envelope_before_opt_in" | "retired" | "superseded" | "retired_list_invalid" | "terminal_state";
     /** Consecutive automatic keep-alive resumes since the last human reset. */
     keep_alive_resume_count?: number;
     /** Time the most recent automatic keep-alive resume was queued. */

package/dist/lib/lanes/types.js

@@ -224,7 +224,7 @@ export const LANE_FIELD_WRITERS = {
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     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_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
-    keep_alive: ["creator", "command"], 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"],
+    keep_alive: ["creator", "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"],
     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"],

package/package.json

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