@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/utils/script-bound-exec.js

@@ -0,0 +1,568 @@
+/**
+ * Bind a script-locked secret release to the process that is actually run
+ * (feedback_0e6abcb8).
+ *
+ * `--script <path>` sends the script's path and hash to the vault, which
+ * releases a script-locked secret when that pair is approved. Before this
+ * module the command after `--` was never compared with that script, so any
+ * command that named an approved script received the secret.
+ *
+ * When any requested secret is script-locked (or its lock state is unknown),
+ * the command after `--` must be one of:
+ *   1. the approved script itself: `-- ./approved.sh [args...]` (realpath
+ *      match). Its `#!` line is parsed and the interpreter it names goes
+ *      through the same allowlist; `#!/usr/bin/env X` resolves X against a
+ *      fixed system PATH, never the caller's PATH;
+ *   2. an allowlisted interpreter followed directly by the script:
+ *      `-- bash approved.sh [args...]`, also resolved against the fixed PATH.
+ * Anything else (wrappers such as env, xargs, sudo, a shell `-c` string, an
+ * interpreter option before the script) is refused and nothing is injected.
+ *
+ * Allowlisted interpreters: sh, dash, ksh, bash (run with --noprofile
+ * --norc), zsh (run with -f), python3/python (run with -I -S), node. Ruby and
+ * perl are not allowlisted. The interpreter's realpath and every parent
+ * directory must be owned by root and not group- or world-writable, so
+ * Homebrew or other user-writable installs are refused.
+ *
+ * At spawn time the script bytes are read once, hashed, compared with the hash
+ * sent to the vault, written to a fresh 0700 private directory, re-hashed, and
+ * that copy is passed to the interpreter. The original path is exposed to the
+ * script as HQ_APPROVED_SCRIPT and its directory as HQ_APPROVED_SCRIPT_DIR.
+ * `$0` / `__file__` / `__dirname` name the copy, so a script that loads
+ * neighbour files relative to itself must use HQ_APPROVED_SCRIPT_DIR. The
+ * working directory is left as the caller's.
+ *
+ * The child environment gets a fixed system PATH and loses the variables that
+ * make an interpreter, the loader or the macOS xcrun shims run other code.
+ * The same names are refused when they arrive in the injected secrets or in
+ * an env-schema / env-local value, because those are merged last.
+ *
+ * The child environment is built from an allowlist (see scriptBoundChildEnv),
+ * not inherited from the caller.
+ *
+ * What the binding does and does not protect: it controls which entrypoint
+ * receives the secret. It does not isolate what that entrypoint runs. A
+ * same-user caller can still influence tools the script calls through files
+ * in HOME (for example ~/.gitconfig and fsmonitor hooks, ~/.curlrc,
+ * ~/.ssh/config, ~/.netrc) or through anything else the user can write. Real
+ * isolation needs the vault-side sandbox release (`hq secrets sandbox`).
+ *
+ * Remaining limits, documented on purpose:
+ *   - Only the script file is hashed. Files it sources, requires or imports
+ *     (neighbour files, modules) are not covered by the approval.
+ *   - A process running as the same user can still race the private copy
+ *     between its re-hash and the interpreter opening it. The window is short
+ *     and the path is random, but same-user code is not a boundary this
+ *     client-side check can enforce.
+ *   - The check runs in the CLI. A modified CLI, or a direct call to the vault
+ *     API with a self-asserted hash, is outside what it can stop.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import { createHash } from "node:crypto";
+import { computeSha256 } from "./integrity.js";
+export class ScriptBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScriptBindingError";
+    }
+}
+/** Root-owned search path used for interpreters and for the child. */
+export const FIXED_SYSTEM_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+const INTERPRETER_NAMES = new Set(["sh", "dash", "ksh", "bash", "zsh", "python", "python3", "node"]);
+function interpreterKind(realPath) {
+    const base = nodePath.basename(realPath);
+    if (/^(sh|dash|ksh)$/.test(base))
+        return "sh";
+    if (base === "bash")
+        return "bash";
+    if (base === "zsh")
+        return "zsh";
+    if (/^python(3(\.\d+)?)?$/.test(base))
+        return "python";
+    if (base === "node")
+        return "node";
+    return undefined;
+}
+const SAFE_FLAGS = {
+    sh: [],
+    bash: ["--noprofile", "--norc"],
+    zsh: ["-f"],
+    python: ["-I", "-S"],
+    node: [],
+};
+const INJECTION_ENV_NAMES = new Set([
+    "BASH_ENV",
+    "ENV",
+    "SHELLOPTS",
+    "BASHOPTS",
+    "PS4",
+    "PROMPT_COMMAND",
+    "ZDOTDIR",
+    "CDPATH",
+    "IFS",
+    "DEVELOPER_DIR",
+    "SDKROOT",
+    "TOOLCHAINS",
+    "XCRUN_LOG",
+    // Node: code-loading switches only, so NODE_ENV and similar stay usable.
+    "NODE_OPTIONS",
+    "NODE_PATH",
+    "NODE_REPL_EXTERNAL_MODULE",
+    // zsh (even with -f) and ksh autoload functions from FPATH.
+    "FPATH",
+    // glibc loads iconv modules from GCONV_PATH and locale data from LOCPATH.
+    "GCONV_PATH",
+    "LOCPATH",
+    "GLIBC_TUNABLES",
+    "NLSPATH",
+    // Reserved for the values this module sets.
+    "PATH",
+    "HQ_APPROVED_SCRIPT",
+    "HQ_APPROVED_SCRIPT_DIR",
+]);
+const INJECTION_ENV_PREFIXES = [
+    "BASH_FUNC_",
+    "PYTHON",
+    "RUBY",
+    "GEM_",
+    "BUNDLE_",
+    "PERL",
+    "LD_",
+    "DYLD_",
+    // OpenSSL reads OPENSSL_CONF / OPENSSL_MODULES / OPENSSL_ENGINES and can load
+    // engines or providers from them. GIO_MODULE_DIR / GIO_EXTRA_MODULES load
+    // GLib modules. SSL_CERT_* only changes trust roots and is left alone.
+    "OPENSSL_",
+    "GIO_",
+    // Config and helper hooks of tools a script commonly calls.
+    "GIT_",
+    "SSH_",
+    "CURL_",
+    "WGET",
+];
+/**
+ * Caller variables a bound script may inherit. Everything else is dropped;
+ * PATH is replaced by FIXED_SYSTEM_PATH.
+ */
+const INHERITED_ENV_NAMES = new Set(["HOME", "USER", "LOGNAME", "LANG", "TERM", "TZ", "TMPDIR"]);
+const INHERITED_ENV_PREFIXES = ["LC_"];
+/** True for a variable a bound script's environment must not take from the caller. */
+export function isDeniedEnvName(name) {
+    return INJECTION_ENV_NAMES.has(name) || INJECTION_ENV_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+ * Names that change where a tool connects, which CA it trusts, which helper
+ * program it runs, or where it reads config. Injected values (secrets and
+ * `hq run` schema literals) may not use them in a bound launch.
+ */
+const DANGEROUS_INJECTED_NAMES = new Set([
+    "NO_PROXY",
+    "no_proxy",
+    "REQUESTS_CA_BUNDLE",
+    "CURL_CA_BUNDLE",
+    "HOME",
+    "PAGER",
+    "MANPAGER",
+    "GIT_PAGER",
+    "EDITOR",
+    "VISUAL",
+    "NLSPATH",
+    "SHELL",
+]);
+const DANGEROUS_INJECTED_PATTERNS = [
+    /_proxy$/i, // HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, FTP_PROXY, lower-case forms
+    /^SSL_/,
+    /^NODE_(?!ENV$)/,
+    /^XDG_/,
+    /^LESS/,
+    /^TERMINFO/,
+    // Tool config and endpoint overrides (fifth review).
+    /^AWS_ENDPOINT_URL/,
+    /^AWS_(CA_BUNDLE|CONFIG_FILE|SHARED_CREDENTIALS_FILE|PROFILE)$/,
+    /^KUBECONFIG$/,
+    /^DOCKER_/,
+    /^PIP_/i,
+    /^NPM_CONFIG_/i,
+    /^BROWSER$/,
+    /^GNUPGHOME$/,
+    /^TF_CLI_CONFIG_FILE$/,
+    /^GO(PROXY|FLAGS)$/,
+    /^CARGO_/,
+    /^SUDO_ASKPASS$/,
+];
+/**
+ * Schema / local env literal names a bound `hq run --script` launch accepts
+ * (fifth review). Literals are caller-written, so instead of denying
+ * tool-config names one by one, only these app-level switches are allowed.
+ * Everything else must come from the vault through hq().
+ */
+export const SAFE_LITERAL_NAMES = new Set([
+    "NODE_ENV",
+    "APP_ENV",
+    "ENVIRONMENT",
+    "LOG_LEVEL",
+    "LOG_FORMAT",
+    "CI",
+    "NO_COLOR",
+    "FORCE_COLOR",
+]);
+/** Refuse schema literals that are not on SAFE_LITERAL_NAMES (or are denied). */
+export function assertLiteralNamesAllowed(names) {
+    const refused = [...names].filter((name) => !SAFE_LITERAL_NAMES.has(name) || isDeniedInjectedName(name));
+    if (refused.length > 0) {
+        refuse(`schema literals ${refused.join(", ")} are not on the --script literal allowlist (${[...SAFE_LITERAL_NAMES].join(", ")}). Store other values in the vault and reference them with hq().`);
+    }
+}
+/**
+ * Design (feedback_0e6abcb8, fourth review): an injected name is accepted in a
+ * bound launch only when it is not on the loader/interpreter denylist, not
+ * one of the inherited allowlist names (HOME, USER, LANG, LC_*, TZ, TMPDIR,
+ * ...), and not on the explicit dangerous list above. Ordinary application
+ * names (FAKE_API_KEY, DATABASE_URL, NODE_ENV) pass.
+ */
+export function isDeniedInjectedName(name) {
+    return (isDeniedEnvName(name) ||
+        INHERITED_ENV_NAMES.has(name) ||
+        INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)) ||
+        DANGEROUS_INJECTED_NAMES.has(name) ||
+        DANGEROUS_INJECTED_PATTERNS.some((re) => re.test(name)));
+}
+/** Refuse a bound launch whose injected values use a denied name. */
+export function assertInjectedNamesAllowed(names) {
+    const denied = [...names].filter(isDeniedInjectedName);
+    if (denied.length > 0) {
+        refuse(`the injected variables include names a bound script may not receive (${denied.join(", ")}).`);
+    }
+}
+/**
+ * Root for private copies. Chosen at module load from fixed locations, never
+ * from the caller's TMPDIR: /tmp when it is root-owned and sticky, otherwise
+ * the platform default.
+ */
+const PRIVATE_COPY_ROOT = (() => {
+    try {
+        const st = fs.statSync("/tmp");
+        if (st.isDirectory() && st.uid === 0 && (st.mode & 0o1000) !== 0)
+            return fs.realpathSync("/tmp");
+    }
+    catch {
+        // fall through
+    }
+    return os.platform() === "win32" ? os.tmpdir() : "/tmp";
+})();
+export function privateCopyRoot() {
+    return PRIVATE_COPY_ROOT;
+}
+function refuse(reason) {
+    throw new ScriptBindingError(`Refusing to inject script-locked secrets: ${reason} With --script, the command after -- must be the approved script itself (for example -- ./script.sh args) or an allowlisted system interpreter followed directly by it (for example -- bash script.sh args).`);
+}
+function realpathOrRefuse(target, what) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        refuse(`${what} '${target}' could not be resolved.`);
+    }
+}
+function isExecutableFile(candidate) {
+    try {
+        if (!fs.statSync(candidate).isFile())
+            return false;
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function lookupOnFixedPath(name) {
+    for (const dir of FIXED_SYSTEM_PATH.split(":")) {
+        const candidate = nodePath.join(dir, name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * True when realPath and every parent directory are owned by root and not
+ * group- or world-writable.
+ */
+export function isRootOwnedChain(realPath) {
+    let current = realPath;
+    for (;;) {
+        let st;
+        try {
+            st = fs.lstatSync(current);
+        }
+        catch {
+            return false;
+        }
+        if (st.uid !== 0 || (st.mode & 0o022) !== 0)
+            return false;
+        const parent = nodePath.dirname(current);
+        if (parent === current)
+            return true;
+        current = parent;
+    }
+}
+function trustedInterpreter(candidate, label) {
+    const real = realpathOrRefuse(candidate, "interpreter");
+    const kind = interpreterKind(real);
+    if (!kind)
+        refuse(`interpreter '${label}' is not allowlisted.`);
+    if (!isRootOwnedChain(real)) {
+        refuse(`interpreter '${label}' resolves to a location that is not root-owned or is writable by other users.`);
+    }
+    return { path: real, kind };
+}
+function interpreterFromShebang(scriptRealPath) {
+    let head;
+    try {
+        const fd = fs.openSync(scriptRealPath, "r");
+        try {
+            const buf = Buffer.alloc(256);
+            const n = fs.readSync(fd, buf, 0, buf.length, 0);
+            head = buf.subarray(0, n).toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        refuse("the approved script could not be read.");
+    }
+    if (!head.startsWith("#!"))
+        refuse("the approved script has no #! line; run it through an interpreter instead.");
+    const line = head.slice(2).split("\n")[0].trim();
+    const tokens = line.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0 || !nodePath.isAbsolute(tokens[0]))
+        refuse("the script's #! line does not name an absolute interpreter.");
+    const first = realpathOrRefuse(tokens[0], "#! interpreter");
+    if (nodePath.basename(first) === "env") {
+        if (!isRootOwnedChain(first))
+            refuse("the script's #! env is not root-owned.");
+        if (tokens.length !== 2 || tokens[1].startsWith("-") || tokens[1].includes("/")) {
+            refuse("the script's #!/usr/bin/env line must name exactly one interpreter, with no options.");
+        }
+        const found = lookupOnFixedPath(tokens[1]);
+        if (!found)
+            refuse(`#! interpreter '${tokens[1]}' was not found on the system PATH.`);
+        return trustedInterpreter(found, tokens[1]);
+    }
+    if (tokens.length !== 1)
+        refuse("the script's #! line passes interpreter options, which are not allowed.");
+    return trustedInterpreter(tokens[0], tokens[0]);
+}
+/**
+ * Resolve the command after `--` against the approved script. Throws
+ * ScriptBindingError when the command is not exactly the script invocation.
+ */
+export async function resolveScriptBoundCommand(scriptPath, childArgs) {
+    if (childArgs.length === 0)
+        refuse("no command was given.");
+    const scriptRealPath = realpathOrRefuse(nodePath.resolve(scriptPath), "script");
+    try {
+        if (!fs.statSync(scriptRealPath).isFile())
+            refuse(`script '${scriptPath}' is not a regular file.`);
+    }
+    catch (err) {
+        if (err instanceof ScriptBindingError)
+            throw err;
+        refuse(`script '${scriptPath}' could not be read.`);
+    }
+    const [first, ...rest] = childArgs;
+    let interpreter;
+    let scriptArgs;
+    if (first.includes("/")) {
+        if (realpathOrRefuse(nodePath.resolve(first), "command") !== scriptRealPath) {
+            refuse("the command after -- is not the approved script.");
+        }
+        interpreter = interpreterFromShebang(scriptRealPath);
+        scriptArgs = rest;
+    }
+    else if (INTERPRETER_NAMES.has(first)) {
+        const found = lookupOnFixedPath(first);
+        if (!found)
+            refuse(`interpreter '${first}' was not found on the system PATH.`);
+        interpreter = trustedInterpreter(found, first);
+        const [scriptArg, ...more] = rest;
+        if (scriptArg === undefined || scriptArg.startsWith("-")) {
+            refuse("interpreter options and inline code are not allowed; the approved script must be the interpreter's first argument.");
+        }
+        if (realpathOrRefuse(nodePath.resolve(scriptArg), "script argument") !== scriptRealPath) {
+            refuse("the interpreter's first argument is not the approved script.");
+        }
+        scriptArgs = more;
+    }
+    else {
+        refuse("the command after -- is not the approved script or an allowlisted interpreter.");
+    }
+    return {
+        scriptRealPath,
+        interpreterPath: interpreter.path,
+        interpreterArgs: SAFE_FLAGS[interpreter.kind],
+        scriptArgs,
+        sha256: await computeSha256(scriptRealPath),
+    };
+}
+/** Compare the script on disk with the hash sent to the vault. */
+export async function assertScriptUnchanged(bound, attestedSha256) {
+    let current;
+    try {
+        current = await computeSha256(bound.scriptRealPath);
+    }
+    catch {
+        refuse("the approved script could not be re-read.");
+    }
+    if (current !== bound.sha256 || (attestedSha256 !== undefined && current !== attestedSha256)) {
+        refuse("the approved script changed after it was hashed.");
+    }
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Read the script once, check its hash, copy those bytes into a fresh 0700
+ * directory, re-hash the copy, and return the spawn target that runs the copy.
+ */
+export function prepareBoundSpawn(bound, attestedSha256) {
+    let bytes;
+    try {
+        bytes = fs.readFileSync(bound.scriptRealPath);
+    }
+    catch {
+        refuse("the approved script could not be re-read before it ran.");
+    }
+    const sha = sha256Hex(bytes);
+    if (sha !== bound.sha256 || (attestedSha256 !== undefined && sha !== attestedSha256)) {
+        refuse("the approved script changed after it was hashed.");
+    }
+    const dir = fs.mkdtempSync(nodePath.join(PRIVATE_COPY_ROOT, "hq-approved-script-"));
+    let removeSignalHandlers = () => undefined;
+    const cleanup = () => {
+        removeSignalHandlers();
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // best effort
+        }
+    };
+    removeSignalHandlers = cleanupOnParentSignals(cleanup);
+    try {
+        fs.chmodSync(dir, 0o700);
+        const copyPath = nodePath.join(dir, nodePath.basename(bound.scriptRealPath));
+        fs.writeFileSync(copyPath, bytes, { flag: "wx", mode: 0o500 });
+        if (sha256Hex(fs.readFileSync(copyPath)) !== sha)
+            refuse("the private copy of the approved script did not match.");
+        return {
+            file: bound.interpreterPath,
+            args: [...bound.interpreterArgs, copyPath, ...bound.scriptArgs],
+            copyPath,
+            cleanup,
+        };
+    }
+    catch (err) {
+        cleanup();
+        if (err instanceof ScriptBindingError)
+            throw err;
+        refuse("a private copy of the approved script could not be written.");
+    }
+}
+/**
+ * Remove the private copy when the parent gets SIGINT, SIGTERM or SIGHUP, or
+ * exits, then re-raise the signal so the default termination still happens.
+ * SIGKILL cannot be handled; a copy left by it stays in the 0700 temp
+ * directory until the OS cleans the temp dir.
+ */
+export function cleanupOnParentSignals(cleanup, proc = process) {
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handlers = new Map();
+    const onExit = () => cleanup();
+    const remove = () => {
+        for (const [sig, handler] of handlers)
+            proc.removeListener(sig, handler);
+        handlers.clear();
+        proc.removeListener("exit", onExit);
+    };
+    for (const sig of signals) {
+        const handler = () => {
+            cleanup();
+            remove();
+            proc.kill(proc.pid, sig);
+        };
+        handlers.set(sig, handler);
+        proc.once(sig, handler);
+    }
+    proc.once("exit", onExit);
+    return remove;
+}
+/**
+ * Child environment for a bound script, built from an allowlist: HOME, USER,
+ * LOGNAME, LANG, LC_*, TERM, TZ and TMPDIR from the caller, a fixed PATH, and
+ * the HQ_APPROVED_* variables. Injected secrets and schema values are added by
+ * the caller after a denylist check.
+ */
+export function scriptBoundChildEnv(env, scriptRealPath) {
+    const out = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (!INHERITED_ENV_NAMES.has(name) && !INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)))
+            continue;
+        out[name] = value;
+    }
+    out.PATH = FIXED_SYSTEM_PATH;
+    if (scriptRealPath) {
+        out.HQ_APPROVED_SCRIPT = scriptRealPath;
+        out.HQ_APPROVED_SCRIPT_DIR = nodePath.dirname(scriptRealPath);
+    }
+    return out;
+}
+/**
+ * Whether the release must be bound to the script. Only rows the vault marked
+ * `scriptLock.mode: "off"` are exempt; enforced or unknown fails closed.
+ */
+export function requiresScriptBinding(keys, lockModes) {
+    return keys.some((key) => lockModes.get(key) !== "off");
+}
+/**
+ * Resolve the binding before any fetch. A refusal is held, not thrown, so a
+ * caller whose secrets turn out not to be script-locked keeps working.
+ */
+export async function planScriptBinding(scriptPath, childArgs) {
+    if (!scriptPath)
+        return undefined;
+    try {
+        return { bound: await resolveScriptBoundCommand(scriptPath, childArgs) };
+    }
+    catch (err) {
+        if (err instanceof ScriptBindingError)
+            return { error: err };
+        throw err;
+    }
+}
+/**
+ * Pick what to spawn once the vault has answered. Unlocked secrets keep the
+ * caller's command unchanged; enforced or unknown lock state requires the
+ * bound script and throws ScriptBindingError otherwise.
+ */
+export function selectChildLaunch(plan, keys, lockModes, attestedSha256, childArgs, env, injected) {
+    if (!plan || !requiresScriptBinding(keys, lockModes)) {
+        const [file, ...args] = childArgs;
+        return { file, args, env: { ...env, ...injected }, cleanup: () => undefined };
+    }
+    if (plan.error)
+        throw plan.error;
+    // Secrets and schema values are merged last, so they must not carry a
+    // control variable (PATH, BASH_ENV, NODE_OPTIONS, ...) into the script.
+    assertInjectedNamesAllowed(Object.keys(injected));
+    const prepared = prepareBoundSpawn(plan.bound, attestedSha256);
+    return {
+        file: prepared.file,
+        args: prepared.args,
+        env: { ...scriptBoundChildEnv(env, plan.bound.scriptRealPath), ...injected },
+        cleanup: prepared.cleanup,
+    };
+}
+//# sourceMappingURL=script-bound-exec.js.map

package/dist/utils/sync-watchdog.d.ts

@@ -0,0 +1,92 @@
+/** Default no-progress limit: off. Opt in with --max-idle / HQ_SYNC_MAX_IDLE. */
+export declare const DEFAULT_SYNC_MAX_IDLE_SECONDS = 0;
+/** Default total cap: off. */
+export declare const DEFAULT_SYNC_MAX_RUNTIME_SECONDS = 0;
+/** How long the worker backstop waits past a limit before it kills. */
+export declare const SYNC_WATCHDOG_BACKSTOP_GRACE_MS = 60000;
+/** Upper bound on the failed-sync report after a timeout, before exit 124. */
+export declare const SYNC_WATCHDOG_REPORT_GRACE_MS = 10000;
+/** Exit code for a run the in-process watchdog ended (same as coreutils `timeout`). */
+export declare const SYNC_WATCHDOG_EXIT_CODE = 124;
+export type SyncWatchdogReason = "idle" | "runtime";
+export declare class SyncWatchdogTimeoutError extends Error {
+    readonly code = "SYNC_WATCHDOG_TIMEOUT";
+    readonly reason: SyncWatchdogReason;
+    readonly seconds: number;
+    constructor(reason: SyncWatchdogReason, seconds: number, label: string);
+}
+export declare function syncWatchdogMessage(reason: SyncWatchdogReason, seconds: number, label: string): string;
+export interface SyncWatchdogLimits {
+    /** No-progress limit in seconds; 0 = off. */
+    idleSeconds: number;
+    /** Total cap in seconds; 0 = off. */
+    maxRuntimeSeconds: number;
+}
+/** Resolve both limits. A flag wins, then the environment, then the default. */
+export declare function resolveSyncWatchdogLimits(raw: {
+    maxIdle?: string;
+    maxRuntime?: string;
+}, env?: NodeJS.ProcessEnv): SyncWatchdogLimits;
+/** Test seam: replace the monotonic clock. `null` restores process.hrtime. */
+export declare function setSyncWatchdogClockForTesting(clock: (() => number) | null): void;
+/** Record sync progress. Cheap; safe to call on every row or event. */
+export declare function noteSyncProgress(): void;
+/** Last recorded progress time, for tests and the in-process check. */
+export declare function lastSyncProgressAt(): number;
+/** The fields of hq-cloud's shared sync-progress snapshot the probe reads. */
+export interface SyncProgressSnapshotLike {
+    pid?: number;
+    phase?: string;
+    company?: string | null;
+    filesTotal?: number;
+    filesDone?: number;
+    conflicts?: number;
+    startedAt?: string;
+}
+/**
+ * Build a probe that calls {@link noteSyncProgress} whenever THIS process's
+ * sync-progress snapshot changes. hq-cloud rewrites that snapshot when a leg
+ * starts, when it plans, and for every file transferred or skipped, for both
+ * push and pull, so a moving sync keeps resetting the idle limit without any
+ * change to the engine's progress recorders. Snapshots written by another
+ * process (the menubar runner) are ignored. A single file transfer is not
+ * seen until it completes; the engine's own per-body idle timeouts cover a
+ * transfer that stalls.
+ */
+export declare function createSnapshotProgressProbe(read: () => SyncProgressSnapshotLike | null, pid?: number): () => void;
+export interface SyncBackstop {
+    cancel(): void;
+}
+export interface SyncBackstopOptions {
+    /** Shared Float64 progress clock (index 0). */
+    clock: Float64Array;
+    startedAt: number;
+    idleMs: number;
+    maxRuntimeMs: number;
+    graceMs: number;
+    idleMessage: string;
+    runtimeMessage: string;
+}
+export type StartSyncBackstop = (options: SyncBackstopOptions) => SyncBackstop;
+export declare const startWorkerBackstop: StartSyncBackstop;
+/** Test seam: replace the worker backstop. `null` restores the real one. */
+export declare function setSyncBackstopStarterForTesting(start: StartSyncBackstop | null): void;
+export interface SyncWatchdogOptions {
+    idleMs: number;
+    maxRuntimeMs: number;
+    label: string;
+    startBackstop?: StartSyncBackstop;
+    backstopGraceMs?: number;
+    /** How often the in-process check runs. Defaults to a quarter of the smallest limit, at most 30s. */
+    checkIntervalMs?: number;
+    /** Called on every check before the limits are tested, e.g. {@link createSnapshotProgressProbe}. */
+    probeProgress?: () => void;
+}
+/**
+ * Run `run` under the watchdog. Resolves or rejects with `run`'s outcome when
+ * it finishes within the limits. Otherwise rejects with
+ * {@link SyncWatchdogTimeoutError} and leaves the backstop armed: the caller
+ * is expected to exit the process. With both limits 0 it just runs `run`.
+ */
+export declare function withSyncWatchdog<T>(run: () => Promise<T>, options: SyncWatchdogOptions): Promise<T>;
+//# sourceMappingURL=sync-watchdog.d.ts.map