@indigoai-us/hq-cli 5.342.0 → 5.342.2

package/dist/commands/secrets.js

@@ -1,16 +1,13 @@
+import { buildSecretUsage, extractApiMessage, highSecuritySandboxOnlyMessage, loadRevealedSecrets, normalizeScriptLockMode, normalizeSecretTier, parseSecretNameList, runSecretsEnvCommand, scopeOpts, secretsCredentialOptions, } from "../secrets-env-action.js";
+export { buildSecretUsage, emitEnvExportsAndExit, loadRevealedSecrets, parseSecretNameList, runSecretsEnvCommand, } from "../secrets-env-action.js";
 import chalk from "chalk";
-import { writeSync } from "node:fs";
-import * as nodePath from "node:path";
-import { cognitoCachePrincipalUid, ensureCognitoToken } from "../utils/cognito-session.js";
-import { isAuthError } from "../utils/auth-error.js";
-import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
-import { computeSha256 } from "../utils/integrity.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { removeCacheEntry, clearAllCache } from "../utils/secrets-cache.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
-import { HQ_API_KEY_PREFIX, formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
-import { CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE, isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from "../utils/secret-load-availability.js";
+import { formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 /**
  * Mirrors `RESOURCE_SURFACES` in hq-pro
@@ -45,34 +42,12 @@ async function requireCognitoTokenForSecrets(commandLabel, capability = null) {
     requireApiKeyCapability(capability, commandLabel, { routeAvailable: false });
     return ensureCognitoToken(secretsCredentialOptions());
 }
-/**
- * A browser login is safe only when a person can answer it. This mirrors the
- * repository's existing terminal convention in `canOfferTeamUpgrade`: both
- * stdin and stderr must be TTYs, and CI is always non-interactive.
- */
-function secretsCredentialOptions() {
-    return {
-        interactive: process.stdin.isTTY === true &&
-            process.stderr.isTTY === true &&
-            !process.env.CI,
-    };
-}
-function scopeOpts(opts) {
-    if (opts.personal && opts.company) {
-        console.error(chalk.red("Error: --personal cannot be combined with --company."));
-        process.exit(1);
-    }
-    return { personal: !!opts.personal, companySlug: opts.company };
-}
 function rejectIfPersonal(opts, action) {
     if (opts.personal) {
         console.error(chalk.red(`Error: ${action} is not supported with --personal.`));
         process.exit(1);
     }
 }
-function shellSingleQuote(value) {
-    return "'" + value.replace(/'/g, "'\\''") + "'";
-}
 // API Gateway v2 URL-decodes `%2F` before route matching, so a full-name
 // `encodeURIComponent` would collapse structural `/` separators into a single
 // segment the `/name/{proxy+}` route can't match.
@@ -245,17 +220,6 @@ function promptSecretInteractively() {
         process.stdin.resume();
     });
 }
-// Maximum names per batch-load request. Mirrors hq-pro's MAX_BATCH_NAMES so a
-// large --only list is chunked client-side rather than 400'd whole by the
-// server (the legacy per-key GET path had no such cap).
-const MAX_BATCH_NAMES = 100;
-const SECRET_LOAD_TIMEOUT_MS = 30_000;
-function highSecuritySandboxOnlyMessage(secretName) {
-    const sandboxExample = secretName
-        ? `hq secrets sandbox --only ${secretName} -- <command>`
-        : "hq secrets sandbox --only <secret> -- <command>";
-    return `High-security secrets can run only in the sandbox (use \`${sandboxExample}\`) or through the HQ secret proxy. Local injection and script locks (\`--script\`) are not supported.`;
-}
 function parseSecretAclPrincipal(principal) {
     const p = principal.trim();
     if (p === "@all") {
@@ -352,53 +316,6 @@ export function parseDestinationUrl(raw) {
     }
     return { ok: true, url: `https://${parsed.hostname}`, hostname: parsed.hostname };
 }
-function normalizeSecretTier(tier) {
-    return tier === "sensitive" || tier === "nuclear" ? tier : "standard";
-}
-function normalizeScriptLockMode(mode) {
-    return mode === "enforced" ? "enforced" : "off";
-}
-function normalizeCacheTtlMs(metadata) {
-    // Controlled rows must never reach the offline cache even if a mixed-version
-    // or malformed response carries a positive TTL. The server is authoritative
-    // for access, but the client still has enough policy metadata to fail safe.
-    if (metadata.tier === "sensitive" ||
-        metadata.tier === "nuclear" ||
-        metadata.scriptLock?.mode === "enforced") {
-        return 0;
-    }
-    if (metadata.cacheTtlMs === undefined) {
-        return DEFAULT_SECRETS_CACHE_TTL_MS;
-    }
-    return typeof metadata.cacheTtlMs === "number" &&
-        Number.isFinite(metadata.cacheTtlMs) &&
-        metadata.cacheTtlMs > 0
-        ? metadata.cacheTtlMs
-        : 0;
-}
-function extractApiMessage(body, fallback) {
-    const message = typeof body.message === "string" ? body.message : undefined;
-    const error = typeof body.error === "string" ? body.error : undefined;
-    return message ?? error ?? fallback;
-}
-async function buildSecretUsage(channel, scriptPath, scriptId, attestationLevel = "self-asserted-hash") {
-    if (scriptId && !scriptPath) {
-        throw new Error("--script-id requires --script");
-    }
-    if (!scriptPath) {
-        return { channel };
-    }
-    const resolvedPath = nodePath.resolve(scriptPath);
-    return {
-        channel,
-        script: {
-            scriptId: scriptId ?? resolvedPath,
-            path: resolvedPath,
-            sha256: await computeSha256(resolvedPath),
-            attestationLevel,
-        },
-    };
-}
 // Commander collector for `--only`: accumulates across REPEATED flags instead
 // of the last one silently winning, and each value may still be
 // comma-separated. So `--only A,B`, `--only A --only B`, and
@@ -407,20 +324,6 @@ export function collectSecretNames(value, previous) {
     const parsed = value.split(",").map((k) => k.trim()).filter(Boolean);
     return (previous ?? []).concat(parsed);
 }
-function parseSecretNameList(input) {
-    const keys = input ?? [];
-    if (keys.length === 0) {
-        console.error(chalk.red("Error: --only requires at least one secret name."));
-        process.exit(1);
-    }
-    for (const key of keys) {
-        if (!SECRET_NAME_PATTERN.test(key)) {
-            console.error(chalk.red(`Invalid secret name '${key}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$`));
-            process.exit(1);
-        }
-    }
-    return keys;
-}
 function mergeScopeOpts(parent, child) {
     return {
         company: child.company ?? parent.company,
@@ -520,362 +423,6 @@ function renderPolicyScripts(scripts) {
         ].join("  "));
     }
 }
-// HQ-4H — load + decrypt secrets through the BATCH-LOAD endpoint
-// (`POST /secrets/{companyUid}/load`) instead of one single-secret GET per key.
-//
-// Every single-secret GET that 404s makes vault-service emit an unattributed
-// "Secret not found" Sentry *warning* — each `response(404, …)` is captured at
-// the response boundary (hq-pro `_error-response.ts`). That capture is the
-// right signal for `hq secrets get <name>` ("a caller genuinely needed THIS
-// secret and it was missing"), but it is pure noise for a multi-key load where
-// a missing / renamed / rotated key is a per-key outcome `exec`/`env` already
-// report cleanly to the user. The batch-load endpoint returns 200 with a
-// per-name `errors[]` array and never captures — the same path `hq run` uses,
-// which is exactly why `hq run` never contributed to HQ-4H. Routing `exec` and
-// `env` through it stops those callers from emitting the warning while keeping
-// identical UX and error text.
-//
-// Every value use through exec/env/reveal is server-authorized when online,
-// including when an encrypted disk-cache entry exists. Only explicitly opted-in
-// exec/env callers may use principal-bound values during classified outages;
-// install authorization and reveal remain online-only. This means a policy,
-// ACL, tier, or script-approval change takes effect on the next online use.
-// Requests are chunked at MAX_BATCH_NAMES and throw on the FIRST unresolved key
-// with the same `Failed to fetch secret '<k>': <reason>` shape the per-key GET
-// path used — never swallows a failure.
-async function loadRevealedSecretsViaApiKey(token, keys) {
-    const resolved = new Map();
-    const requested = [...new Set(keys)];
-    const cacheScope = "__api_key__";
-    for (const name of requested) {
-        const res = await vaultApiFetch({
-            token,
-            path: "/v1/keys/secrets/fetch",
-            method: "POST",
-            body: { name },
-            signal: AbortSignal.timeout(SECRET_LOAD_TIMEOUT_MS),
-        });
-        const body = (await res.json().catch(() => ({})));
-        if (!res.ok) {
-            if (res.status === 404) {
-                throw new Error(`Failed to fetch secret '${name}': Secret not found`);
-            }
-            if (res.status === 403) {
-                const message = typeof body.error === "string"
-                    ? body.error
-                    : typeof body.message === "string"
-                        ? body.message
-                        : "No read permission";
-                if (body.highSecurity === true) {
-                    throw new Error(highSecuritySandboxOnlyMessage(name));
-                }
-                throw new Error(`Failed to fetch secret '${name}': ${message}`);
-            }
-            if (res.status === 401) {
-                throw new Error(`Failed to fetch secret '${name}': Invalid or missing API key`);
-            }
-            throw new Error(`Failed to fetch secret '${name}': ${extractApiMessage(body, res.statusText)}`);
-        }
-        const secret = typeof body.secret === "object" && body.secret !== null
-            ? body.secret
-            : null;
-        if (typeof secret?.value !== "string") {
-            throw new Error(`Failed to fetch secret '${name}': malformed fetch response`);
-        }
-        removeCacheEntry(cacheScope, name);
-        resolved.set(name, secret.value);
-    }
-    return resolved;
-}
-export async function loadRevealedSecrets(token, companyUid, keys, usage, options = {}) {
-    if (token.startsWith(HQ_API_KEY_PREFIX)) {
-        return loadRevealedSecretsViaApiKey(token, keys);
-    }
-    const resolved = new Map();
-    const requested = [...new Set(keys)];
-    const principalUid = cognitoCachePrincipalUid(token);
-    const cachedCandidates = new Set(principalUid
-        ? requested.filter((name) => hasCacheEntry(companyUid, name, principalUid))
-        : []);
-    try {
-        // The batch endpoint is the only non-capturing authorization path that also
-        // evaluates the supplied usage metadata. It covers warm and cold names in
-        // bounded requests, then a warm name may use its locally authenticated
-        // plaintext only when the returned version and current policy TTL agree.
-        for (let i = 0; i < requested.length; i += MAX_BATCH_NAMES) {
-            const chunk = requested.slice(i, i + MAX_BATCH_NAMES);
-            const chunkNames = new Set(chunk);
-            const res = await vaultApiFetch({
-                token,
-                path: `/secrets/${encodeURIComponent(companyUid)}/load`,
-                method: "POST",
-                body: usage ? { names: chunk, usage } : { names: chunk },
-                signal: AbortSignal.timeout(SECRET_LOAD_TIMEOUT_MS),
-            });
-            if (!res.ok) {
-                const body = (await res.json().catch(() => ({})));
-                const message = extractApiMessage(body, res.statusText);
-                // High-security refusal surfaced at the batch level (rather than
-                // per-name): point the caller at the sandbox/proxy and never leak
-                // plaintext. A local script attestation is not an override.
-                if (body.code === "high_security_denied" ||
-                    body.code === "high_security_sandbox_only" ||
-                    body.highSecurity === true) {
-                    throw new Error(highSecuritySandboxOnlyMessage());
-                }
-                if (isUnavailableSecretLoadHttpStatus(res.status)) {
-                    throw new SecretLoadUnavailableError(`Failed to batch-load secrets: ${message}`);
-                }
-                if (res.status >= 400 &&
-                    res.status < 500 &&
-                    typeof body.code === "string") {
-                    throw new Error(message);
-                }
-                if (res.status === 403) {
-                    throw new Error(`Failed to fetch secret '${chunk[0]}': No read permission`);
-                }
-                throw new Error(`Failed to batch-load secrets: ${message}`);
-            }
-            const data = (await res.json());
-            if (!Array.isArray(data.secrets) || !Array.isArray(data.errors)) {
-                throw new Error("Invalid secret load response from vault");
-            }
-            const errorsByName = new Map();
-            const seenNames = new Set();
-            for (const rawSecret of data.secrets) {
-                if (!rawSecret || typeof rawSecret !== "object") {
-                    throw new Error("Invalid secret load response from vault");
-                }
-                const s = rawSecret;
-                if (typeof s.name !== "string" ||
-                    !chunkNames.has(s.name) ||
-                    seenNames.has(s.name) ||
-                    (s.value != null && typeof s.value !== "string")) {
-                    throw new Error("Invalid secret load response from vault");
-                }
-                seenNames.add(s.name);
-                if (s.revokedAt != null) {
-                    errorsByName.set(s.name, {
-                        code: "revoked",
-                        message: `Secret '${s.name}' has been revoked`,
-                    });
-                    removeCacheEntry(companyUid, s.name);
-                    continue;
-                }
-                if (s.value == null) {
-                    errorsByName.set(s.name, {
-                        code: "not_returned",
-                        message: `Secret '${s.name}' has no value (reveal may not be permitted).`,
-                    });
-                    removeCacheEntry(companyUid, s.name);
-                    continue;
-                }
-                const cacheTtlMs = normalizeCacheTtlMs(s);
-                const cached = cachedCandidates.has(s.name) &&
-                    cacheTtlMs > 0 &&
-                    typeof s.version === "number" &&
-                    Number.isSafeInteger(s.version) &&
-                    s.version > 0
-                    ? readCache(companyUid, s.name, principalUid, s.version, cacheTtlMs)
-                    : null;
-                if (cached !== null) {
-                    resolved.set(s.name, cached);
-                    continue;
-                }
-                if (cacheTtlMs > 0) {
-                    if (typeof s.version === "number" &&
-                        Number.isSafeInteger(s.version) &&
-                        s.version > 0) {
-                        if (principalUid) {
-                            writeCache(companyUid, s.name, principalUid, s.value, cacheTtlMs, s.version);
-                        }
-                    }
-                    else if (principalUid) {
-                        writeCache(companyUid, s.name, principalUid, s.value, cacheTtlMs);
-                    }
-                }
-                else {
-                    removeCacheEntry(companyUid, s.name);
-                }
-                resolved.set(s.name, s.value);
-            }
-            for (const rawError of data.errors) {
-                if (!rawError || typeof rawError !== "object") {
-                    throw new Error("Invalid secret load response from vault");
-                }
-                const e = rawError;
-                if (typeof e.name !== "string" ||
-                    !chunkNames.has(e.name) ||
-                    seenNames.has(e.name) ||
-                    typeof e.code !== "string" ||
-                    (e.message !== undefined && typeof e.message !== "string")) {
-                    throw new Error("Invalid secret load response from vault");
-                }
-                seenNames.add(e.name);
-                errorsByName.set(e.name, { code: e.code, message: e.message });
-                resolved.delete(e.name);
-                removeCacheEntry(companyUid, e.name);
-            }
-            // Any requested key in this chunk the server did not return is a per-key
-            // failure — surface it with the same prefix the single-GET path used so
-            // callers (and scripts grepping stderr) see no behavior change.
-            let firstFailure = null;
-            for (const key of chunk) {
-                if (resolved.has(key))
-                    continue;
-                removeCacheEntry(companyUid, key);
-                const err = errorsByName.get(key);
-                // Every caller of loadRevealedSecrets injects or prints the plaintext
-                // locally (`secrets get --reveal`, `secrets exec`, `secrets env`). Both
-                // high-security denial shapes therefore receive the same explicit
-                // sandbox/proxy guidance, even if the caller supplied `--script`.
-                if (err?.code === "high_security_denied" ||
-                    err?.code === "high_security_sandbox_only") {
-                    firstFailure ??= new Error(highSecuritySandboxOnlyMessage(key));
-                    continue;
-                }
-                const reason = err?.code === "not_found"
-                    ? "Secret not found"
-                    : err?.code === "forbidden"
-                        ? err.message ?? "No read permission"
-                        : err?.message ?? err?.code ?? "not returned by vault";
-                firstFailure ??= new Error(`Failed to fetch secret '${key}': ${reason}`);
-            }
-            if (firstFailure) {
-                throw firstFailure;
-            }
-        }
-        return resolved;
-    }
-    catch (err) {
-        if (isSecretLoadUnavailable(err) && options.allowOfflineFallback === true) {
-            const offline = new Map();
-            for (const key of requested) {
-                const cached = cachedCandidates.has(key)
-                    ? readCache(companyUid, key, principalUid)
-                    : null;
-                if (cached === null) {
-                    // Keep the same failure behavior for a cache miss, while leaving any
-                    // still-valid entries untouched for a later retry.
-                    throw err;
-                }
-                offline.set(key, cached);
-            }
-            console.error(CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE);
-            return offline;
-        }
-        if (isSecretLoadUnavailable(err)) {
-            throw err;
-        }
-        // A transport failure, stale session, malformed response, or a later chunk
-        // failure is an explicit denial or unusable response. Evict the whole
-        // request before failing closed. Transient no-answer/5xx/429 failures above
-        // preserve entries and only use values still valid under their stored TTL.
-        for (const key of requested) {
-            removeCacheEntry(companyUid, key);
-        }
-        throw err;
-    }
-}
-/**
- * Emit `hq secrets env` output and terminate deterministically.
- *
- * The process MUST exit even when the consuming pipe has gone away. The
- * orphaned-process leak (personal/projects/hq-secrets-process-leak) was caused
- * by relying on `process.stdout.write(payload, () => process.exit(0))`: when the
- * parent shell reading `source <(hq secrets env …)` is killed on timeout, the
- * stdout pipe loses its reader, the write callback never fires, `process.exit(0)`
- * is never reached, and — because `env` forces no other exit — the process parks
- * in `epoll_pwait(-1)` forever, reparented to PID 1. Hundreds accumulated this
- * way, exhausting swap and driving load into triple digits.
- *
- * Writing synchronously to fd 1 and then exiting unconditionally removes every
- * dependency on the event loop draining and on the reader still being attached:
- * - a live reader receives the export lines (synchronous write reaches the
- *   kernel pipe buffer before we exit, so nothing is truncated);
- * - a dead reader surfaces as EPIPE, which we swallow — the secret is already
- *   resolved and there is nothing left to deliver, so a clean exit is correct;
- * - EAGAIN (stdout in non-blocking mode with a momentarily full buffer) is
- *   retried a bounded number of times. `env` payloads are a few short export
- *   lines, far under the 64 KiB pipe buffer, so this effectively never spins.
- *
- * `exit` and `write` are injectable for tests; production uses the real ones.
- */
-export function emitEnvExportsAndExit(payload, exit = process.exit, write = writeSync) {
-    const buf = Buffer.from(payload, "utf8");
-    const MAX_EAGAIN_RETRIES = 10_000;
-    let offset = 0;
-    let eagainRetries = 0;
-    while (offset < buf.length) {
-        try {
-            offset += write(1, buf, offset, buf.length - offset);
-        }
-        catch (err) {
-            const code = err.code;
-            if (code === "EAGAIN" && eagainRetries++ < MAX_EAGAIN_RETRIES)
-                continue;
-            // EPIPE (reader gone) or retries exhausted: the output cannot be
-            // delivered, but the process must never hang. Stop and exit cleanly.
-            break;
-        }
-    }
-    return exit(0);
-}
-/**
- * Shared `secrets env` action for Commander and the default-off lightweight
- * entrypoint. The fast entrypoint still runs the same credential, usage-audit,
- * server authorization, cache-fallback, redaction, and output code.
- */
-export async function runSecretsEnvCommand(opts, parentScope, options = {}) {
-    let secretLoadStarted = false;
-    try {
-        const redact = process.stdout.isTTY;
-        if (redact) {
-            console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
-        }
-        const keys = parseSecretNameList(opts.only);
-        const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
-        const companyUid = cred.kind === "api-key"
-            ? "__api_key__"
-            : await getEntityUid(cred.token, scopeOpts(parentScope), {
-                allowOfflineScopeFallback: true,
-            });
-        const usage = cred.kind === "cognito"
-            ? await buildSecretUsage("env", opts.script, opts.scriptId)
-            : undefined;
-        secretLoadStarted = true;
-        const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, usage, { allowOfflineFallback: true });
-        let payload = "";
-        for (const key of keys) {
-            const value = revealed.get(key);
-            // loadRevealedSecrets throws on any unresolved key, so a miss here is
-            // unreachable — guard rather than print an `undefined` export line.
-            if (value === undefined) {
-                throw new Error(`Failed to fetch secret '${key}': not returned by vault`);
-            }
-            const out = redact ? "[REDACTED]" : value;
-            payload += `export ${key}=${shellSingleQuote(out)}\n`;
-        }
-        // Write synchronously and exit unconditionally — never depend on the
-        // event loop draining or the stdout write callback firing. See
-        // emitEnvExportsAndExit for the full rationale (orphaned-process leak).
-        emitEnvExportsAndExit(payload);
-        return "handled";
-    }
-    catch (err) {
-        if (options.fallbackOnAuthFailure &&
-            !secretLoadStarted &&
-            (isAuthError(err) ||
-                (err instanceof Error &&
-                    (/^No valid HQ session\b/.test(err.message) ||
-                        /^HQ_API_KEY must start with /.test(err.message))))) {
-            return "fallback";
-        }
-        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-        return "handled";
-    }
-}
 export function registerSecretsCommand(program) {
     const secrets = program
         .command("secrets")

package/dist/lib/lanes/envelope-sequence.d.ts

@@ -0,0 +1,3 @@
+/** Numeric ordering for numbered lane envelope filenames, including 1000+. */
+export declare function compareEnvelopeNames(left: string, right: string): number;
+//# sourceMappingURL=envelope-sequence.d.ts.map

package/dist/lib/lanes/envelope-sequence.js

@@ -0,0 +1,13 @@
+/** Numeric ordering for numbered lane envelope filenames, including 1000+. */
+export function compareEnvelopeNames(left, right) {
+    const leftMatch = /^(\d+)\.json$/.exec(left);
+    const rightMatch = /^(\d+)\.json$/.exec(right);
+    if (leftMatch && rightMatch) {
+        const leftNumber = BigInt(leftMatch[1]);
+        const rightNumber = BigInt(rightMatch[1]);
+        if (leftNumber !== rightNumber)
+            return leftNumber < rightNumber ? -1 : 1;
+    }
+    return left.localeCompare(right);
+}
+//# sourceMappingURL=envelope-sequence.js.map

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

@@ -38,6 +38,15 @@ export interface KeepAliveAuditResult {
     errors: KeepAliveAuditError[];
     summary: KeepAliveAuditSummary;
 }
+export interface StopEnvelope {
+    name: string;
+    mtimeMs: number;
+    nextCheckAt?: string;
+}
+export declare function readStopEnvelopes(hqRoot: string, laneId: string): {
+    allMtimes: number[];
+    stops: StopEnvelope[];
+};
 export declare function buildKeepAliveAudit(input: {
     hqRoot: string;
     now: Date;

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

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS } from "./keep-alive.js";
 import { LanesError } from "./errors.js";
 import { laneRunDir } from "./spawn.js";
+import { compareEnvelopeNames } from "./envelope-sequence.js";
 import { listQuestionIds, readAllLanes, tryReadQuestion } from "./store.js";
 function readDoneClassifications(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);
@@ -77,7 +78,7 @@ function withinRoot(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
-function readStopEnvelopes(hqRoot, laneId) {
+export function readStopEnvelopes(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);
     const envelopeDir = path.join(laneRunDir(root, laneId), "envelopes");
     if (!withinRoot(root, envelopeDir)) {
@@ -89,7 +90,7 @@ function readStopEnvelopes(hqRoot, laneId) {
         if (!withinRoot(root, realDir)) {
             throw new LanesError("keep_alive_audit_path_invalid", `Lane envelope directory escapes the HQ root for ${laneId}`, { lane_id: laneId });
         }
-        names = fs.readdirSync(realDir).filter((name) => /^\d+\.json$/.test(name)).sort();
+        names = fs.readdirSync(realDir).filter((name) => /^\d+\.json$/.test(name)).sort(compareEnvelopeNames);
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -118,11 +119,15 @@ function readStopEnvelopes(hqRoot, laneId) {
         if (raw.decision !== "done" || raw.story_complete !== false)
             continue;
         stops.push({
+            name,
             mtimeMs: stat.mtimeMs,
             ...(typeof raw.next_check_at === "string" ? { nextCheckAt: raw.next_check_at } : {}),
         });
     }
-    return { allMtimes: allMtimes.sort((a, b) => a - b), stops: stops.sort((a, b) => a.mtimeMs - b.mtimeMs) };
+    return {
+        allMtimes: allMtimes.sort((a, b) => a - b),
+        stops: stops.sort((a, b) => a.mtimeMs - b.mtimeMs),
+    };
 }
 function readKeepAliveResumeEvents(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);

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

@@ -52,6 +52,7 @@ export interface ReconcileSummary {
     dead_host: ReconcileChange[];
     heartbeats: string[];
     skipped: ReconcileSkip[];
+    notes?: string[];
     keep_alive_blocked: Array<{
         id: string;
         reason: KeepAliveBlockedReason;