pi-ptc-subagents 5.0.1 → 6.0.0

package/CHANGELOG.md

@@ -1,1265 +0,0 @@
-# Changelog
-
-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).
-
-## [5.0.1] - 2026-10-20
-
-### Changed
-
-- **pi 1.3.0 is now measured, not merely claimed.** The package declares
-  `@earendil-works/pi-coding-agent: ">=0.86.0"`, so it has always _claimed_ to work on every pi
-  release in that range — but 1.3.0, published on 2026-10-19, had never been measured. The
-  differential table's measured versions stopped at 1.2.0 and the compatibility matrix's version
-  list did not name it. pi 1.3.0 was installed on its own and the forty codemode-switch cases were
-  driven through **its own** `DefaultPackageManager.resolve()`: it answered identically to 1.2.0 on
-  all forty, and the static capability probe answered ✓ on all sixteen capability points. The
-  1.3.0 column is that measurement, not an inference from 1.2.0 being older. A user on pi 1.3.0
-  now has a version whose behaviour this package has actually observed rather than assumed.
-- **The test toolchain moves to vitest 5, and the compatibility matrix can measure the version the
-  repository currently pins.** `vitest` 4.1.11 → 5.0.5, `@vitest/coverage-v8` 4.1.11 → 5.0.5,
-  `vite-plus` 0.3.3 → 1.3.0, `oxfmt` 0.70.0 → 0.73.0, `oxlint` 1.85.0 → 1.89.0, `@types/node`
-  22.20.4 → 26.6.5. The coverage provider and the test runner have to move together —
-  `@vitest/coverage-v8@5.0.5` declares `vitest: 5.0.5` as a peer, and the mismatched pair is what
-  produced 79 unhandled rejections (one per test file) in the upgrade's own CI. Separately,
-  `scripts/pi-compat-matrix.mjs` decided "this devDependency entry was not found" by asking
-  whether **replacing the version changed the text** — and replacing `1.3.0` with `1.3.0` does
-  not change the text, so the matrix could not measure the version the repository currently pins.
-  It asks whether the pattern matched now, and a test that _runs_ the function pins that.
-- **The toolchain bump reformats 26 markdown files.** oxfmt 0.73 changed list-continuation
-  indentation and thematic-break fences. No prose changed. The files it touched carry a single
-  unpaired `---` rather than a YAML frontmatter block, so the site's frontmatter stripping never
-  matched them and does not match `***` either; the three files that do carry real frontmatter are
-  untouched.
-
-### Fixed
-
-- **Nothing in the published package's behaviour changed.** The runtime code, the tool
-  descriptions, the argument and result shapes and the declared peer range are all as 5.0.0
-  shipped them; this release carries development-side and documentation-side work only.
-
-## [5.0.0] - 2026-10-19
-
-### Added
-
-- **A dispatch reports the model its child actually ran.** The model used to be resolved inside the
-  child and never came back: neither `pi.dispatch`'s `DispatchResult` nor a background
-  `TaskRecord` said which provider or model served the call, so a wrong-model delegation could
-  only be inferred from a failure after the fact. Both now carry an optional observed-model pair —
-  observed by the host from the child's own assistant turns (last turn wins), not taken from the
-  request — and the model-facing surfaces state the same fact as a `model: provider/id` line on
-  `ptc_subagent` and `ptc_task_output` and as a `model=` fact in a refusal. A transcript that
-  carries only a model id reports the id alone; the absence of both means no observed assistant turn
-  named the pair — no turn, a supported pi that does not report it, or an old record — not "the
-  model is unknown". A background record gains the pair at the same terminal close that writes
-  `usage`, so a failed or canceled close that named a model still states it. The pair is named
-  `observedProvider` / `observedModel` (ADR-0045): the result's `model` input is the requested
-  model, and two different facts no longer share a name. Records written before the rename are
-  still read (the field rename itself is breaking for program-visible result shapes — see the
-  rename entry under Changed). The rendered value is stripped of ANSI escape sequences and
-  control characters and head-capped at 200 characters before it enters model-facing text,
-  because the pair is untrusted child wire data. See
-  ADR-0044, ADR-0016 §"The child's model", and ADR-0022 §3 as amended.
-- **The `ptc_subagent` call row states the model a generalist dispatch will inherit.** When the
-  call names no model and no agent (a generalist child, where a definition cannot pin the tier),
-  the request row says `model=inherit` and its expanded view names the provider/id the caller's
-  session is on; a named agent gets no such claim, and a pinned `model` is stated as before. This
-  is a request fact captured at the call's first render, so a later model switch does not change
-  an already-rendered row — and it is not the observed model, which still appears only after the
-  child ran. ADR-0044.
-
-### Changed
-
-- **BREAKING — the observed-model fields are named `observedProvider` / `observedModel`.**
-  `DispatchResult.provider` / `model` and `TaskRecord.provider` / `model` carried the observed
-  model, while the input's `model` is the requested model; the shared name made two different
-  facts look comparable. The output fields are renamed, the input keeps its name, the child wire
-  and the model-facing `model:` text are unchanged, and a record written before the rename is
-  normalized on read so its observation is not lost. No aliases: the old result keys are removed,
-  which is why this is breaking for program-visible result shapes. See ADR-0045.
-- **BREAKING — a dispatch that names no model now runs on the caller session's current model, not
-  pi's global default.** `pi.dispatch` and `ptc_subagent` resolve the child's model first match
-  wins: the dispatch's `model` argument, then the agent definition's frontmatter `model:`, then
-  the calling session's **current** model, then pi's configured default. A session that switched
-  provider or model mid-conversation now carries that switch into its next dispatched child — the
-  background-dispatch guide previously said the opposite, and that statement is what this changes.
-  Resolution is a snapshot at spawn: a model switched after the child starts does not change it, a
-  nested dispatch inherits the child's own session model, and re-running the dispatch is how a
-  caller picks up a new model. Tiers 1–2 are unchanged, so pinning the model at the call site or in
-  the definition is the explicit opt-out; no config key and no `model: "inherit"` sentinel is
-  added. A direct library caller with no context model, an older pi, or a session started without a
-  model all fall through to pi's default exactly as before — the session read is structural, so
-  the declared 0.86.0 floor gains no new pi type dependency. See ADR-0044 for the decision and its
-  rejected alternatives.
-
-### Fixed
-
-- **A failed foreground dispatch no longer loses the child's own failure.** The child is a pi
-  subprocess: a rate limit or a model error can make it exit 0 after writing
-  `stopReason: "error"` and an `errorMessage` on its assistant turn. The foreground loop
-  discarded that text and reported the generic `dispatch produced no final text`, while the
-  background registry already recorded the child's reason (issue #70's rule). The close decision now
-  returns the child's reported error verbatim, using the background registry's rule — the child's
-  own error outranks the exit-code and truncation inference — with cancellation still first:
-  cancelled, then exit-0-with-text (fulfilled), then the child's error, then exit-0-without-text,
-  then truncation. It logs one warning on that newly diagnosed path only. `stderr` is no longer
-  described as guaranteed; `errorMessage` is the structured failure channel. This is
-  foreground/background parity: one verdict and one sentence for one failure. See ADR-0044
-  Decision 3 and ADR-0016 §Decision 3.
-- **`ptc_subagent refused the call: undefined` is gone.** A rejected dispatch without an
-  `errorMessage` used to render the literal string `undefined`, telling the model nothing the
-  dispatcher knew. The refusal now states the cause plus bounded facts the result already carries —
-  whether a child ran or the harness declined to start, the exit code, turns, report channel, and
-  the observed model when there is one — tail-bounded to 800 characters so a provider's actionable
-  status code survives the cut. See ADR-0044 Decision 3.
-
-## [4.0.0] - 2026-10-19
-
-### Added
-
-- **The `ptc_subagent` call row shows the dispatch, not its argument dump.** The tool had no
-  renderer, so pi fell back to its raw argument serialisation — one enormous
-  `ptc_subagent task="…\\n\\n…"` line of JSON-escaped prose (2026-10-19 field report). It now
-  registers a `renderCall`: collapsed it reads as a heading (agent, foreground/background and
-  read-only flags, and a pinned `model` when one was passed) with one task preview line and
-  `… 还有 N 行`; `ctrl+e` expands `label` / `why` rows and the task block — the first task line
-  plus up to the existing `MAX_LOG_LINES_EXPANDED` continuation lines, so no new cap is
-  introduced. Follows ADR-0013's "no escaped JSON in the call row" rule.
-- **`whyEnabled`, a default-on switch for the dispatch `why` block.** `~/.pi/agent/ptc.json` takes a
-  boolean `whyEnabled`; when it is `false`, a `why` passed to `pi.dispatch` / `ptc_subagent` is
-  dropped instead of delivered, and both the foreground result and the background record say that a
-  suppression happened. **The switch fails on:** a non-boolean value, an unparseable file, or a file
-  that is not a JSON object all leave the feature ON — a broken value must never remove it. A broken
-  _key_ is reported once at `session_start` with the path, the key and the type that arrived; a broken
-  _file_ is already reported by the default-mode reader, so one typo produces one notice. The
-  `why` argument stays on the schema either way, so a running program is never rejected for passing
-  an argument whose value the switch drops. `DispatchResult.whySuppressed` and
-  `TaskRecord.whySuppressed` record **that a reason was withheld, never what it was** — a background
-  dispatch returns a handle rather than a result, so without the record it would have no way at all
-  to say so. See ADR-0043.
-- **`/ptc why on|off`**, a session-scoped override for the switch above. It records one session entry
-  and never writes `ptc.json` — the difference is "about this conversation" against "about every
-  future one". A resumed session restores the last record; a new one starts from the file. Bare
-  `/ptc why` reports the value _and_ which of the two is in force, and an argument that is neither
-  `on` nor `off` warns and changes nothing. See ADR-0043.
-- **A succeeded background task's completion notification now states its report channel.** The
-  `<bg-task-notification>` for a `succeeded` record gains a `<report-channel>` child —
-  `tool`, `prompt-json`, `none` or `opted-out`, the same **total** field ADR-0032 defines —
-  rendered between `<error-message>` and `<output-ref>`. Before this, a model that wanted to
-  know whether a finished child had honoured the report contract had to poll `ptc_task_output`;
-  the push it already receives now answers it, once per finished child. The element is absent from
-  every other event because only a `succeeded` close declares a channel: a running task has not
-  reported _yet_, and a `failed` / `lost` / `canceled` close has no report claim to state
-  (`none` and `opted-out` are claims about a finished child, not the absence of one). See
-  ADR-0022 §7 as amended (2026-10-19).
-
-### Changed
-
-- **BREAKING — a dispatch's `goal` is now `why`.** `pi.dispatch` and `ptc_subagent` took an
-  optional `goal` since 3.4.0; that argument is now `why`, and the child's block is now
-  `<pi-ptc-why>` instead of `<pi-ptc-goal>`. A PTC program that passes `goal` must pass `why`.
-  The block's **wording is unchanged** — it still reads "This goal is context for doing it well" —
-  because that sentence was held constant across ADR-0042's 180 runs and renaming the tag does not
-  re-test the contrast; rewriting the sentence would change what was held still. See ADR-0043.
-  The rename is not cosmetic: in the agent ecosystem `goal` names an objective or a loop, a thing
-  worked toward over time, which is not what this argument holds — the reason one slice was cut out.
-  `background` was the other candidate and was unavailable, because the dispatch schema already
-  carries a `background` argument meaning "detach the child". No compatibility alias is kept: the
-  only consumer is a model reading the live schema each session, and a second name for one value
-  would cost exactly the comprehension this change buys back.
-- **The background-dispatch guide now says which model a dispatched child runs, and that it is
-  not the caller's.** The child is a fresh `pi` subprocess, so its model resolves — first match
-  wins — as the dispatch's `model` argument, then the named agent definition's frontmatter
-  `model:`, then pi's own global default; the calling session's current model (and therefore a
-  provider switched to mid-session) is **not** inherited. Recorded after the 2026-10-19 field
-  report: the parent had switched provider, and the child it dispatched afterwards ran on pi's
-  default provider and hit a 429. No behaviour change — the resolution order is what the code
-  already did, and the guide states it so the failure is also preventable. See the background
-  dispatch guide, `docs/usage/bgdispatch.md`.
-- **The TUI task panel now shows why a background task failed.** The `task-output` panel prints
-  the record's failure reason as an `error: …` line first in the output block — ahead of the
-  preview or the empty-output placeholder — and the `task-list` panel appends one to each
-  `failed` / `lost` row whose record carries an `errorMessage`, so a child that died before
-  writing output stays legible in the panel instead of as an empty preview, without a
-  `ptc_task_output` call. A `lost` record carries the sweep's reason
-  (`session_ended_while_running` / `lost_on_session_restart`) and gets the row too; a
-  `canceled` task carries no reason and does not. Both rows reuse the panel's existing
-  `MAX_ERROR_CHARS` bound (120, first non-blank line), so no new cap or number is added, and
-  neither annotation counts against the panel's row caps — see ADR-0022 §11. A settled
-  failure's empty-output placeholder also stops claiming `(no output yet)`: with a reason on the
-  record it reads `(no output)`, while a page with no recorded reason keeps the `yet` (this
-  payload carries no status to tell a live task from an unlabelled close).
-
-### Fixed
-
-- **A background task that failed with an empty log now says why — on the notification, in
-  `ptc_task_output`, and in the host log.** A 2026-10-19 field report: a child was rate-limited
-  (429) before writing anything, its output log was 0 bytes, the `TaskRecord` carried the reason
-  in `errorMessage`, and the parent agent received only `status="failed"` — it read the empty
-  log as an infrastructure fault and could not act on the real one. Three surfaces now carry the
-  cause. A `<bg-task-notification>` whose record carries an `errorMessage` gains an optional
-  `<error-message>` (head-truncated to at most 1024 code points, an ellipsis marking the cut, and
-  XML-escaped; absent when the record has no such text), so the push that announces the failure
-  states it. `ptc_task_output`
-  renders the reason as an `error=…` line ahead of a failed/lost task's body and exposes the
-  record's `errorMessage` on the codemode projection as `error_message` (and on `details` as
-  `errorMessage`), so the pull after the push reads the same reason. The background pump logs a `logger.warn` with the
-  task id and the failure reason, so the host operator no longer sees only an empty child log. The
-  terminal empty-output fallback also stops saying "yet": a terminal task reads
-  `(no output; task <id> is <status>)`, while `running` / `stopping` keep
-  `(no output yet; …)`. See ADR-0022 §7 as amended (2026-10-19).
-
-## [3.4.0] - 2026-10-19
-
-### Added
-
-- **`goal` on a dispatch.** `pi.dispatch` and `ptc_subagent` take an optional `goal`: the caller's
-  reason for this dispatch slice, not the conversation and not the user's original request. The
-  child receives it as its own `<pi-ptc-goal>` block after the host's policy block, and is told the
-  task remains the deliverable. Measured across five model configurations on twelve conflict
-  fixtures: 35 discordant pairs favoured the real goal, none favoured either control, and an
-  equal-length placebo passed 2 of 60 runs. See ADR-0042.
-- `docs/research/wayfinder-208-negative-results.md` records two candidate features that were built,
-  measured, and dropped (the summary arms and the provenance fields), with the method notes that
-  make their negative results reusable.
-
-## [3.3.3] - 2026-10-18
-
-### Fixed
-
-- **An agent is now reachable under the name it declares, not only under its file name.** A definition
-  written at `beta.md` whose frontmatter said `name: gamma` was advertised by the roster as `gamma`
-  and refused by dispatch — under `gamma` the path was rebuilt to `gamma.md`, which did not exist,
-  and under `beta` the parsed name did not match the request, so **neither** name worked. Discovery
-  now reads the directory and matches each definition's frontmatter `name:`, which is what pi's own
-  subagent loader and every comparable system does. It shares one scan with the roster rather than
-  spelling the identity rule a second time, so the 3.3.2 invariant — for one scope, the names a
-  roster lists are the names a dispatch resolves — holds by construction rather than by two
-  traversals happening to agree. Two files in one scope declaring one name resolve to the first in
-  sorted file-name order, and the shadowed file is reported. Scope precedence is unchanged: user
-  scope still wins over project scope, and `agentScope` still defaults to `"user"`. **Behaviour
-  change:** a definition whose file name disagrees with its `name:` becomes dispatchable under the
-  declared name, and stops being reachable under the file name.
-
-- **A malformed agent definition is now reported instead of silently dropped.** A `.md` file in an
-  agents directory that could not be _read_ already warned, but one that could be read and not
-  _parsed_ — a definition saved with its opening `---` lost — produced no roster entry, no mention in
-  a refusal, and no message at all, so the user saw `registered agents: (none)` for a directory that
-  visibly held files. A file whose first non-blank line opens a frontmatter block, or is a `name:`
-  key, now emits a `console.warn` naming its path. Prose kept beside the agents — a `README.md`, a
-  `notes.txt` — stays silent, and the registry listing is unchanged either way.
-
-### Changed
-
-- **The `ptc_subagent` description and the unknown-agent refusal no longer imply that a definition's
-  file name is its identity.** Both previously pointed at `<name>.md` as the shape to write. The
-  refusal now states that the `name:` header is the agent's name, that naming the file after it is
-  the convention, and that the two are independent. Model-facing text only; no tool, argument or
-  return-value shape changed.
-
-## [3.3.2] - 2026-10-18
-
-### Fixed
-
-- **The agent roster and agent discovery now name the same agents.** A `.md` file whose frontmatter
-  carried no `name:` was advertised by the roster under its file name and refused by dispatch as an
-  unknown agent — in the same message, because the refusal renders that roster. A model told an
-  agent exists could not dispatch it, and the self-contradicting refusal made the real cause hard to
-  read. Identity is the frontmatter `name:` and nothing else, which is what pi's own subagent loader
-  does: it skips a definition whose frontmatter has no string `name`, and never derives identity
-  from the file name. The roster now applies the same predicate `discoverAgent` applies, so the
-  invariant — for one scope, the names the roster lists are the names a dispatch resolves — holds by
-  construction rather than by two patches that happen to agree. A file that exists but cannot be
-  read is likewise no longer listed under its file name; it still emits a `console.warn`, so that
-  failure remains observable. **Behaviour change:** a file relying on the file-name fallback stops
-  appearing in the roster, in the refusal's registry listing, and in the `ptc_subagent` tool
-  description. Add a frontmatter `name:` to keep it dispatchable.
-
-## [3.3.1] - 2026-10-16
-
-### Changed
-
-- **The PTC tool descriptions now state how a `codemode` script reaches the parallel binding.**
-  Measured in the 2026-10-16 dispatch-loop spike: a script that decides to fan out enumerates its
-  own tool table, finds no `pi.dispatch` — correctly, the binding is never a codemode tool on any
-  surface — and nothing model-facing said the two-hop path (`codemode` → `ptc_run_code` /
-  `ptc_workflow` → `tools["pi.dispatch"]`) existed. The script's author read that silence as a
-  missing registration and fell back to `ptc_subagent`, which worked but left the compose-from-a-
-  script path untaught. The binding's own calling convention was already documented in both
-  descriptions, but those sentences address a reader _inside_ a program; the new note addresses a
-  reader inside the script. One shared constant renders into both descriptions, so the two
-  surfaces cannot drift. Model-facing text only: no tool, argument, or behaviour changed.
-
-## [3.3.0] - 2026-10-16
-
-### Added
-
-- **A dispatched child's token usage is persisted on the task record, so a child that reported
-  nothing still accounts for what it cost (issue #199).** `TaskRecord` gains a top-level optional
-  `usage` — the host's own six-field counter (`input`, `output`, `cacheRead`, `cacheWrite`, `cost`,
-  `turns`), accumulated from the child's assistant `message_end` blocks — written on **every**
-  terminal close for any child the host actually started, independent of `reportChannel` and of the
-  outcome: a `"none"` / `"opted-out"` child is accounted for, and so is one that closed `failed` or
-  `canceled`. The same measurement now reaches both model-facing readers of that child:
-  `ptc_task_output` prints the host's `usage:` line for a child that has no report block to put it
-  in, the foreground `ptc_subagent` renders it as a `usage` row in the child-report block it
-  already emitted, and both tools' `structuredContent` gains a top-level `usage` with the same four
-  numbers the text shows. **`report.usage` is unchanged**: still the four-field view (`input`,
-  `output`, `cost`, `turns`), still written only when the close resolves `succeeded` with a report,
-  and still what the report block renders — the two agree on the fields they share because both are
-  read off the same accumulator. An absent `usage` is a claim rather than a gap: a `running` task
-  has not closed yet, a `lost` record was never observed closing, a child that never started has
-  nothing to account for, and a record written before the field existed carries none — while a
-  record without one renders the block it rendered before, unchanged. ADR-0022 §3 and ADR-0032
-  record the amendment.
-
-## [3.2.0] - 2026-10-15
-
-### Added
-
-- **A dispatched child can be asked to be read-only, per call.** A new optional `readOnly`
-  argument on the dispatch call takes `"strict"` or `"lenient"` — strings only. Strict replaces
-  the child's tool list with the read set — `read`, `grep`, `find`,
-  `ls`, plus the child report tool when the report contract is on — so the write tools are never
-  declared to the child and it cannot call them. Lenient leaves the tool list exactly as it would
-  have been and adds one line to the `<pi-ptc-context>` block the child already receives.
-  The design first carried a boolean short spelling, and it was reversed before release rather
-  than after: measured, pi's validator coerces booleans — `readOnly: 0` would have silently
-  become "no tier", a full-capability child for a caller who asked to be read-only — and a string
-  enum refuses every wrong-typed value at the schema instead. No released version ever shipped
-  the boolean form.
-  A tier set on the call beats an agent definition's declared `tools:` for strict; for lenient
-  there is no precedence question, because the tier does not touch the tool list at all.
-  Nothing breaks for anyone who does not pass it: an ordinary dispatch's argv and prompt are
-  unchanged. **This is a capability narrowing, not a security boundary** — `bash` is deliberately
-  absent from the strict set, so a strict child cannot run tests or call `git`, and no hostile
-  child is contained by any of it. ADR-0041 records the reasoning and the alternatives.
-
-## [3.1.0] - 2026-10-15
-
-### Changed
-
-- **A failing PTC binding now reports a bounded diagnostic on every supported pi version.** The
-  binding wrapper catches a builtin tool that REJECTS and routes the failure text through
-  `bindingFailureMessage`, the same 2000-character tail-kept cap the `isError` channel already
-  used. Measured per pi version: `ls` / `read` / `grep` / `find` reject for a bad path on
-  0.86.1 through 1.2.0 — only `bash` moved onto `AgentToolResult.isError` (which arrived in
-  0.99.0). Before this, a rejected builtin crossed the boundary with pi's raw, head-first error
-  text, unbounded. The per-binding contract text is unchanged: a failing call still REJECTS.
-- **A truncated child response is now named instead of silently rejected.** pi 1.2.0 changed print
-  mode so a response cut off at the model's output token limit exits 1 rather than 0. The
-  foreground `DispatchResult` and the background `TaskRecord` now both carry an explicit message for
-  that close, and neither front labels an exit-0 close as a truncation — so the two cannot
-  disagree about the same child.
-
-### Added
-
-- **`detectedSurfaceMode` is re-exported from the built package.** The surface decision (the pure
-  function behind which orchestration face this package registers) was reachable only from the
-  source module, so no artifact-level test or probe could drive it directly. Its four input
-  combinations are now pinned against `dist`.
-- **`pnpm run compat:pi`** measures this package's gate against more than one pi version (floor,
-  pinned, ceiling), reports each step separately, and prints the version-specific legs as a
-  third state so a skipped leg is never mistaken for a passing one. See
-  [docs/agents/pi-compat-matrix.md](docs/agents/pi-compat-matrix.md).
-
-- **The declared peer floor is now a floor you can actually compile against.** `peerDependencies`
-  says `>=0.86.0`, but `tsc --noEmit` over pi 0.86.0 used to report 20 errors — the package ran
-  there and failed to typecheck, which is the worst of both. It now reports 0, and
-  `pnpm run compat:pi 0.86.0` passes every step. The package owns the three post-0.86.0 type
-  surfaces (`ToolExposure`, and `outputSchema` / `exposure` / `defaultActive` on `ToolDefinition`)
-  so `src/` depends on no pi newer than the floor; those fields arrived in 0.99.0, and a pi that
-  does not read them is unaffected by their presence.
-
-  Note the two floors are different things: **0.99.0 is where those capabilities appear** —
-  `isError`, codemode, `exposure`, `structuredContent` — and this package still falls back
-  below it. **0.86.0 is the floor it compiles and runs on.** An earlier revision of these notes
-  recorded 0.86.x/0.87.x as type-broken; that was measured before this work and no longer holds.
-
-### Documentation
-
-- Measured capability and feature-surface matrices across all 14 published pi versions from
-  0.86.0 to 1.2.0, with the corrected finding that the capability floor is **0.99.0**, not 1.0.0.
-
-## [3.0.0] - 2026-10-14
-
-### Changed
-
-- **BREAKING: `tools.bash(...)` is no longer bound by default; it is an explicit opt-in.** A PTC
-  program runs with the user's own machine identity and its binding calls bypass pi's `tool_call`
-  guards, so a default shell binding hands every model-written program a shell with your identity —
-  the largest single thing a program can reach, granted by nothing more than installing this package.
-  `bash` is now an _opt-in_ binding: it stays in the known binding set, and a program only gets it
-  when the install grants it in `~/.pi/agent/ptc.json`:
-
-  ```json
-  { "optInBindings": ["bash"] }
-  ```
-
-  **Migration:** a program that calls `tools.bash(...)` and was relying on the default now fails with
-  `no binding named "bash" in this run; available bindings: …`. Either add the key above (restart
-  pi to pick it up), or, for a narrower change, pass an explicit `names` list to
-  `createBuiltinBindings` — a caller-curated list is honoured verbatim and needs no second key. The
-  error names the bindings that _are_ available, so the fix is readable from the refusal.
-
-  Two properties worth knowing: the opt-in is **separate from the session's tool set** — pi having
-  `bash` enabled does not grant it, because "enabled" and "you agreed to give a model-written program
-  a shell" are different questions; and the file is read with a **fail-closed** direction, so an
-  absent, unparseable or misspelled key grants nothing and reports why at session start rather than
-  falling back to the old default. Note this narrows relative to DSH, whose PTC preset mounts
-  `tool-bash`/`tool-pwsh`; a program written against DSH that wants its shell back needs the key.
-
-## [2.1.0] - 2026-10-12
-
-### Added
-
-- **The registered agents reach the model before it dispatches, not after it fails.** An agent
-  markdown file's `description` was parsed and then dropped: the listing carried names alone, so
-  the only way a model learned an agent existed was to guess its name, be refused, and read the
-  refusal — a signal it could act on only after it had already spent the call. `ptc_subagent`'s
-  description now leads with the omission, then lists every definition under the effective scope
-  with its description and whether it was found in user or project scope, and says that
-  `agentScope` defaults to `"user"` and will not see the others. An empty registry says so rather
-  than rendering as nothing. The roster is rendered from the same traversal the refusal uses, so
-  the two cannot disagree about what is registered.
-
-### Changed
-
-- **A dispatched child is told what it is.** Every child's context block now says that it was
-  dispatched by another session, that it cannot see or ask that session anything, and that its final
-  message is the deliverable. Nothing in pi's own system prompt says any of it, which left a child
-  able to ask a question nobody would answer or to narrate its process where an answer was wanted.
-  It applies to named definitions too, so a definition does not have to restate what the dispatch
-  already knows. For a child with no definition the prompt file holds nothing but that block — pi's
-  own system prompt is still underneath it, which is precisely why the block has to say what the
-  child is. See ADR-0039.
-
-- **`agent` is no longer required by `ptc_subagent` or `pi.dispatch`.** Omitting it dispatches a
-  generalist child — pi's own system prompt, pi's full toolset, nothing narrowed — so a fresh
-  install can delegate without first learning the agent-markdown format and writing a file. Naming
-  one is now how you _narrow_ a child, which is all a definition could ever do: the dispatch prompt
-  is appended to pi's own rather than substituted for it, and no tool list is passed unless the
-  definition declares one. See ADR-0039.
-
-### Fixed
-
-- **A dispatch that named nothing was refused as if it were a mistake.** Both fronts answered an
-  omitted `agent` with _"agent is required (there is no default agent)"_. A name that is _given_
-  and unusable is still refused — a typo must not silently dispatch something else — but the
-  refusal now also says that omitting the argument is an option. The `ptc_subagent` description and
-  the agent roster it carries lead with the omission, so a model can choose it deliberately.
-
-### Removed
-
-- **The startup warning that said `ptc_subagent` had nothing to dispatch.** It fired whenever no
-  agent definition was registered, which 2.0.3 had just started reporting as a problem — and it
-  stopped being one in the same release: with `agent` optional, a dispatch that names nothing runs
-  a generalist child, so an install with an empty registry is a **working** install. The warning was
-  a false alarm about a working tool on exactly the fresh install it was written for. The `ptc-mode`
-  status marker that mirrored it for the rest of the session is gone too. See ADR-0039.
-
-## [2.0.3] - 2026-10-12
-
-### Fixed
-
-- **`ptc_subagent` was registered, described to the model, and still uncallable — with nothing
-  saying so.** On a `subagents` surface the tool needs at least one agent definition under
-  `~/.pi/agent/agents/<name>.md` or `<project>/.pi/agents/<name>.md`, and there is no default agent
-  (ADR-0016). With an empty registry the tool was live and inert: a real 920-message session made
-  520 tool calls and used it zero times, the model decided subagents were right, spent twenty-plus
-  calls hunting the install for definitions that were not there, and gave up. `session_start` now
-  reports it — naming both directories and the file shape — and the same fact is painted on the
-  `ptc-mode` status, so it is still readable after the notice is gone.
-- **Agent files saved with CRLF, a UTF-8 BOM, or a blank line before the delimiter parsed as
-  "no such agent".** The frontmatter pattern matched exactly one shape, and a `null` return reads,
-  from every layer above, as an unregistered name. The body is normalised after the match rather
-  than inside it, so the system prompt handed to a child carries no stray carriage returns. A file
-  that exists but cannot be parsed is now also distinguishable from one that is absent.
-- **`ptc_subagent`'s description states where definitions load from**, and that there is no default
-  agent — it points at the refusal rather than restating it, so the actionable detail keeps one
-  home (the renderer, wired to the same resolver a dispatch uses).
-
-### Added
-
-- **A real-process smoke test**, with a fake `pi` on `PATH` rather than a stubbed lifecycle: the
-  spawn, the `--append-system-prompt` materialisation, the stdout parsing and the exit code are
-  all exercised. Both directions are asserted — an empty registry reports, and a registered agent
-  dispatches to completion — because either alone passes against a build that is broken in the
-  other direction.
-- **A `能力的可用前提` review dimension**, asking when a user learns a tool's precondition is
-  unmet, with "never" as the answer that blocks.
-
-## [2.0.2] - 2026-10-10
-
-### Changed
-
-- **The README leads with what the package is instead of how it works.** The opening now
-  names the two capabilities up front — subagent fan-out and programmable tool calling —
-  and states the relationship with pi's own `codemode` in the first screen. The surface
-  detection deep-dive (three-question table, startup notices, `--print` / `--no-extensions`
-  edge cases) moves out of the README to
-  [docs/usage/surface.md](./docs/usage/surface.md), which now owns it; the README keeps
-  the short version and a pointer. Everything else is tightened, not deleted.
-- **The built-in tool enumeration no longer claims a count pi moved past.** The README used
-  to say "all seven built-ins"; pi 1.1.0 ships eight (`powershell` joined), so the copy now
-  enumerates the tools this package binds (`read`, `bash`, `edit`, `write`, `grep`, `find`,
-  `ls`) without claiming that is pi's full set. Docs only; no code change — note the
-  binding list itself is unchanged, and `powershell` is currently not reachable from PTC
-  programs even when enabled (tracked separately).
-
-[3.3.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v3.2.0...v3.3.0
-[3.2.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v3.1.0...v3.2.0
-[3.1.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v3.0.0...v3.1.0
-[3.0.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v2.1.0...v3.0.0
-[2.1.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v2.0.3...v2.1.0
-[2.0.3]: https://github.com/a1121611810/pi-ptc-subagents/compare/v2.0.2...v2.0.3
-[2.0.2]: https://github.com/a1121611810/pi-ptc-subagents/compare/v2.0.1...v2.0.2
-
-## [2.0.1] - 2026-10-10
-
-### Changed
-
-- **The package introduction copy now describes the package the code ships.**
-  The `description` field — the hero line of the
-  [pi.dev package page](https://pi.dev/packages/pi-ptc-subagents) — named two
-  tools (`ptc_run_code` + `ptc_workflow`) while the package registers six
-  model-facing tools plus the `pi.dispatch` binding, and said nothing about
-  the subagent fan-out the package name advertises. It now centres on both
-  capabilities the package is — programmable tool calling and subagent
-  fan-out — with no tool names hardcoded (the tool set is detected, not
-  configured; see [ADR-0034](./docs/adr/0034-surface-is-detected-not-set.md)).
-  The README's Tools section gains the missing `ptc_subagent` bullet. Docs
-  only; no code change.
-
-[2.0.1]: https://github.com/a1121611810/pi-ptc-subagents/compare/v2.0.0...v2.0.1
-
-## [2.0.0] - 2026-10-10
-
-### Added
-
-- **`ptc_run_code` and `ptc_workflow` reach the line where pi's `codemode` orchestrates.** A
-  session on the `subagents` surface used to hold `ptc_subagent` and the lifecycle face with no
-  program behind them: pi's `codemode` was composing tool calls, and the one capability its
-  QuickJS sandbox cannot provide — spawning a process — was unreachable, because `pi.dispatch`,
-  background tasks and the frozen six-name environment all live inside the PTC worker. Both tools
-  are now registered there at `codemode` reach, which makes them **callable from a `codemode`
-  script without being declared to the model**: `AgentSession._isDeclarable` admits `direct` and
-  `model-only` only, so the request pi sends still carries exactly one orchestrator and it is
-  pi's. Verified end to end on a real pi 1.1.0 session — a `codemode` script enumerates all six
-  `ptc_*` tools in `ALL_TOOLS` and successfully calls `await tools.ptc_run_code({ code: … })`,
-  while the payload carries only the subagent face
-  ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md) §3 as amended).
-
-  **A pi older than 0.99.0 is unaffected.** `ToolExposure` does not exist there — `grep -r
-  exposure` over `pi-coding-agent@0.86.1`'s `dist/` returns nothing, and so does
-  `AgentSession._getCallableTools` — so the field is ignored and the tools are declared to the
-  model, which is correct: such a pi ships no `codemode`, resolves to `full` anyway, and has
-  nothing that could call a `codemode`-reach tool. Measured across 0.86.1 / 0.87.1 / 0.99.0 /
-  0.99.1 / 0.99.2 / 1.0.0 / 1.0.4 / 1.1.0.
-
-  **Naming either tool in `--tools` or `defaultTools` overrides this.** A tool named there is
-  recorded in pi's `toolsAdded`, which the prompt projection filters only against `hidden` and
-  never against `codemode` — so it is declared to the model regardless of its exposure. That is
-  a user's explicit choice and is left alone; it is recorded here because the exposure field does
-  not survive it.
-
-### Changed
-
-- **Surface detection asks pi for the loadout instead of reconstructing it.** The third question —
-  will `codemode` be **active**, i.e. callable by the model — used to be answered by parsing
-  `--tools` / `--exclude-tools` / `--no-tools` / `--no-builtin-tools` out of `process.argv`,
-  merging `defaultTools` across the user-scope and project-scope settings files, and replaying pi's
-  precedence over the result. That is deleted. At `session_start` — the first moment pi's runtime is
-  bound — `getActiveTools()` answers directly, and pi has already applied both the command line and
-  its project-trust decision to what it returns. Registration moves to the same event, where pi
-  adds a tool from it and refreshes its own registry; the command-line reader, the `defaultTools`
-  merge, the precedence replay and the differential test that held them honest all go with it
-  ([ADR-0035](./docs/adr/0035-ask-pi-for-the-loadout.md)).
-
-  **What this fixes.** A project's `defaultTools` was read off disk with no trust check, while pi
-  drops project settings for any project it has not been told to trust. An untrusted project could
-  therefore name `codemode` and put the session on the `subagents` surface — whose
-  `ptc_run_code` and `ptc_workflow` are registered at `codemode` reach, so with no `codemode`
-  running they are reachable from nowhere (#131). A trusted project that configures `codemode` that
-  way keeps the `subagents` surface, exactly as before.
-
-  **What does not change.** The MCP auto-enable evidence stays a file-side read, because pi
-  activates `codemode` from inside its own `session_start` handler and extension order is not ours
-  to choose — measured across pi 0.86.1 → 1.1.0, a read from ours is too early to see it, and the
-  existing cross-check catches it when it lands. The **codemode switch** axis also stays as it is;
-  it may also be collapsible into the live registry, but that loses the distinction between "not
-  shipped" and "not loaded", and it is a separate decision. Behaviour is otherwise unchanged on
-  every pi this package supports, verified from 0.86.1 upward under both trust decisions.
-
-- **BREAKING: the `surfaceMode` setting is removed, and the surface is detected only.** Which
-  model-facing tools this package registers is now a pure function of what pi is — three probes
-  (does this pi ship `codemode`, will pi load it, can the model call it), with `full` as the
-  fallback for every case a probe cannot answer
-  ([ADR-0034](./docs/adr/0034-surface-is-detected-not-set.md)).
-
-  **What is gone:**
-
-  - the `surfaceMode` key in `~/.pi/agent/ptc.json` (`off` / `subagents` / `full`);
-  - the `off` value — a session that wants none of this package's tools no longer has a way to say
-    so here;
-  - the `/ptc surface [off|subagents|full]` subcommand. **`/ptc off` is unaffected** — it turns PTC
-    _mode_ off, which was never the same thing as the extension surface;
-  - the `surfaceModeConflict` notice about a pinned value disagreeing with detection.
-
-  **Migrating: use pi, not this package.** Run `pi config` and disable this package's extensions
-  there — measured on pi 1.1.0 against this package's own `dist/index.js`, a `packages` entry whose
-  `extensions` is `[]` or `["!dist/index.js"]` is not loaded at all, while `["+dist/index.js"]` and
-  an omitted key are. This is strictly better than any value of a key this package reads, because
-  pi honours it **without loading the extension**: none of this package runs, rather than running
-  and then deciding to register nothing. In a project-level `.pi/settings.json` write
-  `["!dist/index.js"]` rather than `[]` — pi resolves the two scopes with two different functions
-  (`package-manager.js:1850`), where an empty project delta means "no change".
-
-  **Expect one warning on upgrade if you had the key set.** A `ptc.json` carrying `surfaceMode` is
-  reported at session start and the key is **not** honoured — deliberately, including for `"off"`,
-  which is why this package comes back after being switched off. The warning names the file, quotes
-  the value, and points at `pi config`; deleting the key silences it.
-
-- **ADR-0025 decision 3 is amended.** `subagents` does register the programming pair now. What
-  the decision protected — the model being offered one orchestration surface, not two — is
-  unchanged and is now enforced by exposure rather than by an absent tool. `CONTEXT.md`'s
-  _orchestration surface_ and _subagent surface_ entries and the README's surface list say so
-  too.
-
-- **The `codemode` activation probe now reads every CLI flag that can remove the tool.** It reads
-  `--exclude-tools` / `-xt` and `--no-tools` / `-nt` in addition to `--tools` / `-t`, and it applies
-  them in pi's own order: `-t` decides the list and beats `-nt`, while `-xt` vetoes whatever list
-  won. That last one was a real misreading — pi builds the active set as
-  `(tools ?? configured).filter(name => !excluded.has(name))` (`sdk.js:148`), so **exclusion beats
-  inclusion**, and `-t codemode -xt codemode` was previously read as `active`. The direction was the
-  harmful one: under `subagents`, `ptc_run_code` / `ptc_workflow` are at `codemode` reach, so an
-  orchestrator believed to be present but absent is an orchestrator nobody can call.
-  `--no-builtin-tools` is deliberately still not read: it maps to `noTools: "builtin"` and
-  `codemode` is not one of pi's built-in tools, so reading it would be a guess about a flag that
-  cannot move it.
-
-[2.0.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v1.6.0...v2.0.0
-
-## [1.6.0] - 2026-10-08
-
-### Fixed
-
-- **On pi 1.0, a session with MCP servers was offered two orchestration tools at once.** pi's MCP
-  extension activates pi's own `codemode` tool by itself — MCP tools default to `codemode`
-  exposure so that they are reachable only from scripts — and it does that with a
-  `pi.setActiveTools` call that no settings file records. This package's surface detection
-  ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)) asked whether `codemode` would
-  be _active_ by mirroring pi's loadout resolution alone ([ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)),
-  so on exactly the sessions pi 1.0 is built around it answered _not active_, registered
-  `ptc_run_code` + `ptc_workflow` as well, and handed the model two ways to compose tools. Detection
-  now reads pi's MCP configuration (`<agentDir>/mcp.json`, then `<cwd>/.pi/mcp.json`) as a second
-  evidence source and unions the two, so those sessions resolve `subagents`: `codemode` for
-  orchestration, `ptc_subagent` and the task lifecycle for fan-out.
-  [ADR-0033](./docs/adr/0033-mcp-auto-enable-evidence.md) records the mirror, what it deliberately
-  does not mirror, and the one under-report path that stays open (a server registered through
-  `pi.registerMcpServer()`, which no file records — the drift notice below is what covers it).
-
-### Added
-
-- **A session start warning for an active `codemode` the probes did not predict.** Once per
-  session, and only on a detected surface: if nothing in `settings.json` or a readable `mcp.json`
-  said codemode would be active, the surface defaulted to `full`, and pi's real tool loadout
-  contains `codemode` anyway, the session is now told it is carrying two orchestration surfaces and
-  which setting picks one. Checked at session start and again on the first turn, because
-  pi's MCP extension may activate codemode after this package's own `session_start` runs. It is
-  `TUI`-only, like every other notice in this package.
-- **A named report for an `mcp.json` this package could not read.** A file that is absent is
-  silent, matching pi; a file that exists and cannot be parsed or read is named at session start
-  with its path, and when both files are broken both are named in the one line.
-
-### Changed
-
-- **`CONTEXT.md` gains a `codemode activation` entry** defining the question surface detection asks
-  and its two evidence classes, so "is codemode active" no longer has to be reconstructed from an
-  ADR.
-- ADR-0029 carries an amendment: its under-reporting bound still holds, but the premise it rested
-  on — that the loadout is the only way pi activates codemode — did not.
-
-## [1.5.1] - 2026-10-08
-
-### Fixed
-
-- **Two claims 1.5.0's changelog made about this repository were false, and are now corrected in
-  the repository itself.** 1.5.0's tarball still carries the original wording — published tarballs
-  are immutable — so the correction lives here, in `main`, and in
-  [ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md)'s amendment blocks:
-  - _"The repository is public … release authority is enforced by a `refs/tags/v*` ruleset."_ The
-    repository was still private at 1.5.0's release, and no ruleset existed. Both were done
-    2026-10-08, hours after the gap was measured: the flip, then an active ruleset (id 24698892)
-    on `refs/heads/main` — no pushes, no merges, no deletions, no force-pushes except by
-    `a1121611810` as sole bypass actor, with one approving review and green `format` / `oxlint` /
-    `test` checks required for everyone else.
-  - _"The next version published from here carries an npm provenance attestation."_ No published
-    version through 1.5.0 has one, because the provenance precondition (a public source
-    repository) only became true with the flip above. **1.5.1 is the first version whose
-    precondition held** — see `dist.attestations` on the registry.
-
-  How the false claims shipped: they were written as decisions in an earlier session
-  (`c1dda59`), recorded as facts, and every gate in this repository checks the shape of a claim —
-  that a `file:line` resolves, that a constant matches a rule — not whether the thing a sentence
-  describes exists. Five review rounds and a green release gate passed them. The same class of
-  gap is recorded in `docs/testing-constraints.md` §"What the gate does not check".
-
-### Added
-
-- **`docs/prototypes/` — the bgdispatch design records, recovered from research branches.** The
-  ten research branches deleted in the run-up to going public carried twelve verdict /
-  measurement / prototype files that had never been merged to `main`: the records of _why_ the
-  background-dispatch design is what it is. They were recovered before the branches were deleted;
-  `AGENTS.md` treats records as load-bearing.
-- **`.mailmap`**, so the public commit history displays `a1121611810` instead of the 224-character
-  padded name that authored 309 commits. No history rewrite.
-
-### Changed
-
-- **`.gitignore` gains `.zcode/` and `.scratch/`.** `.zcode/` was previously protected only by two
-  nested self-ignoring `.gitignore` files that are themselves untracked. `.scratch/` (local ticket
-  drafts, content duplicated on GitHub Issues) is removed from tracking.
-- **Twelve research / feature branches and two `backup/undo-*` tags deleted from the remote.**
-  They carried the developer's machine-local paths (`/Users/lilianda`) that `main` had already
-  scrubbed; GitHub publishes every ref, not just `main`, so a public reader could have clicked
-  into them. Content was verified present in `main` (or recovered above) before each deletion.
-  Four routine `dependabot/*` bumps remain as open branches for the maintainer to review.
-- **`docs/prototypes/**` excluded from oxlint.** The recovered files are measurement scripts and
-  were never part of the linted source; they are records, not production code.
-- **The npm mirror noted during the audit turned out to be local configuration, not the
-  lockfile** — `pnpm-lock.yaml` carries no registry URLs at all.
-
-## [1.5.0] - 2026-10-08
-
-### Added
-
-- **`verify:dist` is now part of the release gate.** `scripts/verify-dist-render.mjs` is the only
-  check that exercises the _built_ artifact, and it ran nowhere: not in CI, not in the publish
-  workflow, not in `prepublishOnly`. A feature in this project's own history passed three review
-  rounds and 696 tests and then failed this script on the release artifact. It now runs on every
-  pull request, in `publish.yml` before the publish step, and in `prepublishOnly`
-  ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §D).
-- **`THIRD_PARTY_NOTICES.md`**, stating what is derived from DeepSeek Harness (MIT, Copyright (c)
-  2026 DeepSeek) and from `pi` (MIT), and shipped inside the npm tarball rather than only on
-  GitHub. The MIT notice is an obligation for the source excerpts in `docs/research/`, not a
-  courtesy.
-- **A dispatched child returns a _child report_ instead of prose alone.** `summary` in the child's
-  own words, `findings` each carrying the independent thing that supports the claim,
-  `files_touched`, and the token usage **the host measured**. The child's prose is kept alongside
-  the report, never replaced by it ([ADR-0032](./docs/adr/0032-child-report.md)).
-- **Two delivery channels, and the result names which one delivered it.** A declared
-  `ptc_child_report` tool (the reliable one) or a fenced JSON block in the child's final text (the
-  fallback, for installs where this package does not load in the child). `reportChannel` is
-  **always** present — `tool`, `prompt-json`, `none` or `opted-out` — because a degradation a
-  caller cannot see is a silent failure, and "ran but did not comply" must not read as "returned
-  nothing".
-- **The report contract is on by default** and an agent opts out with one frontmatter line,
-  `childReport: false`. An opted-out agent reads as `opted-out`, not `none`: nobody was asked is a
-  different claim from having been asked and ignored.
-- **`ptc_subagent` renders the report** where the model reads it, bounded at 20 findings /
-  20 files / 150 characters of evidence per finding, each bound stated in-band when it withholds.
-  This is the first real reader of that tool's declared `structuredContent` — on the `subagents`
-  surface there is no `codemode` to read it.
-
-### Changed
-
-- `src/tools/subagent.ts` gained the OCR rule anchor it never had. It was resolving to the `**`
-  catch-all and being reviewed against the generic floor only.
-- **The repository is public, and `main` is writable only by the maintainer.** Everything else is
-  a pull request that needs CI green and one approving review. Release authority is enforced by a
-  `refs/tags/v*` ruleset plus the npm package's "Require two-factor authentication and disallow
-  tokens" setting, so it no longer depends on where a credential file is kept
-  ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §A–§B).
-  ~~**Measured 2026-10-08: this did not happen.** The repository is still private and no ruleset
-  exists — see §Unreleased above and ADR-0031's correction block. The npm 2FA setting is unverified
-  and is not claimed here.~~
-- **The next version published from here carries an npm provenance attestation.** Under trusted
-  publishing npm generates it automatically once the source repository is public, with no workflow
-  change — so the `homepage` and `repository` fields that pointed at a private GitHub now resolve,
-  and the missing provenance badge that ADR-0018 §7 recorded as expected is no longer expected.
-  ~~**Measured 2026-10-08: this is false and always was.** `dist.attestations` is empty for every
-  published version including 1.5.0; the repository was never public, so the precondition never
-  held and ADR-0018 §7 stands unamended.~~
-- **`node scripts/preview-ptc-render.mjs` requires `PI_ROOT`.** It imported pi's theme from a hard-coded
-  path on one developer's machine, so following the README from anywhere else failed inside a
-  module loader. It now reads the install directory from the environment and, when it is missing or
-  wrong, says so with the commands to find it.
-- **The DSH citations in `docs/research/` point at the public upstream repository** instead of a
-  temporary local extraction, so a reader can follow them. The baseline is tag `dsh-v0.2.0-rc.2`
-  — the release the research actually read. `src/runtime/limits.ts:4` named `0.1.6-alpha.2`; the
-  constants are byte-identical across both tags, so only the version label changed and no behaviour
-  did ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §C).
-
-## [1.4.0] - 2026-10-03
-
-### Added
-
-- **`/ptc surface off|subagents|full` switches the extension surface without a new session.** The
-  surface was configurable only by hand-editing `~/.pi/agent/ptc.json` and restarting, because it is
-  read once in the extension factory and pi has no way to unregister a tool. The new subcommand
-  writes the key and then performs pi's own `/reload`, which clears pi's extension cache and
-  re-runs every factory — the same path the built-in takes, from inside the extension. A malformed
-  `ptc.json` is reported and left byte-for-byte alone, `defaultMode` in the same file survives, and
-  setting the value that is already there writes nothing and does not reload
-  ([ADR-0030](./docs/adr/0030-surface-switch-reloads.md)).
-
-### Fixed
-
-- **A default pi session no longer starts with no orchestration tool at all.** The detected surface
-  followed two questions — does this pi ship a `codemode` directory, and will pi load it — and on a
-  stock pi 1.0.0 install the answer to both is yes, so the surface resolved to `subagents`. But pi
-  registers `codemode` with `defaultActive: false`: it joins the model's tool list only when a
-  loadout names it, and a session that configured nothing has no such loadout. Since the
-  `subagents` surface deliberately does not register `ptc_run_code`, the result was a session
-  holding `ptc_subagent` and three `ptc_task_*` tools with no way to compose any of them, plus a
-  startup warning on **every** session. The detection now asks a third question — whether `codemode`
-  will actually be in the tool list, read from `--tools` and from `defaultTools` in the project and
-  user settings the way pi resolves them — and `subagents` is chosen only on positive evidence that
-  the model can call the tool. The default on an unconfigured install is now `full`, with no
-  warning. To opt into `subagents`, add `codemode` to `defaultTools` or `--tools`
-  ([ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)).
-- **The "pi does not register codemode" startup notice no longer hard-codes the wrong surface.** With
-  a fifth cell in the table, the detected surface is not always `subagents` in that branch, and the
-  message named `SurfaceModeConfig.detected` — a field populated only when an explicit `surfaceMode`
-  overrode detection, so on the very path the notice fires from it would have printed `undefined`.
-  It reports the surface the session actually built.
-
-## [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
-
-- **The expanded `phases` block now says how many phases it withheld.**
-  When a run declared more than eight phases, the block appended a bare
-  ` …` to the roll-up line — it told the reader that something was hidden
-  but not how much. ADR-0013 §3 requires a block to report _what_ it
-  withheld, and the other four blocks (`code`, `log`, `out`, `warn`) all
-  report a count. The tail is now `…+N more phases`, inline, because the
-  phases block is a single roll-up line rather than a list of rows.
-
-### Changed
-
-- **Docs**: the README's `TUI rendering` section now documents the
-  model-facing text block's own bounds — 100 characters for the inline form,
-  200 per line (ADR-0012) — next to the on-screen tree's 4 / 6 / 120, so the
-  two contracts are no longer conflated and lowering one to match the other
-  does not read as a typo fix.
-
-## [1.1.0] - 2026-09-29
-
-### Fixed
-
-- **Background dispatch children no longer reap their parent's tasks (field
-  report, 2026-09-29).** Background children share the session's task storage
-  via `--session-dir`; a child's startup reconcile and exit sweep used to be
-  directory-wide, so a dispatch child — or any `pi` process started in the same
-  directory — flipped every running task to `lost`. Task records now carry an
-  owner identity (`ownerPid` / `ownerBootMs`) and reaping is owner-scoped
-  (ADR-0023); `lost_on_session_restart` now means the owner process died
-  before the task finished, or the record predates ownership (pre-upgrade
-  ownerless rows, which any process binding the directory reaps).
-- **`pi.dispatch` refusals are actionable.** A missing `agent` argument is
-  reported distinctly (`agent is required (there is no default agent)`) and
-  both the missing- and unknown-agent results list the agents registered under
-  the effective scope plus the two lookup paths and the agent-file shape. The
-  binding now runs its arguments through pi's own `validateToolArguments`
-  (the same validation the built-in bindings use) and a validation failure
-  comes back as a `rejected` DispatchResult instead of reaching the
-  subprocess layer.
-
-### Changed
-
-- **PTC program prompts name the dispatch binding precisely.** The
-  `ptc_run_code` / `ptc_workflow` descriptions and the `/ptc` briefing state
-  that `pi.dispatch` is always bound under its literal dot name (call it as
-  `tools["pi.dispatch"](...)`; `tools.pi.dispatch` does not exist), and each
-  run exposes its actual bound names on the new `ptcBindings` global so
-  programs never guess the binding surface.
-- **Docs**: `ptc_run_code`'s `timeoutMs` description and `docs/usage/bgdispatch.md`
-  now state that a run timeout terminates in-flight foreground dispatches, and
-  the guide gains prerequisites (no default agent) and an output-compactness
-  convention (page via `ptc_task_output` instead of truncating).
-
-## [1.0.0] - 2026-09-24
-
-### Added
-
-- **Background dispatch: PTC programs can fan out to long-lived children.**
-  `pi.dispatch(...)` gains an opt-in `{ background: true }` path: instead of
-  awaiting the child, the binding returns a `DispatchHandle`
-  (`{ taskId, label, status: "running" }`) immediately, and a detached pump
-  drives a session-level `TaskRecord` through
-  `running / stopping / succeeded / failed / canceled / lost`, past the end of
-  the program and of the turn. The handle is a frozen spawn-time projection;
-  live state comes from three model-facing tools that stay on when PTC mode is
-  off (`/ptc off` only blocks new spawns):
-  - **`ptc_task_list`** — list this session's tasks (`status?`, `limit?`,
-    default 100, newest first);
-  - **`ptc_task_output`** — read a task's captured output (`taskId`,
-    `sinceBytes?`), tail-truncated to pi's 50 KB / 2000-line contract
-    (ADR-0015) with the full text written to a temp file;
-  - **`ptc_task_stop`** — ask a running task to stop (`taskId`, `reason?`,
-    default `"model stop"`), moving it `running -> stopping -> canceled`.
-
-  Lifecycle changes arrive as user-role `<bg-task-notification>` events under a
-  `<bg-task-notifications>` batch, cursor-delivered per subscriber with a
-  2048-byte inline-preview ceiling. Background tasks count against the existing
-  `dispatchConcurrency` (8) for their whole lifetime and share the
-  `maxDispatchDepth` (3) recursion bound. Existing foreground `pi.dispatch`
-  keeps its `DispatchResult` shape unchanged. ADR-0022.
-
-## [0.1.3] - 2026-09-23
-
-### Added
-
-- **PTC rows show what the program is doing while it runs.** Two partial-state
-  visuals on the `ptc_run_code` / `ptc_workflow` row, both absent until now:
-  - a **shimmer** on the call row — same text, one character at a time bright,
-    the highlight sweeping at 150ms — so a running row is distinguishable from a
-    settled one in a column (ADR-0020);
-  - a **sub-call tree** under it: one row per binding call the program made,
-    live from the moment the call is made, with its own five-state status
-    (`running` / `ok` / `error` / `cancelled` / `rejected`) and duration,
-    visible without expanding the row and capped at 32 with a `+N more` tail
-    (ADR-0021). A failed run shows the failure text but no sub-call tree: the
-    tool throws (pi's convention), and pi builds that error result with an empty
-    `details`, so the tracked calls are dropped with it.
-
-### Changed
-
-- **Build pipeline: minify + source-map exclusion.** `pnpm run build`
-  (`vp pack`) now produces minified `dist/*.js` (rolldown's built-in oxc
-  minifier; no new dependency). The npm tarball excludes `dist/**/*.map`
-  via the `package.json#files` whitelist — sourcemaps stay on disk for
-  local stack traces, but no longer ship. Tarball shrinks from 168.7 kB
-  packed / 548.6 kB unpacked (v0.1.2 baseline) to 40.5 kB / 113.6 kB
-  (−76% / −79%); `dist/*.js` total shrinks from 161,303 B to 53,959 B
-  (−66.5%). All 39 public exports retain their original names. ADR-0019.
-
-## [0.1.2] - 2026-09-23
-
-### Fixed
-
-- **`pi.dispatch` is registered in production again.** The injection check compared the
-  binding-name array by reference against `DEFAULT_BINDING_NAMES`; production resolves
-  names through a `.filter()` that always returns a fresh array, so the comparison never
-  held and shipped sessions had no `pi.dispatch` at all. Injection now keys off a new
-  `includeDispatch` option (defaulting to "the caller passed no explicit `names`"), and
-  both shipped tools pass it explicitly. ADR-0016.
-- **The dispatch concurrency cap honours `dispatchConcurrency` (default 8) and rejects
-  immediately instead of queueing.** The dispatcher used to read `maxParallelSubCalls`
-  (default 10) and FIFO-queue the overflow; per ADR-0016 §2 the N+1th concurrent
-  `pi.dispatch` now resolves at once with `{ status: "rejected", errorMessage:
-  "dispatch concurrency limit reached" }`. The cap applies to `pi.dispatch` only and
-  has its own counter; builtin binding fan-out keeps DSH's `maxParallelSubCalls` (10)
-  FIFO-queueing semantics (ADR-0004), so in-flight builtin calls never consume
-  dispatch slots.
-- **The depth-limit rejection message is verbatim again.** The program receives
-  exactly `dispatch depth limit reached`, matching what the child's
-  `<pi-ptc-context>` hint promises — the diagnostic suffix is gone.
-- **`maxDispatchDepth` bounds recursion again.** Every run reported depth 0 and
-  children never inherited it, so the depth check could never fire. `dispatch()` now
-  stamps `PI_PTC_DEPTH` on the child subprocess's environment, the extension
-  entrypoint reads it back, and `runPtcProgram()` accepts a `depth` baseline that
-  reaches the binding context. ADR-0016 Recursive section.
-
-## [0.1.1] - 2026-09-23
-
-PTC runs inside one agent turn no longer pay a cold start each. Nothing changes in
-what a program may call or return; the difference is latency and cancellation
-behaviour.
-
-### Changed
-
-- **Per-turn worker pool.** One warm `worker_threads` Worker per surface
-  (`run_code`, `workflow`) is kept for the duration of an agent turn and reused
-  across its PTC runs — ~0 ms against ~58 ms for a cold spawn (median of 5). The
-  pool is created lazily by the first PTC run of the turn, the two surfaces do not
-  share one, and the extension's `turn_end` hook retires it. Idle workers are
-  `unref()`-ed, so a warm pool never keeps `pi` alive. `runPtcProgram()` gains an
-  optional `pool` field; without it the original cold-start path runs unchanged.
-  ADR-0017.
-- **The worker entry is a real `dist/worker.js`.** The `data:` URL built from
-  `Function.prototype.toString()` is retired, so V8's code cache and Node's module
-  cache survive warm reuse. TypeScript the _model_ submits at run time is still
-  type-stripped inside the worker — that is `compileProgram`'s path, not the
-  bootstrap's.
-
-### Fixed
-
-- **Cancellation settles within a bound in every ordering.** A still-armed deadline
-  is the ceiling when a cancel arrives first; a worker that never answers a timeout
-  settles at `timeoutMs + graceMs`. A superseded run's frames can no longer settle
-  its successor, and an idle worker answers a cancel instead of making the host wait
-  out its grace window. ADR-0017 §10.
-- **`serializedBytes` no longer bills containers as zero bytes.** `[null × 100k]`
-  was counted as nothing, so a frame could slip past `maxMessageBytes`; the helper
-  now matches `JSON.stringify` byte-for-byte and sums `ArrayBuffer` / typed-array
-  leaves.
-
-## [0.1.0] - 2026-09-22
-
-First npm release. Ports DSH PTC mode — Programmable Tool Calling, formerly
-DSH "Code Mode" — to `pi`. Behaviour tracks
-[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness).
-Not a new design. Re-alignment.
-
-Install with `pi install npm:pi-ptc-subagents`. PTC tools register on next
-`pi` startup. No postinstall hook. No setup.
-
-### Added
-
-- **`ptc_run_code`**. Model submits a JS/TS program. Multiple tools execute
-  in one shot. Return value and collected logs return to context. Worker
-  protocol, dispatcher, and surfaces back it.
-- **`ptc_workflow`**. Narration over `ptc_run_code`. Uses the in-program
-  `log()` helper.
-- **`pi.dispatch` binding**. PTC programs fan out to a fresh per-call `pi`
-  subprocess. DSH parity.
-- **Builtin bindings**. `read`, `bash`, `edit`, `write`, `grep`, `find`,
-  `ls`. Callable from a PTC program as `tools.<name>(args)`. DSH parity.
-- **Hoisted images**. Successful bindings lift image blocks onto the PTC
-  tool result. The model sees the picture. The program never carries it
-  through the return value. Parity with `dsh-tools`'s `exec.deferContext`.
-- **Value-tree rendering**. Container completion values render as a tree.
-  One row per property or array index. Bounded by depth and width caps.
-  Withheld amount is shown in-band. Scalar values render as one-line hints.
-- **Truncation contract**. Model-facing text honors `pi`'s truncation cap.
-  Container values render as compact PTC rows.
-- **Skills restored**. The skills section `pi` withholds is restored. PTC
-  programs call them as bindings. DSH parity.
-- **Build verification scripts**. `verify:dist`, `json-to-tui`,
-  `preview-ptc-render`. Run before publishing.
-
-### Changed
-
-- Build pipeline switched to `vite-plus` (`vp pack`). Type declarations
-  bundle via `rolldown-plugin-dts`.
-- Tooling moved to pnpm 12.5.1. `vitest` coverage pinned. Lockfile
-  determinism set via `minimumReleaseAge: 0`.
-- Lint and format moved to `oxlint` (type-aware) and `oxfmt`.
-
-### Fixed
-
-- `pi.dispatch` now spawns `pi` directly. The host script used to swallow
-  the child's exit.
-- `maxPendingCalls` stays in the worker. The caller no longer trips on
-  arrivals.
-- Bindings mirror the session's active tools. A session that disables a
-  tool also disables it inside PTC programs.
-- pnpm overrides dropped. No-op under pnpm 12.5.1.