@indigoai-us/hq-cli 5.224.0 → 5.226.0

package/dist/lib/lanes/watcher-main.js

@@ -5,6 +5,9 @@
  * Usage: node watcher-main.js <lane-id>
  * Requires HQ_ROOT in the environment.
  */
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { runWatcherLoop } from "./watcher.js";
 import { LanesError } from "./errors.js";
 import { openMeshTransport } from "../mesh/client.js";
@@ -27,8 +30,21 @@ function main() {
         process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
         process.exit(1);
     }
+    const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
     void runWatcherLoop(hqRoot, laneId, {
         resolveQuestionActiveCompany,
+        recoverQueuedMessages: async () => {
+            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
+                env: process.env,
+                encoding: "utf8",
+                timeout: 120_000,
+            });
+            if (result.error)
+                throw result.error;
+            if (result.status !== 0) {
+                throw new Error(`recovery command exited ${result.status ?? result.signal ?? "without status"}: ${(result.stderr ?? "").trim()}`);
+            }
+        },
     }).catch((err) => {
         process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
         process.exit(1);

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

@@ -48,7 +48,7 @@ export declare const WATCHER_HEARTBEAT_MS: number;
  * once the file would exceed this, the oldest complete lines are dropped.
  */
 export declare const WATCHER_OUT_MAX_BYTES: number;
-export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "mesh_event", "mesh_event_failed"];
+export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "message_recovery", "message_recovery_failed", "message_undeliverable", "mesh_event", "mesh_event_failed"];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
 export { ENVELOPE_INVALID_REASON };
 export type WatcherDecisionEvent = (typeof WATCHER_DECISION_EVENTS)[number];
@@ -222,6 +222,8 @@ export interface WatcherLoopDeps {
     retrySpawnDeps?: Omit<SpawnLaneDeps, "admissionHost">;
     /** Active-company fallback when an unscoped lane asks from its envelope. */
     resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
+    /** Resume an atomically queued inbox after this watcher wins terminal CAS. */
+    recoverQueuedMessages?: (lane: LaneRecord) => Promise<void>;
 }
 /**
  * Wrap one mesh call. A failed emit is logged as `mesh_event_failed` with
@@ -231,6 +233,7 @@ export interface WatcherLoopDeps {
 export declare function emitMeshSoft(event: string, logDecision: (record: Record<string, unknown>) => void, at: string, fn: (signal: AbortSignal) => Promise<void>, timeoutMs?: number): Promise<boolean>;
 /** Question ids an ask envelope raised, as `raiseEnvelopeQuestions` mints them. */
 export declare function envelopeQuestionIds(laneId: string, envelopeRef: string, envelope: LaneEnvelope, questionIndexes?: readonly number[]): string[];
+/** Detached and synchronous classifiers share one process-identity claim. */
 export declare function runWatcherLoop(hqRoot: string, laneId: string, deps?: WatcherLoopDeps): Promise<void>;
 export type EnvelopeRepairDecision = {
     action: "spawned";

package/dist/lib/lanes/watcher.js

@@ -37,16 +37,16 @@ import { LanesError } from "./errors.js";
 import { questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, } from "./types.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
-import { readLane, retryUpdateLane } from "./store.js";
+import { readLane, retryUpdateLane, withLaneHireLocks } from "./store.js";
 import { readWorkerRunResult } from "./delivery.js";
 import { applyDefaultQuotaHold, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { PROVIDER_REJECTED_REASON, QUOTA_STATUS, isProviderLoginFailure, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
-import { readToolActivity, toolActivityPath } from "./dropbox.js";
+import { dropboxInboxHasMessages, readToolActivity, toolActivityPath } from "./dropbox.js";
 import { loadLanesConfig, providerProgressEventMinIntervalMs, providerQuotaDefaultHoldMs } from "./config.js";
 import { resolveAdmissionHost as resolveProcessAdmissionHost } from "./admission-host.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneProgressEvent, emitLaneTerminalStateEvent, laneStoryStatusSuppressionKey, progressEventDue, } from "./mesh-events.js";
 import { envelopeQuestionId } from "./questions.js";
-import { laneRunDir, missingPidProbe, probePidRecord, readPidRecord, readProcStarttime, readSpawnManifest, envelopeRepairMode, spawnEnvelopeRepair, retryLaneOnAlternateAccount, } from "./spawn.js";
+import { laneRunDir, missingPidProbe, probePidRecord, readPidRecord, readProcStarttime, readSpawnManifest, envelopeRepairMode, spawnEnvelopeRepair, writePidRecord, retryLaneOnAlternateAccount, } from "./spawn.js";
 /** Spec §5.7: no signal for 20 minutes while the process is still alive. */
 export const SILENCE_MS = 20 * 60 * 1000;
 export const WATCHER_POLL_MS = 5_000;
@@ -66,6 +66,9 @@ export const WATCHER_DECISION_EVENTS = [
     "envelope_repair",
     "classification",
     "terminal_write",
+    "message_recovery",
+    "message_recovery_failed",
+    "message_undeliverable",
     "mesh_event",
     "mesh_event_failed",
 ];
@@ -670,7 +673,56 @@ function defaultSleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+const WATCHER_LOOP_OWNER_FILE = "watcher-loop.pid";
+function claimWatcherLoop(hqRoot, laneId, deps) {
+    const runDir = laneRunDir(hqRoot, laneId);
+    const ownerPath = path.join(runDir, WATCHER_LOOP_OWNER_FILE);
+    const isAlive = deps.isAlive ?? isPidAlive;
+    const readStarttime = deps.readStarttime ?? readProcStarttime;
+    const owner = withLaneHireLocks(hqRoot, [laneId], () => {
+        fs.mkdirSync(runDir, { recursive: true });
+        const existing = readPidRecord(ownerPath);
+        if (existing !== null && probePidRecord(existing, isAlive, readStarttime).alive) {
+            return null;
+        }
+        if (existing !== null)
+            fs.unlinkSync(ownerPath);
+        writePidRecord(ownerPath, {
+            pid: process.pid,
+            starttime: readStarttime(process.pid) ?? readProcStarttime(process.pid) ?? undefined,
+        });
+        const stat = fs.statSync(ownerPath);
+        return { dev: stat.dev, ino: stat.ino };
+    });
+    if (owner === null)
+        return null;
+    return () => {
+        withLaneHireLocks(hqRoot, [laneId], () => {
+            try {
+                const current = fs.statSync(ownerPath);
+                if (current.dev === owner.dev && current.ino === owner.ino)
+                    fs.unlinkSync(ownerPath);
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        });
+    };
+}
+/** Detached and synchronous classifiers share one process-identity claim. */
 export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
+    const release = claimWatcherLoop(hqRoot, laneId, deps);
+    if (release === null)
+        return;
+    try {
+        await runWatcherLoopOwned(hqRoot, laneId, deps);
+    }
+    finally {
+        release();
+    }
+}
+async function runWatcherLoopOwned(hqRoot, laneId, deps) {
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? (() => Date.now());
     const isAlive = deps.isAlive ?? isPidAlive;
@@ -1118,6 +1170,28 @@ export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
                         await emitMeshSoft(`lane_${updated.state}`, logDecision, tick.emit.at, (signal) => emitLaneTerminalStateEvent(mesh, updated, updated.state, updated.terminal_reason ?? classification.reason, signal), meshRequestTimeoutMs);
                     }
                 }
+                if (terminalWrite.changed && deps.recoverQueuedMessages) {
+                    try {
+                        if (dropboxInboxHasMessages(hqRoot, laneId)) {
+                            await deps.recoverQueuedMessages(updated);
+                            logDecision({
+                                event: "message_recovery",
+                                at: tick.emit.at,
+                                state: updated.state,
+                            });
+                        }
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        process.stderr.write(`hq lanes watcher: queued message recovery failed for ${laneId}: ${message}\n`);
+                        logDecision({
+                            event: "message_recovery_failed",
+                            at: tick.emit.at,
+                            state: updated.state,
+                            error: message,
+                        });
+                    }
+                }
             }
         }
         lastSignalMs = tick.nextLastSignalMs;

package/dist/utils/cognito-session.d.ts

@@ -114,6 +114,8 @@ export type EnsureCognitoTokenOptions = {
      * cached. Explicit `"person"` never uses machine creds.
      */
     tokenSource?: CognitoTokenSource;
+    /** Cancels bounded, non-interactive person-session refreshes. */
+    signal?: AbortSignal;
 };
 /**
  * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
@@ -196,6 +198,12 @@ export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessE
  * the response subject differs, put the bytes back and leave them there.
  */
 export declare function refreshActivePersonTokens(cached: CognitoTokens, env?: NodeJS.ProcessEnv): Promise<CognitoTokens>;
+/**
+ * Client-health's short-lived flag read cannot use hq-cloud's unbounded refresh
+ * helper. Reuse its lockfile protocol, attach the caller signal to the refresh
+ * request, and persist only after the request has completed before the deadline.
+ */
+export declare function refreshActivePersonTokensForClientHealth(cached: CognitoTokens, signal: AbortSignal): Promise<CognitoTokens>;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
 /**

package/dist/utils/cognito-session.js

@@ -19,12 +19,13 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
@@ -519,6 +520,194 @@ export async function refreshActivePersonTokens(cached, env = process.env) {
     }
     return refreshed;
 }
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason ?? new Error("Token acquisition was aborted");
+}
+function waitForRefreshLock(signal, delayMs) {
+    return new Promise((resolve, reject) => {
+        const finish = (error) => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => finish(), delayMs);
+        const onAbort = () => finish(signal.reason ?? new Error("Token acquisition was aborted"));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Refresh-lock protocol shared with hq-cloud, with caller cancellation while
+ * waiting. The flag lookup is best-effort, so it never refreshes unlocked.
+ */
+async function withAbortablePersonRefreshLock(signal, fn) {
+    const lockFile = `${personTokenCacheFile()}.lock`;
+    const stateDir = path.dirname(lockFile);
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const candidate = `${lockFile}.candidate.${process.pid}.${randomBytes(8).toString("hex")}`;
+    fs.writeFileSync(candidate, String(process.pid), { flag: "wx", mode: 0o600 });
+    let held = false;
+    try {
+        for (;;) {
+            throwIfAborted(signal);
+            try {
+                fs.linkSync(candidate, lockFile);
+                held = true;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                let ownerPid = null;
+                try {
+                    const parsed = Number.parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+                    if (Number.isInteger(parsed) && parsed > 0)
+                        ownerPid = parsed;
+                }
+                catch {
+                    // An absent or malformed lock may be reclaimed below.
+                }
+                let ownerAlive = false;
+                if (ownerPid !== null) {
+                    try {
+                        process.kill(ownerPid, 0);
+                        ownerAlive = true;
+                    }
+                    catch (probeError) {
+                        ownerAlive = probeError.code === "EPERM";
+                    }
+                }
+                if (!ownerAlive) {
+                    try {
+                        fs.unlinkSync(lockFile);
+                    }
+                    catch {
+                        // Another contender may have reclaimed it first.
+                    }
+                    continue;
+                }
+                await waitForRefreshLock(signal, 50);
+            }
+        }
+        throwIfAborted(signal);
+        return await fn();
+    }
+    finally {
+        if (held) {
+            try {
+                const owner = Number.parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+                if (owner === process.pid)
+                    fs.unlinkSync(lockFile);
+            }
+            catch {
+                // A failed request must not mask its original error.
+            }
+        }
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch {
+            // The candidate may already have been removed.
+        }
+    }
+}
+/**
+ * Client-health's short-lived flag read cannot use hq-cloud's unbounded refresh
+ * helper. Reuse its lockfile protocol, attach the caller signal to the refresh
+ * request, and persist only after the request has completed before the deadline.
+ */
+export async function refreshActivePersonTokensForClientHealth(cached, signal) {
+    // Cognito refresh rotation is off for this client (#2603; ALLOW_REFRESH_TOKEN_AUTH stays), so aborting loses no rotated token; keep this lock protocol identical to hq-cloud withRefreshLock.
+    return withAbortablePersonRefreshLock(signal, async () => {
+        throwIfAborted(signal);
+        const onDisk = readPersonTokenFile();
+        const diskKey = cognitoSubjectKey(onDisk);
+        const cachedKey = cognitoSubjectKey(cached);
+        if (diskKey && cachedKey && diskKey !== cachedKey) {
+            throw new IdentitySwapRefusal(`refusing token refresh: cached subject ${formatCognitoSubject(cached)} ` +
+                `does not match active subject ${formatCognitoSubject(onDisk)}`);
+        }
+        const activeTokens = onDisk ?? cached;
+        if (!isExpiring(activeTokens, 120))
+            return activeTokens;
+        if (!activeTokens.refreshToken) {
+            throw new CognitoRefreshError("No refresh token is available for the cached HQ session", true);
+        }
+        const body = new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: DEFAULT_COGNITO.clientId,
+            refresh_token: activeTokens.refreshToken,
+        });
+        const endpoint = `https://${DEFAULT_COGNITO.userPoolDomain}.auth.${DEFAULT_COGNITO.region}.amazoncognito.com/oauth2/token`;
+        const fingerprint = accessTokenFingerprint(activeTokens.accessToken);
+        let response;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            throwIfAborted(signal);
+            try {
+                response = await fetch(endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: body.toString(),
+                    signal,
+                });
+            }
+            catch (err) {
+                throwIfAborted(signal);
+                if (attempt === 0)
+                    continue;
+                throw new CognitoRefreshError(`Cognito refresh request failed: ${err instanceof Error ? err.message : String(err)}`, false, undefined, fingerprint);
+            }
+            throwIfAborted(signal);
+            if (response.ok)
+                break;
+            const retryable = response.status === 401 ||
+                response.status === 408 ||
+                response.status === 429 ||
+                response.status >= 500;
+            if (retryable && attempt === 0)
+                continue;
+            const reauth = response.status === 401 ||
+                (response.status >= 400 && response.status < 500 && ![408, 429].includes(response.status));
+            throw new CognitoRefreshError(`Cognito refresh failed (${response.status})`, reauth, response.status, fingerprint);
+        }
+        if (!response?.ok) {
+            throw new CognitoRefreshError("Cognito refresh failed after retry", false, undefined, fingerprint);
+        }
+        const data = (await response.json());
+        throwIfAborted(signal);
+        if (typeof data.access_token !== "string" ||
+            typeof data.id_token !== "string" ||
+            typeof data.expires_in !== "number" ||
+            !Number.isFinite(data.expires_in) ||
+            data.expires_in <= 0) {
+            throw new CognitoRefreshError("Cognito refresh returned an invalid token response", false);
+        }
+        const refreshed = {
+            accessToken: data.access_token,
+            idToken: data.id_token,
+            refreshToken: typeof data.refresh_token === "string" && data.refresh_token.length > 0
+                ? data.refresh_token
+                : activeTokens.refreshToken,
+            expiresAt: Date.now() + data.expires_in * 1_000,
+            tokenType: "Bearer",
+        };
+        const activeKey = cognitoSubjectKey(activeTokens);
+        const nextKey = cognitoSubjectKey(refreshed);
+        if (activeKey && nextKey && nextKey !== activeKey) {
+            throw new IdentitySwapRefusal(`refusing token refresh: refreshed subject ${formatCognitoSubject(refreshed)} ` +
+                `does not match active subject ${formatCognitoSubject(activeTokens)}`);
+        }
+        throwIfAborted(signal);
+        saveCachedTokens(refreshed);
+        return refreshed;
+    });
+}
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export function actorKindFromIdToken(idToken) {
     const claims = decodeJwtPayload(idToken);
@@ -769,12 +958,16 @@ async function ensureCognitoTokenUnserialized(options) {
  * identical to `ensureCognitoToken` there.
  */
 export async function ensureCognitoIdToken(options = {}) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options))
         return ensureCognitoIdTokenUnserialized(options);
     return withTokenStateDirSection(() => ensureCognitoIdTokenUnserialized(options));
 }
 async function ensureCognitoIdTokenUnserialized(options) {
     const interactive = options.interactive ?? true;
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options)) {
         const machine = await ensureMachineTokensMaybeFallback(options);
         return machine.idToken;
@@ -788,11 +981,13 @@ async function ensureCognitoIdTokenUnserialized(options) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshActivePersonTokens(cached);
+            const refreshed = options.signal
+                ? await refreshActivePersonTokensForClientHealth(cached, options.signal)
+                : await refreshActivePersonTokens(cached);
             return refreshed.idToken;
         }
         catch (err) {
-            if (isIdentitySwapRefusal(err))
+            if (options.signal?.aborted || isIdentitySwapRefusal(err))
                 throw err;
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;

package/dist/utils/upload-author.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The identity stamped onto uploaded objects (`Metadata['created-by']`,
+ * `created-by-sub`). It must be the identity the push authenticates as: a
+ * machine push on a host that also has a person signed in is the agent, never
+ * the person. The private-folder creator backfill reads `created-by-sub`.
+ */
+import type { UploadAuthor } from "@indigoai-us/hq-cloud";
+/**
+ * Resolve the upload author from the cached id token of the session the push
+ * uses. Decoded, not verified: Cognito verified it at issuance and no auth
+ * decision rides on the label. Returns undefined when that session has no
+ * cached token or the token lacks `sub`/`email`; share() then skips the stamp.
+ */
+export declare function resolveUploadAuthor(env?: NodeJS.ProcessEnv, home?: string): UploadAuthor | undefined;
+//# sourceMappingURL=upload-author.d.ts.map

package/dist/utils/upload-author.js

@@ -0,0 +1,39 @@
+/**
+ * The identity stamped onto uploaded objects (`Metadata['created-by']`,
+ * `created-by-sub`). It must be the identity the push authenticates as: a
+ * machine push on a host that also has a person signed in is the agent, never
+ * the person. The private-folder creator backfill reads `created-by-sub`.
+ */
+import * as os from "node:os";
+import { loadMachineCachedTokens, readPersonTokenFile, wantsMachineCognitoTokens, } from "./cognito-session.js";
+function authorFromIdToken(idToken) {
+    if (!idToken)
+        return undefined;
+    const parts = idToken.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        if (claims.sub && claims.email) {
+            return { userSub: claims.sub, email: claims.email };
+        }
+        return undefined;
+    }
+    catch {
+        // Unparseable claims only mean no author label; share() skips the stamp.
+        return undefined;
+    }
+}
+/**
+ * Resolve the upload author from the cached id token of the session the push
+ * uses. Decoded, not verified: Cognito verified it at issuance and no auth
+ * decision rides on the label. Returns undefined when that session has no
+ * cached token or the token lacks `sub`/`email`; share() then skips the stamp.
+ */
+export function resolveUploadAuthor(env = process.env, home = os.homedir()) {
+    const tokens = wantsMachineCognitoTokens({}, env)
+        ? loadMachineCachedTokens(home, env)
+        : readPersonTokenFile(home, env);
+    return authorFromIdToken(tokens?.idToken);
+}
+//# sourceMappingURL=upload-author.js.map

package/package.json

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