@indigoai-us/hq-cli 5.213.0 → 5.215.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [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
+  as reason codes and counts only.
+
+### Fixed
+
+- The desktop app's first sync push now uploads files inside private folders.
+  The credentials the app hands to `hq sync push --creds-from-stdin` cannot
+  write there directly, so the push also passes the vault config to hq-cloud
+  6.18.5, which sends those files through presigned uploads.
+
 ## [5.213.0] — 2026-09-26
 
 ### Fixed

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/cloud.d.ts

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 import { Command } from "commander";
-import { type ConflictStrategy, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type ConflictStrategy, type EntityContext, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant, type ShareOptions, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 /**
  * Terminal-failure signal for the sync fanout runners. The runners
@@ -264,6 +264,18 @@ export declare function pullAll(options: PullAllOptions, deps: PullAllDeps): Pro
  * deps so tests can drive it without network or filesystem.
  */
 export declare function pushAll(options: PushAllOptions, deps: PushAllDeps): Promise<PushAllResult>;
+/**
+ * Credentials `hq sync push` hands to share(). A pre-vended EntityContext
+ * (AppBar's `--creds-from-stdin` first push) cannot write under private
+ * folders directly, so it travels with the caller's vault config as
+ * `privateFolderVaultConfig`. share() takes exactly one of `vaultConfig` /
+ * `entityContext`.
+ */
+export declare function pushShareCredentials(input: {
+    entityContext?: EntityContext;
+    vaultConfig?: VaultServiceConfig;
+    scopeVaultConfig?: VaultServiceConfig;
+}): Pick<ShareOptions, "entityContext" | "vaultConfig" | "privateFolderVaultConfig">;
 /**
  * Resolve the canonical person entity UID for the logged-in user. Used by
  * `hq sync {push,pull,now} --personal` to target the personal vault without

package/dist/commands/cloud.js

@@ -455,6 +455,24 @@ export async function pushAll(options, deps) {
     }
     return result;
 }
+/**
+ * Credentials `hq sync push` hands to share(). A pre-vended EntityContext
+ * (AppBar's `--creds-from-stdin` first push) cannot write under private
+ * folders directly, so it travels with the caller's vault config as
+ * `privateFolderVaultConfig`. share() takes exactly one of `vaultConfig` /
+ * `entityContext`.
+ */
+export function pushShareCredentials(input) {
+    if (input.entityContext) {
+        return {
+            entityContext: input.entityContext,
+            ...(input.scopeVaultConfig
+                ? { privateFolderVaultConfig: input.scopeVaultConfig }
+                : {}),
+        };
+    }
+    return input.vaultConfig ? { vaultConfig: input.vaultConfig } : {};
+}
 /**
  * Resolve the canonical person entity UID for the logged-in user. Used by
  * `hq sync {push,pull,now} --personal` to target the personal vault without
@@ -715,7 +733,7 @@ export function registerCloudCommands(program) {
             //   2. default: vend via cached Cognito session (the human CLI path).
             let entityContext;
             let vaultConfig;
-            /** Vault API config for membership/grant scope lookups. Set even on the pre-vended `--creds-from-stdin` path — share() accepts entityContext OR vaultConfig, not both. */
+            /** Vault API config for membership/grant scope lookups and, on the pre-vended `--creds-from-stdin` path, private-folder uploads. */
             let scopeVaultConfig;
             if (options.credsFromStdin) {
                 if (process.stdin.isTTY) {
@@ -798,8 +816,11 @@ export function registerCloudCommands(program) {
                 company: targetCompany,
                 message: options.message,
                 onConflict: options.onConflict,
-                vaultConfig,
-                entityContext,
+                ...pushShareCredentials({
+                    entityContext,
+                    vaultConfig,
+                    scopeVaultConfig,
+                }),
                 hqRoot: options.hqRoot,
                 onEvent,
                 ...(personalMode ? { personalMode: true } : {}),

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/doctor/checks/sync-health.d.ts

@@ -64,6 +64,8 @@ export interface SyncManifestUploadStatus {
 }
 /** Injectable dependencies — defaults are the real collectors. */
 export interface SyncHealthDeps {
+    /** Runner log and conflict signals; omitted in unit tests of other checks. */
+    runtime?: (now: Date) => CheckResult[];
     versions: (hqRoot: string) => SyncVersionInfo;
     journals: () => readonly SyncJournalSummary[];
     now: () => Date;

package/dist/lib/doctor/checks/sync-health.js

@@ -23,6 +23,7 @@
  * Every dependency is injectable so the family is unit-testable without an HQ
  * tree, a state dir, or the wall clock.
  */
+import { defaultSyncRuntimeResults } from "./sync-runtime.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // Namespace import, deliberately: hq-cloud is an ESM package, so a static
@@ -50,6 +51,7 @@ export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "
 function withDefaults(deps, hqRoot) {
     return {
         ...deps,
+        runtime: deps.runtime ?? (() => []),
         manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
         manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
         unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
@@ -118,6 +120,7 @@ const DEFAULT_DEPS = {
     journals: () => hqCloud.listJournals(),
     now: () => new Date(),
     manifestStatuses: defaultManifestStatuses,
+    runtime: defaultSyncRuntimeResults,
 };
 /**
  * Map the machine's journal shards onto the manifest scopes hq-cloud keys its
@@ -190,6 +193,7 @@ export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
             ...journalAndManifestResults(deps),
+            ...deps.runtime(deps.now()),
         ];
     }
     catch (error) {

package/dist/lib/doctor/checks/sync-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { CheckResult } from "../types.js";
+export declare const SYNC_RUNTIME_WINDOW_MS: number;
+export interface SyncRuntimeOptions {
+    now: number;
+    conflictCount?: number;
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export declare function analyzeSyncRuntimeLog(lines: readonly string[], options: SyncRuntimeOptions): CheckResult[];
+/** Read the machine's sync logs and client health file. */
+export declare function defaultSyncRuntimeResults(now: Date, hqHome?: string): CheckResult[];
+//# sourceMappingURL=sync-runtime.d.ts.map

package/dist/lib/doctor/checks/sync-runtime.js

@@ -0,0 +1,166 @@
+/**
+ * Sync runtime checks: problems visible only in the running sync runner's log
+ * (realtime lag, receiver permission errors, restart loops, device-limit
+ * backoff) plus the conflict counter the desktop app keeps in client health.
+ *
+ * Results carry only a closed reason code and counts. Log content (paths,
+ * tenant ids, AWS error prose) never leaves this module.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const SYNC_RUNTIME_WINDOW_MS = 60 * 60_000;
+const LAG_SECONDS = 15 * 60;
+const LAG_MIN_RECEIPTS = 3;
+const RESTART_MIN_STARTS = 4;
+const CONFLICT_MIN_COUNT = 5;
+const LOG_TAIL_BYTES = 8 * 1024 * 1024;
+const TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\s/;
+const PERMISSION = /AccessDenied|not authorized to perform|\b403\b/;
+const DEVICE_LIMIT = /sync device limit exceeded|"sync_device_limit"/;
+function parseRecord(rest) {
+    const start = rest.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        const value = JSON.parse(rest.slice(start));
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export function analyzeSyncRuntimeLog(lines, options) {
+    const since = options.now - SYNC_RUNTIME_WINDOW_MS;
+    let slowReceipts = 0;
+    let denied = 0;
+    let starts = 0;
+    let deviceLimited = 0;
+    for (const line of lines) {
+        const stamp = TIMESTAMP.exec(line);
+        if (!stamp)
+            continue;
+        const time = Date.parse(stamp[1]);
+        if (!Number.isFinite(time) || time < since || time > options.now)
+            continue;
+        const rest = line.slice(stamp[0].length);
+        if (DEVICE_LIMIT.test(rest))
+            deviceLimited += 1;
+        const record = parseRecord(rest);
+        if (!record)
+            continue;
+        const event = record.event;
+        if (event === "fanout.receive") {
+            const latency = record.latencySeconds;
+            if (typeof latency === "number" && latency > LAG_SECONDS)
+                slowReceipts += 1;
+        }
+        else if (event === "receiver.start") {
+            starts += 1;
+        }
+        if ((record.type === "receiver" || record.type === "error") &&
+            PERMISSION.test(JSON.stringify(record.err ?? record.message ?? ""))) {
+            denied += 1;
+        }
+    }
+    const conflicts = options.conflictCount ?? 0;
+    const checks = [
+        { id: "realtime-lag", reasonCode: "realtime-lag-stuck", failing: slowReceipts >= LAG_MIN_RECEIPTS, count: slowReceipts, label: "incoming changes delayed over 15 minutes" },
+        { id: "receiver-permission", reasonCode: "receiver-permission-denied", failing: denied > 0, count: denied, label: "cloud permission refusals" },
+        { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "sync runner starts" },
+        { id: "device-limit", reasonCode: "device-limit-backoff", failing: deviceLimited > 0, count: deviceLimited, label: "device-limit backoffs" },
+        { id: "conflicts", reasonCode: "repeated-conflicts", failing: conflicts >= CONFLICT_MIN_COUNT, count: conflicts, label: "unresolved conflicts" },
+    ];
+    return checks.map((check) => check.failing
+        ? {
+            status: "WARN",
+            checkId: `sync.runtime.${check.id}`,
+            reasonCode: check.reasonCode,
+            message: `${check.count} ${check.label} in the last hour.`,
+            remediation: "Run `hq sync status` and check ~/.hq/logs/hq-sync.log.",
+        }
+        : {
+            status: "PASS",
+            checkId: `sync.runtime.${check.id}`,
+            message: `${check.count} ${check.label} in the last hour.`,
+        });
+}
+const LOG_GENERATIONS = 4;
+function readLogTail(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString("utf8").split("\n");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function firstTimestamp(lines) {
+    for (const line of lines) {
+        const stamp = TIMESTAMP.exec(line);
+        if (stamp)
+            return Date.parse(stamp[1]);
+    }
+    return null;
+}
+/**
+ * Lines from the active log and as many rotated generations as needed to
+ * cover the window. Throws when a present log cannot be read.
+ */
+function readWindowLines(logFile, since) {
+    const generations = [];
+    for (let n = 0; n < LOG_GENERATIONS; n += 1) {
+        const file = n === 0 ? logFile : `${logFile}.${n}`;
+        if (!fs.existsSync(file))
+            break;
+        const lines = readLogTail(file);
+        generations.unshift(lines);
+        const first = firstTimestamp(lines);
+        if (first !== null && first <= since)
+            break;
+    }
+    return generations.length > 0 ? generations.flat() : null;
+}
+function readConflictCount(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        const count = value?.conflictCount;
+        return typeof count === "number" && Number.isFinite(count) ? count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Read the machine's sync logs and client health file. */
+export function defaultSyncRuntimeResults(now, hqHome = path.join(os.homedir(), ".hq")) {
+    const options = {
+        now: now.getTime(),
+        conflictCount: readConflictCount(path.join(hqHome, "client-health.json")),
+    };
+    const logFile = path.join(hqHome, "logs", "hq-sync.log");
+    let lines;
+    try {
+        lines = readWindowLines(logFile, options.now - SYNC_RUNTIME_WINDOW_MS);
+    }
+    catch {
+        return [
+            { status: "UNKNOWN", checkId: "sync.runtime.log", message: "The sync runner log could not be read." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    if (lines === null) {
+        return [
+            { status: "NA", checkId: "sync.runtime.log", message: "No sync runner log on this machine." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    return analyzeSyncRuntimeLog(lines, options);
+}
+//# sourceMappingURL=sync-runtime.js.map

package/dist/lib/doctor/client-health-sentry.d.ts

@@ -5,7 +5,7 @@ export declare const CLIENT_HEALTH_INSTALL_ID_FILENAME = "install-id";
 export declare const CLIENT_HEALTH_LAST_RESULT_FILENAME = "last-result.json";
 export type ClientHealthFixOutcome = "not_auto_fixable" | "fix_failed" | "fix_timed_out";
 export type ClientHealthStatus = "FAIL" | "WARN";
-export type ClientHealthCheckClass = "sync.update.core" | "sync.journal.personal" | "sync.journal.personal_vault" | "sync.journal.company" | "sync.manifest.personal" | "sync.manifest.personal_vault" | "sync.manifest.company" | "other";
+export type ClientHealthCheckClass = "sync.update.core" | "sync.journal.personal" | "sync.journal.personal_vault" | "sync.journal.company" | "sync.manifest.personal" | "sync.manifest.personal_vault" | "sync.manifest.company" | "sync.runtime" | "other";
 export interface ClientHealthSentryEvent {
     message: string;
     level: "warning";

package/dist/lib/doctor/client-health-sentry.js

@@ -24,6 +24,11 @@ const REASON_CODES = new Set([
     "never-uploaded",
     "invalid-upload-time",
     "unresolved-company-uid",
+    "realtime-lag-stuck",
+    "receiver-permission-denied",
+    "runner-restart-loop",
+    "device-limit-backoff",
+    "repeated-conflicts",
 ]);
 const FIX_OUTCOMES = new Set(["not_auto_fixable", "fix_failed", "fix_timed_out"]);
 const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -52,6 +57,8 @@ function cleanArchitecture(value) {
 export function normalizeClientHealthCheckId(checkId) {
     if (checkId === "sync.update.core")
         return checkId;
+    if (checkId === "sync.runtime" || checkId.startsWith("sync.runtime."))
+        return "sync.runtime";
     if (checkId === "sync.journal.__hq_personal_vault__")
         return "sync.journal.personal_vault";
     if (checkId === "sync.manifest.__hq_personal_vault__")

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

@@ -19,7 +19,7 @@ export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTE
  */
 export type DoctorStatus = (typeof DOCTOR_STATUSES)[number];
 /** Stable, privacy-safe diagnostics emitted by the sync health family. */
-export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid"];
+export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid", "realtime-lag-stuck", "receiver-permission-denied", "runner-restart-loop", "device-limit-backoff", "repeated-conflicts"];
 export type SyncReasonCode = (typeof SYNC_REASON_CODES)[number];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export declare function isDoctorStatus(value: unknown): value is DoctorStatus;

package/dist/lib/doctor/types.js

@@ -35,6 +35,11 @@ export const SYNC_REASON_CODES = [
     "never-uploaded",
     "invalid-upload-time",
     "unresolved-company-uid",
+    "realtime-lag-stuck",
+    "receiver-permission-denied",
+    "runner-restart-loop",
+    "device-limit-backoff",
+    "repeated-conflicts",
 ];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export function isDoctorStatus(value) {

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.213.0",
+  "version": "5.215.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -41,7 +41,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.74",
+    "@indigoai-us/hq-cloud": "~6.18.5",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",