@indigoai-us/hq-cli 5.345.48 → 5.345.50

package/dist/lib/daemon/flag.js

@@ -1,12 +1,13 @@
 /**
  * Feature flags read by the daemon. The daemon runs for weeks, so each read
  * asks the registry again instead of holding a per-process answer, and it
- * reads as off unless the registry itself says on (or a local override does).
+ * reads as each flag's fallback unless the registry or a local override decides it.
  */
 import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
 import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
 import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
 import { resolveProcessFlagCompanyContext } from "../flag-registry.js";
+import { HQ_ANYWHERE_RUNTIME_FLAG, hqAnywhereRuntimeLocallyDisabled } from "../anywhere-runtime-flag-key.js";
 /** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
 export const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
 /** Self-updates build the new CLI beside the running one and swap it in, so `hq` never disappears mid-update. */
@@ -14,6 +15,9 @@ export const STAGED_SELF_UPDATE_FLAG = "cli.staged-self-update";
 const READ_TIMEOUT_MS = 5_000;
 export async function readDaemonFlag(flagKey, options = {}) {
     const env = options.env ?? process.env;
+    if (flagKey === HQ_ANYWHERE_RUNTIME_FLAG && hqAnywhereRuntimeLocallyDisabled(env))
+        return false;
+    const fallback = flagKey === HQ_ANYWHERE_RUNTIME_FLAG;
     const override = readLocalOverride(flagKey, env);
     const localOverrideMode = options.localOverrideMode ?? "respect";
     if (override !== null && (localOverrideMode === "respect" || (localOverrideMode === "off-only" && !override)))
@@ -28,10 +32,10 @@ export async function readDaemonFlag(flagKey, options = {}) {
     let client;
     try {
         const company = resolveProcessFlagCompanyContext(env);
-        // Signed out reads as off without reaching the registry.
+        // Signed out reads as the flag fallback without reaching the registry.
         const token = await (options.getToken ?? (() => ensureCognitoIdToken({ interactive: false })))();
         if (typeof token !== "string" || token.trim() === "")
-            return false;
+            return fallback;
         client = (options.createClient ?? createFlagClient)({
             endpoint: resolveFlagRegistryEndpoint(undefined, env),
             getToken: () => token,
@@ -42,20 +46,27 @@ export async function readDaemonFlag(flagKey, options = {}) {
             ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
             onError,
         });
-        await client.ready();
-        const resolution = client.explain(flagKey, { fallback: false });
-        if (failed && options.throwOnError) {
+        try {
+            await client.ready();
+        }
+        catch (error) {
+            onError(error);
+        }
+        const resolution = client.explain(flagKey, { fallback });
+        if (failed && options.throwOnError && !fallback) {
             throw new Error("hq-flags registry read failed", { cause: reportedError });
         }
-        return !failed && resolution.source === "snapshot" && resolution.value === true;
+        if (resolution.source === "snapshot")
+            return resolution.value === true;
+        return fallback && resolution.value === true;
     }
     catch (error) {
         if (!failed)
             onError(error);
-        if (options.throwOnError && failed) {
+        if (options.throwOnError && failed && !fallback) {
             throw new Error("hq-flags registry read failed", { cause: reportedError ?? error });
         }
-        return false;
+        return fallback;
     }
     finally {
         try {

package/dist/lib/daemon/hq-cloud.d.ts

@@ -14,8 +14,6 @@ export interface HqCloudCopy {
 }
 export interface PickedHqCloud extends HqCloudCopy {
     source: "bundled" | "managed";
-    /** Set when a version is pinned but that version is not the installed managed copy. */
-    pinnedVersionMissing?: string;
 }
 export type ManagedHqCloud = PickedHqCloud & {
     source: "managed";
@@ -85,6 +83,8 @@ export interface UpdateHqCloudDeps {
     run?: (file: string, args: string[], shell: boolean, env: NodeJS.ProcessEnv) => NpmRunResult;
     bundled?: HqCloudCopy | null;
     platform?: NodeJS.Platform;
+    /** Test seam for bounded install retry delays. */
+    sleep?: (ms: number) => void;
 }
 /** Install or update the updater's copy, as this (the login) user. */
 export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv, deps?: UpdateHqCloudDeps): HqCloudUpdateOutcome;

package/dist/lib/daemon/hq-cloud.js

@@ -54,10 +54,11 @@ export function pickHqCloud(bundled, managed, usable = () => true, pinnedVersion
         if (managed && managed.version === pinnedVersion && b && m && m[0] === b[0] && usable(managed)) {
             return { ...managed, source: "managed" };
         }
-        // The pinned version is not installed yet (the updater installs it). Keep
-        // running the newest usable copy meanwhile instead of dropping to an older
-        // bundled one, and report the missing pin.
-        return { ...pickNewest(bundled, managed, b, m, usable), pinnedVersionMissing: pinnedVersion };
+        if (bundled.version === pinnedVersion && b && usable(bundled))
+            return { ...bundled, source: "bundled" };
+        // A pin is an exact version contract. Do not silently run another installed
+        // package while npm has not yet delivered the pinned version.
+        return null;
     }
     return pickNewest(bundled, managed, b, m, usable);
 }
@@ -160,6 +161,17 @@ export function currentHqCloudAfterLeaseRelease(daemonRoot, expectedVersion) {
         return null;
     return { ...managed, source: "managed" };
 }
+function isTransientNpmFailure(result) {
+    // spawnSync's ETIMEDOUT means this attempt hit our full 10-minute process
+    // timeout. Retrying that result would multiply one stall across every attempt.
+    if (result.error?.code === "ETIMEDOUT")
+        return false;
+    const text = `${result.stderr ?? ""}\n${result.stdout ?? ""}\n${result.error?.message ?? ""}`;
+    return /\b(?:ETARGET|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ENETUNREACH|ENOTFOUND|ETIMEDOUT|EHOSTUNREACH|ENETWORK|ECONNABORTED)\b|\bnotarget\b|network timeout|fetch failed|socket hang up/i.test(text);
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function runNpm(file, args, shell, env) {
     return spawnSync(file, args, {
         encoding: "utf8",
@@ -180,7 +192,7 @@ export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
     const platform = deps.platform ?? process.platform;
     const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
     const bundled = deps.bundled !== undefined ? deps.bundled : bundledHqCloud();
-    const from = currentHqCloud(daemonRoot)?.version ?? null;
+    const from = managedHqCloud(daemonRoot)?.version ?? bundled?.version ?? null;
     if (!bundled)
         return { ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" };
     const prefix = managedHqCloudDir(daemonRoot);
@@ -203,9 +215,26 @@ export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
         version = latest;
     }
     const cmd = hqCloudInstallCommand(prefix, version, platform);
-    const r = run(cmd.file, cmd.args, cmd.shell, env);
-    if (r.status !== 0)
-        return { ok: false, from, to: null, detail: npmFailure(r) };
-    return { ok: true, from, to: currentHqCloud(daemonRoot)?.version ?? null };
+    const retryDelays = [500, 1_000, 2_000];
+    const sleep = deps.sleep ?? sleepSync;
+    let r;
+    for (let attempt = 0;; attempt++) {
+        r = run(cmd.file, cmd.args, cmd.shell, env);
+        if (r.status === 0)
+            break;
+        const retryable = pinnedVersion !== undefined && pinnedVersion !== null && isTransientNpmFailure(r);
+        const delay = retryDelays[attempt];
+        if (!retryable || delay === undefined) {
+            const retries = retryable ? attempt : 0;
+            return {
+                ok: false,
+                from,
+                to: null,
+                detail: retries > 0 ? `pinned hq-cloud install failed after ${retries + 1} attempts: ${npmFailure(r)}` : npmFailure(r),
+            };
+        }
+        sleep(delay);
+    }
+    return { ok: true, from, to: managedHqCloud(daemonRoot)?.version ?? null };
 }
 //# sourceMappingURL=hq-cloud.js.map

package/dist/lib/daemon/run.js

@@ -105,17 +105,26 @@ const HANDOFF_FLAG_TIMEOUT_MS = 10_000;
 const HQD_PERSON_SETTING_GRACE_MS = 30 * 60_000;
 export function syncRunnerSourceForPlan(stagedRunnerPath, hqCloud, legacyBundledRunnerPath = null, staged = { version: null }, currentSyncRunnerSource = null) {
     // A managed copy lives in the daemon directory, so it survives a CLI
-    // replacement. Before lease release pickHqCloud returns it only when it is
-    // pinned or newer than the bundled copy; after release it is the only
-    // eligible package, so it must not displace a newer staged bundle unless it
-    // is the pinned version. The staged bundle is built from the bundled copy and
-    // otherwise only stands in for that copy (hq-cli#1547).
+    // replacement. A configured pin is an exact version contract: only that
+    // installed package or an exactly matching staged bundle may start.
     const pin = staged.pinnedVersion;
-    const hasRunnerAtOrAbovePin = pin != null &&
-        ((staged.version !== null && !hqCloudVersionOlder(staged.version, pin)) ||
-            (hqCloud !== null && !hqCloudVersionOlder(hqCloud.version, pin)));
-    if (pin && !hasRunnerAtOrAbovePin && currentSyncRunnerSource?.runnerPath) {
-        return currentSyncRunnerSource;
+    if (pin) {
+        if (hqCloud?.version === pin) {
+            if (hqCloud.source === "managed") {
+                return { kind: "managed-full-package", runnerPath: path.join(hqCloud.root, "dist", "bin", "sync-runner.js") };
+            }
+            if (stagedRunnerPath && staged.version === pin)
+                return { kind: "staged-sync", runnerPath: stagedRunnerPath };
+            return { kind: "bundled-full-package", runnerPath: path.join(hqCloud.root, "dist", "bin", "sync-runner.js") };
+        }
+        if (stagedRunnerPath && staged.version === pin)
+            return { kind: "staged-sync", runnerPath: stagedRunnerPath };
+        // A transient install gap must not stop a runner that is already serving
+        // sync. On cold start there is no current source, so mismatched bundles
+        // remain unavailable and cannot be started.
+        if (currentSyncRunnerSource?.runnerPath)
+            return currentSyncRunnerSource;
+        return { kind: "unavailable", runnerPath: null };
     }
     const managedYieldsToStaged = stagedRunnerPath !== null &&
         hqCloud?.source === "managed" &&
@@ -408,6 +417,7 @@ export async function runDaemon(opts) {
     let legacySyncRunnerPathChecked = false;
     let legacySyncRunnerPath = null;
     let lastPlannedSyncRunnerSource = null;
+    let lastPlannedSyncRunnerVersion = null;
     let packageUseLeaseReleased = false;
     let hqCloudVersionBeforeRelease = null;
     let startupPlanOpen = true;
@@ -580,6 +590,7 @@ export async function runDaemon(opts) {
     let warnedMissingPin = null;
     let warnedMissingSyncRunner = false;
     const daemonSyncRunnerPids = new Set();
+    let supervisor = null;
     const plan = () => {
         const config = readDaemonConfig(paths.configPath);
         const legacy = legacyUnits();
@@ -594,19 +605,34 @@ export async function runDaemon(opts) {
             : currentHqCloud(paths.root);
         if (!packageUseLeaseReleased)
             hqCloudVersionBeforeRelease = hqCloud?.version ?? staged?.metadata.version ?? null;
-        const missingPin = hqCloud?.pinnedVersionMissing ?? null;
-        if (missingPin !== warnedMissingPin) {
-            warnedMissingPin = missingPin;
-            if (missingPin && hqCloud) {
-                log("warn", `hq-cloud is pinned to ${missingPin}, which is not installed; running ${hqCloud.version} (${hqCloud.source}) until the updater installs it`);
-            }
-        }
         if (!packageUseLeaseReleased && !legacySyncRunnerPathChecked) {
             legacySyncRunnerPath = resolveSyncRunnerPath();
             legacySyncRunnerPathChecked = true;
         }
-        const syncSource = syncRunnerSourceForPlan(staged?.runnerPath ?? null, hqCloud, packageUseLeaseReleased ? null : legacySyncRunnerPath, { version: staged?.metadata.version ?? null, pinnedVersion: config.hqCloudVersion ?? null }, lastPlannedSyncRunnerSource);
+        const syncSource = syncRunnerSourceForPlan(staged?.runnerPath ?? null, hqCloud, packageUseLeaseReleased ? null : legacySyncRunnerPath, { version: staged?.metadata.version ?? null, pinnedVersion: config.hqCloudVersion ?? null }, supervisor?.state().units.some((unit) => unit.id === "sync" && unit.status === "running" && typeof unit.pid === "number")
+            ? lastPlannedSyncRunnerSource
+            : null);
+        const retainedLiveSource = syncSource === lastPlannedSyncRunnerSource;
+        const syncRunnerVersion = retainedLiveSource
+            ? lastPlannedSyncRunnerVersion
+            : syncSource.kind === "staged-sync"
+                ? staged?.metadata.version ?? null
+                : hqCloud?.version ?? null;
+        const missingPin = config.hqCloudVersion && syncRunnerVersion !== config.hqCloudVersion ? config.hqCloudVersion : null;
+        const pinWarningKey = missingPin
+            ? `${missingPin}:${retainedLiveSource ? syncRunnerVersion ?? "unknown" : "unavailable"}`
+            : null;
+        if (pinWarningKey !== warnedMissingPin) {
+            warnedMissingPin = pinWarningKey;
+            if (missingPin && retainedLiveSource) {
+                log("warn", `hq-cloud is pinned to ${missingPin}, but the running sync runner is ${syncRunnerVersion ?? "unknown"}; keeping it running while the updater retries`);
+            }
+            else if (missingPin && syncSource.kind === "unavailable") {
+                log("warn", `hq-cloud is pinned to ${missingPin}, which is not installed; sync is unavailable until the updater installs it`);
+            }
+        }
         lastPlannedSyncRunnerSource = syncSource.runnerPath ? syncSource : null;
+        lastPlannedSyncRunnerVersion = syncSource.runnerPath ? syncRunnerVersion : null;
         if (!syncSource.runnerPath && !warnedMissingSyncRunner) {
             warnedMissingSyncRunner = true;
             log("warn", "the hq-cloud sync runner was not found in this CLI install; sync is unavailable");
@@ -797,7 +823,7 @@ export async function runDaemon(opts) {
     // Set once the shutdown path exists below; a restart request before then is dropped.
     let restartDaemon = () => false;
     let extendSyncShutdownCap;
-    const supervisor = createSupervisor({
+    supervisor = createSupervisor({
         machineType,
         host: opts.host,
         pid: process.pid,

package/dist/lib/daemon/server.d.ts

@@ -39,7 +39,7 @@ export interface HqdServerOptions {
     env?: NodeJS.ProcessEnv;
     /** Work-mesh root override for mesh.presence (tests). */
     workMeshRoot?: string;
-    /** Test seam for the hq-anywhere-runtime default-off gate. */
+    /** Test seam for the hq-anywhere-runtime fail-safe gate. */
     mcpEnabled?: () => boolean | Promise<boolean>;
     /** Test seam for the live hq-flags read used by the daemon's bounded runtime monitor. */
     runtimeFlagReader?: (options: ReadDaemonFlagOptions) => Promise<boolean>;

package/dist/lib/db/app-ref.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve the `--app` value of the `hq db` commands to an app id. The value can
+ * be the app id, its name or its subdomain. Only apps in the given company are
+ * searched, so a name never resolves to another company's app.
+ */
+import { deployApiRequest } from "../deploy-api.js";
+export interface AppRefRow {
+    id?: unknown;
+    name?: unknown;
+    subdomain?: unknown;
+}
+export declare class AppRefError extends Error {
+    constructor(message: string);
+}
+export declare function matchAppRef(apps: AppRefRow[], ref: string): string;
+export declare function resolveAppRef(input: {
+    token: string;
+    companySlug: string;
+    ref: string;
+}, request?: typeof deployApiRequest): Promise<string>;
+//# sourceMappingURL=app-ref.d.ts.map

package/dist/lib/db/app-ref.js

@@ -0,0 +1,45 @@
+/**
+ * Resolve the `--app` value of the `hq db` commands to an app id. The value can
+ * be the app id, its name or its subdomain. Only apps in the given company are
+ * searched, so a name never resolves to another company's app.
+ */
+import { deployApiRequest } from "../deploy-api.js";
+import { listDeployApps } from "../deploy-apps.js";
+export class AppRefError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppRefError";
+    }
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function matchAppRef(apps, ref) {
+    const ids = (rows) => [
+        ...new Set(rows.map((row) => row.id).filter((id) => typeof id === "string")),
+    ];
+    const byId = ids(apps.filter((row) => row.id === ref));
+    if (byId.length === 1)
+        return byId[0];
+    const byName = ids(apps.filter((row) => row.name === ref || row.subdomain === ref));
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new AppRefError(`More than one app in this company is called "${ref}" (${byName.join(", ")}). Use the app id.`);
+    }
+    throw new AppRefError(`No app called "${ref}" was found in this company.`);
+}
+export async function resolveAppRef(input, request = deployApiRequest) {
+    const ref = input.ref.trim();
+    if (UUID_RE.test(ref))
+        return ref;
+    const headers = { "X-Org-Slug": input.companySlug };
+    const apps = await listDeployApps(async (cursor) => {
+        const route = cursor ? `/api/apps?cursor=${encodeURIComponent(cursor)}` : "/api/apps";
+        const res = await request(input.token, route, "GET", undefined, headers);
+        if (!res.ok) {
+            throw new AppRefError(`Could not look up the app "${ref}" (hq-deploy returned ${res.status}). Use the app id.`);
+        }
+        return (await res.json());
+    });
+    return matchAppRef(apps, ref);
+}
+//# sourceMappingURL=app-ref.js.map

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

@@ -1,4 +1,4 @@
-type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "stranded" | "keep_alive_off" | "waiting";
+type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "stranded" | "keep_alive_off" | "finished_story" | "idle_no_queued_work" | "waiting";
 interface KeepAliveAuditRestart {
     at: string | null;
     trigger: string;
@@ -17,6 +17,7 @@ interface KeepAliveAuditRow {
     blocked_outcome?: "woken" | "skipped";
     blocked_outcome_reason?: string;
     verdict: KeepAliveAuditVerdict;
+    queued_work_at_audit_time?: boolean;
     remediation?: string;
     terminal_reason?: string;
 }
@@ -25,6 +26,8 @@ interface KeepAliveAuditSummary {
     not_restarted: number;
     stranded: number;
     restarted_untimed: number;
+    finished_story: number;
+    idle_no_queued_work: number;
     late_restarts_after_window: number;
     late_over_10m: number;
     early_wake_by_others: number;
@@ -53,6 +56,7 @@ export interface StopEnvelope {
     name: string;
     mtimeMs: number;
     decision: "done" | "blocked";
+    storyComplete: boolean;
     nextCheckAt?: string;
 }
 export declare function readStopEnvelopes(hqRoot: string, laneId: string): {

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS, doneKeepAliveVerdict, hasPendingKeepAliveWork, undeliveredAnsweredQuestions } from "./keep-alive.js";
+import { dropboxDir, dropboxInboxPath } from "./dropbox.js";
 import { LanesError } from "./errors.js";
 import { laneRunDir } from "./spawn.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
@@ -63,6 +64,8 @@ const VERDICTS = [
     "keep_alive_off",
     "not_restarted",
     "stranded",
+    "finished_story",
+    "idle_no_queued_work",
     "waiting",
 ];
 function parseTime(value) {
@@ -174,7 +177,7 @@ export function readStopEnvelopes(hqRoot, laneId) {
         if (!isRecord(raw) || raw.schema_version !== "hq-lane-envelope.v1") {
             throw new LanesError("keep_alive_audit_envelope_invalid", `Lane envelope is not hq-lane-envelope.v1: ${file}`, { lane_id: laneId, path: file });
         }
-        const doneStop = raw.decision === "done" && raw.story_complete === false;
+        const doneStop = raw.decision === "done";
         const blockedStop = raw.decision === "blocked" && typeof raw.next_check_at === "string" &&
             isIsoDateTime(raw.next_check_at) && Date.parse(raw.next_check_at) > stat.mtimeMs;
         if (!doneStop && !blockedStop)
@@ -183,6 +186,7 @@ export function readStopEnvelopes(hqRoot, laneId) {
             name,
             mtimeMs: stat.mtimeMs,
             decision: blockedStop ? "blocked" : "done",
+            storyComplete: raw.story_complete === true,
             ...(typeof raw.next_check_at === "string" ? { nextCheckAt: raw.next_check_at } : {}),
         });
     }
@@ -428,6 +432,48 @@ function firstRestartAfter(lane, stop, nextEnvelopeMs, workerResumeEvents) {
     // untimed instead of using the lane's mutable current state as a proxy.
     return nextEnvelopeMs === undefined ? null : { at: null, trigger: "unknown", caller: null };
 }
+/**
+ * When the work a finished standing lane is now waiting on first appeared.
+ * The earliest signal wins: if work was queued at 10:05 and more arrived at
+ * 11:59, keep-alive has owed a launch since 10:05. Returns undefined when no
+ * signal carries a time, which leaves the caller unable to open a window.
+ */
+function keepAliveQueuedWorkAt(hqRoot, lane) {
+    const candidates = [];
+    const pendingAt = parseTime(lane.pending_resume?.at);
+    if (pendingAt !== undefined)
+        candidates.push(pendingAt);
+    for (const candidate of [dropboxInboxPath(hqRoot, lane.lane_id), dropboxDir(hqRoot, lane.lane_id)]) {
+        try {
+            candidates.push(fs.statSync(candidate).mtimeMs);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    const questions = [];
+    for (const questionId of listQuestionIds(hqRoot)) {
+        try {
+            const question = tryReadQuestion(hqRoot, questionId);
+            if (question)
+                questions.push(question);
+        }
+        catch {
+            // One unreadable question file must not fail the whole audit.
+            continue;
+        }
+    }
+    for (const question of undeliveredAnsweredQuestions(lane, questions)) {
+        const answeredAt = parseTime(question.answer?.answered_at);
+        if (answeredAt !== undefined)
+            candidates.push(answeredAt);
+    }
+    if (candidates.length === 0)
+        return undefined;
+    return Math.min(...candidates);
+}
 function classifyVerdict(input) {
     const { dueAt, restart, lane, nowMs } = input;
     if (restart?.trigger === "unknown" && laneWasKeepAliveOffAtStop(lane, input.stoppedAt))
@@ -478,6 +524,34 @@ function classifyVerdict(input) {
     }
     if (laneWasKeepAliveOffAtStop(lane, input.stoppedAt))
         return "keep_alive_off";
+    // Split the unrestarted stops by whether keep-alive owes this lane a wake at
+    // all. The discriminator is the shared done-state policy, not whether the
+    // envelope declared a next_check_at: a stop with story_complete false is owed
+    // a wake with or without one. Only done stops with no later envelope reach
+    // this branch, because a later envelope means the lane carried on.
+    if (input.decision === "done" && input.nextEnvelopeAt === undefined) {
+        const eligibility = doneKeepAliveVerdict(lane, {
+            decision: "done",
+            story_complete: input.storyComplete,
+            ...(input.nextCheckAt === undefined ? {} : { next_check_at: input.nextCheckAt }),
+        }, input.hasQueuedWork, { nowMs });
+        // Keep-alive is specified not to wake either case, so neither is a
+        // keep-alive liveness failure and neither counts against the KPI.
+        if (eligibility === "story_complete")
+            return "finished_story";
+        if (eligibility === "standing_idle")
+            return "idle_no_queued_work";
+        // A finished story becomes eligible again only once work is queued, which
+        // can be long after the stop. Open the failure window when that work
+        // appeared, not at the stop's own due time, or every normal exit from
+        // idle_no_queued_work reads as a liveness failure the moment it happens.
+        if (input.storyComplete) {
+            if (input.queuedWorkAt === undefined)
+                return "waiting";
+            const anchor = Math.max(dueAt, input.queuedWorkAt);
+            return nowMs > anchor + KEEP_ALIVE_NOT_RESTARTED_GRACE_MS ? "not_restarted" : "waiting";
+        }
+    }
     if (nowMs > dueAt + KEEP_ALIVE_NOT_RESTARTED_GRACE_MS)
         return "not_restarted";
     return "waiting";
@@ -546,6 +620,10 @@ export function buildKeepAliveAudit(input) {
         try {
             const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
             const keepAliveResumeEvents = readKeepAliveResumeEvents(input.hqRoot, lane.lane_id);
+            // Read at audit time, not stop time: for a stop with no restart the
+            // question is whether anything is going to resume the lane now.
+            const hasQueuedWork = lane.keep_alive_standing === true && hasPendingKeepAliveWork(input.hqRoot, lane);
+            const queuedWorkAt = hasQueuedWork ? keepAliveQueuedWorkAt(input.hqRoot, lane) : undefined;
             const laneWorkerResumeEvents = readLaneWorkerResumeEvents(input.hqRoot, lane.lane_id);
             const terminalClassifications = readTerminalClassifications(input.hqRoot, lane.lane_id);
             for (const stop of stops) {
@@ -572,7 +650,8 @@ export function buildKeepAliveAudit(input) {
                         blocked_outcome: blockedOutcome.status,
                         ...(blockedOutcome.reason === undefined ? {} : { blocked_outcome_reason: blockedOutcome.reason }),
                     } : {}),
-                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, ...(nextEnvelopeMs === undefined ? {} : { nextEnvelopeAt: nextEnvelopeMs }), hqRoot: input.hqRoot }),
+                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, decision: stop.decision, storyComplete: stop.storyComplete, hasQueuedWork, ...(queuedWorkAt === undefined ? {} : { queuedWorkAt }), lane, nowMs, resumeEvents: keepAliveResumeEvents, ...(nextEnvelopeMs === undefined ? {} : { nextEnvelopeAt: nextEnvelopeMs }), hqRoot: input.hqRoot }),
+                    ...(stop.decision === "done" ? { queued_work_at_audit_time: hasQueuedWork } : {}),
                 });
             }
         }
@@ -611,6 +690,8 @@ export function buildKeepAliveAudit(input) {
             not_restarted: byVerdict.not_restarted,
             stranded: byVerdict.stranded,
             restarted_untimed: byVerdict.restarted_untimed,
+            finished_story: byVerdict.finished_story,
+            idle_no_queued_work: byVerdict.idle_no_queued_work,
             late_restarts_after_window: lateRestartsAfterWindow,
             late_over_10m: lateOverTenMinutes,
             early_wake_by_others: byVerdict.early_wake,
@@ -642,6 +723,7 @@ export function formatKeepAliveAuditText(result) {
         "",
         `Since ${result.since}; ${counts}`,
         `not_restarted=${result.summary.not_restarted}, stranded=${result.summary.stranded}, late_restarts_after_window=${result.summary.late_restarts_after_window}, late_over_10m=${result.summary.late_over_10m}, early_wake_by_others=${result.summary.early_wake_by_others}, self_wake=${result.summary.self_wake}`,
+        `finished_story=${result.summary.finished_story}, idle_no_queued_work=${result.summary.idle_no_queued_work} (neither counts against the keep-alive KPI)`,
         `Stopped and not restarted on their own: ${result.summary.stopped_and_not_restarted_on_their_own}`,
         ...result.rows.filter((row) => row.remediation).map((row) => `Stranded ${row.lane}: ${row.remediation}`),
         ...result.companyless_lead_lanes.map((lane) => `Company-less lead ${lane.lane} (${lane.project}): ${lane.reason}; repair with hq lanes repair-company ${lane.lane} --company <slug>`),

package/dist/lib/lanes/reconcile.js

@@ -22,7 +22,7 @@ import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDa
 import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, nextEnvelopePath, readPidRecord, readProcStarttime, readSpawnManifest, markSpawnFailure, stopLaneProcesses, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, listQuestionIds, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyObservation, recordCpuBusyObservation, throttleStatePath, writeThrottleState, } from "./throttle.js";
-import { readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "./registry-flag.js";
+import { readLanesRegistryFlag, readLanesRegistryFlagFailOff, readLanesRegistryFlagFailOpen } from "./registry-flag.js";
 import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, LANE_LEAD_ADMISSION_PRIORITY_FLAG, LANE_QUOTA_ACCOUNT_FAILOVER_FLAG, } from "./flag-keys.js";
 import { checkLaneDiskSpace, configuredCodexRolloutHomes, laneDiskAccount, retainCodexRollouts } from "./disk-guard.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
@@ -1216,6 +1216,7 @@ export async function runPassBody(hqRoot, deps) {
         }
     }
     const readRegistryFlag = deps.readRegistryFlag ?? readLanesRegistryFlag;
+    const readRegistryFlagFailOpen = deps.readRegistryFlag ?? readLanesRegistryFlagFailOpen;
     const storyCloseCompanies = new Map();
     for (const lane of lanes) {
         if (lane.depth < 1 || lane.state !== "interrupted" || lane.keep_alive === true ||
@@ -1303,10 +1304,10 @@ export async function runPassBody(hqRoot, deps) {
             readRegistryFlag(LEAD_LANE_KEEP_ALIVE_FLAG, options),
             readRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, options),
             hasBlockedKeepAliveLane
-                ? readRegistryFlag(LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, options)
+                ? readRegistryFlagFailOpen(LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, options)
                 : Promise.resolve(false),
             readRegistryFlag(LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, options),
-            readRegistryFlag(LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, options),
+            readRegistryFlagFailOpen(LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, options),
         ]);
         keepAliveFlagByCompany.set(key, keepAliveEnabled);
         blockedResumeFlagByCompany.set(key, blockedResumeEnabled);
@@ -3585,6 +3586,7 @@ async function runTerminalKeepAliveCandidatePass(hqRoot, lanes, summary, deps, n
     if (company === null)
         return summary;
     const readFlag = deps.readRegistryFlag ?? readLanesRegistryFlag;
+    const readFlagFailOpen = deps.readRegistryFlag ?? readLanesRegistryFlagFailOpen;
     const options = { company, env: deps.env ?? process.env };
     let keepAliveEnabled;
     let lineageAware;
@@ -3595,7 +3597,7 @@ async function runTerminalKeepAliveCandidatePass(hqRoot, lanes, summary, deps, n
             readFlag(LEAD_LANE_KEEP_ALIVE_FLAG, options),
             readFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, options),
             readFlag(LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, options),
-            readFlag(LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, options),
+            readFlagFailOpen(LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, options),
         ]);
     }
     catch (err) {

package/dist/lib/lanes/registry-flag.d.ts

@@ -19,12 +19,22 @@ export interface ReadLanesFlagOptions {
     reportFailure?: (error: unknown) => void;
 }
 export declare function readLanesFlagLocalOverride(flagKey: string, env?: NodeJS.ProcessEnv): boolean | null;
+export type LanesRegistryFlagResult = {
+    state: "resolved";
+    value: boolean;
+} | {
+    state: "unknown";
+};
 /**
  * Read a lanes flag once for each company identity in this CLI process. The
- * cache contains only an in-flight or settled boolean promise; it is never
+ * cache contains only an in-flight or settled decision result; it is never
  * written to disk. A local override is checked on every call and wins first.
  */
 export declare function readLanesRegistryFlag(flagKey: string, options?: ReadLanesFlagOptions): Promise<boolean>;
+/** Read a lanes flag while preserving registry failure as an explicit unknown state. */
+export declare function readLanesRegistryFlagResult(flagKey: string, options?: ReadLanesFlagOptions): Promise<LanesRegistryFlagResult>;
+/** Delivery and wake call sites opt in to availability when the registry is unreadable. */
+export declare function readLanesRegistryFlagFailOpen(flagKey: string, options?: ReadLanesFlagOptions): Promise<boolean>;
 /**
  * Flag readers normally report their own failures and return the safe default.
  * Keep enforcement callers safe if an injected or unexpected reader rejects.