pi-braid 0.43.3 → 0.43.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -141,6 +141,15 @@ both code and any docs that reference it - or mark the doc
141
141
  Add new API names to `TRACKED_NAMES` in `check-doc-drift.mjs` as new
142
142
  drift surfaces emerge.
143
143
 
144
+ A third gate covers the counts these documents state, which the status and drift
145
+ gates do not read: **`scripts/check-source-claims.mjs`** re-runs the command
146
+ behind every count enrolled in `scripts/source-claims.json` and fails when a
147
+ document states a different number (`npm run check:source-claims`, part of
148
+ `npm run ci:check`). Enrol a count only when a command re-derives it: a measured
149
+ figure (a duration, a load average) and a released changelog's number belong to
150
+ the run that produced them, and an entry that holds an expected value with no
151
+ command behind it is the same drift with a gate painted on it.
152
+
144
153
  ## Tool Inventory
145
154
 
146
155
  The canonical, source-derived inventory of every tool provided/exposed by this
package/CHANGELOG.md CHANGED
@@ -43,6 +43,91 @@ reader-facing record; the tag scheme above applies unchanged.
43
43
 
44
44
  ---
45
45
 
46
+ ## Core — 0.43.5 (2026-10-28: the runtime suite runs eight files at once, and a planted hang still dies at its cap)
47
+
48
+ - **The core suite stopped waiting on one file at a time.** Its 320 files ran serially in 640s; eight in flight measured
49
+ 157s here, a 3.9x drop, with every file's own result unchanged: 320 passed either way. Results print in fixture
50
+ order, so the fixture lines of two runs of the same tree still match and a failing file's own output stays under
51
+ its line; the summary tail carries the run's wall clock, so that line differs whenever the run did.
52
+ - **Width sixteen is past the knee, and the numbers say why.** It bought 8 to 14 seconds of makespan over eight and
53
+ cost 82% more total work, 2,490s against 1,364s, doubling the median file's duration from 3.5s to 7.3s and turning
54
+ eight files red. The default is the machine's own parallelism capped at eight, and `--jobs 1` restores the serial
55
+ order a bisect needs.
56
+ - **The default cap moved from 30s to 60s because the cap was making the verdict.** A file's own duration grows by
57
+ 1.03x to 2.5x beside seven others, and the slowest file without an allowance of its own takes 21.5s alone; in the
58
+ pooled run measured for this release `fleet/test-drain-contention.mjs` took 33.9s, which a 30s cap kills as a
59
+ timeout the code did not earn. The three declared allowances stay: they bound wedges, not durations.
60
+ - **The pool cleans up after itself.** SIGINT and SIGTERM kill every live file group before the runner exits, so a
61
+ cancelled run leaves no detached children; a `PI_TEST_ROOT` that resolves to nothing is a failure instead of a
62
+ green run of zero files; `--timings` and `--timings-json` expose the durations a width has to be argued from.
63
+ - **The new fixture pins the contract, and it was made to fail before it was trusted.** It checks the three outcome
64
+ classes, the exit code, that a hang is killed at its cap rather than awaited, and that two one-second files at
65
+ width two overlap. At width one the two pool assertions redden and print the numbers that explain it: 2,278ms for
66
+ the pair, and 2,188ms of summed file duration inside a 2,192ms run.
67
+ - **A telegram fixture stopped inheriting the machine's own poller state, and its five siblings followed.**
68
+ `busy-steer.test.mjs` failed deterministically on any machine where a live pi process held the poller ownership
69
+ lock, because the extension correctly refuses to start a second `getUpdates` consumer and every delivery wait then
70
+ starved on a poller that never polled. It now pins `BRAID_HOME`, the lock path and the session role for the whole
71
+ case, and so do `coalesce`, `inbound-queue-durability`, `collision-aware`, `collision-idle-ctx` and `index`, which
72
+ inherited the same state: the whole telegram suite now runs green beside a live seat, where five of its files
73
+ previously failed up to twenty cases each. A refused start names its three causes instead of starving mute.
74
+ - **The runner names what it is waiting on, and the width it was given.** A run that has printed nothing for 30
75
+ seconds says once which file is holding the line, so an ordered flush that stalls on one slow file is visible
76
+ instead of looking like a hung suite. The contract fixture now also pins `--jobs` by census: a runner that ignores
77
+ the flag is caught, where before it passed every check in the file.
78
+ - **Four claims the runner made about itself were wrong, and the sentences moved rather than the behaviour.** An
79
+ invalid `PI_TEST_TIMEOUT_MS` now warns like its siblings instead of silently keeping the default; the loader
80
+ allowance is 200s because twelve cases over five lanes is three waves of a 60s driver cap, not two; `SKIP` is keyed
81
+ by path relative to the test root, and its dead entry for a file that exists nowhere is gone; and the verdict's
82
+ reliance on the file's output pipes closing, not just its exit, is now stated and pinned by a fixture, because a
83
+ helper holding the inherited stdout keeps the file open past its own exit.
84
+ - **Three fixtures were printing a verdict their cases had not earned.** Their local `test()` helper called an
85
+ `async` case and discarded the promise, so the case ran detached: a rejected case was marked as passing, the tally
86
+ read `0 failed`, and only Node's default unhandled-rejection handler made the exit non-zero. With nothing keeping
87
+ the loop alive past the summary, the same file printed `7 passed, 0 failed` and exited 0. Both halves are fixed -
88
+ the helper awaits its case and the call sites await the helper - and a rejecting case now fails the file.
89
+ - **A cleanup kill no longer fails a case because the process left first.** `fleet/test-cli.mjs` failed under a loaded
90
+ pooled run with `kill ESRCH`, because the supervisor had already exited when the signal arrived. A gone process is
91
+ what that cleanup wanted, so `ESRCH` is accepted there and any other errno still fails the case; the four kill
92
+ sites share the one helper.
93
+ - **The suite's tally stopped counting modules it never judged.** The run counted every walked `.mjs` as a passed
94
+ fixture, so three shared modules that assert nothing and the root aggregator added five to a number readers
95
+ compare between runs. They are now declared in `packages/core/test/runtime/fixture-manifest.json` with a reason each, the run
96
+ lists them beside the count instead of running them, and `check:suite-coverage` fails in both directions: a
97
+ counted module that cannot fail, and a declaration for a module the tree no longer carries.
98
+ - **A run that is interrupted leaves nothing behind.** `SIGINT` and `SIGTERM` killed every live file group but not
99
+ the per-file temp sandbox the runner creates, so every interrupted run stranded one directory. The handler now
100
+ sweeps them too, and both signals keep their exit codes.
101
+ - **The telegram suite stopped leaving 246 directories per run.** Its runner spawned each file with no `TMPDIR`, so
102
+ every per-case tree a fixture made landed in the machine's real temp directory and stayed. Each file now gets its
103
+ own sandbox, removed when it settles and on a signal, with the per-file `BRAID_HOME` and poller lock derived from
104
+ it so nothing a child writes to temp lands outside it.
105
+ - **Two fixtures stopped deciding their verdict from a fixed sleep.** They waited a guessed number of milliseconds
106
+ for a chain of deferrals and then read a count, which failed 19 times in 130 loaded attempts; they now poll for
107
+ arrival, hold until the count stops moving so a double send is still caught, and say which way a count went wrong.
108
+ - **`scripts/prompt-capture.mjs` renders a build's assembled prompt and diffs two captures.** Two captures of one
109
+ build are byte-identical, each hunk is labelled with its prompt region, and the header lists the surfaces the
110
+ pinning hides. The misdirection audit's third probe pointed at a two-build prompt diff no tool could produce;
111
+ it names this one now.
112
+ - **Two files earned a longer allowance from measurement rather than from their idle duration.** `test-pack-provenance`
113
+ and `test-braid-home-containment` sit at 48.3s and 47.2s beside seven other files under load and at 28.1s and
114
+ 21.9s one at a time, so a pool on a box slower than this one would have killed them for the box's weather.
115
+
116
+ ## Core — 0.43.4 (2026-10-28: the pane guide is named for the model, and a seat can hand over)
117
+
118
+ - **The skill about panes is named for what it teaches.** Workspaces, tabs, panes, opaque ids, read sources and the
119
+ agent lifecycle are not Herdr's inventions, so a skill named after Herdr read as a product scope rather than a
120
+ model. It is `pane-topology` now: the containment model leads, every fact that is Herdr's stays named as Herdr's,
121
+ and the triggers include the three tool names, so a model that has the tools but not the product word still finds
122
+ it. Three trimmed tool descriptions, the prompt-builder table row and the six fixtures that pin the shipped name
123
+ follow the rename.
124
+ - **`subagent-orchestration` carries the self-transfer procedure**: what opens a handover (a newer build, changed
125
+ settings, an exhausted seat), the ordered steps, which side closes which pane, and the `wait:false` trap with what
126
+ it costs, since a blocked predecessor holds the channel after it has already handed over.
127
+ - **`test-skills-floor` no longer requires a naming coincidence.** Its trigger assertion held only because one skill
128
+ was named after the multiplexer whose tools share its prefix; it now carries a positive control and asserts
129
+ whichever of the two renderings the real inputs produce.
130
+
46
131
  ## Core — 0.43.3 (2026-10-28: one description, two intros, and a gate that keeps them honest)
47
132
 
48
133
  - **The registry page and the repository page open with the same claim.** The npm README still opened with a summary
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.3",
4
- "sha": "de3d490983070d6167f69effced95968567c905d",
5
- "shaShort": "de3d4909",
3
+ "version": "0.43.5",
4
+ "sha": "e4d4f633f2707551090ffe407362b0266788dee9",
5
+ "shaShort": "e4d4f633",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-28T12:01:27.384Z"
8
+ "packedAt": "2026-10-29T11:33:28.249Z"
9
9
  }
@@ -15,7 +15,7 @@
15
15
  * The registered tool DESCRIPTIONS of herdr_* are trimmed
16
16
  * to 1-2 lines at the provider-payload layer (tool-description-trim.ts,
17
17
  * before_provider_request) and the deep topology guidance lives in the
18
- * herdr-topology SKILL (progressive disclosure). This map keeps its
18
+ * pane-topology SKILL (progressive disclosure). This map keeps its
19
19
  * render-fallback role (priority 3) — still load-bearing if pi-herdr ever
20
20
  * stops self-registering promptGuidelines.
21
21
  */
@@ -15,7 +15,7 @@
15
15
  * The registered tool DESCRIPTIONS of herdr_* are trimmed
16
16
  * to 1-2 lines at the provider-payload layer (tool-description-trim.ts,
17
17
  * before_provider_request) and the deep topology guidance lives in the
18
- * herdr-topology SKILL (progressive disclosure). This map keeps its
18
+ * pane-topology SKILL (progressive disclosure). This map keeps its
19
19
  * render-fallback role (priority 3) — still load-bearing if pi-herdr ever
20
20
  * stops self-registering promptGuidelines.
21
21
  */
@@ -26,7 +26,7 @@
26
26
  *
27
27
  * Dependency-inversion compatibility: descriptions remain owned by the
28
28
  * registering package. The curated strings below only SHORTEN the channel
29
- * form and point at the herdr-topology SKILL for the deep form
29
+ * form and point at the pane-topology SKILL for the deep form
30
30
  * (progressive disclosure). The when-gate ("only when the user explicitly
31
31
  * mentions Herdr") is load-bearing and preserved in every rewrite.
32
32
  *
@@ -26,7 +26,7 @@
26
26
  *
27
27
  * Dependency-inversion compatibility: descriptions remain owned by the
28
28
  * registering package. The curated strings below only SHORTEN the channel
29
- * form and point at the herdr-topology SKILL for the deep form
29
+ * form and point at the pane-topology SKILL for the deep form
30
30
  * (progressive disclosure). The when-gate ("only when the user explicitly
31
31
  * mentions Herdr") is load-bearing and preserved in every rewrite.
32
32
  *
@@ -38,16 +38,16 @@
38
38
  * name; currently covers @ogulcancelik/pi-herdr (layout/pane/agent).
39
39
  */
40
40
  export const TRIM_TOOL_DESCRIPTIONS = {
41
- herdr_layout: "Create/inspect Herdr terminal topology (workspaces, tabs, panes; layout only, never starts agents or commands). Use only when the user explicitly mentions Herdr. Read pane IDs from results; deep procedures live in the herdr-topology skill.",
42
- herdr_pane: "Raw Herdr terminal pane control: run, read, wait_output, send_text/send_keys, inspect, close. Use only when the user explicitly mentions Herdr; prefer herdr_agent for recognized coding agents. Deep procedures: herdr-topology skill.",
43
- herdr_agent: "Drive a recognized coding agent in an existing Herdr pane: start, prompt, wait, read, send_keys. Use only when the user explicitly mentions Herdr; needs an available shell pane from herdr_layout first. Deep procedures: herdr-topology skill.",
41
+ herdr_layout: "Create/inspect Herdr terminal topology (workspaces, tabs, panes; layout only, never starts agents or commands). Use only when the user explicitly mentions Herdr. Read pane IDs from results; deep procedures live in the pane-topology skill.",
42
+ herdr_pane: "Raw Herdr terminal pane control: run, read, wait_output, send_text/send_keys, inspect, close. Use only when the user explicitly mentions Herdr; prefer herdr_agent for recognized coding agents. Deep procedures: pane-topology skill.",
43
+ herdr_agent: "Drive a recognized coding agent in an existing Herdr pane: start, prompt, wait, read, send_keys. Use only when the user explicitly mentions Herdr; needs an available shell pane from herdr_layout first. Deep procedures: pane-topology skill.",
44
44
  };
45
45
  /** Third-party family the trim applies to (prefix match for the fallback). */
46
46
  const TRIMMED_PREFIX = "herdr_";
47
47
  /** The when-gate is load-bearing. */
48
48
  const HERDR_GATE = "Use only when the user explicitly mentions Herdr";
49
49
  /** Skill pointer appended to fallback trims (progressive disclosure home). */
50
- const SKILL_POINTER = "Deep procedures: herdr-topology skill.";
50
+ const SKILL_POINTER = "Deep procedures: pane-topology skill.";
51
51
  /** Fallback trim applies only to descriptions longer than this. */
52
52
  const FALLBACK_MAX_CHARS = 240;
53
53
  /** Cap the description to its leading sentences within maxChars. */
package/docs/LOCAL_DEV.md CHANGED
@@ -47,20 +47,129 @@ npm install # installs all workspaces (peer-resolves the pi packages)
47
47
  npm run typecheck # all four code packages
48
48
  npm run build # compile core to dist/
49
49
  npm test # build + runtime test suites (core)
50
+ node packages/core/scripts/run-tests.mjs --jobs 1 --timings # the same files serially, with durations
50
51
  npm run lint # ESLint over all four code packages
51
52
  npm run format # prettier --write .
52
53
  npm run format:check # prettier --check .
53
54
  npm run check:docs # every in-scope .md has a status marker
54
55
  npm run check:doc-drift # current-state docs must not reference APIs missing from code
55
56
  npm run check:deps # layer-boundary check
57
+ npm run check:source-claims # every count a doc states is re-derived from the tree
56
58
  ```
57
59
 
60
+ The counts these documents state are re-derived, not copied.
61
+ `packages/core/scripts/source-claims.json` holds the counts the gate governs - the
62
+ file and line each one is written on, a pattern that reads it out of that line,
63
+ and the command that derives it from the tree - and `npm run check:source-claims`
64
+ re-runs every command and fails on a disagreement. A count no command re-derives
65
+ is not enrolled: a measurement (a duration, a load average) belongs to the run
66
+ that produced it, and a figure in a released changelog belongs to that release.
67
+
68
+ The core runtime suite runs its files in a bounded pool: the machine's own
69
+ parallelism, at most eight. The width is a flag, so the same files can be run
70
+ one at a time when a failure needs the serial order, and their durations can
71
+ be printed or written for a comparison between two widths:
72
+
73
+ ```bash
74
+ node packages/core/scripts/run-tests.mjs --jobs 1 # one file at a time
75
+ node packages/core/scripts/run-tests.mjs --timings # per-file durations, slowest first
76
+ node packages/core/scripts/run-tests.mjs --timings-json=/tmp/timings.json
77
+ ```
78
+
79
+ `PI_TEST_JOBS` sets the width without the flag. Results always print in
80
+ fixture order, so the per-file lines of two runs of the same tree match; the
81
+ summary line carries the run's own wall clock, so it differs whenever the run
82
+ did, and a diff between two widths should compare the file lines rather than
83
+ the tail. The cost of that order is that a slow file at the head of the walk
84
+ holds every later line, so a run that has printed nothing for 30 seconds says
85
+ once which file it is waiting on.
86
+
58
87
  Per-workspace variants use the workspace flag, e.g.
59
88
  `npm run build -w packages/core`, `npm test -w packages/providers`.
60
89
 
61
90
  The combined gate is `npm run ci:check` (docs, drift, deps, format,
62
91
  typecheck, tests).
63
92
 
93
+ ### Fixtures and process groups
94
+
95
+ The runner starts each file in its own process group and signals the group: at
96
+ the file's cap with `SIGKILL`, and the same on `SIGINT`/`SIGTERM`. A fixture's
97
+ own helpers therefore stay in that group, so nothing a helper starts outlives
98
+ the run: the group is killed when the file settles or reaches its cap.
99
+
100
+ The file settles when its output pipes close, not when its process exits. A
101
+ helper that inherits the file's stdout keeps that pipe open after the file
102
+ exits, so the runner still counts the file as running; if the helper outlives
103
+ the cap, the file is reported as a timeout even though its own exit code was 0.
104
+ Give a helper its own stdio, or wait for it to exit, before the fixture exits.
105
+
106
+ A helper spawned with `detached: true` calls `setsid()`, leaves the group, and
107
+ outlives the run that started it: no group signal reaches it. One fixture needs
108
+ that escape - `test/runtime/fleet/test-supervisor-recovery.mjs` fabricates an
109
+ owner and an orphaned turn, and `detached: true` is what keeps those processes
110
+ from being the fixture's own children, since a zombie child keeps its group
111
+ answering a liveness check long after the kernel killed the process. It reaps
112
+ each of them by pid when it is done, and an interrupt caught while that file is
113
+ in flight leaves nothing longer-lived than its own `sleep 30`, which ends
114
+ itself. Any other fixture that escapes the group owes an explicit cleanup on
115
+ every exit path, the interrupt one included.
116
+
117
+ ### Fixtures and their own temp directory
118
+
119
+ Every runner that spawns fixture files gives each file its own `TMPDIR` and
120
+ removes that tree when the file settles, and on `SIGINT`/`SIGTERM` too. A
121
+ fixture's `mkdtemp` then writes inside the sandbox instead of the machine's
122
+ temp directory: a case that never cleans up after itself, or a file killed at
123
+ its cap, which cannot clean up, costs one tree the runner already owns.
124
+ `packages/core/scripts/run-tests.mjs` and
125
+ `packages/telegram/test/run-tests.mjs` both do this; the telegram runner also
126
+ derives its per-file `BRAID_HOME` and poller-lock pins from that same temp
127
+ root, so nothing a child writes to temp lands outside the sandbox.
128
+
129
+ The signal path needs a runner that is not blocked in a synchronous spawn:
130
+ a JS signal handler cannot run while `spawnSync` waits, so a blocking loop
131
+ only cleans up after the file it was waiting on has already returned. The
132
+ core runner's pool and the telegram runner's per-file `spawn` both keep the
133
+ loop free for the handler.
134
+
135
+ When you change a runner, count the fixture-named directories under `$TMPDIR`
136
+ before and after a full run. A non-zero delta is the leak this rule prevents.
137
+
138
+ ### New fixtures: use `node:test`
139
+
140
+ A new fixture is written on `node:test`. The runner does not care which style a
141
+ file uses - 87 of the core suite's 321 fixtures already use `node:test` - so the
142
+ reason is the failure the other style produces. A hand-rolled helper that calls
143
+ `fn()` without awaiting it discards the case's promise, so an `async` case runs
144
+ detached and the file can print its green tally before that case settles, with
145
+ the exit code computed from a counter the case never reached. `node:test` cannot
146
+ take that shape. Existing files are not rewritten for style; a file with async
147
+ cases that a synchronous helper discards is fixed when it is touched, by
148
+ awaiting the helper's call or by moving to `node:test`.
149
+
150
+ ### What the count counts
151
+
152
+ The runner walks every `.mjs` under `test/runtime` and counts each file that
153
+ exits 0 as a passed fixture, so a module the walk sees and no case ever judges
154
+ would still add one to the summary line. A shared helper in `test/runtime/lib/`
155
+ is exactly that: the fixtures import it, it registers nothing, and it asserts
156
+ nothing when the runner loads it on its own.
157
+
158
+ Those modules are declared in `test/runtime/fixture-manifest.json`, under
159
+ `notFixtures`, each with the reason it is not a fixture. The runner neither runs
160
+ nor counts a declared module, and says so where it introduces the count. The
161
+ reason is required, so a module leaves the count with one on record, and
162
+ `node packages/core/scripts/run-tests.mjs --list` prints the whole population
163
+ with the declarations beside it, running nothing.
164
+
165
+ `npm run check:suite-coverage` holds both halves of that declaration. A counted
166
+ module must register a case with `node:test`, assert from `node:assert` while it
167
+ loads, or call a function it declares at load (the hand-rolled harness that
168
+ names its own cases and sets the exit code). A declared module must be none of
169
+ those, because a declaration that names a real fixture keeps a test out of the
170
+ run. A new helper therefore fails the gate until it is declared, and a declared
171
+ helper that grows a case fails it until it is taken back into the count.
172
+
64
173
  ## Two install modes
65
174
 
66
175
  ### 1. Live symlink (default for active development)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.3",
3
+ "version": "0.43.5",
4
4
  "description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -19,7 +19,7 @@ Three probes, in order. Record command, exit code, and raw output for each.
19
19
 
20
20
  1. **Tree provenance scan.** `npm run check:placement -- --strict` at the repo root. Flags provenance tokens (wave/worker/round labels, ISO dates, commit refs) in comments and string literals, role words used as policy in generic layers, and owner home paths anywhere. Exit 0 is clean; every hit is an instance with a file:line.
21
21
  2. **Domain-literal grep.** Beyond the checker's built-in classes, grep the generic layers for policy that belongs to a domain: role names inside cwd gates or classification logic, hardcoded home-directory roots, project or feature names inside shared mechanism code. The checker's exclusion list documents which paths legitimately own these words; a hit outside the owners is an instance.
22
- 3. **Prompt-capture diff.** Capture the assembled prompt from two builds (shipped vs candidate), then byte-diff. Every delta must map to an intended text change; an unintended delta is an instance (unmeasured innovation, or doc drift at the prompt layer).
22
+ 3. **Prompt-capture diff.** Capture the assembled prompt from two builds (shipped vs candidate) with `node scripts/prompt-capture.mjs capture --root <dir holding dist> --out <file>`, then `node scripts/prompt-capture.mjs diff <old> <new>`. The root is the directory that holds `dist/`, and that differs by arm: a checkout is `<repo>/packages/core`, while the installed package at `~/.pi/agent/npm/node_modules/pi-braid` carries `dist/` at its own root, so pointing the command at `<installed>/packages/core` exits 2 with ENOENT. Every delta must map to an intended text change; an unintended delta is an instance (unmeasured innovation, or doc drift at the prompt layer). The capture pins every non-code input, so two captures of one build are byte-identical and the only hunks are real; it labels each hunk with the prompt region it belongs to. What it cannot see is listed in its header.
23
23
 
24
24
  Then read the recent output corpus: reports, briefs, and the git log since the last audit. Admit an instance only with a file:line, message id, or commit ref. "It feels like" is not an instance.
25
25
 
@@ -1,25 +1,39 @@
1
1
  ---
2
- name: herdr-topology
3
- description: "Deep topology guidance for driving Herdr terminal panes and coding agents through the herdr_layout, herdr_pane, and herdr_agent tools: the workspace/tab/pane model, opaque ID handling, read sources and output recovery, agent lifecycle states, and orchestrator field procedures (fresh-restart over nudge-resume, staged-prompt verification, pane hygiene). Load when actually controlling Herdr, not on first mention."
2
+ name: pane-topology
3
+ description: "Use when work needs more than one terminal surface, or when a pane, tab or agent has to be read or driven: the containment model (workspaces hold tabs, tabs hold panes, panes hold processes), opaque ID handling, the read sources that recover output, the two control surfaces the herdr_layout, herdr_pane and herdr_agent tools expose (a raw terminal channel and a coding-agent channel), agent lifecycle states, and the orchestrator procedures that keep a multi-pane wave honest about its progress. Load when actually splitting, reading or driving a pane, not on first mention."
4
4
  triggers:
5
- - "driving herdr panes or agents"
6
- - "herdr_layout / herdr_pane / herdr_agent in use"
7
- - "multi-pane worker coordination"
5
+ - "pane topology"
6
+ - "split a pane"
7
+ - "terminal panes"
8
+ - "driving panes"
9
+ - "herdr_layout"
10
+ - "herdr_pane"
11
+ - "herdr_agent"
8
12
  validated: 2026-09-07
9
13
  verdict: KEEP
10
14
  ---
11
15
 
12
- # Herdr Topology
16
+ # Pane Topology
13
17
 
14
- Progressive-disclosure companion to the Herdr tools. The tool descriptors
15
- carry one line each; this file carries the deep form. Herdr itself is used
16
- **only when the user explicitly mentions Herdr** - if you are reading this,
17
- that gate has already been satisfied.
18
+ A containment model and two control surfaces over it. The model is the part a
19
+ model needs before it touches anything: what a terminal multiplexer contains,
20
+ what an identifier points at, and what a read can recover. The surfaces are
21
+ `herdr_layout` (shape and inspect the topology), `herdr_pane` (raw terminal
22
+ control) and `herdr_agent` (drive a recognized coding agent in a pane).
23
+
24
+ This file is the deep form; each tool descriptor carries one line. Where a
25
+ fact is Herdr's - its CLI quirks, its version behavior, its lifecycle states,
26
+ its issue numbers - the fact says Herdr, because that is where it is true. The
27
+ rest is the model, and a different multiplexer keeps the model and replaces
28
+ the facts.
29
+
30
+ Herdr itself is used **only when the user explicitly mentions Herdr**. If you
31
+ are reading this, that gate has already been satisfied.
18
32
 
19
33
  ## The containment model
20
34
 
21
- Workspaces contain tabs; tabs contain panes. Herdr recognizes coding agents
22
- occupying panes and exposes them by name.
35
+ Three levels, and every operation names one of them. Herdr calls them
36
+ workspaces, tabs and panes; the shape is what matters:
23
37
 
24
38
  - Creating a workspace or tab also creates its root pane; splitting an
25
39
  existing pane creates another pane. There is no "create empty container".
@@ -28,6 +42,8 @@ occupying panes and exposes them by name.
28
42
  - A pane exists whether or not an agent occupies it. `herdr_agent start`
29
43
  requires an existing, available shell pane and never creates, splits, or
30
44
  moves layout.
45
+ - Herdr recognizes coding agents occupying panes and exposes them by name, so
46
+ an agent is addressable two ways: by name, or by the pane hosting it.
31
47
 
32
48
  ## IDs are opaque: read, never construct
33
49
 
@@ -57,7 +73,8 @@ replaced: a process cannot close the pane it runs in, so during a
57
73
  mastership transfer the incoming seat owns that close and runs
58
74
  `herdr_pane close <pane>` on the outgoing seat's pane. The exception covers
59
75
  that pane and nothing else - worker panes you did not spawn, tabs, and
60
- workspaces still wait for the user's word.
76
+ workspaces still wait for the user's word. The transfer procedure, including
77
+ when it is worth its cost, is in the subagent-orchestration skill.
61
78
 
62
79
  ## Panes: raw terminal control
63
80
 
@@ -120,8 +137,8 @@ prompt, wait, read, and send_keys instead of raw pane input.
120
137
  whole run - and a timed-out wait does NOT mean the prompt failed; check `get`
121
138
  before re-sending. Only prompt with the default when blocking is the intent.
122
139
  (Observed 2026-10-09: a helper that had read only the native `herdr` docs
123
- omitted `wait:false` and hung its dispatcher; the native `herdr` skill is
124
- model-disabled on this machine, this skill is the operating surface.)
140
+ omitted `wait:false` and hung its dispatcher; the native `herdr` skill can be
141
+ model-disabled, leaving this skill as the operating surface.)
125
142
  - `idle` means ready for input with the tab seen in the focused UI; `done`
126
143
  is the same underlying readiness after unseen background work finishes.
127
144
  Focusing the tab (or targeting the pane/agent) marks it seen; CLI reads do
@@ -269,6 +286,6 @@ left running holds a name, a pane, and possibly a bill.
269
286
  is the always-visible form; this skill is the on-demand deep form.
270
287
  - `herdr_layout` results are the single source of topology truth; everything
271
288
  else takes IDs from there.
272
- - Orchestration-level concerns (spawn patterns, worker lifecycles, context
273
- handoff between agents) live in the subagent-orchestration skill; this
274
- file only covers the terminal topology underneath them.
289
+ - Orchestration-level concerns (spawn patterns, worker lifecycles, mastership
290
+ transfer, context handoff between agents) live in the subagent-orchestration
291
+ skill; this file only covers the terminal topology underneath them.
@@ -323,7 +323,10 @@ herdr action=send pane=<successor> text="[agent:orchestrator→successor] Read /
323
323
 
324
324
  Best for a successor that will orchestrate subagents. TUI pi persists, accepts signaling, can spawn its own workers.
325
325
 
326
- 3. Transfer mastership: the current session closes when the successor completes. The successor closes the predecessor's pane with `herdr_pane close <predecessor-pane>` - the predecessor cannot close the pane it runs in, so the incoming seat owns that one close and the transfer ends there.
326
+ 3. Transfer mastership: the self-transfer procedure below owns the detail. The short form: the
327
+ successor closes the predecessor's pane with `herdr_pane close <predecessor-pane>` after
328
+ verifying the predecessor's process is gone, because a process cannot close the pane it runs
329
+ in, and the incoming seat owns that one close. The predecessor stands down by ending its turn.
327
330
  4. The successor starts clean (no bloat) and reads the handoff.
328
331
 
329
332
  This is a **pipeline, not a loop**: each session is a fresh stage. Never compact above 70% - cascade instead.
@@ -490,6 +493,64 @@ Master: "I am pane-abc. Your task is X. When done, close pane-abc."
490
493
 
491
494
  Without this, the child cannot locate the parent to close it.
492
495
 
496
+ ### Self-transfer: a seat hands mastership to a fresh successor
497
+
498
+ A running process keeps the module it booted with, so a fresh process is the only way to pick
499
+ up a newer build, a changed setting, or a new route order. The seat may hand over whenever that
500
+ is what the work needs; it does not wait for a crisis.
501
+
502
+ Reach for it when:
503
+
504
+ - a newer build exists than the one this process booted with (an adoption wave merged, or the
505
+ owner published),
506
+ - settings or route order changed and the running process cannot see them,
507
+ - the seat is wedged, or its context is exhausted past recovery,
508
+ - the owner asks for it.
509
+
510
+ Not a first resort for a long session: a handover costs a boot, a re-derivation of every claim,
511
+ and a window in which neither seat fully owns the channel.
512
+
513
+ 1. **Write the handoff and finish the turn's durable writes first.** Goal, live state (workers
514
+ and their panes, open locks, branches), the queue with paths, and the traps this seat
515
+ learned. After step 2 a prompt may be the last thing this seat does, so anything still only
516
+ in context is lost.
517
+ 2. **Spawn the successor in its own pane, on the newest installed build.** Dispatch the handoff
518
+ prompt with `wait: false` and let it boot; the successor reads the handoff, re-derives its
519
+ boot claims from instruments, and writes its boot report in its own pane, because the pane is
520
+ the only channel between seats.
521
+ 3. **Verify the boot claims from that pane.** Version and model, the session it opened, the
522
+ skills and settings it loaded: a successor reporting a different build than the one you mean
523
+ to hand over to has not picked up the change, and the transfer stops there.
524
+ 4. **Release the channel, then stand down.** `telegram_poller` disable, write "CHANNEL IS FREE"
525
+ into the successor's pane through a herdr call that passes `wait: false`, and end the turn with
526
+ a text-only reply. After that the outgoing seat touches no channel, fleet, queue, repo or
527
+ setting, and arms at most one timer to read the successor's pane.
528
+
529
+ **The trap, and what it costs.** Never end a handover with a `herdr_agent prompt` against the
530
+ successor's pane and the default `wait: true`. The default waits for the successor's lifecycle
531
+ to settle; a booting successor is working and does not settle, so the outgoing seat blocks
532
+ inside the call, never stands down, and the poller lock stays with a seat that has already
533
+ handed over. The successor's `telegram_poller` enable is then refused while a live foreign pid
534
+ holds that lock, and the inbound channel goes to a process that has stopped reading it.
535
+
536
+ The mirror rule, for the incoming side: a handoff message that arrives as a herdr-delivered
537
+ prompt is a blocked predecessor waiting on your lifecycle. Finish the durable writes of that
538
+ turn (lock read, journal, scratchpad) and end the turn with a text-only reply; the turn end is
539
+ what releases it, and holding your own turn open to wait for the predecessor blocks both seats.
540
+
541
+ **Who closes which pane.** The outgoing seat does not close its own pane, because a process
542
+ cannot close the pane it runs in. The successor closes it with `herdr_pane close <pane>` after
543
+ verifying the outgoing process is actually gone (the pid the poller lock named, or `ps`), since
544
+ a close against a live process destroys in-flight state. That one pane close is the whole of the
545
+ exception: the successor still does not close panes it did not inherit.
546
+
547
+ **The journal.** The transfer is two lines in the project journal, not a paragraph in the
548
+ handoff: an intention line before the successor is spawned (`node
549
+ packages/core/scripts/journal-append.mjs`), and an outcome line once the outgoing process is
550
+ gone, with the poller-lock read as its evidence (`node
551
+ packages/core/scripts/check-journal.mjs`). An intention with no outcome entry is an unfinished
552
+ handover, and the next seat treats the channel as contended until it reads otherwise.
553
+
493
554
  ## Next-Task Selection
494
555
 
495
556
  After every `finalize`, decide what to do next. Do not guess - use this procedure:
@@ -37,7 +37,7 @@ Every file in this folder either:
37
37
  | `pi-reference-section.ts` | Pi docs seat: `PI_REFERENCE_POINTER` + `piReferenceSection()` - a static pointer to the `pi-reference` skill (docs index + install paths), rendered after the tools section. Replaced the native `<docs>` re-emission; the parity registry marks the native `docs` key dropped. |
38
38
  | `system-info-tool.ts` | `system_info` tool: full Instance data on demand (detail full or compact). The seat for volatile facts (elapsed, last event, turns, tool average) and the core/cwd/settings path triple; a tool result is not a cached prefix. |
39
39
  | `inspect.ts` | `prompt_inspect` tool: reads the actual system prompt from runtime. |
40
- | `tool-description-trim.ts` | Third-party tool-description trim: `before_provider_request` handler that shortens registered descriptions of `herdr_*` tools to 1-2 lines in the API tools channel (curated map + prefix fallback); the deep form moved to the `herdr-topology` skill (progressive disclosure). When-gate preserved in every rewrite. |
40
+ | `tool-description-trim.ts` | Third-party tool-description trim: `before_provider_request` handler that shortens registered descriptions of `herdr_*` tools to 1-2 lines in the API tools channel (curated map + prefix fallback); the deep form moved to the `pane-topology` skill (progressive disclosure). When-gate preserved in every rewrite. |
41
41
 
42
42
  ## Local Contracts
43
43
 
@@ -15,7 +15,7 @@
15
15
  * The registered tool DESCRIPTIONS of herdr_* are trimmed
16
16
  * to 1-2 lines at the provider-payload layer (tool-description-trim.ts,
17
17
  * before_provider_request) and the deep topology guidance lives in the
18
- * herdr-topology SKILL (progressive disclosure). This map keeps its
18
+ * pane-topology SKILL (progressive disclosure). This map keeps its
19
19
  * render-fallback role (priority 3) — still load-bearing if pi-herdr ever
20
20
  * stops self-registering promptGuidelines.
21
21
  */
@@ -26,7 +26,7 @@
26
26
  *
27
27
  * Dependency-inversion compatibility: descriptions remain owned by the
28
28
  * registering package. The curated strings below only SHORTEN the channel
29
- * form and point at the herdr-topology SKILL for the deep form
29
+ * form and point at the pane-topology SKILL for the deep form
30
30
  * (progressive disclosure). The when-gate ("only when the user explicitly
31
31
  * mentions Herdr") is load-bearing and preserved in every rewrite.
32
32
  *
@@ -40,11 +40,11 @@
40
40
  */
41
41
  export const TRIM_TOOL_DESCRIPTIONS: Record<string, string> = {
42
42
  herdr_layout:
43
- "Create/inspect Herdr terminal topology (workspaces, tabs, panes; layout only, never starts agents or commands). Use only when the user explicitly mentions Herdr. Read pane IDs from results; deep procedures live in the herdr-topology skill.",
43
+ "Create/inspect Herdr terminal topology (workspaces, tabs, panes; layout only, never starts agents or commands). Use only when the user explicitly mentions Herdr. Read pane IDs from results; deep procedures live in the pane-topology skill.",
44
44
  herdr_pane:
45
- "Raw Herdr terminal pane control: run, read, wait_output, send_text/send_keys, inspect, close. Use only when the user explicitly mentions Herdr; prefer herdr_agent for recognized coding agents. Deep procedures: herdr-topology skill.",
45
+ "Raw Herdr terminal pane control: run, read, wait_output, send_text/send_keys, inspect, close. Use only when the user explicitly mentions Herdr; prefer herdr_agent for recognized coding agents. Deep procedures: pane-topology skill.",
46
46
  herdr_agent:
47
- "Drive a recognized coding agent in an existing Herdr pane: start, prompt, wait, read, send_keys. Use only when the user explicitly mentions Herdr; needs an available shell pane from herdr_layout first. Deep procedures: herdr-topology skill.",
47
+ "Drive a recognized coding agent in an existing Herdr pane: start, prompt, wait, read, send_keys. Use only when the user explicitly mentions Herdr; needs an available shell pane from herdr_layout first. Deep procedures: pane-topology skill.",
48
48
  };
49
49
 
50
50
  /** Third-party family the trim applies to (prefix match for the fallback). */
@@ -54,7 +54,7 @@ const TRIMMED_PREFIX = "herdr_";
54
54
  const HERDR_GATE = "Use only when the user explicitly mentions Herdr";
55
55
 
56
56
  /** Skill pointer appended to fallback trims (progressive disclosure home). */
57
- const SKILL_POINTER = "Deep procedures: herdr-topology skill.";
57
+ const SKILL_POINTER = "Deep procedures: pane-topology skill.";
58
58
 
59
59
  /** Fallback trim applies only to descriptions longer than this. */
60
60
  const FALLBACK_MAX_CHARS = 240;