@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/shared/child-process.d.ts

@@ -23,13 +23,17 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
     cwd: string;
     shell: boolean;
     stdio: ['ignore' | 'pipe', 'pipe', 'pipe'];
-    /** Set only when the invocation needs env overrides (e.g. GIT_INDEX_FILE);
-     *  absent → the child inherits this process's environment as before. */
+    /** Set only when the invocation needs env overrides — git-state-guard's
+     *  `GIT_INDEX_FILE` throwaway index is the one caller. Absent → the child
+     *  inherits this process's environment. */
     env?: NodeJS.ProcessEnv;
     /** true → give the child its own process group (POSIX `detached`), so any
-     *  server it backgrounds (`bun run dev &`) can be reaped as a group when the
-     *  child exits instead of leaking as an orphan holding a port (mx5 run 9
-     *  item 3). Set only for model children (json-events); plumbing stays put. */
+     *  server it backgrounds (`bun run dev &`) can be reaped as a group instead
+     *  of leaking as an orphan holding a port. The flag is what makes the reap
+     *  possible at all: with `detached`, a `kill(-pid)` issued after the child
+     *  has exited still takes the backgrounded grandchild with it; without it
+     *  the same call throws ESRCH and the grandchild survives. Set only for
+     *  model children (json-events); plumbing stays in-group. */
     detached?: boolean;
 }) => ProcLike;
 export interface ChildResult {
@@ -58,7 +62,7 @@ export interface ChildResult {
      * true when the STREAM watchdog killed the child: no output at all for the
      * configured inactivity window, regardless of whether the backend answers a
      * probe. Distinct from `stalled`, which requires an UNREACHABLE endpoint —
-     * the run-14 hangs had a perfectly healthy server and a dead stream, so the
+     * these hangs have a perfectly healthy server and a dead stream, so the
      * probe path could never fire. Callers must check this BEFORE `aborted`
      * (the kill sets aborted too) and route it into the connection-error retry.
      */
@@ -72,8 +76,10 @@ export interface ToolCall {
     /**
      * pi's id for this tool call, carried on both `tool_execution_start` and
      * `tool_execution_end` so a caller can pair them (the command watchdog arms
-     * on start and disarms on the matching end). Optional because the loop
-     * detector — the other consumer — keys on name+args and never needs it.
+     * on start and disarms on the matching end). It is the only thing that pairs
+     * them: the end event carries `toolName`, `result` and `isError`, but no
+     * `args`. Optional because the loop detector — the other consumer — keys on
+     * name+args and never needs it.
      */
     toolCallId?: string;
 }
@@ -98,9 +104,10 @@ export interface ContextSnapshot {
 export interface RunChildTextOptions {
     mode: 'text';
     /**
-     * Drop stdout chunks instead of buffering them into the result. Use for
-     * pipe-through tools (npm install, build commands) where we only need the
-     * exit code and stderr — verbose stdout can exceed V8's max string length.
+     * Drop stdout chunks instead of buffering them into the result. Use when only
+     * the exit code and stderr are wanted and stdout is bulk noise. Its one caller
+     * is the docs extractor, which discards a verbose stdout and keeps stderr
+     * because stderr is what it came for.
      */
     discardStdout?: boolean;
     /**
@@ -117,29 +124,28 @@ export interface RunChildJsonEventsOptions {
     onContextUsage?: (snapshot: ContextSnapshot) => void;
     /**
      * The child's context window in tokens, supplied BY THE CALLER — pi's event
-     * stream does not carry one (GitHub issue #16).
+     * stream does not carry one.
      *
-     * Verified against the published tarballs of @earendil-works/pi-coding-agent
-     * and @earendil-works/pi-agent-core at 0.80.2 and 0.84.2, and against pi's
-     * own docs/json.md: the wire union is session / agent_* / turn_* / message_*
-     * / tool_execution_* / queue_update / compaction_* / auto_retry_*, the
-     * session header is {type,version,id,timestamp,cwd,parentSession}, and no
-     * member of either carries a window or even a model id. `contextUsage`
-     * exists ONLY as the in-process `ctx.getContextUsage()` extension API, which
-     * a `--mode json` child never speaks back to its parent.
+     * Checked against a real `--mode json` capture rather than assumed: across
+     * every event it emits, no key anywhere names a context or a window. The
+     * stream DOES carry a model id and a token `usage` block, so the COUNT is
+     * available and only the window is missing. `getContextUsage()` exists solely
+     * as an in-process extension API, which a `--mode json` child never speaks
+     * back to its parent.
      *
      * The parent therefore has to say. Children are spawned without `-m`
      * (CHILD_BASE_ARGS), so they resolve the same default model the parent runs
-     * and the parent session's window is the honest answer. 0 / omitted keeps
-     * the old behaviour: report the token count with no window.
+     * and the parent session's window is the honest answer. 0 or omitted reports
+     * the token count with no window.
      */
     contextWindow?: number;
     onToolCall?: (call: ToolCall) => LoopHit | null;
     /**
-     * Fires when a tool call finishes, carrying its RESULT (mx5 run 10 item 6: the
-     * verify debug log recorded the `bash:` command but never its output, so "verify
-     * claimed curl PASS on a server that cannot serve" was undecidable from the log).
-     * Text is the tool's combined output; `isError` distinguishes a failed call.
+     * Fires when a tool call finishes, carrying its RESULT. `onToolCall` reports
+     * only the request, so without this a debug trail records that a `bash:`
+     * command ran and never what it printed — and a step that claims a command
+     * passed cannot be checked against what the command actually said. Text is
+     * the tool's combined output; `isError` distinguishes a failed call.
      */
     onToolResult?: (result: {
         name: string;
@@ -149,13 +155,13 @@ export interface RunChildJsonEventsOptions {
     }) => void;
     onFirstByte?: () => void;
     /**
-     * Dead-backend stall guard (mx5 run 7: model server died mid-child, the
-     * child hung MUTE for 64 minutes). Liveness is OUTPUT PROGRESS, not wall
-     * time: any stdout/stderr chunk resets the window, so honest long work is
-     * never killed. Only when nothing arrived for `afterMs` is `probe` asked
-     * whether the model backend is reachable — reachable → keep waiting
-     * (prompt processing legitimately emits nothing for minutes); unreachable
-     * → the child is killed and the result carries `stalled: true` so callers
+     * Dead-backend stall guard: the model server dies mid-child and the child
+     * hangs mute with nothing to throw. Liveness is OUTPUT PROGRESS, not wall
+     * time — any stdout/stderr chunk resets the window, so honest long work is
+     * never killed. Only when nothing has arrived for `afterMs` is `probe` asked
+     * whether the model backend is reachable: reachable → keep waiting, because
+     * prompt processing legitimately emits nothing while it runs; unreachable →
+     * the child is killed and the result carries `stalled: true` so callers
      * report the real cause instead of hanging or mislabeling a user cancel.
      */
     stall?: {
@@ -166,9 +172,9 @@ export interface RunChildJsonEventsOptions {
      * Stream-inactivity ceiling in ms (shared/stream-watchdog.ts). Unlike `stall`
      * this asks NOTHING of the backend: a stream that has produced no bytes for
      * this long is dead whether or not the server answers a health probe, which
-     * is exactly the run-14 shape (server Up(healthy), stream silent for hours).
-     * Any stdout/stderr chunk resets it, so a slow model emitting one token every
-     * 30s is never killed. 0 / omitted = off.
+     * is exactly the shape of a hung stream: server reporting healthy, nothing
+     * coming down the wire for hours. Any stdout/stderr chunk resets it, so a
+     * merely slow model is never killed, however slow it is. 0 / omitted = off.
      */
     streamInactivityMs?: number;
 }
@@ -196,10 +202,11 @@ export declare class JsonEventSink {
      * CLEARED when a LATER agent_end delivers assistant text: pi retries a failed
      * turn itself (`auto_retry_start`) and each attempt emits its own agent_end,
      * so a recovered blip arrives as agent_end(stopReason "error", empty) followed
-     * by agent_end(text). Measured live against a proxy that drops the first
-     * connection: pi makes up to 4 attempts over ~15s, and on attempts 1–3 the
-     * child returns the real answer WITH the dead first attempt's errorMessage
-     * still in the stream. Latching that would report a failure for a run that
+     * by agent_end(text). How many attempts and how long they take is the user's
+     * `retry` setting — one initial call plus `retry.maxRetries`, backing off
+     * from `retry.baseDelayMs` — so on any attempt but the last the child
+     * returns the real answer WITH the dead first attempt's errorMessage still
+     * in the stream. Latching that would report a failure for a run that
      * succeeded. An error AFTER the last text-bearing turn still latches — that
      * one really did lose the tail of the work.
      */

package/dist/shared/child-process.js

@@ -35,10 +35,11 @@ export class JsonEventSink {
      * CLEARED when a LATER agent_end delivers assistant text: pi retries a failed
      * turn itself (`auto_retry_start`) and each attempt emits its own agent_end,
      * so a recovered blip arrives as agent_end(stopReason "error", empty) followed
-     * by agent_end(text). Measured live against a proxy that drops the first
-     * connection: pi makes up to 4 attempts over ~15s, and on attempts 1–3 the
-     * child returns the real answer WITH the dead first attempt's errorMessage
-     * still in the stream. Latching that would report a failure for a run that
+     * by agent_end(text). How many attempts and how long they take is the user's
+     * `retry` setting — one initial call plus `retry.maxRetries`, backing off
+     * from `retry.baseDelayMs` — so on any attempt but the last the child
+     * returns the real answer WITH the dead first attempt's errorMessage still
+     * in the stream. Latching that would report a failure for a run that
      * succeeded. An error AFTER the last text-bearing turn still latches — that
      * one really did lose the tail of the work.
      */
@@ -46,9 +47,9 @@ export class JsonEventSink {
     textDeltaAccum = '';
     // json-events lines can split across data chunks; this holds the trailing
     // partial line between feeds so events spanning a boundary still parse. We
-    // deliberately do NOT accumulate the full raw stream: a long-running child
-    // emits hundreds of MB of events and buffering it would overflow V8's max
-    // string length (≈512MB). We keep only the parsed text.
+    // deliberately do NOT accumulate the full raw stream — only the parsed text
+    // is kept, so a long-running child cannot walk a buffer toward the runtime's
+    // max-string-length ceiling.
     buf = '';
     constructor(opts, 
     /** Invoked when onToolCall reports a loop hit — runChild kills the child. */
@@ -88,12 +89,12 @@ export class JsonEventSink {
     handleEvent(evt) {
         const opts = this.opts;
         const t = typeof evt.type === 'string' ? evt.type : '';
-        // `message_end` is the ONLY context readout pi gives a `--mode json`
-        // child's parent. There used to be a `context_usage` branch above this
-        // one that was preferred over it; no released pi has ever emitted such
-        // an event (see `contextWindow` on RunChildJsonEventsOptions), so it was
-        // unreachable, and its presence is what made the zero window below look
-        // like a harmless fallback rather than the only path. Issue #16.
+        // Token usage rides on assistant messages, and `message_end` is where the
+        // stream delivers them (`agent_end` then repeats the final one). There is
+        // no `context_usage` event to prefer over this: the string appears nowhere
+        // in the installed pi, and a real `--mode json` capture carries no key
+        // naming a context or a window. So the zero window below is not a
+        // fallback — it is what every caller that omits `contextWindow` gets.
         if (t === 'message_end' && opts.onContextUsage) {
             const msg = evt.message;
             if (msg?.role === 'assistant') {
@@ -209,15 +210,15 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         let stderr = '';
         let aborted = false;
         const discardStdout = opts?.mode === 'text' && opts.discardStdout === true;
-        // Deliver the prompt on stdin, not argv: a large prompt (e.g. an inlined
-        // design doc) blows past the OS command-line limit — Windows CreateProcessW
-        // caps it at 32767 chars and Node throws `spawn ENAMETOOLONG`. When a
-        // prompt is present we open stdin as a pipe; otherwise keep it 'ignore'
-        // (git and other arg-only spawns are unaffected). See GitHub issue #1.
+        // Deliver the prompt on stdin, not argv. A large prompt — an inlined design
+        // doc, say — exceeds the OS argv ceiling and the spawn fails outright rather
+        // than truncating: on this platform it surfaces as `E2BIG`. When a prompt is
+        // present we open stdin as a pipe; otherwise it stays 'ignore', so git and
+        // other arg-only spawns are unaffected.
         const usesStdin = invocation.stdin !== undefined;
         // Model children (json-events) run arbitrary bash — they can `bun run dev &`
         // a server that outlives the child and holds a port, wrecking the final gate
-        // with a self-inflicted EADDRINUSE (mx5 run 9 item 3). Spawn them in their
+        // with a self-inflicted EADDRINUSE. Spawn them in their
         // OWN process group so every such grandchild can be reaped as a unit on exit.
         // Plumbing (git, mode:'text') never backgrounds anything and stays in-group.
         const ownGroup = opts?.mode === 'json-events';
@@ -354,53 +355,43 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             else
                 stdout += chunk;
         });
-        // This accumulation is deliberately unbounded, unlike `discardStdout`
-        // above. The asymmetry was investigated on 2026-07-28 and the "stderr can
-        // overflow V8's max string length" hypothesis is REFUTED at ~5 orders of
-        // magnitude — do not re-open it without new volume evidence.
+        // This accumulation is deliberately unbounded, unlike `discardStdout` above.
         //
-        // Measured ceiling (binary search on `'a'.repeat`, not cited from memory):
-        // node v26.2.0 536,870,888 chars (512 MiB, 2^29-24), bun 1.3.14
-        // 2,147,483,647 (2 GiB). Both throw RangeError, not OOM — node's default
-        // heap is 4192 MiB, well clear of its own string ceiling. If it were ever
-        // reached the severity would be high: a throw in this handler escapes as
-        // an uncaughtException and the enclosing promise never settles (measured),
-        // so it would kill the host, not fail the child.
+        // A string ceiling does exist — the runtime's max string length, which
+        // throws a RangeError rather than running out of memory. What makes the
+        // asymmetry worth a comment is the severity if it were ever hit: a throw
+        // inside this handler is NOT catchable by the enclosing promise. With no
+        // `uncaughtException` handler installed the runtime prints the stack and
+        // exits, so the promise never settles because the host process is gone. It
+        // would take pi down rather than fail one child.
         //
-        // Measured volume, real runs not synthetic: the largest single tool output
-        // in a full mx5 run is 5,043 bytes and that whole run's verify-debug.log is
-        // 112,216 bytes. The heaviest commands in the system are far under —
-        // pi-task's own 2,452-test suite emits 162 bytes of stderr, mx5's
-        // prettier+eslint+tsc lint 90, a cached `bun install` 0. Observed max is
-        // ~106,000x below the node ceiling; reaching it inside the 15-min command
-        // bound would need ~596 KB/s sustained on stderr for the full window.
+        // What keeps it far away is which children reach here: `pi` model children,
+        // `git`, and `npm install --loglevel=error`. Genuinely verbose work — test
+        // runners, builds, boot probes — never uses runChild. It goes through
+        // command-run's `BoundedOutput`, which caps each stream's head and tail and
+        // elides the middle.
         //
-        // The structural reason is the population of children that reach here:
-        // `pi` model children (stderr near-empty), `git`, and one
-        // `npm install --loglevel=error`. Genuinely verbose work — test runners,
-        // builds, boot probes — does not use runChild; final-gate.ts spawns its own
-        // and already caps at 8000 chars. So `discardStdout`'s single caller
-        // (docs-core.ts) is not an oversight to mirror: it discards the verbose
-        // stream and KEEPS stderr precisely because stderr is that call's payload.
-        //
-        // A symmetric `discardStderr` would therefore have no caller, and a naive
-        // cap here would be actively unsafe: consumers disagree about which end
-        // carries the cause — phases.ts:474 takes the tail (-500), phases.ts:936
-        // takes the head (0, 300), and child-runner.ts:172 feeds the whole string
-        // into failure classification.
+        // So a symmetric `discardStderr` would have no caller. `discardStdout`'s one
+        // caller (docs-core) discards the verbose stream and KEEPS stderr precisely
+        // because stderr is that call's payload. A naive cap here would also be
+        // unsafe: consumers disagree about which END carries the cause —
+        // research-worker slices the TAIL of stderr in two places and the HEAD in a
+        // third, and child-runner feeds the whole string into its failure message.
         proc.stderr?.on('data', (d) => {
             lastActivity = Date.now();
             streamWatch?.note();
             stderr += d.toString();
         });
         // One idempotent settle path for close/error/abort. Detaching the abort
-        // listener here is the point: `{once: true}` only fires-and-removes on an
-        // ACTUAL abort, so a child that finishes normally used to leave its
-        // listener on the signal forever. A TaskRunner shares ONE AbortController
-        // across every child of a run, so those listeners accumulated linearly and
-        // each one retained, via `killProc`'s closure, the finished child process,
-        // this invocation (including its full prompt), and `opts` — together with
-        // everything the caller's callbacks close over. See GitHub issue #9.
+        // listener here is the point. `{once: true}` fires-and-removes on an ACTUAL
+        // abort and at no other time, so a child that finishes normally leaves its
+        // listener attached: five children that all exited cleanly still had five
+        // live listeners, all five fired on the eventual abort, and all five
+        // closures survived a forced GC. A TaskRunner shares ONE AbortController
+        // across every child of a run, so they accumulate linearly, and each one
+        // retains — through `killProc`'s closure — the finished child process, this
+        // invocation including its full prompt, and `opts`, along with everything
+        // the caller's callbacks close over.
         let settled = false;
         const cleanup = () => {
             if (stallTimer)
@@ -464,8 +455,8 @@ export function summarizeToolArgs(toolName, args) {
         return a.command.replace(/\s+/g, ' ').trim();
     }
     // Each worker tool's argument shape is its own row's fact (worker-channels.ts);
-    // this used to be a third copy of the names AND a re-statement of each one's
-    // parameters. A row that has nothing to say falls through to the generic keys.
+    // without it this is a third copy of the names AND a re-statement of each
+    // one's parameters. A row that has nothing to say falls through to the generic keys.
     const channel = workerChannel(toolName);
     if (channel) {
         const summary = channel.summarize(a);

package/dist/shared/command-watchdog.d.ts

@@ -2,9 +2,12 @@
  * Command watchdog — the per-tool-call wall-clock machine, shared by both
  * surfaces that can run a command which never returns.
  *
- * WHY THIS LIVES IN shared/: pi's bash tool takes an OPTIONAL `timeout` with NO
- * default (pi-coding-agent core/tools/bash.js), so ANY command the model didn't
- * bound runs forever. That is true in two places, and they are disjoint:
+ * WHY THIS LIVES IN shared/: pi's bash tool takes an OPTIONAL `timeout` and has
+ * no default for it. Its schema says so in as many words — "Timeout in seconds
+ * (optional, no default timeout)" — and its resolver returns `undefined` for an
+ * absent value, which skips arming any timer at all. So ANY command the model
+ * did not bound itself runs forever. That is true in two places, and they are
+ * disjoint:
  *
  *   MAIN SESSION — the implementation turn, handed off via sendUserMessage
  *                  (task/orchestrator.ts). Guarded by registerCommandWatchdog
@@ -20,7 +23,8 @@
  *
  *   main session — ctx.abort() ends the whole agent operation, not just the one
  *                  tool call (pi types it "Abort the current agent operation"),
- *                  and pi runs sibling tool calls CONCURRENTLY by default. So an
+ *                  and pi's agent defaults `toolExecution` to "parallel", so
+ *                  siblings really are in flight together. An
  *                  overrun kills every tool in flight in that turn — including
  *                  one exempted via commandTimeoutExemptTools, which only stops
  *                  a timer being armed FOR that tool, not its being collateral
@@ -79,9 +83,9 @@ export declare function reminderMessage(toolName: string, timeoutMs: number): st
  * child that believes it starts clean may re-apply them or misread the tree.
  * Only the CONVERSATION is gone; the hint must say so precisely.
  *
- * Replaces the generic worker-timeout hint for this case: that one blames
- * "exploring too long", which is the wrong diagnosis for a hung command and
- * never mentions the timeout parameter.
+ * Used instead of the generic worker-timeout hint, which blames the child for
+ * "exploring too long" — the wrong diagnosis for a hung command, and one that
+ * never mentions the `timeout` parameter that would prevent it.
  */
 export declare function commandTimeoutHint(toolName: string, timeoutMs: number, opts?: {
     commandDetail?: string;
@@ -89,9 +93,10 @@ export declare function commandTimeoutHint(toolName: string, timeoutMs: number,
 }): string;
 export declare class CommandWatchdog {
     private readonly deps;
-    /** Armed timers, keyed by the tool call they guard. Tool executions are
-     *  sequential, so this holds at most one entry in normal operation, but the
-     *  map keeps it correct even if pi ever overlaps two calls. */
+    /** Armed timers, keyed by the tool call they guard. A map rather than one
+     *  handle because pi's agent defaults `toolExecution` to "parallel": a batch
+     *  of sibling calls is genuinely in flight together, so several timers can be
+     *  armed at once and each must be cancelled by its own id. */
     private readonly active;
     constructor(deps: WatchdogDeps);
     /** Arm a timer for a starting tool. No-op when the watchdog is off. */
@@ -108,11 +113,75 @@ export declare class CommandWatchdog {
  * Real-clock schedule/cancel. Shared by both adapters; tests substitute a fake
  * scheduler instead.
  *
- * REF'd, for the same measured reason as the stream watchdog's poll (see
- * realStreamTimerDeps): under Bun on windows an unref'd timer never fires once
- * nothing ref'd is pending, and a child sitting in a hung command is exactly
- * that state — so the unref disabled the guard in the one case it exists for.
- * The timer is cleared when the tool ends and in runWorker's `finally`, so it
- * cannot outlive the call it watches.
+ * REF'd deliberately, and NOT unref'd. Measured on this platform, on both
+ * runtimes: an unref'd timer with nothing else ref'd and pending never fires at
+ * all — the process simply exits — while the identical ref'd timer does. A
+ * watchdog whose whole job is to fire while everything else is stuck cannot
+ * afford that. Holding the loop open is safe here because the timer is cancelled
+ * when the tool ends and again in runWorker's `finally`, so it cannot outlive
+ * the call it watches.
  */
 export declare const realTimerDeps: Pick<WatchdogDeps, 'schedule' | 'cancel'>;
+/** What the command watchdog recorded when it killed a child attempt. */
+export interface CommandKill {
+    toolName: string;
+    timeoutMs: number;
+    /** The command line itself, when the tool carried one — quoted into the hint
+     *  so the fresh child knows which call it must not repeat unbounded. */
+    detail?: string;
+}
+/**
+ * The tool-call fields the child-side watchdog reads. Structural rather than
+ * `ToolCall` from child-process.ts, so this module keeps its zero imports and a
+ * caller cannot be forced to reach for the runner's types to arm a timer.
+ */
+export interface WatchedToolCall {
+    name: string;
+    toolCallId?: string;
+    args: unknown;
+}
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine whose `onFire` aborts `signal`, which runChild turns into a
+ * process-GROUP kill — reaping the hung command itself, not just the pi child
+ * holding it.
+ *
+ * LIMIT: the group kill only reaches processes still IN the group. A hung command
+ * that detached a daemon (setsid, nohup, a background dev server) leaves it
+ * running, so the fresh attempt can hit a port the dead attempt's escapee still
+ * holds. There is no cheap fix from here; the restart hint's "check current state"
+ * line is the mitigation.
+ *
+ * Returns null when the watchdog is off, so the caller keeps the plain timeout
+ * signal and no per-call bookkeeping happens at all.
+ */
+export declare function commandWatch(timeoutMs: number): {
+    onStart: (call: WatchedToolCall) => void;
+    onEnd: (toolCallId: string | undefined) => void;
+    killed: () => CommandKill | undefined;
+    signal: AbortSignal;
+    clear: () => void;
+} | null;
+/**
+ * The per-command ceiling for attempt N, halving each time a hang recurs.
+ *
+ * The first attempt gets the full configured ceiling — a genuinely slow build or
+ * test suite deserves it. But every hang-caused restart carries
+ * commandTimeoutHint, which tells the model in as many words to bound its
+ * command; a SECOND hang means it ignored an explicit instruction, and a third
+ * means it ignored it twice. Giving a non-complying child the full ceiling again
+ * makes the worst case three times the ceiling, resting entirely on the model
+ * obeying prose. Halving bounds it at under twice the ceiling while costing a
+ * complying child nothing.
+ *
+ * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
+ * restart budget is shared with loop kills, and a child restarted for LOOPING
+ * never received the bound-your-command hint, so its first hang still deserves
+ * the full ceiling. Only a hang after a hang is defiance.
+ *
+ * Floored at 30s so repeated halving cannot shrink the ceiling to something no
+ * real command could finish inside — but the floor is `min(base, 30s)`, never
+ * above the configured ceiling, so a caller asking for 10s keeps 10s at every
+ * hang count. A base of 0 or less disables the watchdog and stays 0.
+ */
+export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;