@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/shared/command-watchdog.js

@@ -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
@@ -32,16 +36,17 @@
  *                  {@link commandTimeoutHint} prepended. Coarser by necessity:
  *                  the child's accumulated context is lost.
  */
-/** Whole minutes, floored at 1, for the human-facing ceiling in both messages. */
+/** Whole minutes for the human-facing ceiling in both messages: rounded to
+ *  nearest, then floored at 1 so a sub-minute ceiling never reads "0 minutes". */
 function minutes(timeoutMs) {
     const mins = Math.max(1, Math.round(timeoutMs / 60_000));
     return `${mins} minute${mins === 1 ? '' : 's'}`;
 }
 /**
- * The core correction, shared by both adapters' messages. Two jobs, both
- * learned from live runs: stop the model reporting a killed command as a
- * success, and name the ONE mechanism that prevents a repeat (the bash tool's
- * own `timeout` parameter) rather than leaving "be faster" as the takeaway.
+ * The core correction, shared by both adapters' messages. Two jobs: stop the
+ * model reporting a killed command as a success, and name the one mechanism
+ * that prevents a repeat — the bash tool's own `timeout` parameter — rather
+ * than leaving "be faster" as the takeaway.
  */
 function correction() {
     return (`The command was killed before it finished and produced NO result, so do not `
@@ -82,9 +87,9 @@ export function reminderMessage(toolName, timeoutMs) {
  * 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 function commandTimeoutHint(toolName, timeoutMs, opts) {
     const what = opts?.commandDetail ? ` (${opts.commandDetail})` : '';
@@ -103,9 +108,10 @@ export function commandTimeoutHint(toolName, timeoutMs, opts) {
 }
 export class CommandWatchdog {
     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. */
     active = new Map();
     constructor(deps) {
         this.deps = deps;
@@ -154,14 +160,102 @@ export 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 const realTimerDeps = {
     schedule: (fn, ms) => setTimeout(fn, ms),
     cancel: handle => clearTimeout(handle)
 };
+/**
+ * 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 function commandWatch(timeoutMs) {
+    if (!(timeoutMs > 0))
+        return null;
+    const ctrl = new AbortController();
+    // pi's toolCallId pairs start↔end. When it is absent (a fake stream in a
+    // test, an older pi), fall back to one shared slot: tool executions in a
+    // child are sequential, so a single slot is still correctly paired.
+    const key = (id) => id ?? 'anon';
+    const details = new Map();
+    let killed;
+    const watchdog = new CommandWatchdog({
+        getTimeoutMs: () => timeoutMs,
+        ...realTimerDeps,
+        onFire: (toolCallId, toolName, ms) => {
+            killed = {
+                toolName,
+                timeoutMs: ms,
+                ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
+            };
+            ctrl.abort();
+        }
+    });
+    return {
+        onStart: call => {
+            const id = key(call.toolCallId);
+            const args = call.args;
+            if (typeof args?.command === 'string') {
+                details.set(id, args.command.slice(0, 120));
+            }
+            watchdog.onStart(id, call.name);
+        },
+        onEnd: id => {
+            // Drop the command line with its call. The `'anon'` fallback above is a
+            // SHARED slot, so a stale entry would be attributed to whatever ran
+            // next: a `read` that later overran would be reported as
+            // "ran a `read` command (bun run dev)".
+            details.delete(key(id));
+            watchdog.onEnd(key(id));
+        },
+        killed: () => killed,
+        signal: ctrl.signal,
+        clear: () => watchdog.clearAll()
+    };
+}
+/**
+ * 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 function commandCeilingForAttempt(baseMs, priorHangs) {
+    if (!(baseMs > 0))
+        return 0;
+    const floor = Math.min(baseMs, 30_000);
+    return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
+}

package/dist/shared/fs-text.d.ts

@@ -1,18 +1,24 @@
 /**
  * Text-file reads with line endings normalized to LF.
  *
- * Every task-file parser in pi-task assumes `\n` line endings: the front-matter
- * regex (`^---\n`), the body-delimiter strip, `sectionRegex` (`## h[ \t]*\n`),
- * the checkbox/VERIFY-token line splits. On Windows a task file can carry CRLF
- * (an editor save, or a `git` checkout with `core.autocrlf=true`), and classic
- * Mac tooling can emit lone CR. Any of those makes `parseFrontMatter` return
- * null ("malformed front matter") and every `extractSection` miss.
+ * A checked-out task file need not hold LF. Confirmed against real git: with
+ * `core.autocrlf=true`, a blob committed as LF comes back into the working tree
+ * as CRLF while the stored object is unchanged. Other tooling can write a lone CR.
  *
- * Rather than teach each parser about `\r`, we normalize ONCE at the read
- * boundary — the single place file bytes enter the task layer — so everything
- * downstream sees LF. See GitHub issue #1.
+ * CRLF alone would not need this any more — `parseFrontMatter` and `sectionRegex`
+ * both spell `\r?\n`, and a CRLF task file parses correctly with or without
+ * normalization. LONE CR is the case that still does. Measured on an otherwise
+ * valid task file: with CR line endings `parseFrontMatter` returns null and
+ * `extractSection` finds nothing; normalized first, both succeed. Neither parser
+ * regex can match a lone CR, because both require an `\n`.
+ *
+ * Normalizing once at the read boundary is what keeps that from becoming a third
+ * line-ending case in every parser. Every task-file read goes through
+ * `readTextFile`; the `readFileSync` calls elsewhere in the task layer read
+ * package.json, Makefiles and .env files, which have parsers of their own.
  */
-/** Collapse CRLF and lone CR to LF. `\r\n?` matches Windows CRLF and classic-Mac CR. */
+/** Collapse CRLF and lone CR to LF. The optional `\n` in `\r\n?` consumes a CRLF
+ *  pair as one unit, so a CRLF file does not come back with doubled newlines. */
 export declare function normalizeNewlines(text: string): string;
 /** Read a UTF-8 text file with line endings normalized to LF. */
 export declare function readTextFile(filePath: string): Promise<string>;

package/dist/shared/fs-text.js

@@ -1,19 +1,25 @@
 /**
  * Text-file reads with line endings normalized to LF.
  *
- * Every task-file parser in pi-task assumes `\n` line endings: the front-matter
- * regex (`^---\n`), the body-delimiter strip, `sectionRegex` (`## h[ \t]*\n`),
- * the checkbox/VERIFY-token line splits. On Windows a task file can carry CRLF
- * (an editor save, or a `git` checkout with `core.autocrlf=true`), and classic
- * Mac tooling can emit lone CR. Any of those makes `parseFrontMatter` return
- * null ("malformed front matter") and every `extractSection` miss.
+ * A checked-out task file need not hold LF. Confirmed against real git: with
+ * `core.autocrlf=true`, a blob committed as LF comes back into the working tree
+ * as CRLF while the stored object is unchanged. Other tooling can write a lone CR.
  *
- * Rather than teach each parser about `\r`, we normalize ONCE at the read
- * boundary — the single place file bytes enter the task layer — so everything
- * downstream sees LF. See GitHub issue #1.
+ * CRLF alone would not need this any more — `parseFrontMatter` and `sectionRegex`
+ * both spell `\r?\n`, and a CRLF task file parses correctly with or without
+ * normalization. LONE CR is the case that still does. Measured on an otherwise
+ * valid task file: with CR line endings `parseFrontMatter` returns null and
+ * `extractSection` finds nothing; normalized first, both succeed. Neither parser
+ * regex can match a lone CR, because both require an `\n`.
+ *
+ * Normalizing once at the read boundary is what keeps that from becoming a third
+ * line-ending case in every parser. Every task-file read goes through
+ * `readTextFile`; the `readFileSync` calls elsewhere in the task layer read
+ * package.json, Makefiles and .env files, which have parsers of their own.
  */
 import * as fsp from 'node:fs/promises';
-/** Collapse CRLF and lone CR to LF. `\r\n?` matches Windows CRLF and classic-Mac CR. */
+/** Collapse CRLF and lone CR to LF. The optional `\n` in `\r\n?` consumes a CRLF
+ *  pair as one unit, so a CRLF file does not come back with doubled newlines. */
 export function normalizeNewlines(text) {
     return text.replace(/\r\n?/g, '\n');
 }

package/dist/shared/git-runner.d.ts

@@ -1,33 +1,33 @@
 /**
- * git-runner — the ONE way this codebase runs `git`.
- *
- * WHY IT EXISTS. The right shape already existed, privately, inside
- * `task/git-state-guard.ts`: an abort-aware async runner carrying an injectable
- * `spawnFn` seam, returning `{stdout, exitCode}` and never throwing. Nothing
- * outside that file could reach it, so ~27 other sites hand-rolled their own —
- * with FOUR incompatible failure contracts (throws / returns null / returns '' /
- * returns a result object) and THREE different maxBuffer limits. A caller reading
- * one of them learns nothing about the next, and a git failure means something
- * different at every site. Lifting the seam here does not add a capability; it
- * removes the ambiguity about which contract you are holding.
+ * git-runner — the shared async way to run `git`, and the one to reach for.
  *
  * THE CONTRACT, deliberately narrow:
- *   - NEVER THROWS. A missing git, a non-repo cwd, a fatal subcommand — all of
- *     them arrive as a non-zero `exitCode`. Callers branch on the number, they do
- *     not wrap in try/catch. (`git rev-parse --verify HEAD` on an unborn HEAD is
- *     an ordinary answer, not an exception, and every guard built on this one
- *     treats "git could not tell me" as "no claim" rather than a crash.)
+ *   - NEVER THROWS. Every failure arrives as a non-zero `exitCode`, measured
+ *     rather than assumed: a non-repo cwd answers 128, a bogus subcommand
+ *     answers 1, `git rev-parse --verify HEAD` on a freshly-init'd repo with an
+ *     unborn HEAD answers 128, and even a MISSING binary comes back as
+ *     `{exitCode: 1, aborted: false}` instead of rejecting. Callers branch on
+ *     the number, they do not wrap in try/catch, and every guard built on this
+ *     treats "git could not tell me" as "no claim" rather than a crash.
  *   - Only `stdout` and `exitCode` are exposed. stderr is deliberately absent:
- *     the callers that legitimately need it (auto-commit's identity-failure
- *     sniffing) also need `aborted`, and widening this type for them would push
- *     two fields nobody else reads onto every call site.
+ *     the caller that legitimately needs it (auto-commit's identity-failure
+ *     sniffing) also needs `aborted`, and widening this type for it would push
+ *     two fields nobody else reads onto every call site. That one caller goes
+ *     to `runChildDefault` directly instead.
  *   - `signal` is honoured by the underlying runChild, including its listener
- *     detach discipline (GitHub issue #9) — a run-long orchestrator signal does
- *     not accumulate one listener per git invocation.
- *   - `env` entries are MERGED over `process.env` (the GIT_INDEX_FILE
- *     throwaway-index pattern), not substituted for it.
- *   - `spawnFn` is the test seam: pass a fake from `test-utils/fake-spawn.ts` and
- *     the runner never touches a real repo.
+ *     detach discipline — a run-long orchestrator signal does not accumulate
+ *     one listener per git invocation.
+ *   - `env` entries are MERGED over `process.env`, not substituted for it, which
+ *     is what lets git-state-guard point `GIT_INDEX_FILE` at a throwaway index
+ *     without losing PATH and HOME. Confirmed: such a call still resolves the
+ *     repo normally.
+ *   - `spawnFn` is the test seam: pass a fake from `test/test-utils/fake-spawn.ts`
+ *     and the runner never touches a real repo.
+ *
+ * It is NOT universal, which matters before assuming any git call arrived here.
+ * Several sites still invoke git themselves with `spawnSync`, each carrying its
+ * own timeout and one its own maxBuffer, and accept-debt goes through the
+ * bounded command runner instead.
  */
 import { type SpawnFn } from './child-process.js';
 export interface GitRunner {

package/dist/shared/git-runner.js

@@ -1,33 +1,33 @@
 /**
- * git-runner — the ONE way this codebase runs `git`.
- *
- * WHY IT EXISTS. The right shape already existed, privately, inside
- * `task/git-state-guard.ts`: an abort-aware async runner carrying an injectable
- * `spawnFn` seam, returning `{stdout, exitCode}` and never throwing. Nothing
- * outside that file could reach it, so ~27 other sites hand-rolled their own —
- * with FOUR incompatible failure contracts (throws / returns null / returns '' /
- * returns a result object) and THREE different maxBuffer limits. A caller reading
- * one of them learns nothing about the next, and a git failure means something
- * different at every site. Lifting the seam here does not add a capability; it
- * removes the ambiguity about which contract you are holding.
+ * git-runner — the shared async way to run `git`, and the one to reach for.
  *
  * THE CONTRACT, deliberately narrow:
- *   - NEVER THROWS. A missing git, a non-repo cwd, a fatal subcommand — all of
- *     them arrive as a non-zero `exitCode`. Callers branch on the number, they do
- *     not wrap in try/catch. (`git rev-parse --verify HEAD` on an unborn HEAD is
- *     an ordinary answer, not an exception, and every guard built on this one
- *     treats "git could not tell me" as "no claim" rather than a crash.)
+ *   - NEVER THROWS. Every failure arrives as a non-zero `exitCode`, measured
+ *     rather than assumed: a non-repo cwd answers 128, a bogus subcommand
+ *     answers 1, `git rev-parse --verify HEAD` on a freshly-init'd repo with an
+ *     unborn HEAD answers 128, and even a MISSING binary comes back as
+ *     `{exitCode: 1, aborted: false}` instead of rejecting. Callers branch on
+ *     the number, they do not wrap in try/catch, and every guard built on this
+ *     treats "git could not tell me" as "no claim" rather than a crash.
  *   - Only `stdout` and `exitCode` are exposed. stderr is deliberately absent:
- *     the callers that legitimately need it (auto-commit's identity-failure
- *     sniffing) also need `aborted`, and widening this type for them would push
- *     two fields nobody else reads onto every call site.
+ *     the caller that legitimately needs it (auto-commit's identity-failure
+ *     sniffing) also needs `aborted`, and widening this type for it would push
+ *     two fields nobody else reads onto every call site. That one caller goes
+ *     to `runChildDefault` directly instead.
  *   - `signal` is honoured by the underlying runChild, including its listener
- *     detach discipline (GitHub issue #9) — a run-long orchestrator signal does
- *     not accumulate one listener per git invocation.
- *   - `env` entries are MERGED over `process.env` (the GIT_INDEX_FILE
- *     throwaway-index pattern), not substituted for it.
- *   - `spawnFn` is the test seam: pass a fake from `test-utils/fake-spawn.ts` and
- *     the runner never touches a real repo.
+ *     detach discipline — a run-long orchestrator signal does not accumulate
+ *     one listener per git invocation.
+ *   - `env` entries are MERGED over `process.env`, not substituted for it, which
+ *     is what lets git-state-guard point `GIT_INDEX_FILE` at a throwaway index
+ *     without losing PATH and HOME. Confirmed: such a call still resolves the
+ *     repo normally.
+ *   - `spawnFn` is the test seam: pass a fake from `test/test-utils/fake-spawn.ts`
+ *     and the runner never touches a real repo.
+ *
+ * It is NOT universal, which matters before assuming any git call arrived here.
+ * Several sites still invoke git themselves with `spawnSync`, each carrying its
+ * own timeout and one its own maxBuffer, and accept-debt goes through the
+ * bounded command runner instead.
  */
 import { runChildDefault } from './child-process.js';
 export function makeGit(cwd, signal, spawnFn) {

package/dist/shared/leaked-tool-call.d.ts

@@ -2,10 +2,9 @@
  * Detect tool calls that leaked into a child's assistant *text* instead of
  * being executed.
  *
- * Background: every child pi runs under `--mode json`; pi-task only ever treats
- * a structured `tool_execution_start` event as a tool call (see
- * shared/child-process.ts). When a local model emits a call in a markup dialect
- * pi's harness doesn't recognise — e.g.
+ * A call only counts when a structured `tool_execution_start` event fires —
+ * shared/child-process.ts recognises nothing else. Model-side tool-call markup
+ * like
  *
  *     <tool_call>
  *     <function=bash>
@@ -13,14 +12,21 @@
  *     </function>
  *     </tool_call>
  *
- * pi passes the raw markup through as ordinary assistant text. The command never
- * runs, no event fires, and pi-task's guards (loop detector, widget) never see
- * it. The phase then "passes" on its only gates (non-empty text + exit 0) and
- * the unexecuted call flows downstream — a silently skipped beat.
+ * is not a format pi itself parses: those tags appear nowhere in any installed
+ * pi package. So whether such a turn RUNS is decided entirely by the inference
+ * server in front of it, and both outcomes are real.
  *
- * This is fundamentally an upstream mismatch (model output format ↔ pi's parser)
- * that pi-task cannot fix. What it CAN do is notice the leaked markup and refuse
- * to accept the turn, so the skip becomes visible instead of silent.
+ * Checked against a live endpoint, the server parsed the dialect itself and
+ * handed pi structured tool calls — the markup EXECUTED rather than leaking, and
+ * the parse was sloppy enough to fold the closing tags and the surrounding prose
+ * into the command argument. A server that does not parse it produces the case
+ * this module exists for: pi receives the markup as ordinary assistant text, the
+ * command never runs, no event fires, and pi-task's guards never see it. The
+ * turn then clears its only acceptance gates — non-empty assistant text and exit
+ * 0 — and the unexecuted call flows downstream as a silently skipped beat.
+ *
+ * pi-task cannot fix the mismatch. What it CAN do is notice the markup in the
+ * answer and refuse the turn, so the skip becomes visible instead of silent.
  */
 export declare const MAX_LEAK_RETRIES = 2;
 /**

package/dist/shared/leaked-tool-call.js

@@ -2,10 +2,9 @@
  * Detect tool calls that leaked into a child's assistant *text* instead of
  * being executed.
  *
- * Background: every child pi runs under `--mode json`; pi-task only ever treats
- * a structured `tool_execution_start` event as a tool call (see
- * shared/child-process.ts). When a local model emits a call in a markup dialect
- * pi's harness doesn't recognise — e.g.
+ * A call only counts when a structured `tool_execution_start` event fires —
+ * shared/child-process.ts recognises nothing else. Model-side tool-call markup
+ * like
  *
  *     <tool_call>
  *     <function=bash>
@@ -13,25 +12,34 @@
  *     </function>
  *     </tool_call>
  *
- * pi passes the raw markup through as ordinary assistant text. The command never
- * runs, no event fires, and pi-task's guards (loop detector, widget) never see
- * it. The phase then "passes" on its only gates (non-empty text + exit 0) and
- * the unexecuted call flows downstream — a silently skipped beat.
+ * is not a format pi itself parses: those tags appear nowhere in any installed
+ * pi package. So whether such a turn RUNS is decided entirely by the inference
+ * server in front of it, and both outcomes are real.
  *
- * This is fundamentally an upstream mismatch (model output format ↔ pi's parser)
- * that pi-task cannot fix. What it CAN do is notice the leaked markup and refuse
- * to accept the turn, so the skip becomes visible instead of silent.
+ * Checked against a live endpoint, the server parsed the dialect itself and
+ * handed pi structured tool calls — the markup EXECUTED rather than leaking, and
+ * the parse was sloppy enough to fold the closing tags and the surrounding prose
+ * into the command argument. A server that does not parse it produces the case
+ * this module exists for: pi receives the markup as ordinary assistant text, the
+ * command never runs, no event fires, and pi-task's guards never see it. The
+ * turn then clears its only acceptance gates — non-empty assistant text and exit
+ * 0 — and the unexecuted call flows downstream as a silently skipped beat.
+ *
+ * pi-task cannot fix the mismatch. What it CAN do is notice the markup in the
+ * answer and refuse the turn, so the skip becomes visible instead of silent.
  */
 // A child that wrote a tool call as plain text (wrong dialect, never executed)
 // gets re-prompted with a correction hint up to this many times before the
 // caller gives up. Mirrors MAX_LOOP_RESTARTS: 3 attempts total.
 export const MAX_LEAK_RETRIES = 2;
-// The Hermes-style wrapper a leaked call is most often wrapped in. pi-task never
-// legitimately emits this tag, so its presence alone is a confident signal.
+// The Hermes-style wrapper. Nothing else in this codebase emits the tag — its
+// only other appearance is the correction hint below, which names it back to the
+// model — so seeing it in an answer is signal enough on its own.
 const TOOL_CALL_WRAPPER = /<tool_call\b[^>]*>/i;
 // The "XML function call" dialect: <function=name> … <parameter=key>. Either tag
-// alone is too weak (a stray "<function=x>" can appear in prose or source), so we
-// require the structural pair before flagging it.
+// alone is too weak — one can appear in prose or in source — so the structural
+// PAIR is required. Confirmed: a lone <function=bash> and a lone
+// <parameter=command> each return null, and only the two together flag.
 const FUNCTION_TAG = /<function=[\w.-]+\s*>/i;
 const PARAMETER_TAG = /<parameter=[\w.-]+\s*>/i;
 /**

package/dist/shared/model-endpoint.d.ts

@@ -1,21 +1,26 @@
 /** Base URLs of every custom provider pi is configured with (possibly none). */
 export declare function discoverModelEndpoints(agentDir?: string): string[];
 /**
- * true → at least one endpoint ANSWERED (any HTTP status counts — a 404 still
- * proves the server is alive); false → every probe was refused or hung past the
- * timeout. An empty list is true: nothing to probe means never kill.
+ * true → at least one endpoint ANSWERED. Any HTTP status counts, because the
+ * question is liveness, not correctness: probing a path that 404s still returns
+ * true, while a closed port returns false. Both confirmed against a live server.
+ * An empty list is true — nothing to probe means never kill.
+ *
+ * `models` is joined RELATIVELY here, and deliberately: it lives under the
+ * OpenAI-compatible prefix a baseUrl already carries. Contrast `/props` below.
  */
 export declare function probeModelEndpoints(urls: string[], timeoutMs?: number): Promise<boolean>;
 /**
  * What a llama.cpp server's own chat template can actually do about reasoning,
  * as reported by `GET /props`.
  *
- * This is the only source of truth that does NOT come from models.json. It
- * answers the one question the host-side clamp cannot: *is models.json lying
- * about the server?* — the case that matters being pi's built-in llama.cpp
- * provider, which hardcodes `reasoning: false`, so anyone who reached their
- * server through `/login llama.cpp` rather than a hand-written provider entry
- * has a dead knob and nothing to tell them so.
+ * This is the only source of truth that does NOT come from models.json, and it
+ * answers the question the host-side clamp cannot: is models.json lying about
+ * the server? The case that matters is pi's built-in llama.cpp provider, which
+ * really does hardcode `reasoning: false` — the literal line is in
+ * `extensions/llama/provider.js`, under `LLAMA_PROVIDER_ID = "llama.cpp"`. So
+ * anyone who reached their server through `/login llama.cpp` rather than a
+ * hand-written provider entry has a dead knob and nothing to tell them so.
  */
 export interface ChatTemplateCaps {
     /** The template reads `reasoning_effort` — i.e. levels, not just on/off. */
@@ -30,13 +35,21 @@ export interface ChatTemplateCaps {
  * answer worth having" — not a llama.cpp server, unreachable, or a body in a
  * shape this does not recognise.
  *
- * `null` is a first-class result, not an error: every non-llama.cpp backend
- * returns it, and the caller must degrade to the models.json view rather than
- * warn about a server it could not read. Never throws.
+ * `null` is a first-class result, not an error: a backend that does not serve
+ * this shape returns it, and the caller must degrade to the models.json view
+ * rather than warn about a server it could not read. Never throws — a closed
+ * port answers `null`, confirmed.
+ *
+ * The LEADING SLASH in `/props` is load-bearing, because `/props` lives at the
+ * server ROOT while a configured baseUrl carries an OpenAI-compatible prefix.
+ * How a relative `'props'` resolves depends on whether that prefix ends in a
+ * slash, which is not something this can rely on:
+ *
+ *     new URL('props',  'http://host/v1')   →  /props
+ *     new URL('props',  'http://host/v1/')  →  /v1/props     ← 404
+ *     new URL('/props', either)             →  /props
  *
- * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
- * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
- * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
- * which this would report as `null`, i.e. as a silent loss of the better signal.
+ * A 404 would come back from here as `null`, silently losing the better signal.
+ * The absolute form is right for both.
  */
 export declare function probeChatTemplateCaps(baseUrl: string, timeoutMs?: number): Promise<ChatTemplateCaps | null>;