pi-ptc-subagents 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -7,6 +7,119 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+(nothing yet)
+
+## [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

package/README.md

@@ -4,13 +4,21 @@ DSH-style **PTC mode** (Programmable Tool Calling) for [pi](https://pi.dev):
 the model writes a JS/TS program that calls pi's tools from inside a worker,
 and only the program's return value plus its logs come back to the model.
 
+**Source is open.** This repository is public and the source is here — `dist/` on npm is the
+compiled form of what you read below. Contributions go through pull requests: see
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the gate your PR has to pass, and
+[SECURITY.md](./SECURITY.md) before reporting anything. Releases are cut from `main` by the
+maintainer only; if you find something you think needs a release, open an issue and say so.
+
 ## Status
 
-Pre-1.0, but functional: `ptc_run_code` and `ptc_workflow` are registered and run
+Functional and actively used: `ptc_run_code` and `ptc_workflow` are registered and run
 programs through the same tested worker machinery (dispatcher, wire protocol,
 budgets, built-in bindings). The implementation is written clean-room from
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) PTC
-behaviour (tracked as a wayfinder map in this repo's issues).
+behaviour — see [ADR-0002](./docs/adr/0002-source-strategy.md) for how that boundary is
+kept, and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for the attribution that
+follows from it.
 
 ## Install
 
@@ -72,6 +80,23 @@ const [read, scoutA, scoutB] = await Promise.all([
 ]);
 ```
 
+**The child report.** A dispatched child returns more than prose. Under the report contract ([ADR-0032](./docs/adr/0032-child-report.md)) a child hands back a **child report** — a `summary` in its own words, `findings` each carrying the independent thing that supports the claim, the `files_touched` it is sure about, and the token usage **the host measured** (never a number the child made up). The child's prose is kept alongside the report, never replaced by it.
+
+The report travels one of two channels. It prefers a declared `ptc_child_report` tool, whose payload the host reads back as JSON. If that tool is not available to the child, the host still reads a fenced JSON block from its final message. Either way the result **names the channel that delivered it**:
+
+```ts
+const r = await tools["pi.dispatch"]({ agent: "scout", task: "survey the auth code" });
+if (r.reportChannel === "none") {
+  // The child ran and did not comply. r.text is its prose; treat it as unbacked.
+} else {
+  for (const f of r.report?.findings ?? []) console.log(f.what, "←", f.evidence);
+}
+```
+
+`reportChannel` is **always present** — `"tool"`, `"prompt-json"` or `"none"` — because a degradation a caller cannot see is a silent failure, and "ran but did not comply" must not read as "returned nothing". `ptc_subagent` renders the same report into the text the model reads, bounded at 20 findings with the withheld count stated in-band.
+
+The contract is **on by default**. An agent opts out with one line of frontmatter, `childReport: false`, and then its channel reads `"opted-out"` — nobody was asked, which is a different claim from having been asked and ignored.
+
 **Bounded.** Three knobs keep fan-out from running away:
 
 - `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.
@@ -338,7 +363,8 @@ pnpm run test:ui      # vp test --ui (local browser UI; not for CI)
 pnpm exec vp test --run tests/render-ptc.test.ts  # renderer unit tests only
 pnpm run build        # vp pack + declaration emit
 pnpm run verify:dist  # exercise renderCall/renderResult through the built dist (no LLM needed)
-node scripts/preview-ptc-render.mjs   # print the rendered rows with real theme colors
+PI_ROOT=<global-node-modules>/@earendil-works/pi-coding-agent \
+  node scripts/preview-ptc-render.mjs   # print the rendered rows with real theme colors
 ```
 
 Tooling: [oxc](https://oxc.rs) — `oxlint` + `oxfmt` (official defaults) — alongside
@@ -346,6 +372,14 @@ Tooling: [oxc](https://oxc.rs) — `oxlint` + `oxfmt` (official defaults) — al
 
 See ADR-0009 for the Vitest adoption decision (reopens ADR-0008's earlier deferment).
 
+## Credits
+
+Built clean-room from the PTC behaviour of
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (MIT,
+Copyright (c) 2026 DeepSeek), read at tag `dsh-v0.2.0-rc.2`, and hosted by
+[pi](https://pi.dev) (`earendil-works/pi`, MIT). Full attribution, and what is
+derived from what, is in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
 ## License
 
-Apache-2.0
+Apache-2.0. See [LICENSE](./LICENSE) and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-Party Notices
+
+`pi-ptc-subagents` is licensed under [Apache-2.0](./LICENSE). It depends on the third-party
+software listed below. Each project remains under its own license; nothing in this file changes
+those terms.
+
+## What is actually derived from what
+
+This project implements DSH's **PTC** (Programmable Tool Calling) mode as a `pi` extension. It is
+a clean-room implementation: see [ADR-0002](docs/adr/0002-source-strategy.md). What the code
+_derives_ from DeepSeek Harness is the **behavioural contract** — the tool surface, the
+`run_code` semantics, the numeric limits — and the **research notes under `docs/research/` cite
+it, line by line, from the public source.** Those notes reproduce substantial portions of DSH's
+source, which is why the attribution below is a licence obligation rather than a courtesy.
+
+| Project                                                                                                            | Licence | Role                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------- |
+| [`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness)                                  | MIT     | Behavioural reference and citation target for the PTC contract. Read at tag **`dsh-v0.2.0-rc.2`**. |
+| [`earendil-works/pi`](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`) | MIT     | The host this extension loads into. Peer dependency, not vendored.                                 |
+
+## DeepSeek Harness
+
+```
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Citations in `docs/research/upstream-20260930/` name paths inside that repository, pinned to
+`dsh-v0.2.0-rc.2`. Upstream also carries its own `THIRD_PARTY_NOTICES.md` for its dependency
+closure; that closure is upstream's concern, and this package depends on the harness only through
+reading it, not through importing it.
+
+## Runtime dependency
+
+| Package                                            | Licence       |
+| -------------------------------------------------- | ------------- |
+| [`minimatch`](https://github.com/isaacs/minimatch) | BlueOak-1.0.0 |
+
+`minimatch` is the only runtime (`dependencies`) entry; everything else is a `devDependency` or a
+`peerDependency` on the host.

package/dist/index.d.ts

@@ -41,6 +41,27 @@ interface ParsedAgentEvent {
     errorMessage?: string;
   };
   message_text?: string;
+  /**
+   * `tool_execution_end` carries the executed tool's name (`pi-agent-core`'s
+   * `ToolExecutionEndEvent`, alongside `toolCallId` and `isError`).
+   */
+  toolName?: string;
+  /** The tool call this event closes; carried through because the wire carries it. */
+  toolCallId?: string;
+  /** Whether that call was treated as an error; a failed call's payload is not a report. */
+  isError?: boolean;
+  /**
+   * The executed tool's full `AgentToolResult`, verbatim. `result.structuredContent` is where a
+   * tool that DECLARES an `outputSchema` puts its machine-readable value (ADR-0032's tool
+   * channel), and this repo already depends on that reaching it for three other tools.
+   *
+   * Typed `unknown` rather than a hand-written mirror of `AgentToolResult`: what arrives is
+   * whatever the child actually wrote, and the one reader of it validates through
+   * `validateChildReport` rather than trusting the shape to have survived the wire.
+   */
+  result?: {
+    structuredContent?: unknown;
+  };
 }
 /**
  * Opaque per-handle state owned by the adapter that produced it. The dispatch code
@@ -111,6 +132,76 @@ interface ChildProcessLifecycle {
   stderr(handle: ChildHandle): Promise<string>;
 }
 //#endregion
+//#region src/runtime/child-report.d.ts
+/**
+ * The child report's types (ADR-0032, `CONTEXT.md` §child report).
+ *
+ * These four declarations used to live in `dispatch.ts` next to the extraction that produces
+ * them. They moved here so the *persisted* `TaskRecord` field (`task-storage.ts`, Layer 1) can
+ * name the shape without a type-only import back up into the dispatch layer — a record that
+ * stores a report has to be able to say what a report is, and the storage layer is below the
+ * dispatcher, not above it. `dispatch.ts` re-exports all four, so every existing import site
+ * (and the report tool's) keeps working unchanged.
+ *
+ * The EXTRACTION stays in `dispatch.ts`. This module owns vocabulary, not parsing.
+ *
+ * #101 added the last two constants here, and the reason is the same one: ADR-0032's "the
+ * contract has exactly one home". The report tool's NAME and the SHAPE it demands are both
+ * needed by two modules that must not know about each other — `dispatch.ts`, which has to put
+ * the tool in the child's argv and read its `structuredContent` back, and the tool declaration
+ * in `src/tools/`, which must not import `dispatch.ts` (that edge has broken this repo's tests
+ * once; see `CHILD_REPORT_MAX_FINDINGS` below for why). Neither can reach the other's module, so
+ * both read the text from here, which imports nothing at all.
+ */
+/** One claim the child makes, with the evidence it rests on. */
+interface ChildReportFinding {
+  what: string;
+  evidence: string;
+}
+/**
+ * Which channel a {@link ChildReport} arrived over (ADR-0032 "The channel is always stated").
+ *
+ * `tool` is the report tool's `structuredContent`, read off `tool_execution_end`; `prompt-json`
+ * is the fenced block in the child's final assistant message, which is the channel that still
+ * works when this package does not load in the child at all; `none` means the contract was on and
+ * the child did not comply.
+ *
+ * `opted-out` is the fourth value, added by ticket #102, and it is the one that keeps `none`
+ * honest. Without it, an agent that opted out and a child that ignored the contract would produce
+ * the same string, and ADR-0032 has already said which of those two is a defect — so a reader
+ * could not tell "nobody asked" from "it did not comply". A field whose value cannot distinguish
+ * those is the silent failure `docs/testing-constraints.md` #3 forbids.
+ */
+type ChildReportChannel = "tool" | "prompt-json" | "none" | "opted-out";
+/**
+ * What the child DECLARES. `files_touched` is snake_case on purpose: this object is produced by a
+ * model emitting JSON, and renaming it on the way in would mean the wire text and the type
+ * disagree. The child's prose is returned alongside it, never replaced by it.
+ */
+interface ChildReportPayload {
+  summary: string;
+  findings: ChildReportFinding[];
+  files_touched: string[];
+}
+/**
+ * The child report as the host stamps it: the payload the child declared, plus `usage`, which is
+ * what the host OBSERVED and read off the child's own `message_end` usage blocks.
+ *
+ * `usage` is deliberately not on {@link ChildReportPayload}. A model cannot know its token
+ * count, so a child-declared `usage` would be a fabricated number that happened to look like a
+ * measurement — `docs/testing-constraints.md` #4 requires the expected value to point at an
+ * independent source, and the host's counter is that source. Anything the child puts under
+ * `usage` is read and discarded.
+ */
+interface ChildReport extends ChildReportPayload {
+  usage: {
+    input: number;
+    output: number;
+    cost: number;
+    turns: number;
+  };
+}
+//#endregion
 //#region src/runtime/task-storage.d.ts
 /**
  * The 6-state TaskRecord status (ADR-0022 §2). `queued` is deliberately absent in v1
@@ -167,6 +258,26 @@ interface TaskRecord {
   ownerPid?: number;
   /** ADR-0023: wall-clock ms when the owning runtime instance started; pairs with `ownerPid`. */
   ownerBootMs?: number;
+  /**
+   * ADR-0032: the child report a background child produced, read off its final message by the
+   * same extraction the foreground loop runs and stamped onto the record at the terminal
+   * transition — so `ptc_task_output` can hand a background child back with the same shape a
+   * foreground `DispatchResult` carries.
+   *
+   * **Both report fields are ABSENT unless the record reached `succeeded`** (the registry writes
+   * them; see `resolve-exit` in `task-registry.ts`). Absent is a claim in its own right: a child
+   * that is still running has not reported *yet*, and a child that failed did not report at all.
+   * Neither is the same claim as "ran and complied with nothing to say", which is what a
+   * `succeeded` record carrying `reportChannel: "none"` states.
+   */
+  report?: ChildReport;
+  /**
+   * ADR-0032 "The channel is always stated": which channel delivered `report`, and — when there
+   * is no `report` — the explicit marker that the child ignored the contract. Written with
+   * `report` and only on a `succeeded` record, so `reportChannel === undefined` never has to be
+   * read as "none".
+   */
+  reportChannel?: ChildReportChannel;
 }
 /**
  * Per-subscriber cursor for one TaskRecord (ADR-0022 §5). Cursor is per-subscriber (not per-task)
@@ -273,6 +384,8 @@ type TaskCommand = {
   outputBytes?: number;
   outputPreview?: string;
   childError?: string;
+  report?: ChildReport;
+  reportChannel: ChildReportChannel;
 };
 /** Outcome of one successful command: the persisted record, emitted events, and cursor. */
 interface TransitionResult {
@@ -857,10 +970,32 @@ export declare function buildPtcSkillsSection(skills: readonly Skill[], format?:
 /**
  * PTC run limits and spawn-time hardening, in one frozen `DEFAULT_CONFIG`.
  *
- * The numbers are DSH's (`dsh-v0.1.6-alpha.2`, `@deepseek-ai/dsh-ptc-runtime-node`)
- * carried over verbatim — see ADR-0003 (output budget), ADR-0004 (pending calls) and
- * ADR-0005 (execution boundary, F1–F4). Tests assert against these constants rather
- * than repeating the literals, so a future re-sync only has to change this file.
+ * The numbers are DSH's (`dsh-v0.2.0-rc.2`, `@deepseek-ai/dsh-ptc-runtime-node`,
+ * `NodePtcRuntime.Config` defaults) carried over verbatim — see ADR-0003 (output budget),
+ * ADR-0004 (pending calls) and ADR-0005 (execution boundary, F1–F4). Tests assert against
+ * these constants rather than repeating the literals, so a future re-sync only has to change
+ * this file.
+ *
+ * The baseline was `dsh-v0.1.6-alpha.2` until 2026-10-03. That tag was never the source of
+ * these numbers — the research the values came from read a `0.2.0-rc.2` checkout, and the
+ * values are byte-identical in both tags (verified field by field: 120000 / 600000 /
+ * 67108864 / 134217728 / 128 / 3000, in `packages/ptc-runtime/ptc-runtime-node/src/index.ts`).
+ * So the correction is to the version label only; no constant changed. The prior label was
+ * wrong for a different reason worth keeping in mind: it was read off this comment rather
+ * than off the research, and `docs/research/ptc-upstream-parity-audit-20260930.md` had
+ * already recorded the mismatch (and that this file's self-description was the stale side).
+ *
+ * **These limits match a generation of the upstream that upstream has since deprecated.**
+ * `dsh-v0.0.x` through `v0.1.6-alpha.2` ran a PTC program on `worker_threads` inside the host
+ * process; DSH superseded that on 2026-09-11 and moved Node PTC into a separate process in
+ * `v0.1.7-rc.1`, which also renamed the packages into the `ptc-runtime` family with no legacy
+ * aliases. The numeric defaults did not change across that move — which is why they still match
+ * — but the *shape* around them did, and this file configures the superseded shape (ADR-0005's
+ * worker boundary, not a process boundary). So "the numbers are DSH's" is true of two versions
+ * and describes an architecture upstream no longer recommends. Upstream's own README warns that
+ * there will be compatibility-breaking changes; the parity audit's recommendations 1-3 (upgrade
+ * pi, compare against its built-in `codemode`, and re-base this project's position) are the open
+ * work, and none of them is a comment fix.
  *
  * Deliberately absent:
  * - `syncTimeoutMs` / `maxConcurrentAgents` / `maxTotalAgents` — workflow-engine caps