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 +9 -0
- package/CHANGELOG.md +85 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +1 -1
- package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +1 -1
- package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +1 -1
- package/dist/extensions/core/prompt-builder/tool-description-trim.js +5 -5
- package/docs/LOCAL_DEV.md +109 -0
- package/package.json +1 -1
- package/skills/misdirection-audit/SKILL.md +1 -1
- package/skills/{herdr-topology → pane-topology}/SKILL.md +35 -18
- package/skills/subagent-orchestration/SKILL.md +62 -1
- package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
- package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +1 -1
- package/src/extensions/core/prompt-builder/tool-description-trim.ts +5 -5
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.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.5",
|
|
4
|
+
"sha": "e4d4f633f2707551090ffe407362b0266788dee9",
|
|
5
|
+
"shaShort": "e4d4f633",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
+
"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)
|
|
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:
|
|
3
|
-
description: "
|
|
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
|
-
- "
|
|
6
|
-
- "
|
|
7
|
-
- "
|
|
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
|
-
#
|
|
16
|
+
# Pane Topology
|
|
13
17
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
|
|
22
|
-
|
|
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
|
|
124
|
-
model-disabled
|
|
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,
|
|
273
|
-
handoff between agents) live in the subagent-orchestration
|
|
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
|
|
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 `
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
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:
|
|
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;
|