@indigoai-us/hq-cli 5.99.0 → 5.99.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.99.1] — 2026-08-12
+
 ## [5.99.0] — 2026-08-11
 
 ### Added

package/dist/commands/core-checkpoint.js

@@ -552,7 +552,7 @@ export function siblingArgs(backend, prompt) {
                 // journal helper, the queue-draining `mv` — hits an approval gate with
                 // no human attached; headless `claude -p` then denies it and the run
                 // stalls having written no report. `bypassPermissions` is the same
-                // unattended posture codex gets from `-s workspace-write` and grok from
+                // unattended posture codex gets from `-s danger-full-access` and grok from
                 // `--always-approve --sandbox workspace`. Hooks still fire natively —
                 // this only removes the interactive approval gate, not the hook chain.
                 "--permission-mode",
@@ -570,7 +570,7 @@ export function siblingArgs(backend, prompt) {
                 // scan, the journal helper — then hits an approval gate with no human
                 // attached, and grok cancels the whole run: `stopReason: cancelled,
                 // cancellationCategory: PermissionCancelled`. Unattended approval plus
-                // a sandbox is the same posture codex gets from `-s workspace-write`.
+                // a sandbox is the same posture codex gets from `-s danger-full-access`.
                 "--always-approve",
                 "--sandbox",
                 "workspace",
@@ -581,8 +581,16 @@ export function siblingArgs(backend, prompt) {
             return [
                 "exec",
                 "--skip-git-repo-check",
+                // danger-full-access, NOT workspace-write. `-s workspace-write` force-
+                // enables Codex's restrictive sandbox, which denies the temp/cache/socket
+                // writes the maintenance sibling needs on macOS (git/Xcode cache, zsh/asdf
+                // heredocs) and cannot even initialize bubblewrap on some Linux hosts
+                // (`bwrap: loopback: Failed RTM_NEWADDR`) — HQ harness finding 2.3, which
+                // wedged the sibling before it wrote any report. HQ's safety boundary is
+                // its hooks, which still fire here via --dangerously-bypass-hook-trust;
+                // the sandbox is not what guards the HQ root.
                 "-s",
-                "workspace-write",
+                "danger-full-access",
                 "--dangerously-bypass-hook-trust",
                 "-m",
                 CODEX_SIBLING_MODEL,

package/dist/commands/core.js

@@ -44,6 +44,8 @@ import { createWorktree } from "../lib/core-utils/worktree.js";
 import { runCodexSkillBridgeCommand } from "../lib/core-utils/codex-skill-bridge-entry.js";
 import { archiveOldThreads } from "../lib/core-utils/archive-old-threads.js";
 import { qmdReindexAfterSync } from "../lib/core-utils/qmd-reindex-after-sync.js";
+import { softTimeoutCommand } from "../lib/core-utils/soft-timeout.js";
+import { timeoutGuardCommand } from "../lib/core-utils/timeout-guard.js";
 /**
  * These commands are now native implementations. Their retained shell assets
  * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
@@ -421,6 +423,39 @@ export function registerCoreCommands(program) {
             runCommand(entry, args, cmd);
         });
     }
+    // `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+    // Async and bespoke (the NATIVE_UTILITY_COMMANDS table is synchronous), since
+    // it spawns a child and warns over time. Warn-don't-kill primitive for
+    // finding 2.1 — the CLI-hosted twin of core/scripts/lib/soft-timeout.sh.
+    core
+        .command("soft-timeout")
+        .description("Run a command under a soft (warn, don't kill) timeout")
+        // Passthrough: the wrapped command owns everything after `--`.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .helpOption(false)
+        .argument("[args...]", "<interval> [--hard-cap <spec>] [--label <name>] -- <cmd...>")
+        .action(async (args = [], _opts, cmd) => {
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        const code = await softTimeoutCommand(operands);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `hq core timeout-guard` — PreToolUse decision for the foreground-timeout
+    // guard (finding 2.1). Reads the hook JSON on stdin and exits 2 to block, 0
+    // to allow. The shipped .claude hook is a thin shim over this.
+    core
+        .command("timeout-guard")
+        .description("PreToolUse guard: block over-ceiling foreground timeouts (reads hook JSON on stdin)")
+        .helpOption(false)
+        .action(async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const code = timeoutGuardCommand(Buffer.concat(chunks).toString("utf8"));
+        if (code !== 0)
+            process.exit(code);
+    });
     return core;
 }
 //# sourceMappingURL=core.js.map

package/dist/lib/core-utils/soft-timeout.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+ *
+ * Run a command under a SOFT timeout: WARN, don't kill. This is the CLI-hosted
+ * form of the shell primitive `core/scripts/lib/soft-timeout.sh`, so HQ scripts
+ * and hooks can call `hq core soft-timeout …` directly instead of shelling out
+ * to a bundled script.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events):
+ * a fixed deadline SIGTERMs an operation still making progress and loses the
+ * in-flight work. The fix is warn-and-continue — on each interval the command
+ * keeps running and a SOFT-TIMEOUT notice is written to stderr so whoever is
+ * watching decides (wait / background / kill), instead of the runner deciding
+ * by killing progressing work.
+ *
+ * Contract (identical to the shell primitive):
+ *   - `<interval>` — warn every interval. Bare number = seconds; 90s / 2m / 1h.
+ *   - `--hard-cap <spec>` — OPTIONAL safety ceiling for unattended callers.
+ *     Pure soft has no cap and never terminates. At the cap the command is
+ *     SIGTERM'd, then SIGKILL'd after a short grace, and the exit code is 124.
+ *   - `--label <name>` — name shown in the notice (default: the command basename).
+ *   - Exit status: the command's own, verbatim — except 124 on a hard-cap.
+ *     A soft warning alone never changes the exit status.
+ */
+import { spawn } from "node:child_process";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export declare function parseDurationSecs(spec: string): number | null;
+export interface ParsedSoftTimeoutArgs {
+    intervalSecs: number;
+    hardCapSecs: number | null;
+    label: string | null;
+    command: string[];
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export declare function parseSoftTimeoutArgs(argv: string[]): ParsedSoftTimeoutArgs;
+export interface RunSoftTimeoutDeps {
+    spawnFn?: typeof spawn;
+    stderr?: NodeJS.WritableStream;
+    now?: () => Date;
+    /** Signal a whole process group by (leader) pid. Defaults to process.kill(-pid). */
+    killGroup?: (pid: number, sig: NodeJS.Signals) => void;
+}
+/**
+ * Execute the command under the soft timeout. Resolves to the exit code the
+ * process should exit with. Never rejects on a timeout — a warning is only a
+ * stderr line. Rejects only on spawn failure.
+ */
+export declare function runSoftTimeout(parsed: ParsedSoftTimeoutArgs, deps?: RunSoftTimeoutDeps): Promise<number>;
+/**
+ * Entry point for the `hq core soft-timeout` command. Parses argv, runs, and
+ * returns the exit code (never throws for a timeout; throws only on misuse or
+ * spawn failure, which the caller maps to a non-zero exit).
+ */
+export declare function softTimeoutCommand(argv: string[]): Promise<number>;
+//# sourceMappingURL=soft-timeout.d.ts.map

package/dist/lib/core-utils/soft-timeout.js

@@ -0,0 +1,205 @@
+/**
+ * `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+ *
+ * Run a command under a SOFT timeout: WARN, don't kill. This is the CLI-hosted
+ * form of the shell primitive `core/scripts/lib/soft-timeout.sh`, so HQ scripts
+ * and hooks can call `hq core soft-timeout …` directly instead of shelling out
+ * to a bundled script.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events):
+ * a fixed deadline SIGTERMs an operation still making progress and loses the
+ * in-flight work. The fix is warn-and-continue — on each interval the command
+ * keeps running and a SOFT-TIMEOUT notice is written to stderr so whoever is
+ * watching decides (wait / background / kill), instead of the runner deciding
+ * by killing progressing work.
+ *
+ * Contract (identical to the shell primitive):
+ *   - `<interval>` — warn every interval. Bare number = seconds; 90s / 2m / 1h.
+ *   - `--hard-cap <spec>` — OPTIONAL safety ceiling for unattended callers.
+ *     Pure soft has no cap and never terminates. At the cap the command is
+ *     SIGTERM'd, then SIGKILL'd after a short grace, and the exit code is 124.
+ *   - `--label <name>` — name shown in the notice (default: the command basename).
+ *   - Exit status: the command's own, verbatim — except 124 on a hard-cap.
+ *     A soft warning alone never changes the exit status.
+ */
+import { spawn } from "node:child_process";
+import { basename } from "node:path";
+import { constants as osConstants } from "node:os";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export function parseDurationSecs(spec) {
+    const m = /^([0-9]+)([smh]?)$/.exec(spec);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        default:
+            return null;
+    }
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export function parseSoftTimeoutArgs(argv) {
+    const args = [...argv];
+    if (args.length === 0 || args[0].startsWith("--")) {
+        throw new Error("soft-timeout: first argument must be the warn interval");
+    }
+    const intervalSecs = parseDurationSecs(args.shift());
+    if (intervalSecs === null || intervalSecs <= 0) {
+        throw new Error("soft-timeout: interval must be a positive duration (e.g. 120, 2m)");
+    }
+    let hardCapSecs = null;
+    let label = null;
+    // Consume our own options; the FIRST non-option token (or an explicit `--`)
+    // begins the wrapped command. `--` is optional because Commander strips a
+    // single leading `--` before these args reach us — so `hq core soft-timeout
+    // 30 -- sleep 60` arrives here as `30 sleep 60`, and treating the first
+    // non-option as the command start makes both forms parse identically.
+    while (args.length > 0) {
+        const tok = args[0];
+        if (tok === "--") {
+            args.shift();
+            break;
+        }
+        if (tok === "--hard-cap") {
+            args.shift();
+            const spec = args.shift();
+            const secs = spec ? parseDurationSecs(spec) : null;
+            if (secs === null || secs <= 0)
+                throw new Error(`soft-timeout: invalid --hard-cap '${spec ?? ""}'`);
+            hardCapSecs = secs;
+        }
+        else if (tok === "--label") {
+            args.shift();
+            label = args.shift() ?? null;
+            if (label === null)
+                throw new Error("soft-timeout: --label needs a value");
+        }
+        else {
+            break; // first non-option token: the wrapped command starts here
+        }
+    }
+    if (args.length === 0) {
+        throw new Error("soft-timeout: no command given (expected: soft-timeout <interval> [...] -- cmd)");
+    }
+    return { intervalSecs, hardCapSecs, label: label ?? null, command: args };
+}
+function hhmmss(now) {
+    return now.toISOString().slice(11, 19);
+}
+/**
+ * Execute the command under the soft timeout. Resolves to the exit code the
+ * process should exit with. Never rejects on a timeout — a warning is only a
+ * stderr line. Rejects only on spawn failure.
+ */
+export function runSoftTimeout(parsed, deps = {}) {
+    const spawnFn = deps.spawnFn ?? spawn;
+    const err = deps.stderr ?? process.stderr;
+    const now = deps.now ?? (() => new Date());
+    const killGroup = deps.killGroup ?? ((pid, sig) => process.kill(-pid, sig));
+    const { intervalSecs, hardCapSecs, command } = parsed;
+    const label = parsed.label ?? basename(command[0]);
+    return new Promise((resolve, reject) => {
+        // detached: the child leads its own process group so a hard cap can signal
+        // the WHOLE group (child + descendants), not just the child — otherwise an
+        // orphaned grandchild (e.g. run-project's builder) keeps running after the
+        // wrapper returns. stdio inherited so the command's stdin/stdout/stderr —
+        // including piped or interactive input — pass through unchanged.
+        const child = spawnFn(command[0], command.slice(1), { stdio: "inherit", detached: true });
+        let capped = false;
+        let ticks = 0;
+        // Signal the child's process group when we can (detached leader), else the
+        // child alone. Guarded: the group may already be gone.
+        const signalTree = (sig) => {
+            try {
+                if (typeof child.pid === "number")
+                    killGroup(child.pid, sig);
+                else
+                    child.kill(sig);
+            }
+            catch {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        const warner = setInterval(() => {
+            ticks += 1;
+            const elapsed = ticks * intervalSecs;
+            err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} still running after ${elapsed}s ` +
+                `(${ticks}× ${intervalSecs}s window) — exceeded its window; NOT killed. ` +
+                `Decide: wait / background / kill (kill ${child.pid}).\n`);
+        }, intervalSecs * 1000);
+        // The hard cap runs on its OWN timer, independent of the warning interval,
+        // so a cap shorter than (or not a multiple of) the interval still fires on
+        // time rather than at the next interval boundary.
+        let capTimer = null;
+        let killTimer = null;
+        if (hardCapSecs !== null) {
+            capTimer = setTimeout(() => {
+                capped = true;
+                err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} hit hard cap ${hardCapSecs}s — sending SIGTERM.\n`);
+                signalTree("SIGTERM");
+                killTimer = setTimeout(() => signalTree("SIGKILL"), 5000);
+            }, hardCapSecs * 1000);
+        }
+        const cleanup = () => {
+            clearInterval(warner);
+            if (capTimer)
+                clearTimeout(capTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        child.on("error", (e) => {
+            cleanup();
+            reject(e);
+        });
+        child.on("exit", (code, signal) => {
+            cleanup();
+            if (capped) {
+                resolve(124);
+            }
+            else if (code !== null) {
+                resolve(code);
+            }
+            else {
+                // Killed by a signal (external SIGINT/SIGHUP/SIGTERM/…): mirror the
+                // shell convention of 128 + signal number for whichever signal it was,
+                // so callers keep the real termination status (e.g. 130 for SIGINT).
+                const n = signal ? osConstants.signals[signal] : undefined;
+                resolve(typeof n === "number" ? 128 + n : 1);
+            }
+        });
+    });
+}
+/**
+ * Entry point for the `hq core soft-timeout` command. Parses argv, runs, and
+ * returns the exit code (never throws for a timeout; throws only on misuse or
+ * spawn failure, which the caller maps to a non-zero exit).
+ */
+export async function softTimeoutCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseSoftTimeoutArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    try {
+        return await runSoftTimeout(parsed);
+    }
+    catch (e) {
+        process.stderr.write(`soft-timeout: failed to run command: ${e.message}\n`);
+        return 127;
+    }
+}
+//# sourceMappingURL=soft-timeout.js.map

package/dist/lib/core-utils/timeout-guard.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export declare function parseInnerDeadlineSecs(command: string): number;
+export interface TimeoutGuardInput {
+    command: string;
+    toolTimeoutMs?: number;
+    runInBackground?: boolean;
+}
+export interface GuardVerdict {
+    block: boolean;
+    reason?: string;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export declare function evaluateTimeoutGuard(input: TimeoutGuardInput): GuardVerdict;
+export interface TimeoutGuardDeps {
+    /** Resolve the current HQ user email for the rollout gate. Default: cached id token. */
+    getEmail?: () => string | undefined;
+    env?: NodeJS.ProcessEnv;
+    stderr?: NodeJS.WritableStream;
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export declare function isGatedUser(email: string | undefined): boolean;
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export declare function timeoutGuardCommand(stdin: string, deps?: TimeoutGuardDeps): number;
+//# sourceMappingURL=timeout-guard.d.ts.map

package/dist/lib/core-utils/timeout-guard.js

@@ -0,0 +1,207 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../../utils/id-token.js";
+// Observed Claude Code Bash-tool bounds. The tool `timeout` (ms) raises the
+// deadline up to the max; with none declared the default applies.
+const HARNESS_DEFAULT_MS = 120_000; // 2 min
+const HARNESS_MAX_MS = 600_000; // 10 min
+const GATE_DOMAIN = "@getindigo.ai";
+function basename(token) {
+    const i = token.lastIndexOf("/");
+    return i >= 0 ? token.slice(i + 1) : token;
+}
+/** Duration spec (Ns / Nm / Nh / Nd / bare N=seconds) → seconds, or 0. */
+function durationToSecs(tok) {
+    const m = /^([0-9]+)([smhd]?)$/.exec(tok);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        case "d":
+            return n * 86400;
+        default:
+            return 0;
+    }
+}
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export function parseInnerDeadlineSecs(command) {
+    let worst = 0;
+    for (const rawSeg of command.split(/[;|&()]/)) {
+        const seg = rawSeg.trim();
+        if (!seg)
+            continue;
+        const words = seg.split(/\s+/);
+        let i = 0;
+        while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
+            i++; // skip env assigns
+        if (i >= words.length)
+            continue;
+        const cmd = basename(words[i]);
+        if (cmd !== "timeout" && cmd !== "gtimeout")
+            continue;
+        i++;
+        let dur = "";
+        while (i < words.length) {
+            const t = words[i];
+            if (t === "--foreground" || t === "--preserve-status" || t === "-v" || t === "--verbose") {
+                i++;
+                continue;
+            }
+            if (t === "-s" || t === "--signal" || t === "-k" || t === "--kill-after") {
+                i += 2;
+                continue;
+            }
+            if (t.startsWith("-")) {
+                i++;
+                continue;
+            }
+            dur = t;
+            break;
+        }
+        if (dur)
+            worst = Math.max(worst, durationToSecs(dur));
+    }
+    // perl alarm() — spans separators, so match on the raw command.
+    const mMin = /alarm\(\s*([0-9]+)\s*\*\s*60/.exec(command);
+    if (mMin)
+        worst = Math.max(worst, Number(mMin[1]) * 60);
+    else {
+        const mSec = /alarm\(?\s*([0-9]+)/.exec(command);
+        if (mSec)
+            worst = Math.max(worst, Number(mSec[1]));
+    }
+    return worst;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export function evaluateTimeoutGuard(input) {
+    const { command, toolTimeoutMs } = input;
+    if (input.runInBackground)
+        return { block: false };
+    if (toolTimeoutMs !== undefined && toolTimeoutMs > HARNESS_MAX_MS) {
+        return {
+            block: true,
+            reason: `the Bash tool 'timeout' parameter is ${toolTimeoutMs}ms (> the ${HARNESS_MAX_MS}ms / 10-minute harness ceiling)`,
+        };
+    }
+    const effectiveMs = toolTimeoutMs !== undefined ? Math.min(toolTimeoutMs, HARNESS_MAX_MS) : HARNESS_DEFAULT_MS;
+    const innerSecs = parseInnerDeadlineSecs(command);
+    if (innerSecs > 0 && innerSecs * 1000 > effectiveMs) {
+        const ceilingDesc = toolTimeoutMs !== undefined
+            ? `the declared ${Math.round(effectiveMs / 1000)}s tool deadline`
+            : `the ~${HARNESS_DEFAULT_MS / 1000}s default foreground deadline`;
+        return {
+            block: true,
+            reason: `an inner ${innerSecs}s deadline (timeout/gtimeout/alarm) exceeds ${ceilingDesc}`,
+        };
+    }
+    return { block: false };
+}
+const BLOCK_MESSAGE = (reason) => `BLOCKED: this FOREGROUND command declares a timeout past the harness ceiling —
+${reason}.
+
+A foreground shell tool call is SIGTERM'd at the harness's outer deadline
+(~2 min default, 10 min max) regardless of any longer timeout you declared. It
+will die with exit 143 ("timed out after 10m 0s") and lose whatever it was doing
+— the largest harness-friction cluster in the 2026-08-10 team analysis
+(finding 2.1, 1,393 events).
+
+Do this instead: launch it as a background task (run_in_background: true).
+Background tasks survive turn boundaries, have no outer deadline, and auto-notify
+on completion. (\`hq core soft-timeout\` warns without killing for work you
+supervise yourself.)
+
+Policy: hq-foreground-timeout-killed-by-harness-deadline.
+Bypass for one sanctioned foreground run: prefix HQ_ALLOW_LONG_FOREGROUND=1.`;
+function defaultEmail() {
+    try {
+        const cached = loadCachedTokens();
+        if (!cached)
+            return undefined;
+        const email = peekIdToken(cached.idToken).email;
+        return typeof email === "string" ? email : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export function isGatedUser(email) {
+    return typeof email === "string" && email.toLowerCase().endsWith(GATE_DOMAIN);
+}
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export function timeoutGuardCommand(stdin, deps = {}) {
+    const env = deps.env ?? process.env;
+    const err = deps.stderr ?? process.stderr;
+    let payload;
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return 0;
+    }
+    const ti = payload?.tool_input ?? {};
+    const command = typeof ti.command === "string" ? ti.command : "";
+    if (!command)
+        return 0;
+    // The inline escape hatch and the env escape hatch both bypass.
+    if (env.HQ_ALLOW_LONG_FOREGROUND === "1")
+        return 0;
+    if (/(^|\s)HQ_ALLOW_LONG_FOREGROUND=1(\s|$)/.test(command))
+        return 0;
+    // Rollout gate: only act for @getindigo.ai identities.
+    const getEmail = deps.getEmail ?? defaultEmail;
+    if (!isGatedUser(getEmail()))
+        return 0;
+    const runInBackground = ti.run_in_background === true;
+    const toolTimeoutMs = typeof ti.timeout === "number" ? ti.timeout : undefined;
+    const verdict = evaluateTimeoutGuard({ command, toolTimeoutMs, runInBackground });
+    if (!verdict.block)
+        return 0;
+    err.write(`${BLOCK_MESSAGE(verdict.reason ?? "declared timeout exceeds the harness ceiling")}\n`);
+    return 2;
+}
+//# sourceMappingURL=timeout-guard.js.map

package/package.json

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