@mjasnikovs/pi-task 0.38.29 → 0.38.30

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>;

package/dist/shared/model-endpoint.js

@@ -2,18 +2,18 @@
  * model-endpoint — discovery + reachability probe for the model backend(s) a
  * child pi process talks to.
  *
- * The failure this serves (mx5 run 7, validated): the model server went down
- * mid-gate-child and the child hung MUTE for 64 minutes — pi's own
- * connection-error handling only fires when a request FAILS, not when the
- * backend freezes and the open request simply never answers. The stall guard in
- * runChild uses this module to tell the two apart: no output could be honest
- * long work (prompt processing emits nothing for minutes), so only "no output
- * AND the endpoint does not answer" is treated as a dead backend.
+ * The failure this serves: the model server dies mid-child and the child hangs
+ * mute. pi's own connection-error handling cannot help, because it runs from a
+ * catch — a request that FAILS reaches it, a request that simply never answers
+ * does not. The stall guard in runChild uses this module to tell the two apart:
+ * silence alone could be honest long work, since prompt processing emits nothing
+ * while it runs, so only "no output AND the endpoint does not answer" counts as
+ * a dead backend.
  *
- * Discovery is generic: the custom providers pi itself is configured with
- * (models.json `providers.*.baseUrl`), no provider or server names hardcoded.
- * No discoverable endpoint → nothing to probe → the guard NEVER kills (a child
- * on a backend we cannot see must get the benefit of the doubt).
+ * Discovery is generic — the custom providers pi is configured with, read from
+ * models.json `providers.*.baseUrl`, with no provider or server name hardcoded.
+ * No discoverable endpoint means nothing to probe, and the guard then NEVER
+ * kills: a child on a backend we cannot see gets the benefit of the doubt.
  */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -34,9 +34,13 @@ export function discoverModelEndpoints(agentDir = path.join(os.homedir(), '.pi',
     }
 }
 /**
- * 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 async function probeModelEndpoints(urls, timeoutMs = 5_000) {
     if (urls.length === 0)
@@ -59,14 +63,22 @@ export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
  * 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 async function probeChatTemplateCaps(baseUrl, timeoutMs = 2_000) {
     try {

package/dist/shared/pi-invocation.d.ts

@@ -1,11 +1,14 @@
 /** Pick the right way to re-invoke pi: prefer the current pi script under the
- *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
- *  pattern from pi-coding-agent's official subagent example.
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. This mirrors
+ *  pi's own subagent example, which ships a function of the same name and the
+ *  same three-step shape in `examples/extensions/subagent/index.ts`. What is
+ *  added here is the `PI_BIN` override, the `/$bunfs/root/` guard, and `stdin`.
  *
  *  `stdin`, when given, is the prompt to feed the child over stdin instead of as
  *  an argv element — pi reads its prompt from stdin when no positional message
- *  is passed, which keeps a large prompt off the length-limited command line
- *  (see runChild / GitHub issue #1). It is threaded through unchanged. */
+ *  is passed, which keeps a large prompt off the argv ceiling that would
+ *  otherwise fail the spawn outright (see runChild). It is threaded through
+ *  unchanged: every branch below returns it as given. */
 export declare function getPiInvocation(args: string[], stdin?: string): {
     command: string;
     args: string[];

package/dist/shared/pi-invocation.js

@@ -1,17 +1,22 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 /** Pick the right way to re-invoke pi: prefer the current pi script under the
- *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
- *  pattern from pi-coding-agent's official subagent example.
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. This mirrors
+ *  pi's own subagent example, which ships a function of the same name and the
+ *  same three-step shape in `examples/extensions/subagent/index.ts`. What is
+ *  added here is the `PI_BIN` override, the `/$bunfs/root/` guard, and `stdin`.
  *
  *  `stdin`, when given, is the prompt to feed the child over stdin instead of as
  *  an argv element — pi reads its prompt from stdin when no positional message
- *  is passed, which keeps a large prompt off the length-limited command line
- *  (see runChild / GitHub issue #1). It is threaded through unchanged. */
+ *  is passed, which keeps a large prompt off the argv ceiling that would
+ *  otherwise fail the spawn outright (see runChild). It is threaded through
+ *  unchanged: every branch below returns it as given. */
 export function getPiInvocation(args, stdin) {
-    // Test/dev override: point at a specific pi binary directly. Bypasses the
-    // re-invoke-current-script heuristic, which goes wrong under `bun test`
-    // (currentScript is the .test.ts file, not a pi entrypoint).
+    // Test/dev override: point at a specific pi binary directly. It bypasses the
+    // re-invoke-current-script heuristic below, which goes wrong under the test
+    // runner — confirmed by printing it from inside a test, where `process.argv[1]`
+    // is the `.test.ts` file itself. Without this the child would be the runtime
+    // re-running a test file, not pi.
     if (process.env.PI_BIN) {
         return { command: process.env.PI_BIN, args, stdin };
     }

package/dist/shared/pkg-version.d.ts

@@ -1,8 +1,16 @@
 /**
- * The installed pi-task version, read from package.json at runtime so nothing
- * has to be regenerated on release. Two levels up holds for both src/<dir>
- * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
- * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
- * (a User-Agent, a title bar) and none is worth failing over.
+ * The installed pi-task version, read from package.json on every call so no
+ * build step has to bake it in and nothing needs regenerating on release.
+ *
+ * Two levels up is right for BOTH trees: `src/<dir>/../..` and `dist/<dir>/../..`
+ * each land on the package root, because tsconfig.build.json sets
+ * `rootDir: "src"` and tsc therefore reproduces the directory layout under dist.
+ * Called from each, both answer the version package.json declares.
+ *
+ * There are two ways to reach the '0.0.0' fallback and neither throws: an absent
+ * or unreadable package.json is caught, and a `version` that is not a string
+ * fails the typeof guard. Both were run. Throwing would be wrong for what the
+ * two callers do with it — one builds a fetch User-Agent, the other the title on
+ * the /task-config settings box. Neither is worth failing a session over.
  */
 export declare function readPkgVersion(): string;

package/dist/shared/pkg-version.js

@@ -2,11 +2,19 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
- * The installed pi-task version, read from package.json at runtime so nothing
- * has to be regenerated on release. Two levels up holds for both src/<dir>
- * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
- * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
- * (a User-Agent, a title bar) and none is worth failing over.
+ * The installed pi-task version, read from package.json on every call so no
+ * build step has to bake it in and nothing needs regenerating on release.
+ *
+ * Two levels up is right for BOTH trees: `src/<dir>/../..` and `dist/<dir>/../..`
+ * each land on the package root, because tsconfig.build.json sets
+ * `rootDir: "src"` and tsc therefore reproduces the directory layout under dist.
+ * Called from each, both answer the version package.json declares.
+ *
+ * There are two ways to reach the '0.0.0' fallback and neither throws: an absent
+ * or unreadable package.json is caught, and a `version` that is not a string
+ * fails the typeof guard. Both were run. Throwing would be wrong for what the
+ * two callers do with it — one builds a fetch User-Agent, the other the title on
+ * the /task-config settings box. Neither is worth failing a session over.
  */
 export function readPkgVersion() {
     try {

package/dist/shared/reasoning-capability.d.ts

@@ -3,31 +3,38 @@
  *
  * WHY A LOCAL COPY OF PI'S CLAMP
  * ------------------------------
- * pi never reports that it ignored or downgraded a level. Measured live against
- * this machine's llama-server, with a proxy capturing the request body:
+ * pi does not report that it ignored or downgraded a level. Captured on the wire,
+ * with a logging proxy between pi and the model server. All three runs completed
+ * normally and printed no warning of any kind:
  *
  *   1. a model with `reasoning: false` + `--thinking medium`
- *        → the body carries NO reasoning field at all. No error, no warning.
- *   2. `thinkingLevelMap: {off: null, ...}` + `--thinking off`
- *        → silently clamped UP to `medium`. Thinking stays on.
+ *        → the request body carries NO reasoning field and no
+ *          `chat_template_kwargs`. The level is erased, not refused.
+ *   2. `thinkingLevelMap: {off: null, …}` + `--thinking off`
+ *        → thinking STAYS ON: the body arrives with
+ *          `chat_template_kwargs.enable_thinking: true`. The clamp walks UP one
+ *          rung at a time, so `off` lands on `minimal` — not on `medium`.
  *   3. `--thinking low` where `low: null`
- *        → silently clamped to `medium`.
+ *        → `medium` on the wire.
  *
  * All three are the same arithmetic, and it is pure: `getSupportedThinkingLevels`
- * / `clampThinkingLevel` in @earendil-works/pi-ai's models module. Reproducing it
+ * / `clampThinkingLevel` in @earendil-works/pi-ai's `models.js`. Reproducing it
  * lets one predicate — `clampToModel(m, wanted) !== wanted` — catch all three
  * host-side, before a single request is sent.
  *
  * Reimplemented rather than imported because `@earendil-works/pi-ai` is neither a
- * dependency nor a peerDependency of pi-task: it is present only because
- * pi-coding-agent hoists it, so importing it would take a hard dependency on a
- * transitive package to get twenty lines of arithmetic. SOURCE OF TRUTH is that
- * module; `reasoning-capability.test.ts` is where a change upstream shows up.
+ * dependency, a devDependency nor a peerDependency of pi-task — it is in none of
+ * the three, and sits in node_modules only because pi-coding-agent depends on it.
+ * Importing it would take a hard dependency on a transitive package for twenty
+ * lines of arithmetic. SOURCE OF TRUTH is that module, and what follows is
+ * line-for-line identical to it, ladder included. Nothing here imports pi-ai, so
+ * an upstream change will not fail a test — the two have to be re-compared.
  */
 import { type ReasoningGroup, type GroupSetting } from '../config/reasoning.js';
 /**
- * pi's own level ladder, in order. The order is the whole algorithm: an
- * unsupported level is resolved by walking UP first, then down.
+ * pi's own level ladder, in order — the same seven names, in the same sequence,
+ * as `EXTENDED_THINKING_LEVELS` in pi-ai's models.js. The order IS the algorithm:
+ * an unsupported level is resolved by walking UP first, then down.
  */
 export declare const THINKING_LADDER: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export type LadderLevel = (typeof THINKING_LADDER)[number];
@@ -48,9 +55,11 @@ export interface ReasoningModelFacts {
  *    1: the knob is not rejected, it is erased.
  *  - a MISSING map entry means "supported" for the standard levels but
  *    "unsupported" for `xhigh` / `max`, which are opt-in and must be declared.
- *    This is why config/reasoning.ts does not offer those two: a model with no
- *    map at all would receive the raw string, and Qwen3.8's chat template
- *    answers an unknown effort with HTTP 500 rather than a clamp.
+ *    This is why config/reasoning.ts offers neither: without a map the raw
+ *    string reaches the server, and a chat template that does not know the level
+ *    fails rather than clamping. Confirmed against a live server — an effort
+ *    string its template does not handle comes back HTTP 500, raised from inside
+ *    the template itself, while one it does handle returns 200.
  */
 export declare function supportedThinkingLevels(model: ReasoningModelFacts): LadderLevel[];
 /**
@@ -69,15 +78,17 @@ export interface ReasoningMismatch {
 /**
  * Every group whose setting the model will silently change.
  *
- * `inherit` groups are skipped entirely, and that is what keeps a default
- * install permanently quiet: with the shipped all-`inherit` table this returns
- * an empty array for every model, including one with no reasoning at all.
+ * `inherit` groups are skipped entirely, because an inherited group asks for
+ * nothing. That is not the same as a quiet default: the shipped table is mostly
+ * DECIDED, with a single cell left on `inherit`, so a default install is not
+ * silent. Run against a `reasoning: false` model it reports a mismatch for every
+ * group whose level that model cannot honour.
  *
  * It reports mismatches in BOTH directions, which is wider than "warn when
- * reasoning is on but unsupported". The failure actually captured on this
- * machine is the mirror of that — `off` clamped UP to `medium`, so a user who
- * turned thinking off still pays for it — and it is the same comparison. Warning
- * about one direction while staying silent about the other would ship this
- * feature with its own measured failure mode unreported.
+ * reasoning is on but unsupported". The mirror case is the one captured on the
+ * wire — `off` clamped UP with `enable_thinking: true` still going out, so a
+ * user who turned thinking off still pays for it — and it is the same
+ * comparison. Warning about one direction while staying silent about the other
+ * would ship this feature unable to see its own failure mode.
  */
 export declare function reasoningMismatches(model: ReasoningModelFacts | undefined, levels: Readonly<Record<ReasoningGroup, GroupSetting>>): ReasoningMismatch[];