@indigoai-us/hq-cli 5.345.177 → 5.345.179

package/dist/lib/hot-channels/sync-lock.js

@@ -0,0 +1,224 @@
+/**
+ * One hot-channel sync at a time per person per company. The bot's scheduled
+ * run and a manual `hq sources sync` can fire together; the index files are
+ * read-modify-write, so two runs at once can lose rows and process the same
+ * event twice. The lock is `sources/_runs/@{personKey}/.lock`, created with
+ * O_EXCL and holding the pid, host, start time and last heartbeat.
+ *
+ * A lock is stale when its holder on this host is no longer alive, or when its
+ * last heartbeat is older than `SYNC_LOCK_STALE_MS`. The holder heartbeats the
+ * lock while it runs, so a long signals pass is never taken over mid-write.
+ * Takeover runs under an O_EXCL `.takeover` guard: the guard holder renames the
+ * stale file to a unique name, checks it moved the file it judged stale, and
+ * every contender then competes on the O_EXCL create of a fresh lock.
+ * Release removes the file only while it still names this holder.
+ */
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { assertNotIntegrationSecretsPath, personDirName } from "./cursors.js";
+/** A lock whose last heartbeat is older than this is stale. */
+export const SYNC_LOCK_STALE_MS = 30 * 60 * 1000;
+/** How often a held lock is refreshed; well under the stale limit. */
+export const SYNC_LOCK_HEARTBEAT_MS = 60 * 1000;
+export const SYNC_LOCK_BUSY_REASON = "another sync is running";
+/**
+ * The run no longer holds its sync lock (another run took it over, for example
+ * after this machine slept past the stale limit). The run stops before its
+ * next write.
+ */
+export class SyncLockLostError extends Error {
+    constructor() {
+        super("sync lock lost to another run; stopped before the next write");
+        this.name = "SyncLockLostError";
+    }
+}
+export function syncLockPath(vaultRoot, personKey) {
+    const file = path.join(vaultRoot, "sources", "_runs", personDirName(personKey), ".lock");
+    assertNotIntegrationSecretsPath(file);
+    return file;
+}
+function serialize(body) {
+    return `${JSON.stringify(body)}\n`;
+}
+async function tryCreate(file, body) {
+    try {
+        await fs.writeFile(file, serialize(body), { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+async function readBody(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "missing";
+        return null;
+    }
+}
+/** True when `pid` names a live process on this host. EPERM means it exists. */
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+async function isStale(file, nowMs, staleMs, alive) {
+    const body = await readBody(file);
+    if (body === "missing")
+        return "missing";
+    if (body && typeof body.pid === "number" && body.host === os.hostname() && !alive(body.pid))
+        return true;
+    const stamp = body?.heartbeatAt ?? body?.startedAt;
+    let at = typeof stamp === "string" ? Date.parse(stamp) : Number.NaN;
+    if (Number.isNaN(at)) {
+        try {
+            at = (await fs.stat(file)).mtimeMs;
+        }
+        catch {
+            return "missing";
+        }
+    }
+    return nowMs - at >= staleMs;
+}
+/**
+ * Take the sync lock, or return null when a live run holds it. A stale lock is
+ * moved aside and taken over once; a race lost during takeover returns null.
+ */
+export async function acquireSyncLock(vaultRoot, personKey, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const staleMs = options.staleMs ?? SYNC_LOCK_STALE_MS;
+    const heartbeatMs = options.heartbeatMs ?? SYNC_LOCK_HEARTBEAT_MS;
+    const alive = options.pidAlive ?? pidAlive;
+    const file = syncLockPath(vaultRoot, personKey);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const startedAt = now().toISOString();
+    const body = { pid: process.pid, host: os.hostname(), startedAt, heartbeatAt: startedAt };
+    const ownsFile = async () => {
+        const current = await readBody(file);
+        return (current !== null &&
+            current !== "missing" &&
+            current.pid === body.pid &&
+            current.host === body.host &&
+            current.startedAt === body.startedAt);
+    };
+    const held = () => {
+        let released = false;
+        let timer;
+        const heartbeat = async () => {
+            if (released || !(await ownsFile()))
+                return;
+            const tmp = `${file}.${randomUUID()}.tmp`;
+            await fs.writeFile(tmp, serialize({ ...body, heartbeatAt: now().toISOString() }), "utf8");
+            await fs.rename(tmp, file);
+        };
+        if (heartbeatMs > 0) {
+            timer = setInterval(() => {
+                heartbeat().catch(() => undefined);
+            }, heartbeatMs);
+            timer.unref();
+        }
+        return {
+            file,
+            assertHeld: async () => {
+                if (released || !(await ownsFile()))
+                    throw new SyncLockLostError();
+            },
+            heartbeat,
+            release: async () => {
+                released = true;
+                if (timer)
+                    clearInterval(timer);
+                if (await ownsFile())
+                    await fs.rm(file, { force: true });
+            },
+        };
+    };
+    if (await tryCreate(file, body))
+        return held();
+    const stale = await isStale(file, now().getTime(), staleMs, alive);
+    if (stale === false)
+        return null;
+    if (stale === true && !(await takeOverStale(file, now, staleMs, alive)))
+        return null;
+    return (await tryCreate(file, body)) ? held() : null;
+}
+/** A takeover guard older than this belongs to a contender that died mid-takeover. */
+const TAKEOVER_GUARD_STALE_MS = 60 * 1000;
+/**
+ * Move a stale lock out of the way. Only the contender that O_EXCL-creates the
+ * `.takeover` guard may touch the lock file, so two contenders can never both
+ * remove it. Under the guard the lock is re-read, renamed to a unique name,
+ * and the moved file is compared with what was read: if it changed in between
+ * (its holder released and a new run took the lock), it is put back. Returns
+ * false when this contender should give up.
+ */
+async function takeOverStale(file, now, staleMs, alive) {
+    const guard = `${file}.takeover`;
+    const takeGuard = async () => {
+        try {
+            await fs.writeFile(guard, `${process.pid}\n`, { encoding: "utf8", flag: "wx" });
+            return true;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            return false;
+        }
+    };
+    if (!(await takeGuard())) {
+        let age = 0;
+        try {
+            age = now().getTime() - (await fs.stat(guard)).mtimeMs;
+        }
+        catch {
+            return false;
+        }
+        if (age < TAKEOVER_GUARD_STALE_MS)
+            return false;
+        const staleGuard = `${guard}.stale-${randomUUID()}`;
+        await fs.rename(guard, staleGuard).catch(() => undefined);
+        await fs.rm(staleGuard, { force: true });
+        if (!(await takeGuard()))
+            return false;
+    }
+    try {
+        const seen = await fs.readFile(file, "utf8").catch(() => null);
+        if (seen === null)
+            return true;
+        if ((await isStale(file, now().getTime(), staleMs, alive)) !== true)
+            return false;
+        const aside = `${file}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            await fs.rename(file, aside);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return true;
+            throw err;
+        }
+        const moved = await fs.readFile(aside, "utf8").catch(() => null);
+        if (moved !== seen) {
+            await fs.link(aside, file).catch(() => undefined);
+            await fs.rm(aside, { force: true });
+            return false;
+        }
+        await fs.rm(aside, { force: true });
+        return true;
+    }
+    finally {
+        await fs.rm(guard, { force: true });
+    }
+}
+//# sourceMappingURL=sync-lock.js.map

package/dist/lib/install/hook-target.d.ts

@@ -1,6 +1,10 @@
 import { type HookTarget } from './claude-targets.js';
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
+/**
+ * True when this user's hq daemon unit (launchd plist, systemd unit, or the
+ * per-user Windows Scheduled Task) exists. On Windows the shared task an older
+ * install registered counts only when it runs as this user.
+ */
+export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean, taskName?: () => string, legacyTaskIsMine?: () => boolean): boolean;
 /**
  * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
  * the hqd shim; otherwise to master-hook.sh / the Codex adapter.

package/dist/lib/install/hook-target.js

@@ -7,15 +7,20 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { realpathOrSelf } from '../../commands/mcp-registration.js';
-import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../daemon/install.js';
+import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, SYSTEM_UNIT_DIR, currentWindowsIdentity, legacyWindowsTask, windowsTaskName } from '../daemon/install.js';
+import { defaultRunCommand } from '../service-manager/launchd.js';
 import { readDaemonConfig } from '../daemon/config.js';
 import { daemonPaths } from '../daemon/paths.js';
 import { registrationEngine } from '../hook-engine/registration.js';
 import { shimPath } from './claude-targets.js';
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
+/**
+ * True when this user's hq daemon unit (launchd plist, systemd unit, or the
+ * per-user Windows Scheduled Task) exists. On Windows the shared task an older
+ * install registered counts only when it runs as this user.
+ */
+export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0, taskName = () => windowsTaskName(currentWindowsIdentity()), legacyTaskIsMine = () => legacyWindowsTask(defaultRunCommand, currentWindowsIdentity()).state === 'mine') {
     if (platform === 'win32')
-        return queryTask(DAEMON_WINDOWS_TASK);
+        return queryTask(taskName()) || legacyTaskIsMine();
     const candidates = platform === 'darwin'
         ? [path.join(home, 'Library', 'LaunchAgents', `${DAEMON_LAUNCHD_LABEL}.plist`)]
         : platform === 'linux'

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

@@ -222,6 +222,16 @@ export declare function inspectLoopRecovery(runDir: string): {
     kind: "pending" | "hold" | "protected" | "empty";
     reason?: string;
 };
+/**
+ * Budget for an envelope that carries an absolute deadline. The deadline is
+ * stamped when the phase is routed, so the budget is the time between enqueue
+ * and that deadline, counted from when the lane starts the envelope. Time the
+ * envelope spent waiting in the queue does not count against it. Without a
+ * usable queued_at the remaining time from start is used, as before.
+ * A deadline at or before its enqueue still gets a 1 s execution window.
+ * An unparsable deadline returns undefined so the caller uses the phase budget.
+ */
+export declare function absoluteDeadlineBudget(deadline: string, queuedAt: string | undefined, startedAtMs: number): number | undefined;
 /** Reset only after an explicit, durable disposition; this never starts work. */
 export declare function resetLoopAfterDisposition(runDir: string, laneId: string, decision: string, hasPending: boolean): void;
 /** Run queued phases serially. Sessions are isolated by story and provider. */

package/dist/lib/lanes/loop.js

@@ -985,6 +985,23 @@ function phaseDeadlineBudget(envelope, defaultSeconds) {
     const configured = Number(process.env.HQ_LANE_LOOP_PHASE_DEADLINE_SECS);
     return Number.isFinite(configured) && configured > 0 ? configured : defaultSeconds;
 }
+/**
+ * Budget for an envelope that carries an absolute deadline. The deadline is
+ * stamped when the phase is routed, so the budget is the time between enqueue
+ * and that deadline, counted from when the lane starts the envelope. Time the
+ * envelope spent waiting in the queue does not count against it. Without a
+ * usable queued_at the remaining time from start is used, as before.
+ * A deadline at or before its enqueue still gets a 1 s execution window.
+ * An unparsable deadline returns undefined so the caller uses the phase budget.
+ */
+export function absoluteDeadlineBudget(deadline, queuedAt, startedAtMs) {
+    const deadlineMs = Date.parse(deadline);
+    if (!Number.isFinite(deadlineMs))
+        return undefined;
+    const queuedMs = typeof queuedAt === "string" ? Date.parse(queuedAt) : Number.NaN;
+    const fromMs = Number.isFinite(queuedMs) && queuedMs <= startedAtMs ? queuedMs : startedAtMs;
+    return Math.max(1, Math.round((deadlineMs - fromMs) / 1000));
+}
 function persistStallCount(runDir, laneId, envelopeId, count) {
     const status = loopStatus(runDir, laneId);
     persistStatus(runDir, laneId, { stall_counts: { ...status.stall_counts, [envelopeId]: count } });
@@ -1121,7 +1138,7 @@ export async function runLoopLane(options) {
         const absoluteDeadline = envelope.deadline;
         const budget = record.deadline_budget_seconds ?? firstDeadline.get(record.envelope_id) ??
             (typeof absoluteDeadline === "string"
-                ? Math.max(1, Math.round((Date.parse(absoluteDeadline) - startedAtMs) / 1000)) // An absolute deadline already in the past still gets a 1 s execution window.
+                ? absoluteDeadlineBudget(absoluteDeadline, record.queued_at, startedAtMs) ?? phaseDeadlineBudget(envelope, defaultDeadlineSeconds)
                 : phaseDeadlineBudget(envelope, defaultDeadlineSeconds));
         firstDeadline.set(record.envelope_id, budget);
         record.deadline_budget_seconds = budget;

package/dist/lib/mesh/live/daemon/work-subscribe.d.ts

@@ -17,6 +17,7 @@ export interface WorkCacheSubscriber {
 export { AGENT_INBOX_PUSH_STATE_BASENAME, SYNC_WAKE_STATE_BASENAME } from "../paths.js";
 export type SyncWakeVaults = Record<string, {
     wakeSequence: number;
+    head?: number;
 }>;
 export declare function startWorkCacheSubscriber(opts: {
     meshRoot: string;

package/dist/lib/mesh/live/daemon/work-subscribe.js

@@ -15,6 +15,7 @@ const INBOX_PUSH_HEARTBEAT_MS = 5_000;
 const SYNC_WAKE_KEYS = new Set(["v", "type", "vault", "head", "rootId"]);
 const SYNC_WAKE_VAULT = /^(?:prs|cmp|agt)_[0-9A-Za-z]+$/;
 const SYNC_WAKE_ROOT = /^[0-9a-f]{64}$/i;
+const SYNC_WAKE_MAX_BYTES = 4_096;
 function parseSyncWakeEnvelope(payload) {
     let parsed;
     try {
@@ -38,7 +39,7 @@ function parseSyncWakeEnvelope(payload) {
         Number(message.head) > 0 &&
         (message.rootId === null ||
             (typeof message.rootId === "string" && SYNC_WAKE_ROOT.test(message.rootId)));
-    return valid ? { vault: message.vault } : null;
+    return valid ? { vault: message.vault, head: Number(message.head) } : null;
 }
 function readVaultSequences(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -47,9 +48,11 @@ function readVaultSequences(raw) {
     for (const [vault, entry] of Object.entries(raw)) {
         if (!SYNC_WAKE_VAULT.test(vault) || !entry || typeof entry !== "object")
             continue;
-        const sequence = entry.wakeSequence;
+        const { wakeSequence: sequence, head } = entry;
         if (Number.isSafeInteger(sequence) && Number(sequence) >= 0) {
-            vaults[vault] = { wakeSequence: Number(sequence) };
+            vaults[vault] = Number.isSafeInteger(head) && Number(head) >= 0
+                ? { wakeSequence: Number(sequence), head: Number(head) }
+                : { wakeSequence: Number(sequence) };
         }
     }
     return vaults;
@@ -85,6 +88,9 @@ function readWakeSequence(meshRoot, basename, label, onInfo) {
         };
     }
 }
+function withoutHeads(vaults) {
+    return Object.fromEntries(Object.entries(vaults).map(([vault, entry]) => [vault, { wakeSequence: entry.wakeSequence }]));
+}
 function writeWakeState(meshRoot, basename, state, durable) {
     fs.mkdirSync(meshRoot, { recursive: true, mode: 0o700 });
     const rootInfo = fs.lstatSync(meshRoot);
@@ -162,15 +168,27 @@ export async function startWorkCacheSubscriber(opts) {
             timers.clearTimeout(heartbeatTimer);
         heartbeatTimer = null;
     };
+    let syncWakeHeadsOmitted = false;
     const persistState = (basename, label, connected, wakeSequence, identity, durable = true, vaults) => {
         try {
-            writeWakeState(opts.meshRoot, basename, {
+            const state = {
                 connected,
                 heartbeatAtMs: now().getTime(),
                 wakeSequence,
                 ...(connected && actorUid && identity ? { [identity]: actorUid } : {}),
                 ...(vaults ? { vaults } : {}),
-            }, durable);
+            };
+            if (vaults) {
+                const oversized = Buffer.byteLength(`${JSON.stringify(state)}\n`) > SYNC_WAKE_MAX_BYTES;
+                if (oversized) {
+                    state.vaults = withoutHeads(vaults);
+                    if (!syncWakeHeadsOmitted) {
+                        opts.onInfo?.(`${label} state over ${SYNC_WAKE_MAX_BYTES} bytes; vault heads omitted`);
+                    }
+                }
+                syncWakeHeadsOmitted = oversized;
+            }
+            writeWakeState(opts.meshRoot, basename, state, durable);
         }
         catch (error) {
             const name = error instanceof Error ? error.name : "UnknownError";
@@ -318,8 +336,10 @@ export async function startWorkCacheSubscriber(opts) {
                     return;
                 }
                 syncWakeSequence += 1;
+                const previous = syncWakeVaults[envelope.vault];
                 syncWakeVaults[envelope.vault] = {
-                    wakeSequence: (syncWakeVaults[envelope.vault]?.wakeSequence ?? 0) + 1,
+                    wakeSequence: (previous?.wakeSequence ?? 0) + 1,
+                    head: Math.max(previous?.head ?? 0, envelope.head),
                 };
                 persistSyncState(true);
                 return;

package/dist/run/hq-plugin.d.ts

@@ -18,6 +18,9 @@ export interface PluginState {
     }>;
     loadedSecretsByName: Map<string, string>;
 }
+/** True when the varlock item has an `# @optional` decorator. */
+export declare function itemIsOptional(item: unknown): boolean;
+export declare function isSkippableOptionalSecretError(code: string | undefined): boolean;
 export declare function installHqPlugin(graph: any, opts: InstallHqPluginOpts): PluginState;
 export declare function prewarmHqSecrets(graph: any, opts: InstallHqPluginOpts, state: PluginState): Promise<void>;
 //# sourceMappingURL=hq-plugin.d.ts.map

package/dist/run/hq-plugin.js

@@ -16,6 +16,15 @@ function normalizeCacheTtlMs(secret) {
         ? secret.cacheTtlMs
         : 0;
 }
+const SKIPPABLE_OPTIONAL_CODES = new Set(['forbidden', 'not_found', 'not_returned']);
+/** True when the varlock item has an `# @optional` decorator. */
+export function itemIsOptional(item) {
+    const decorators = item?.effectiveDecorators;
+    return Boolean(decorators && Object.prototype.hasOwnProperty.call(decorators, 'optional'));
+}
+export function isSkippableOptionalSecretError(code) {
+    return Boolean(code && SKIPPABLE_OPTIONAL_CODES.has(code));
+}
 export function installHqPlugin(graph /* EnvGraph */, opts) {
     const pluginState = {
         schemaCompanySlug: null,
@@ -63,6 +72,10 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                 }
                 const err = pluginState.errorsByName.get(secretName);
                 if (err) {
+                    // `# @optional`: missing ACL or a missing secret leaves the var unset.
+                    if (itemIsOptional(this._ownerItem) && isSkippableOptionalSecretError(err.code)) {
+                        return undefined;
+                    }
                     if (err.code === 'forbidden') {
                         throw new ResolutionError(`No read permission for secret "${secretName}" — ask an admin to share it via \`hq secrets share ${secretName} --with <you> --permission read\``);
                     }
@@ -85,13 +98,18 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                 if (inMemory != null) {
                     return inMemory;
                 }
+                if (itemIsOptional(this._ownerItem)) {
+                    return undefined;
+                }
                 throw new ResolutionError(`Secret "${secretName}" was not returned by vault after server authorization`);
             },
         };
         // Captured during process(parent); used by resolve() to fall back to the var key.
         _ownerKey;
+        _ownerItem;
         process(parent) {
             super.process(parent);
+            this._ownerItem = parent;
             if (parent != null && typeof parent.key === 'string') {
                 this._ownerKey = parent.key;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.177",
+  "version": "5.345.179",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.177",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.177",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.177",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.177",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.177",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.177"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.179",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.179",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.179",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.179",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.179",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.179"
   }
 }