pi-ptc-subagents 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,221 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.3.0] - 2026-10-02
+
+### Fixed
+
+- **A failing `bash` binding no longer resolves as a success on pi 1.0.0.** pi 1.0.0 added a
+  non-throwing failure channel — `AgentToolResult.isError`: "Report a failure without throwing. The
+  model sees `content` as an error result, like a thrown error" — and `bash` moved its non-zero exit
+  onto it, so `tools.bash({ command: "exit 3" })` inside a PTC program **resolved** where on 0.86.1
+  it threw. The binding wrapper forwarded only `{ content, details }`, so `isError` was dropped at
+  the boundary and the failure crossed into the program as a successful resolution whose only tell
+  was a sentence at the end of its stdout. The binding layer now translates `isError` back into the
+  rejection ADR-0024's contract already promises, which is what keeps a failing call from being
+  silent.
+- **Disabling pi's `codemode` now brings the PTC surfaces back.** The detected surface asked one
+  question — does this pi ship a `codemode` extension directory — and since pi 0.99.0 that is no
+  longer the same as the one that matters. A user who put `"extensions": ["-builtin:codemode"]` in
+  their settings, or launched with `--no-extensions`, turned the orchestrator off and this package
+  kept handing the orchestration to it: `ptc_run_code` and `ptc_workflow` stayed unregistered and
+  the session was left with `ptc_subagent` and nothing to compose with. Nothing errored; two tools
+  were simply missing.
+
+  A second probe now reads the **switch** — whether pi will actually load the extension — from the
+  same three places pi reads it and in the same order (command line, `<cwd>/.pi/settings.json`,
+  `<agentDir>/settings.json`), and the detected default follows both questions:
+
+  | ships `codemode`? | will load it?                               | surface     |
+  | ----------------- | ------------------------------------------- | ----------- |
+  | yes               | yes (default, or `+builtin:codemode`)       | `subagents` |
+  | yes               | no (`-builtin:codemode`, `--no-extensions`) | `full`      |
+  | no                | —                                           | `full`      |
+
+  An explicit `surfaceMode` still wins; a settings file that cannot be read as a JSON object still
+  falls back to the next source rather than half-applying. Two notices are added at session start:
+  one naming an unreadable settings file, one reporting that a pinned `surfaceMode` disagrees with
+  the table. [ADR-0027](./docs/adr/0027-codemode-switch-decides-surface.md)
+
+  Verified on a real 1.0.0 install for the three reachable cells, asserting on the registered tool
+  set rather than on the resolver: `-builtin:codemode` → `ptc_run_code` + `ptc_workflow`; no switch
+  entry → `ptc_subagent`; `+builtin:codemode` → `ptc_subagent`. The fourth cell (no `codemode` on
+  disk at all) is not reachable on a machine with 1.0 installed and is covered by unit tests only.
+
+### Added
+
+- **The four model-facing tools declare a structured result, so pi's `codemode` can consume them.**
+  A script calling a tool used to get back prose: `ptc_subagent` returned
+  `"Started background task 01J…"` with the id embedded, and the `ptc_task_*` tools returned
+  newline-joined lines to re-parse. `ptc_subagent` is the acute case — it is the only way a
+  `subagents`-surface session can start a subagent at all, because pi's QuickJS sandbox has no file
+  system, no network and no `child_process`.
+
+  All four now declare an `outputSchema` and return a matching `structuredContent`, which codemode
+  scripts receive instead of the text. The shape is a lean projection rather than a mirror of
+  `details`: `ptc_task_list` mirroring `TaskRecord[]` would push ~200 KB of per-record
+  `outputPreview` into a sandbox whose purpose is to keep intermediate data away from the model.
+  `content` and `details` are byte-identical to before on every path, and the model still sees
+  exactly the same text — `structuredContent` is documented as "not sent to the model".
+  [ADR-0028](./docs/adr/0028-structured-results-for-codemode.md); usage in
+  [Structured results for codemode](./docs/usage/structured-results.md).
+
+### Changed
+
+- **The codemode switch now mirrors pi's own matchers instead of approximating them.** Reading the
+  `!` bucket by comparing a pattern's literal prefix was the wrong SHAPE of fix: the bucket is a
+  continuum (globs, character classes, extglobs, nested negations, backslash escapes, multi-segment
+  paths), so every review round found one more member — four costful defects in four rounds, and a
+  412-case sweep of the prefix version still had 24 divergences. A case list cannot be finished.
+  `resolveCodemodeSwitch` now calls the same `minimatch` pi does, through the same
+  `matchesAnyPattern` / `normalizeExactPattern` helpers and with pi's own `baseDir` per scope, which
+  adds one small runtime dependency (`minimatch ^10.2.6`, the version pi itself pins) and **shortens**
+  the code. A 192-case sweep of the mirror has zero divergences in either direction, and all eight
+  reachable cells agree with a real pi 1.0.0 end to end.
+- **The dev toolchain now compiles against pi 1.0.0** rather than 0.86.1 / 0.87.0, so the type check
+  and the whole suite run against the pi this package is actually used with. `peerDependencies`
+  already declared `>=0.86.0`; that claim had no evidence behind it until now. Two consequences of
+  the bump are fixed in the same change: pi narrowed a tool's fifth `execute` parameter from
+  `ExtensionContext` to `ExtensionToolContext` (which adds `tools` and `executeTool`), and the
+  `isError` channel above.
+
+## [1.2.1] - 2026-09-30
+
+### Fixed
+
+- **The `ptc_subagent` tests no longer depend on a pi agent being registered.**
+  Five tests reached for pi's `__smoke_echo` agent, which does not resolve on every pi build,
+  so the suite was green on one platform and red on the release runner. The fixture is now
+  written by the test into `<cwd>/.pi/agents`, the path the agent resolver actually reads at
+  project scope, and every dispatch asks for project scope explicitly rather than inheriting
+  the `user` default, which points at the real `~/.pi`. Verified with an empty `HOME`: the whole
+  suite is green with no ambient agent state at all.
+
+  No product code changed in this release.
+
+## [1.2.0] - 2026-09-30
+
+### Added
+
+- **The surface default is detected from the pi that loaded us (ADR-0026).** With no
+  `surfaceMode` set, a pi that ships its own `codemode` resolves to `subagents` and a pi that
+  does not resolves to `full`. Setting the key always wins, and a probe that cannot answer
+  falls back to `full` rather than guessing.
+
+  This is the one behaviour change that is not invisible on upgrade: on pi 0.99.1 or newer, a
+  user who has never set `surfaceMode` moves from `full` to `subagents`. `codemode` ships
+  inactive (`defaultActive: false`), so such a session has a subagent front and no active
+  orchestrator until codemode is added to the tool list -- the startup warning says so. Set
+  `{ "surfaceMode": "full" }` to keep today's tools.
+
+  Detection is a filesystem probe over `process.argv[1]`, because pi's own tool listing is
+  unavailable at factory time: `getAllTools()` is a `notInitialized` stub until `bindCore`
+  runs, and a throwing factory makes the extension fail to load rather than return an empty
+  list.
+
+  A detection the user cannot see is the one failure this design has, so the outcome is
+  reported: at session start, through the TUI notification channel, a session with no
+  `surfaceMode` set is told how the probe came out whenever it could not answer, and which
+  surface the default therefore is. The expected case — a pi that ships `codemode`, detected as
+  `subagents` — stays silent. A second notice covers the case the probe structurally cannot
+  see: it walks the filesystem, so under `--no-extensions` or `--exclude-tools codemode` it
+  answers `present` for a tool the session does not have. `session_start` cross-checks the
+  probe against pi's own `getAllTools()` and reports a disagreement in either direction.
+
+  Both notices are `ui.notify`, which is TUI-only — and that gap is **new here**, not inherited:
+  measured, three `--print` runs that each emit one produced 0 bytes on stdout and 0 on
+  stderr. The README is the only channel on which a `--print` user learns why they got the
+  surface they got. What is established is that the outcome is issued through the documented
+  TUI channel; no test observes either notice end to end through a real pi TUI.
+
+- **The model-facing surface is now a setting, and a subagent can be started
+  without writing a program (ADR-0025).** A new `surfaceMode` key in
+  `~/.pi/agent/ptc.json` decides what this extension registers: `full`
+  (today's behaviour, and the detected default on a pi without `codemode`)
+  registers `ptc_run_code`, `ptc_workflow` and the `ptc_task_*` trio;
+  `subagents` registers a new top-level `ptc_subagent`
+  plus the `ptc_task_*` trio and leaves orchestration to pi's own `codemode`;
+  `off` registers nothing at all, so the session is stock pi. The new tool takes
+  the same arguments as the `pi.dispatch` binding and calls the same dispatcher,
+  so depth, concurrency and the background task lifecycle behave identically and
+  a task spawned through it is listable with `ptc_task_list`.
+
+  Motivation, measured rather than assumed: pi 0.99.1 ships its own programmable
+  tool calling as the built-in `codemode`, which is stronger than `ptc_run_code` at
+  isolation and tool discovery but cannot spawn a process at all. With both
+  installed the model is taught two programming models per request
+  (`docs/research/codemode-vs-ptc-capability-20260930.md`).
+
+- **The PTC tool descriptions now declare what a binding call resolves to
+  (ADR-0024).** `ptc_run_code` and `ptc_workflow` carry one shared binding
+  contract: a binding result is `{ content, details }`, `content` is an array of
+  content blocks (the text of a text-file result is `result.content[0].text`),
+  `details` is an object or `null`, and there is no `files` / `output` /
+  `matches` / `entries` field to read — `bash`, `grep`, `find` and `ls` return one text block
+  of newline-separated rows that the program splits itself. A `builtin binding`
+  that fails rejects with `ToolCallError`; `pi.dispatch` resolves to a
+  `DispatchResult` with `text` and `status` and no `content`.
+
+  Model-facing only: the wire, the worker and every existing program are
+  unchanged. Field report before: a pty-driven run of the real TUI with PTC mode
+  on produced 31 program crashes across 16 runs, the largest error class being the
+  model treating a binding result as a string or as an object with a `files`
+  field — neither is ever true, and nothing said so
+  (`docs/research/ptc-binding-contract-measurement-20260930.md`).
+
+  Re-measured after the change, same harness and tasks: **0 of those three crash
+  classes in 16 runs**, the correct `result.content[0].text` access in 16 of 16,
+  and the context median for a PTC run down from 36,669 to 8,360 with median
+  turns from 8 to 2. Exact-match rate is not claimed to have improved — it moved
+  10/16 to 11/16 while the control arm moved 15/16 to 13/16, which is this
+  harness's noise floor
+  (`docs/research/ptc-binding-contract-re-measurement-20260930.md`).
+
+### Changed
+
+- **The dispatch concurrency cap is one counter per session, not one per run.** The acquire
+  moved out of the dispatcher and into `dispatch()`, so a single `DispatchSlotCounter` now
+  serves every front: concurrent programs in the same session, the `ptc_subagent` tool, and
+  background children. The value is still `PtcConfig.dispatchConcurrency` (default 8) and the
+  refusal shape is unchanged; what changed is whose calls the cap counts.
+
+  This reduces effective concurrency in two measurable ways, and neither is a rounding
+  difference — 24 concurrent foreground calls against a real fake-`pi` spawn:
+
+  - two concurrent programs that could each have 8 in flight now share 8 (16 spawned -> 8);
+  - a program sharing a session with 8 live background children can now be refused **every**
+    foreground slot (8 foreground spawned -> 0). The refusal is a hard reject with no queue, so
+    an over-cap call is not parked behind a long-running child.
+
+  A single program on its own is unchanged (8 of 24, before and after), which is why the
+  change passed three review rounds. ADR-0016 §2 and ADR-0022 §9 are amended; the depth cap is
+  not.
+
+  The knob is now live rather than dead: the live control is
+  `createBackgroundTaskRuntime({ concurrency })`, which sizes the session counter from
+  `PtcConfig.dispatchConcurrency`. Passing `dispatchConcurrency` through
+  `runPtcProgram({ config })` no longer sizes the cap a pi session uses (measured: 2
+  configured, 8 dispatched).
+
+### Fixed
+
+- **A background task that produced no answer is no longer reported as a
+  success (#70, field report).** A child that hits a rate limit or a model
+  error still exits 0: pi writes the reason onto the assistant `message_end`
+  as `stopReason: "error"`, retries, and closes clean. The background pump
+  read the exit code alone, so such a task was recorded `succeeded` and the
+  model was told it had worked — while `ptc_task_output` answered "(no output
+  yet; task X is succeeded)". `succeeded` now requires the child to exit 0
+  **and** to have produced assistant text, which is the rule
+  `decideCloseOutcome` already applied to the foreground path; one failure now
+  has one verdict and one sentence in both paths. A failing `resolve-exit`
+  writes `errorMessage`, and the child's own `stopReason: "error"` text is
+  carried onto the record so the model is told _why_, not only _that_
+  (ADR-0022 §2, amended). A non-zero exit is still left unlabelled and a model
+  stop still resolves `canceled` — neither is relabelled by this change.
+
 ## [1.1.1] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -74,10 +74,27 @@ const [read, scoutA, scoutB] = await Promise.all([
 
 **Bounded.** Three knobs keep fan-out from running away:
 
-- `PtcConfig.dispatchConcurrency` (default **8**) — hard cap on concurrently in-flight `pi.dispatch` calls per run. The N+1th concurrent call resolves immediately with `{ status: "rejected", errorMessage: "dispatch concurrency limit reached" }` instead of queuing or spawning.
+- `PtcConfig.dispatchConcurrency` (default **8**) — hard cap on concurrently in-flight dispatch **in one pi session**. It is one counter, not one per run: foreground `pi.dispatch`, the top-level `ptc_subagent` front, and live background children all spend it, and a background child holds its slot for its whole lifetime. The N+1th concurrent call resolves immediately with `{ status: "rejected", errorMessage: "dispatch concurrency limit reached" }` instead of queuing or spawning — so a call over the cap is not made to wait for a slot to come back.
 - `PtcConfig.maxDispatchDepth` (default **3**) — recursion bound. The child subprocess loads pi-ptc too, so it can write its own PTC programs and call `pi.dispatch` itself; the `childDepth = parentDepth + 1` is rejected when it would exceed `maxDispatchDepth`. The child sees a `<pi-ptc-context depth="N" max-depth="M">…</pi-ptc-context>` hint appended to its system prompt so it can budget its recursion.
 - `signal` — when the parent run is cancelled (deadline, abort, user Esc), every in-flight child receives `SIGTERM` followed by `SIGKILL` after a 5-second grace window, the same shape as pi's `examples/extensions/subagent/index.ts` reference.
 
+**What the concurrency cap now governs, and which knob is live.** The cap is **one counter per pi
+session** ([ADR-0016](./docs/adr/0016-ptc-dispatch-binding.md) §2 as amended,
+[ADR-0022](./docs/adr/0022-background-dispatch.md) §9), acquired inside `dispatch()` so a single
+owner gates every front. Two consequences are worth stating plainly, because both were measured and
+neither is a rounding difference: two programs running concurrently in one session now share 8
+rather than 8 each, and a program sharing a session with eight live background children can be
+refused **every** foreground slot. The live control is `createBackgroundTaskRuntime({ concurrency })`,
+the call that builds that session counter, and the value it is given is `PtcConfig.dispatchConcurrency`.
+It is not a background-only knob: changing it changes how many foreground children a whole session
+can have in flight.
+
+The `dispatchConcurrency` a caller passes to `runPtcProgram({ config })` sizes the
+dispatcher's own per-run counter, and that counter is only reached when no session counter is
+supplied (`dispatcher.ts` hands the binding `options.dispatchDeps?.slots ?? dispatchSlots`). In a
+pi session a session counter always is, so the per-run one is not what enforces the cap you are
+looking at.
+
 **Opt out.** Pass an explicit binding subset to `createBuiltinBindings` to opt out — the parallel binding is mixed in only when the caller accepts the default set:
 
 ```ts
@@ -111,7 +128,7 @@ A detached pump drives the task's lifecycle (`running` -> `succeeded` / `failed`
 - `ptc_task_output({ taskId, sinceBytes? })` — read a task's captured output, tail-truncated to pi's 50 KB / 2000-line contract (ADR-0015).
 - `ptc_task_stop({ taskId, reason? })` — ask a running task to stop.
 
-Background tasks count against the same `dispatchConcurrency` (default 8) for their whole lifetime and share the `maxDispatchDepth` (default 3) recursion bound. A pre-spawn refusal (depth or concurrency cap, unknown agent) still comes back as the familiar `DispatchResult` with `status: "rejected"`. Full guide: [`docs/usage/bgdispatch.md`](./docs/usage/bgdispatch.md).
+Background tasks count against the same `dispatchConcurrency` (default 8) for their whole lifetime and share the `maxDispatchDepth` (default 3) recursion bound — and since the gate moved into `dispatch()` that cap is the **one session counter** the foreground path uses too, not a second one held beside it. A session running eight long background children therefore has no foreground dispatch headroom left, and a foreground call over the cap is refused outright rather than queued behind them. A pre-spawn refusal (depth or concurrency cap, unknown agent) still comes back as the familiar `DispatchResult` with `status: "rejected"`. Full guide: [`docs/usage/bgdispatch.md`](./docs/usage/bgdispatch.md).
 
 ## TUI rendering
 
@@ -183,10 +200,80 @@ the session. The mode's rationale and rejected alternatives are in [ADR-0010](./
 { "defaultMode": false }
 ```
 
+**Choosing the surface.** `defaultMode` decides whether the session _enters_ PTC mode; `surfaceMode`
+decides which model-facing tools this package registers at all. It is read once, at startup, so a
+surface change needs a new session ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)):
+
+```jsonc
+// ~/.pi/agent/ptc.json
+{ "surfaceMode": "subagents" }
+```
+
+- `off` — a stock pi session: no tool, no `/ptc` command, no briefing.
+- `subagents` — `ptc_subagent` plus the three `ptc_task_*` tools, with pi's own `codemode`
+  doing the orchestration; warns at startup when `codemode` is not in the active tool set.
+- `full` — today's set: `ptc_run_code` / `ptc_workflow` plus the three `ptc_task_*` tools.
+
+**The default is detected, and it is not `full` everywhere.** With no `surfaceMode` key, the surface
+follows two questions, not one ([ADR-0026](./docs/adr/0026-surface-default-is-detected.md),
+[ADR-0027](./docs/adr/0027-codemode-switch-decides-surface.md)):
+
+| does this pi ship `codemode`? | will pi load it?                               | surface     |
+| ----------------------------- | ---------------------------------------------- | ----------- |
+| yes                           | yes (default, or `+builtin:codemode`)          | `subagents` |
+| yes                           | no (`-builtin:codemode`, or `--no-extensions`) | `full`      |
+| no                            | —                                              | `full`      |
+
+Setting the key always wins. A probe that cannot answer falls back to `full` — the safe direction,
+since `subagents` as a failure mode would take away the orchestration tool the session was relying
+on.
+
+> Upgrading onto pi 0.99.1 or newer without setting the key moves you to `subagents`. `codemode`
+> ships **inactive** (`defaultActive: false`), so until you add it to your tool list you get a
+> subagent front with no orchestrator, and the startup warning says so. If you would rather keep
+> today's tools, set `{ "surfaceMode": "full" }`.
+
+> Turning pi's `codemode` **off** — `"extensions": ["-builtin:codemode"]`, or launching with
+> `--no-extensions` — brings the PTC surfaces back on its own. Before ADR-0027 it did not: the
+> detection asked only whether the extension directory exists, so a pi told not to load it still
+> counted as an orchestrator and you got `ptc_subagent` with nothing to compose with. The switch is
+> read from the same three places pi reads it — the command line, `<cwd>/.pi/settings.json`, and
+> `<agentDir>/settings.json` — in the same order.
+
+No file, or a value outside that set, falls back to the detected default and says so at startup
+rather than half-applying: which tools exist is not something to change on a guess.
+
+**A detection you cannot see is the failure this design has**, so the result is reported. With no
+`surfaceMode` key, the outcome is issued through the TUI notification channel at session start —
+how the probe came out and which surface the default therefore is — but only when the probe could
+not answer. A pi that ships `codemode` and is detected as `subagents` is the expected case and says
+nothing. A second notice is issued when the probe and pi's own tool registry disagree, which is the
+case the probe structurally cannot see: it walks the filesystem, so under `--exclude-tools codemode`
+it answers `present` for a tool this session does not have (and the mirror: a restructured `dist`
+answers `not-found` for one pi plainly registers). A third notice covers ADR-0027: a settings file
+that could not be read, and an explicit `surfaceMode` that disagrees with the table — the pinned
+value still wins, and the notice only says so. What is **not**
+established is that either line actually paints in a real pi TUI: a pty capture at review time
+showed neither the notice nor a control marker, and a TUI quits on stdin EOF before a toast
+renders, so that is an unmeasured end to end rather than a broken one. No test in this repository
+observes a notice through a real TUI. If you are relying on the notice rather than on your own
+`surfaceMode` key, verify it once.
+
+**On a `--print` session, none of it prints.** `ui.notify` is the TUI channel; measured across
+three `--print` runs that each emit one of these notices, stdout and stderr received **0 bytes**
+each. That makes this page the only channel on which a `--print` user learns why they got the
+surface they got — ADR-0025's decision-4 warning shares the gap, and there the answer is the same
+one line of JSON: set `surfaceMode` yourself and the detection no longer matters.
+
 **Where it does not run.** Print / JSON / RPC sessions are left exactly as launched, and so is a
 session started with an explicit tool restriction (`--tools`, `--exclude-tools`,
-`--no-builtin-tools`) — the extension does not override what you asked for. If another extension
-changes the tool set while the mode is on, the mode yields and tells you.
+`--no-builtin-tools`, `--no-extensions`) — the extension does not override what you asked for.
+`--no-extensions` does, however, change the **detected surface**: pi's own `codemode` is a built-in
+extension, so turning extensions off means it will not load, and ADR-0027's table resolves the
+default to `full` — you keep `ptc_run_code` / `ptc_workflow` rather than a `ptc_subagent` with
+nothing to compose with. If you would rather pin the surface regardless, set `"surfaceMode"` in
+`ptc.json`. If another extension changes the tool set while the mode is on, the mode yields and
+tells you.
 
 **The important consequence:** in a TUI session, bindings come from the loadout recorded _before_
 the mode narrowed it. That is what keeps `tools.read(…)` working — and it is why a `--tools`

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ExtensionAPI, Skill, truncateTail } from "@earendil-works/pi-coding-agent";
+import "typebox";
 import "@earendil-works/pi-ai";
 import { MessagePort, Worker } from "node:worker_threads";
 //#region src/runtime/ulid.d.ts
@@ -271,6 +272,7 @@ type TaskCommand = {
   outputRef?: string;
   outputBytes?: number;
   outputPreview?: string;
+  childError?: string;
 };
 /** Outcome of one successful command: the persisted record, emitted events, and cursor. */
 interface TransitionResult {
@@ -362,10 +364,11 @@ declare class DispatchSlotCounter {
   release(holder?: string): void;
 }
 /**
- * Injected dependencies for the background branch. The foreground path ignores this object
- * entirely (it uses the module-level {@link DISPATCH_LIFECYCLE}); every field is optional so
- * existing zero-argument call sites keep working. Tests pass an in-memory registry and a
- * mock lifecycle so no real `pi` process is ever spawned.
+ * Injected dependencies. The background branch uses this object for everything; the foreground
+ * branch uses `slots` (the one cap both fronts share since ADR-0026 round 3) and
+ * `lifecycle`. Every field is optional so existing zero-argument call sites keep working, and
+ * both branches fall back to the module-level {@link DISPATCH_LIFECYCLE}. Tests pass an
+ * in-memory registry and a mock lifecycle so no real `pi` process is ever spawned.
  */
 interface DispatchDeps {
   /** Session-level TaskRegistry (ADR-0022 §3). Defaults to a lazy in-memory registry. */
@@ -544,6 +547,139 @@ interface DefaultModeConfig {
  * on** — the caller should surface the problem rather than silently changing behavior.
  */
 export declare function readDefaultModeConfig(agentDir: string): DefaultModeConfig;
+/**
+ * Which model-facing tools this package registers, independent of PTC mode (which decides
+ * which registered tools are *active*). Read from the same agent-dir file as
+ * {@link readDefaultModeConfig}, beside the `defaultMode` key. ADR-0025.
+ *
+ * The order below is the order of increasing responsibility: `off` hands the whole
+ * orchestration question back to pi, `subagents` keeps only the subagent face and lets pi's
+ * `codemode` orchestrate, `full` keeps today's set.
+ */
+declare const SURFACE_MODES: readonly ["off", "subagents", "full"];
+type SurfaceMode = (typeof SURFACE_MODES)[number];
+/**
+ * Whether the pi that launched us will actually LOAD its `codemode` extension.
+ *
+ * - `"absent"` — nothing in any settings file names it, so pi's own default applies, which is to
+ *   load it (`settings.md`: "They load by default").
+ * - `"enabled"` — an explicit `+builtin:codemode`, or `-e builtin:codemode` on the command line.
+ * - `"disabled"` — `-builtin:codemode` or `!builtin:codemode` in a settings file, or `--no-extensions`.
+ *
+ * This is a different question from {@link CodemodePresence}, which asks whether the directory is
+ * on disk. Both are needed, and conflating them is what ADR-0027 fixes: pi 0.99.0 added
+ * `-builtin:<name>`, so "the directory exists" and "codemode will run" stopped being the same
+ * answer, and a probe that only asks the first one hands orchestration to a tool that is not there.
+ */
+type CodemodeSwitch = "absent" | "enabled" | "disabled";
+/** How the switch was decided, so a test can tell a measured answer from a failed read. */
+type CodemodeSwitchSource = "cli" | "project" | "user" | "default" | "invalid";
+/** The switch plus enough provenance to explain it in a notice. */
+interface CodemodeSwitchResolution {
+  switch: CodemodeSwitch;
+  source: CodemodeSwitchSource;
+  /** Set when a settings file could not be read as a JSON object; the switch still resolves. */
+  error?: string;
+}
+/**
+ * The two directories pi resolves the `!` bucket's globs against.
+ *
+ * `matchesAnyPattern` also tests `relative(baseDir, path)` and the basename, so a glob whose
+ * answer depends on where pi's directories sit is only correct for the directories pi actually
+ * used. These are the two it uses: `join(cwd, CONFIG_DIR_NAME)` for project scope -- pi 1.0.0's
+ * `CONFIG_DIR_NAME` is `".pi"`, `package-manager.js:720` -- and `agentDir` for user scope (`:719`).
+ */
+interface CodemodeBaseDirs {
+  project: string;
+  user: string;
+}
+export declare function resolveCodemodeSwitch(argv: readonly string[], projectSettings: unknown, userSettings: unknown, baseDirs?: CodemodeBaseDirs): CodemodeSwitchResolution;
+/**
+ * Read pi's own settings files and resolve the switch.
+ *
+ * Project settings live at `<cwd>/.pi/settings.json` and user settings at
+ * `<agentDir>/settings.json` — the two `DefaultPackageManager` reads, via
+ * `join(this.cwd, CONFIG_DIR_NAME)` and `this.agentDir`.
+ */
+export declare function readCodemodeSwitch(agentDir: string, cwd: string, argv?: readonly string[]): CodemodeSwitchResolution;
+/**
+ * Whether an explicit `surfaceMode` disagrees with what the table above decided.
+ *
+ * The explicit key always WINS — that is what an override is for — so this exists only to be
+ * reported. `off` is exempt: it means "I do not want this package's surface at all", which is a
+ * statement about the package rather than a claim about who orchestrates, and warning about it on
+ * every session would be crying wolf.
+ */
+export declare function surfaceModeConflict(explicit: SurfaceMode | undefined, detected: SurfaceMode): boolean;
+/**
+ * Whether the pi that launched us ships its own `codemode` orchestration tool.
+ *
+ * pi's own tool listing is NOT usable here, and that is why this probe exists at all.
+ * `getAllTools()` and `getActiveTools()` are `notInitialized` stubs until `bindCore` runs
+ * (`loader.js:106-108`), which happens after every factory body has returned. Calling one from
+ * a factory throws, and `initializeExtension` catches that throw while `loadExtension` answers
+ * `{ extension: null, error }` (`loader.js:493-520`) -- a throwing factory makes the extension
+ * fail to load entirely, not degrade to an empty tool list. Registration has to happen in the
+ * factory, so the default has to be knowable there.
+ *
+ * Those line numbers are pi **0.99.1**'s `dist/core/extensions/loader.js`, read from a real
+ * install, and that is the version this reasoning is about rather than the one this repo compiles
+ * against: the 0.86.1 in `devDependencies` has the same two regions at 106-108 and 445-473.
+ *
+ * So this walks the filesystem from the entry script instead. `process.argv[1]` is whatever the
+ * user typed, which for a package-manager install is a shim, so it is resolved first. The answer
+ * is "does this pi ship codemode", NOT "can this session call it": codemode registers with
+ * `defaultActive: false`, so it is absent from `getActiveTools()` even when fully present.
+ * `session_start` is where the second question gets asked, and where a session handed to an
+ * orchestrator that is not there gets told.
+ */
+export declare function probeCodemodePresence(argv?: readonly string[]): CodemodePresence;
+interface CodemodePresence {
+  /** Whether the directory was found. */
+  present: boolean;
+  /** How the answer was reached, so a test can tell a measured yes from a failed probe. */
+  how: "found" | "not-found" | "no-entry" | "unresolvable-entry";
+}
+/** Result of reading the surface mode, with enough detail to warn about a broken file. */
+interface SurfaceModeConfig {
+  surfaceMode: SurfaceMode;
+  source: "file" | "default" | "invalid";
+  error?: string;
+  /**
+   * What the probe found, on the paths where the surface was NOT decided by the file. Absent
+   * when the user set the key: that call never consults the probe (see
+   * {@link readSurfaceModeConfig}), so there is nothing to report.
+   */
+  codemode?: CodemodePresence;
+  /**
+   * Whether pi will actually load its own codemode (ADR-0027). Absent for the same reason as
+   * {@link codemode}: an explicit key short-circuits the probe, so there is nothing to report.
+   */
+  codemodeSwitch?: CodemodeSwitchResolution;
+  /**
+   * What the four-case table decided, carried even when an explicit key overrode it — that
+   * difference is exactly what {@link surfaceModeConflict} reports on.
+   */
+  detected?: SurfaceMode;
+}
+/**
+ * Read `surfaceMode` from the agent-dir config file.
+ *
+ * A pure function over the filesystem, shaped like {@link readDefaultModeConfig} on purpose:
+ * an absent file, an absent key, unparseable JSON, a non-object, a wrong-typed value and an
+ * out-of-set value all resolve to the detected default rather than a hardcoded one, and every
+ * malformed shape additionally reports `invalid` with a reason. A malformed setting must never
+ * half-apply - which tools exist is not something to change on a guess.
+ *
+ * The `presence` and `codemodeSwitch` arguments are parameters rather than hidden calls, so a test
+ * can state the pi it is reasoning about instead of depending on the machine it runs on. Omit
+ * them and the real probes answer, but only on a path that actually needs the answer: they are
+ * resolved inside the fallback branches rather than in a default parameter, because a default
+ * parameter is evaluated on EVERY call -- including the ones an explicit `surfaceMode` key
+ * short-circuits, where the user paid a `realpathSync` plus up to three `statSync` and two
+ * settings reads to set one line of JSON and get a constant.
+ */
+export declare function readSurfaceModeConfig(agentDir: string, presence?: CodemodePresence, codemodeSwitch?: CodemodeSwitchResolution, cwd?: string): SurfaceModeConfig;
 /** Why the mode declined to turn on. Surfaced in the entry notification / debug logs. */
 type ModeBlockReason = "not-tui" | "config-off" | "tools-unavailable" | "restricted-session";
 /** Either the loadout to apply, or the reason the mode stayed off. */
@@ -689,13 +825,26 @@ interface PtcConfig {
    */
   maxParallelSubCalls: number;
   /**
-   * Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls,
-   * enforced by the dispatcher: the next concurrent call resolves
-   * immediately with `{ status: "rejected", errorMessage: "dispatch
-   * concurrency limit reached" }` — never queued, never spawned.
+   * Hard cap on concurrently in-flight dispatch in ONE pi session, not
+   * per run. Enforced inside `dispatch()` by a single
+   * `DispatchSlotCounter`, so every front spends it: concurrent programs,
+   * the `ptc_subagent` tool, and background children (which hold their
+   * slot for the task's whole lifetime). The next call over the cap
+   * resolves immediately with `{ status: "rejected", errorMessage:
+   * "dispatch concurrency limit reached" }` — never queued, never
+   * spawned, and never parked behind a long-running child.
    * Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
-   * ADR-0016 section 2. Independent of `maxParallelSubCalls`: builtin
-   * calls never consume a dispatch slot and vice versa.
+   * ADR-0016 section 2 (as amended 2026-09-30), ADR-0022 section 9.
+   *
+   * Where the number is READ from is the counter's construction, not
+   * this field alone: a pi session's counter is built by
+   * `createBackgroundTaskRuntime({ concurrency })` with this value, and
+   * the dispatcher hands the binding `options.dispatchDeps?.slots ??
+   * dispatchSlots` — so a `runPtcProgram({ config })` override sizes only
+   * the per-run counter, which a pi session never reaches.
+   *
+   * Independent of `maxParallelSubCalls`: builtin calls never consume a
+   * dispatch slot and vice versa.
    */
   dispatchConcurrency: number;
   /** Maximum recursion depth for `pi.dispatch`. The child PTC run spawned by
@@ -1170,8 +1319,29 @@ export declare class TurnPools {
 export interface PtcSubagentsOptions {
   /** Use this session-scoped background runtime instead of constructing one. */
   backgroundRuntime?: BackgroundTaskRuntime;
+  /**
+   * Test seam for ADR-0025's surface mode. When set it wins over the agent-dir `ptc.json`,
+   * so a test never reads the developer's real settings -- and the four test files that all
+   * build this factory through one stub would otherwise inherit whatever the machine happens
+   * to have. Undefined in production, where the file is the only source.
+   */
+  surfaceMode?: SurfaceMode;
+  /**
+   * ADR-0026 test seam: what the codemode probe found. Undefined in production, where the
+   * probe really runs. A test that exercises the DETECTED default states the pi it
+   * assumes rather than inheriting whatever process.argv the test runner happens to have,
+   * which is how the previous version of that test passed for the wrong reason.
+   */
+  codemode?: CodemodePresence;
+  /**
+   * ADR-0027 test seam: whether pi will actually LOAD its own codemode. Undefined in
+   * production, where `readCodemodeSwitch` reads pi's real settings files. Separate from
+   * `codemode` on purpose — a pi can ship the directory and still be told not to load it,
+   * and that is the case this seam exists to state.
+   */
+  codemodeSwitch?: CodemodeSwitchResolution;
 }
 export default function ptcSubagents(pi: ExtensionAPI, options?: PtcSubagentsOptions): void;
 //#endregion
-export type { Binding, BindingContext, BindingTable, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
+export type { Binding, BindingContext, BindingTable, CodemodePresence, CodemodeSwitch, CodemodeSwitchResolution, CodemodeSwitchSource, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, SurfaceModeConfig, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
 //# sourceMappingURL=index.d.ts.map