@indigoai-us/hq-cli 5.246.0 → 5.247.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.247.0] — 2026-09-27
+### Changed
+
+- The default-off `lanes.supersession-lineage-aware` flag lets a worker's lane
+  keep-alive and message delivery continue when its newer lane senior or a
+  same-profile sibling under that senior would otherwise look like a replacement.
+- Keep-alive setup reads lineage settings before provider locks, and message
+  eligibility rechecks lane and retirement state after that read.
+
+### Changed
+
+- `hq agent kit install` no longer implies the `@reboot` crontab entry is
+  enough on its own. The entry is installed and does restart the kit on an
+  ordinary host, but on a container whose root filesystem is rebuilt each boot
+  both cron and the CLI are erased along with it. The line now says so and
+  says what to do instead.
+
 ## [5.246.0] — 2026-09-27
 
 ### Fixed

package/dist/commands/agent-kit.js

@@ -279,6 +279,10 @@ export function registerAgentKitCommand(agent) {
                 console.log(`  kit log:   ${result.fallback.logPath}`);
                 if (result.fallback.reboot.installed) {
                     console.log(chalk.green("  reboot:    a @reboot crontab entry was installed, so the kit restarts with the host"));
+                    console.log(chalk.dim("             That holds only if cron and this CLI survive the restart. On a container " +
+                        "whose root filesystem is rebuilt each boot, both are erased and the entry goes with " +
+                        "them — reinstall the kit from your persistent storage after a restart, or have your " +
+                        "platform start `hq agent kit run all` for you."));
                 }
                 else {
                     console.log(chalk.red(`  reboot:    NOT protected — ${result.fallback.reboot.reason}. Until this is fixed the kit ` +

package/dist/commands/lanes.js

@@ -46,7 +46,7 @@ import { effectiveAccountHome } from "../lib/lanes/account-home.js";
 import { AccountResolutionError, compareLaneQueueOrder, coveredLaneIds, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, 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, parseQuestionRecord, parseSeniorKind, readLane, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, appendDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, withLaneHireLocks, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
 import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
-import { keepAliveExclusion, LEAD_LANE_KEEP_ALIVE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
+import { keepAliveExclusion, LEAD_LANE_KEEP_ALIVE_FLAG, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
 import { questionBodyAbsPath, resolveQuestionCompanyWithFallback, resolveProjectQuestionCompany, } from "../lib/lanes/questions.js";
 import { assertQuestionBodySecretSafe } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
@@ -4891,21 +4891,22 @@ async function runKeepAlive(ctx, laneId, opts) {
         throw new LanesError("keep_alive_mode_invalid", "Pass exactly one of --on or --off", { lane_id: laneId });
     }
     const hqRoot = ctx.hqRoot();
+    let lineageAware = false;
+    if (opts.on) {
+        const initialLane = readLane(hqRoot, laneId);
+        assertKeepAliveChangeAllowed(ctx, initialLane, laneId);
+        lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+            company: initialLane.company,
+            env: ctx.env,
+        });
+    }
     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 });
-        }
+        assertKeepAliveChangeAllowed(ctx, lane, laneId);
         let optedInAt;
         if (opts.on) {
             const retiredLaneIds = loadRetiredLaneIds(hqRoot);
-            const exclusion = keepAliveExclusion(lane, loadAllLanes(hqRoot), retiredLaneIds);
+            const exclusion = keepAliveExclusion(lane, loadAllLanes(hqRoot), retiredLaneIds, lineageAware);
             if (exclusion !== undefined) {
                 throw new LanesError("keep_alive_lane_excluded", `Cannot opt in lane ${laneId}: it is ${exclusion}`, { lane_id: laneId, blocked_reason: exclusion });
             }
@@ -4926,6 +4927,17 @@ async function runKeepAlive(ctx, laneId, opts) {
         lane: updated,
     });
 }
+function assertKeepAliveChangeAllowed(ctx, lane, 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 });
+    }
+}
 async function runGrant(ctx, laneId, opts) {
     if (opts.hire === undefined) {
         throw new LanesError("missing_hire_grant", "--hire is required", {});
@@ -5808,7 +5820,9 @@ async function runMessage(ctx, laneId, opts) {
         }
     }
     try {
-        const exclusion = messageLaneExclusion(ctx, lane);
+        const eligibility = await messageLaneExclusion(ctx, lane);
+        lane = eligibility.lane;
+        const exclusion = eligibility.exclusion;
         if (exclusion !== undefined) {
             let messageCount;
             if (dropboxInboxHasMessages(hqRoot, laneId)) {
@@ -6183,10 +6197,24 @@ async function runMessage(ctx, laneId, opts) {
         throw err;
     }
 }
-function messageLaneExclusion(ctx, lane) {
-    if (lane.state === "killed" || lane.state === "cancelled")
-        return lane.state;
-    return keepAliveExclusion(lane, loadAllLanes(ctx.hqRoot()), loadRetiredLaneIds(ctx.hqRoot()));
+async function messageLaneExclusion(ctx, lane) {
+    if (lane.state === "killed" || lane.state === "cancelled") {
+        return { lane, exclusion: lane.state };
+    }
+    const lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+        company: lane.company,
+        env: ctx.env,
+    });
+    const currentLane = readLane(ctx.hqRoot(), lane.lane_id);
+    if (currentLane.state === "killed" || currentLane.state === "cancelled") {
+        return { lane: currentLane, exclusion: currentLane.state };
+    }
+    const lanes = loadAllLanes(ctx.hqRoot());
+    const retiredLaneIds = loadRetiredLaneIds(ctx.hqRoot());
+    return {
+        lane: currentLane,
+        exclusion: keepAliveExclusion(currentLane, lanes, retiredLaneIds, lineageAware),
+    };
 }
 function recordMessageUndeliverable(ctx, lane, reason, messageCount) {
     writeWatcherDecision(watcherOutLogPath(ctx.hqRoot(), lane.lane_id), {
@@ -6206,10 +6234,12 @@ function recordMessageUndeliverable(ctx, lane, reason, messageCount) {
  */
 async function recoverQueuedMessages(ctx, laneId) {
     const hqRoot = ctx.hqRoot();
-    const lane = readLane(hqRoot, laneId);
+    let lane = readLane(hqRoot, laneId);
     if (!dropboxInboxHasMessages(hqRoot, laneId))
         return { action: "none", message_count: 0 };
-    const exclusion = messageLaneExclusion(ctx, lane);
+    const eligibility = await messageLaneExclusion(ctx, lane);
+    lane = eligibility.lane;
+    const exclusion = eligibility.exclusion;
     const refusal = exclusion ?? (lane.state === "done"
         ? "done_before_envelope"
         : lane.state === "awaiting_input"

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

@@ -1,6 +1,9 @@
 import type { LaneRecord, QuestionRecord } 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;
+/** Missing or unreadable registry values retain the legacy supersession behavior. */
+export declare const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
+export declare const LANE_SUPERSESSION_LINEAGE_AWARE_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;
@@ -27,7 +30,7 @@ export declare function retiredLaneRegistryPath(hqRoot: string): string;
 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 keepAliveSupersededBy(lane: LaneRecord, lanes: readonly LaneRecord[], lineageAware?: boolean): LaneRecord | undefined;
+export declare function keepAliveExclusion(lane: LaneRecord, lanes: readonly LaneRecord[], retiredLaneIds: ReadonlySet<string>, lineageAware?: boolean): "retired" | "superseded" | undefined;
 export declare function leadLaneKeepAliveBackoffMs(attempt: number): number;
 //# sourceMappingURL=keep-alive.d.ts.map

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

@@ -5,6 +5,9 @@ import { dropboxInboxHasMessages } from "./dropbox.js";
 import { listQuestionIds, readQuestion } from "./store.js";
 export const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
 export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values retain the legacy supersession behavior. */
+export const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
+export const LANE_SUPERSESSION_LINEAGE_AWARE_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;
@@ -119,11 +122,22 @@ export function isRetiredLaneId(laneId, retiredLaneIds) {
     }
     return false;
 }
-export function keepAliveSupersededBy(lane, lanes) {
+export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED) {
     const createdAt = Date.parse(lane.created_at);
     if (!Number.isFinite(createdAt))
         return undefined;
     const lanesById = new Map(lanes.map((candidate) => [candidate.lane_id, candidate]));
+    const targetAncestorIds = new Set();
+    if (lineageAware) {
+        let parentLaneId = lane.senior.kind === "lane" ? lane.senior.id : undefined;
+        while (parentLaneId) {
+            if (targetAncestorIds.has(parentLaneId))
+                break;
+            targetAncestorIds.add(parentLaneId);
+            const parent = lanesById.get(parentLaneId);
+            parentLaneId = parent?.senior.kind === "lane" ? parent.senior.id : undefined;
+        }
+    }
     return lanes.find((candidate) => {
         if (candidate.lane_id === lane.lane_id || Date.parse(candidate.created_at) <= createdAt)
             return false;
@@ -132,6 +146,8 @@ export function keepAliveSupersededBy(lane, lanes) {
             : candidate.company?.uid === lane.company.uid;
         if (!sameCompany)
             return false;
+        if (lineageAware && targetAncestorIds.has(candidate.lane_id))
+            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();
@@ -144,18 +160,22 @@ export function keepAliveSupersededBy(lane, lanes) {
             const parent = lanesById.get(parentLaneId);
             parentLaneId = parent?.senior.kind === "lane" ? parent.senior.id : undefined;
         }
+        const sameLaneSenior = lane.senior.kind === "lane" &&
+            candidate.senior.kind === "lane" &&
+            candidate.senior.id === lane.senior.id;
         const sameProfile = lane.worker_profile !== undefined &&
-            candidate.worker_profile === lane.worker_profile;
+            candidate.worker_profile === lane.worker_profile &&
+            !(lineageAware && sameLaneSenior);
         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) {
+export function keepAliveExclusion(lane, lanes, retiredLaneIds, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED) {
     if (isRetiredLaneId(lane.lane_id, retiredLaneIds))
         return "retired";
-    return keepAliveSupersededBy(lane, lanes) === undefined ? undefined : "superseded";
+    return keepAliveSupersededBy(lane, lanes, lineageAware) === undefined ? undefined : "superseded";
 }
 export function leadLaneKeepAliveBackoffMs(attempt) {
     if (!Number.isSafeInteger(attempt) || attempt < 1) {

package/dist/lib/lanes/reconcile.js

@@ -22,7 +22,7 @@ import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecor
 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_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, canResumeDoneKeepAliveLane, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, canResumeDoneKeepAliveLane, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
@@ -821,17 +821,24 @@ export async function runPassBody(hqRoot, deps) {
         keepAliveFlagCompanies.set(key, lane.company);
     }
     const keepAliveFlagByCompany = new Map();
+    const supersessionLineageAwareByCompany = new Map();
     const env = deps.env ?? process.env;
     await Promise.all([...keepAliveFlagCompanies.entries()].map(async ([key, company]) => {
-        keepAliveFlagByCompany.set(key, await readRegistryFlag(LEAD_LANE_KEEP_ALIVE_FLAG, {
+        const options = {
             company: company ?? undefined,
             env,
-        }));
+        };
+        const [keepAliveEnabled, lineageAware] = await Promise.all([
+            readRegistryFlag(LEAD_LANE_KEEP_ALIVE_FLAG, options),
+            readRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, options),
+        ]);
+        keepAliveFlagByCompany.set(key, keepAliveEnabled);
+        supersessionLineageAwareByCompany.set(key, lineageAware);
     }));
     await withAllLaneAdmissionLocks(hqRoot, async () => {
         const freshLanes = loadLaneRecords(hqRoot, summary);
         const freshQuestions = loadQuestionRecords(hqRoot, summary);
-        resumeKeepAlive(hqRoot, freshLanes, freshQuestions, summary, deps, now, keepAliveFlagByCompany);
+        resumeKeepAlive(hqRoot, freshLanes, freshQuestions, summary, deps, now, keepAliveFlagByCompany, supersessionLineageAwareByCompany);
         const drainLanes = loadLaneRecords(hqRoot, summary);
         await admitQueued(hqRoot, drainLanes, summary, deps, now);
         await resumeAwaiting(hqRoot, drainLanes, freshQuestions, summary, deps);
@@ -1546,7 +1553,7 @@ function latestEnvelopeMtimeMs(hqRoot, lane, ref) {
         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 resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCompany) {
+function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCompany, supersessionLineageAwareByCompany) {
     const nowMs = now.getTime();
     const nowIso = now.toISOString();
     const config = loadLanesConfig(hqRoot);
@@ -1702,7 +1709,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             recordKeepAliveSkip(hqRoot, lane, "retired_list_invalid", summary, deps);
             continue;
         }
-        const exclusion = keepAliveExclusion(lane, lanes, retiredLaneIds);
+        const exclusion = keepAliveExclusion(lane, lanes, retiredLaneIds, supersessionLineageAwareByCompany.get(keepAliveCompanyKey(lane.company)) === true);
         if (exclusion !== undefined) {
             recordKeepAliveSkip(hqRoot, lane, exclusion, summary, deps);
             continue;
@@ -1790,7 +1797,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             continue;
         }
         const currentLanes = loadLaneRecords(hqRoot, summary);
-        const currentExclusion = keepAliveExclusion(current, currentLanes, retiredLaneIds);
+        const currentExclusion = keepAliveExclusion(current, currentLanes, retiredLaneIds, supersessionLineageAwareByCompany.get(keepAliveCompanyKey(current.company)) === true);
         if (currentExclusion !== undefined) {
             recordKeepAliveSkip(hqRoot, current, currentExclusion, summary, deps);
             continue;

package/package.json

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