@evoclock/pi-agentic-driver 0.5.0 → 0.6.0

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.
Files changed (5) hide show
  1. package/README.md +267 -215
  2. package/package.json +2 -1
  3. package/scripts/enforcement/guest_containment_taxonomy.v1.json +26 -0
  4. package/scripts/enforcement/linux_microvm_cutover_pi.js +184 -17
  5. package/scripts/enforcement/linux_microvm_remote_fixture.sh +2418 -19
package/README.md CHANGED
@@ -1,83 +1,87 @@
1
- # pi-agentic-driver v0.5.0
1
+ # pi-agentic-driver v0.6.0
2
2
 
3
3
  <p align="center">
4
- <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver — Yamagane origami mark" width="140"/>
4
+ <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver, Yamagane origami mark" width="140"/>
5
5
  </p>
6
6
 
7
7
  <p align="center">
8
8
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat" alt="License: AGPL v3"/></a>
9
9
  <a href="https://www.npmjs.com/package/@evoclock/pi-agentic-driver"><img src="https://img.shields.io/npm/v/@evoclock/pi-agentic-driver?style=flat" alt="npm version"/></a>
10
- <img src="https://img.shields.io/badge/version-0.5.0-blue?style=flat" alt="Version 0.5.0"/>
10
+ <img src="https://img.shields.io/badge/version-0.6.0-blue?style=flat" alt="Version 0.6.0"/>
11
11
  <img src="https://img.shields.io/badge/status-active%20development%20%26%20testing-orange?style=flat" alt="Status"/>
12
12
  <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat&logo=javascript&logoColor=black" alt="JavaScript"/>
13
13
  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript"/>
14
14
  <img src="https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white" alt="Python"/>
15
15
  </p>
16
16
 
17
- Without guardrails, an agent can rewrite code that an existing abstraction
18
- already covers. It can ship to the wrong remote, lose context, or report
19
- success without evidence. Pi is an excellent agent harness. I need these
20
- guardrails for the way I work.
17
+ An agent without guardrails will rewrite code an existing abstraction already
18
+ covers. It will ship to the wrong remote. It will lose context and report
19
+ success without evidence. Pi is deliberately lean by design: the harness is yours to
20
+ shape. That philosophy is exactly what these extensions practice, they make them mine (and possibly yours too). They take
21
+ some concerns I consider worth addressing, and make them part of the
22
+ harness.
21
23
 
22
- **pi-agentic-driver adds these guardrails as Pi extensions. The agent does the
23
- work. Each extension makes the work verifiable and bounded.** Review happens
24
- before the agent writes code. Communication carries reports, not authority.
24
+ **pi-agentic-driver makes agent work verifiable and controllable. The agent does
25
+ the work and each extension makes sure the work can be checked.** Review happens
26
+ before code is written. Communication carries reports without asserting authority that isn't granted.
25
27
  Isolation proofs verify their own cleanup. Sessions survive compaction and
26
- handover. Git operations stay exact, confirmed, and protected.
28
+ Git operations stay exact, confirmed, and protected.
27
29
 
28
- Each capability passes fixture-based acceptance, native tests, live-session
29
- checks, and independent model review before release. We document each
30
- extension's restrictions before release.
30
+ Every capability passes fixture-based acceptance, native tests, live-session
31
+ checks, and independent model review before release. I/we document each
32
+ extension's restrictions before release, not after.
31
33
 
32
34
  Extensions for [Pi](https://github.com/earendil-works/pi-coding-agent):
33
- advisory code review, bounded role communication, and governed isolation
35
+ advisory code review, controlled role communication, and governed isolation
34
36
  proofs for agentic workflows.
35
37
 
38
+ <p align="center">
39
+ <img src="assets/agentic-driver-full-color.gif" alt="Full-color Agentic Driver control vault" width="768">
40
+ </p>
41
+
36
42
  ## Shipped features
37
43
 
38
44
  | Tool | What it does | Status |
39
45
  |------|--------------|--------|
40
- | `code_phage` | Reviews a plan against a stated goal before code is written. | shipped |
46
+ | `code_phage` | Reviews a plan against a stated goal before code is written and advises your agent. | shipped |
41
47
  | `agentic_herdr_communication` | Exchanges marked reports with worker agents; never grants authority. | shipped |
42
48
  | `agentic_herdr_spawn_worker` | Starts one Pi worker in a pane or tab, with native confirmation. | shipped |
43
- | `agentic_aidr` | Reviews writing for clarity, simplicity, brevity, and humanity. | shipped |
44
- | `agentic_linux_microvm_cutover` | Runs one job in a throwaway QEMU/KVM virtual machine on a Linux host. | user-enabled, native confirmation |
45
- | `agentic_worker_dispatch` | Runs bounded worker journeys and observes worker liveness. | shipped |
49
+ | `agentic_aidr` | A remedy for AI;DR. Reviews writing for clarity, simplicity, brevity, and humanity. | shipped |
50
+ | `agentic_linux_microvm_cutover` | Runs one job in a throwaway QEMU/KVM virtual machine on a Linux host, with a severity-tiered killswitch that stops escape attempts. | user-enabled, native confirmation |
51
+ | `agentic_worker_dispatch` | Runs controlled worker journeys and observes worker liveness. | shipped |
46
52
 
47
53
  **Status: active development and testing.** Each extension ships only after
48
54
  it passes fixture-based acceptance, native tests, live-session checks, and
49
- independent model review. You can install released components. This README
50
- lists pending components for transparency; pending components are not packaged.
55
+ independent model review. You can install released components. Pending
56
+ components are listed here for transparency and are not packaged.
51
57
 
52
58
  ## Code review and planning
53
59
 
54
- *Extensions that review, route, and bound what an agent does.*
60
+ *Extensions that review, route, and control what an agent does.*
55
61
 
56
62
  <details>
57
- <summary><strong>code-phage — advisory code review</strong> <em>(released, 0.1.1)</em></summary>
63
+ <summary><strong>code-phage, advisory code review</strong> <em>(released, 0.1.1)</em></summary>
58
64
 
59
65
  `code_phage` reviews a proposed change against a stated goal before the agent
60
- writes or commits code. Given a goal, candidate files, accepted requirements,
61
- and test paths, it:
66
+ writes or commits code. Give it a goal, candidate files, accepted
67
+ requirements, and test paths. It will:
62
68
 
63
- - **Finds prior art structurally** — matches exported symbols, function
64
- signatures, and dependency imports against a repository inventory, so an
69
+ - **Find prior art structurally.** It matches exported symbols, function
70
+ signatures, and dependency imports against a repository inventory, so the
65
71
  agent reuses an existing abstraction instead of writing a parallel version.
66
- Word overlap alone never counts. The implementation requires credit (source,
67
- version, license) whenever prior art informs it.
68
- - **Binds an implementation budget** — goal, accepted requirements, write
69
- set, and tests become one reviewable budget, with coverage checks that
70
- flag unbound requirements and uncovered tests.
71
- - **Measures diagnostic signals** — per-function cognitive and cyclomatic
72
- complexity, line counts, duplication, module-level mutable state,
73
- dependency lists, test burden, and a rollback proxy. These are signals
74
- for human judgment, never rejection thresholds.
75
- - **Redirects scope drift** — it names and excludes files that support no
76
- accepted requirement, then recommends the smallest coherent write set. The
77
- deletion test ("what fails if we remove this?") guards justified complexity
78
- from false-positive flagging.
79
- - **Stays advisory** — it never mutates files, creates tasks, grants
80
- authority, or blocks work; every result states `advisoryOnly: true`.
72
+ Word overlap alone never counts. When prior art informs the result, the
73
+ implementation records its source, version, and license.
74
+ - **Bind an implementation budget.** Goal, requirements, write set, and tests
75
+ become one reviewable budget. Coverage checks flag requirements nothing
76
+ binds and tests nothing covers.
77
+ - **Measure diagnostic signals.** Cognitive and cyclomatic complexity, line
78
+ counts, duplication, module-level mutable state, dependencies, test burden.
79
+ These are signals for human judgment, never rejection thresholds.
80
+ - **Redirect scope drift.** It names the files that support no accepted
81
+ requirement and recommends the smallest coherent write set. The deletion
82
+ test guards justified complexity: what would fail if we removed this?
83
+ - **Stay advisory.** It never mutates files, creates tasks, grants authority,
84
+ or blocks work. Every result says `advisoryOnly: true`.
81
85
 
82
86
  Concept credit: Matty Stratton, "Cognitive Complexity" (2024-09-20, concept
83
87
  only, no code copied); `flake8-cognitive-complexity` 0.1.0, MIT (concept
@@ -85,69 +89,63 @@ only, not a runtime dependency).
85
89
 
86
90
  </details>
87
91
 
88
- **Under development in this theme:**
89
92
 
90
- - **prompted planning lifecycle** — natural-language goals derived into
91
- complete semantic proposals with parent/scope choices at native
92
- boundaries; no retry loops, no model-supplied identifiers.
93
- - **native assignment selection** — planned assignments chosen through a
93
+ - **prompted planning lifecycle.** Natural-language goals become complete
94
+ semantic proposals with parent and scope choices at native boundaries. No
95
+ retry loops, no model-supplied identifiers.
96
+ - **native assignment selection.** Planned assignments are chosen through a
94
97
  native UI over derived candidates, never by model-supplied targets.
95
- - **inventory refresh** — Git-aware codebase inventory regeneration with
98
+ - **inventory refresh.** Git-aware codebase inventory regeneration with
96
99
  verification receipts, so prior-art matching stays honest.
97
100
 
98
101
  ## Multi-agent communication
99
102
 
100
- *Extensions for bounded coordination between agents.*
103
+ *Extensions for controlled coordination between agents.*
101
104
 
102
105
  <details>
103
- <summary><strong>herdr-communication — bounded role communication</strong> <em>(released, 0.2.1)</em></summary>
104
-
105
- `agentic_herdr_communication` exchanges bounded, marked reports with
106
- configured Pi worker roles running under [Herdr](https://herdr.dev/)
107
- 0.8.2. Each operation:
108
-
109
- - **Lists and observes** worker roles (`list`, `get`) filtered to trusted
110
- repositories only — a checked-in registry plus canonical-path validation;
111
- the extension denies unlisted or symlink-escaped repositories.
112
- - **Prompts exactly once** (`prompt`): re-observes the role, sends one
113
- bounded prompt with a role-specific report contract, waits for terminal
114
- settlement (`idle`/`done`/`blocked`), and reads exactly one latest
115
- complete marked report. No retry, no target substitution, no resend on
116
- timeout.
117
- - **Waits and reads** (`wait`, `read`) with the same trust checks for
118
- partial journeys.
119
- - **Grants nothing** — fixed argv with `shell: false`, a pinned executable,
120
- the coordinator role class denied, and returns results as untrusted
121
- evidence (`nonAuthorizing: true`). It cannot control panes, start agents,
122
- run shells, or create authority.
123
-
124
- - **Scales to many workers** — the trusted registry accepts up to 32
125
- worker repositories, and any dynamic non-coordinator role within them
126
- is eligible; `list` observes every live agent in one call. Fan-out is
127
- sequential by design: one role per prompt, one complete exchange, no
128
- broadcast primitive.
106
+ <summary><strong>herdr-communication, controlled role communication</strong> <em>(released, 0.2.1)</em></summary>
107
+
108
+ `agentic_herdr_communication` exchanges controlled, marked reports with
109
+ configured Pi worker roles running under [Herdr](https://herdr.dev/) 0.8.2.
110
+
111
+ - **List and observe.** Worker roles are filtered to trusted repositories: a
112
+ checked-in registry plus canonical-path validation. Unlisted or
113
+ symlink-escaped repositories are denied.
114
+ - **Prompt exactly once.** The tool re-observes the role, sends one approved
115
+ prompt with a role-specific report contract, waits for terminal settlement,
116
+ and reads exactly one complete marked report. No retry, no target
117
+ substitution, no resend on timeout.
118
+ - **Wait and read.** The same trust checks apply to partial journeys.
119
+ - **Grant nothing.** Fixed argv, `shell: false`, a pinned executable, the
120
+ coordinator role class denied. Results come back as untrusted evidence. The
121
+ tool cannot control panes, start agents, run shells, or create authority.
122
+ - **Scale to many workers.** The trusted registry accepts up to 32 worker
123
+ repositories, and any dynamic non-coordinator role within them is eligible.
124
+ Fan-out is sequential by design: one role per prompt, one complete
125
+ exchange, no broadcast primitive.
129
126
 
130
127
  </details>
131
128
 
132
129
  <details>
133
- <summary><strong>herdr-lifecycle — role-labelled worker dispatch</strong> <em>(released, 0.2.1)</em></summary>
130
+ <summary><strong>herdr-lifecycle, role-labelled worker dispatch</strong> <em>(released, 0.2.1)</em></summary>
131
+
134
132
  `agentic_herdr_spawn_worker` turns one natural-language request into Herdr's
135
- native documented lifecycle. Select `right`, `below`, or `tab`; give the
136
- worker a safe role label; choose a model from the active Pi model roster; and
137
- name a trusted repository. The extension:
133
+ native lifecycle. Choose a placement (`right`, `below`, or `tab`), a safe role
134
+ label, a model from the active Pi model roster, and a trusted repository. The
135
+ extension:
138
136
 
139
- - creates a right/down split pane or an individual labelled tab;
140
- - starts exactly one Pi agent in the returned shell pane;
141
- - verifies the role, model arguments, pane identity and canonical repository;
137
+ - creates the split pane or labelled tab;
138
+ - starts exactly one Pi agent in it;
139
+ - verifies the role, model arguments, pane identity, and canonical repository;
142
140
  - requires native confirmation before changing layout or starting a process;
143
- - uses fixed argv with `shell: false`, with no arbitrary Herdr or shell surface;
141
+ - uses fixed argv with `shell: false` and no arbitrary Herdr or shell surface;
144
142
  - returns explicit `pane_created`, `tab_created`, or `agent_started` partial
145
143
  states when only part of the operation succeeds; and
146
144
  - never retries, moves, closes, or deletes created state automatically.
147
145
 
148
146
  ![A role-labelled worker spawned in a right-hand pane](assets/spawn-right-pane.png)
149
147
 
150
- The same request can place a worker below the coordinator or retain it in an
148
+ The same request can place a worker below the coordinator or keep it in an
151
149
  individual tab:
152
150
 
153
151
  <p>
@@ -156,91 +154,81 @@ individual tab:
156
154
  </p>
157
155
 
158
156
  See [Dispatching a Multi-Model Workforce from Anywhere](https://evoclock.github.io/fieldnotes/articles/herdr-natural-language-agent-automation.html)
159
- for the wider task/model-routing and remote-session workflow.
157
+ for the wider task and model-routing workflow.
160
158
 
161
159
  </details>
162
160
 
163
- **Under development in this theme:**
164
-
165
- - **project status and state review** — read-only projections of workspace
166
- Git state, formal records, and task-state health (`/agentic-status`
167
- family).
168
- - **role-lane routing and warm sessions** — smart model routing sends work
169
- to the right model for the job. Separate lanes handle implementation,
170
- planning, and review. The router prefers a warm session when a lane already
171
- has an established agent, so context and cache survive across tasks. Route
172
- affinity is an optimisation, never authority: an incompatible or
173
- unavailable lane yields an explicit review-required result, never silent
174
- model substitution. Routing grants no dispatch or shell authority.
175
- - **worker pulse** — now part of the shipped `agentic_worker_dispatch` tool
176
- (see below). Broader role-lane observation remains future work.
177
- - **task-ledger integration for planned work** — agents read and act
178
- within the task ledger's card states (what is dispatchable, in progress,
179
- blocked) without owning board authority: no admission, completion,
180
- reconciliation, or migration by the agent itself.
181
-
182
161
  <details>
183
- <summary><strong>herdr-dispatch — continuous worker journeys</strong> <em>(released, 0.5.0)</em></summary>
162
+ <summary><strong>herdr-dispatch, continuous worker journeys</strong> <em>(released, 0.5.0)</em></summary>
184
163
 
185
- `agentic_worker_dispatch` runs bounded worker journeys and observes worker
164
+ `agentic_worker_dispatch` runs controlled worker journeys and observes worker
186
165
  liveness. Two actions:
187
166
 
188
167
  - **pulse** reports whether a worker role is alive, its current state, and
189
168
  whether it is dispatch-eligible.
190
169
  - **dispatch** runs one journey. The worker works through the existing task
191
- sequence (pending, unblocked, unowned items) and handles one
192
- prompt-and-report exchange per task. A journey runs at most `maxSteps`
170
+ sequence, one prompt-and-report exchange per task, at most `maxSteps`
193
171
  steps (default 50, cap 200).
194
172
 
195
173
  Continuous mode is the default: the journey keeps going until the worker
196
174
  finishes the queue or reaches the step bound. Turn-by-turn mode stops after
197
175
  each step and is explicit opt-in. Each journey emits one collated marked
198
- report that covers every step.
176
+ report covering every step.
199
177
 
200
- A hung worker ends the journey with an explicit `worker-hung` state. A
201
- worker hangs when it never reaches `idle` across the observed exchange
202
- cycle, or when its exchange stalls. You can then spawn a replacement agent
178
+ A worker that never reaches idle across the observed exchange cycle ends the
179
+ journey with an explicit unresponsive state. You can then spawn a replacement
203
180
  through the guarded lifecycle boundary. The replacement resumes the same
204
- pending tasks; the journey reuses existing task cards and never duplicates
205
- them. The stuck exchange is never resent to the same worker.
181
+ pending tasks, reuses existing task cards, and never duplicates them. The
182
+ stuck exchange is never resent to the same worker.
206
183
 
207
184
  Journeys never create, own, or complete task cards themselves, never retry
208
185
  silently, and return results as untrusted evidence.
209
186
 
210
187
  </details>
211
188
 
189
+
190
+ - **project status and state review.** Read-only projections of workspace Git
191
+ state, formal records, and task-state health.
192
+ - **role-lane routing and warm sessions.** Separate lanes handle
193
+ implementation, planning, and review, and the router prefers a warm session
194
+ so context and cache survive across tasks. Route affinity is an
195
+ optimisation, never authority: an incompatible lane yields an explicit
196
+ review-required result, never silent model substitution.
197
+ - **task-ledger integration.** Agents read and act within the task ledger's
198
+ card states without owning board authority: no admission, completion,
199
+ reconciliation, or migration by the agent itself.
200
+
212
201
  ## Writing clearly
213
202
 
214
- *AI;DR (AI; Didn't Read) keeps technical writing clear without flattening the writer's voice.*
203
+ *AI;DR (AI; Didn't Read) keeps technical writing clear without flattening the
204
+ writer's voice.*
215
205
 
216
206
  <details>
217
- <summary><strong>AI;DR — writing review</strong> <em>(released, 0.4.2)</em></summary>
207
+ <summary><strong>AI;DR, writing review</strong> <em>(released, 0.4.2)</em></summary>
218
208
 
219
209
  `agentic_aidr` reviews the last assistant response, supplied prose, or a
220
- Markdown/documentation file. It checks four principles:
210
+ Markdown file. It checks four principles:
221
211
 
222
- - **Clarity:** keep each sentence focused on one useful idea.
223
- - **Simplicity:** remove clutter, pompous phrases, and needless jargon.
224
- - **Brevity:** use fewer words when they carry the same meaning.
225
- - **Humanity:** keep an authentic human voice.
212
+ - **Clarity.** Each sentence carries one useful idea.
213
+ - **Simplicity.** Clutter, pompous phrases, and needless jargon go.
214
+ - **Brevity.** Fewer words when they carry the same meaning.
215
+ - **Humanity.** An authentic human voice stays.
226
216
 
227
- The `simple` and `ste` modes also run an ASD-STE100-informed profile. The
228
- profile checks sentence length, direct word choice, precise verbs, and clear
229
- requirements, permissions, abilities, and conditions. It uses a 20-word target
230
- for procedural text and a 25-word target for descriptive text. It returns the
231
- rule and an example for each finding.
217
+ The `simple` and `ste` modes add an ASD-STE100-informed profile: sentence
218
+ length, direct word choice, precise verbs, and clear requirements,
219
+ permissions, abilities, and conditions. It targets 20 words per procedural
220
+ sentence and 25 per descriptive one, and returns the rule and an example for
221
+ each finding.
232
222
 
233
- Use `simple` for the four principles plus the profile. Use `ste` for a
234
- profile-focused report. The profile is advisory. It does not include the
235
- licensed ASD-STE100 approved-word dictionary. It does not certify conformance.
236
- Check final text against the licensed specification and your project
237
- terminology list.
223
+ The profile is advisory. It does not include the licensed ASD-STE100
224
+ approved-word dictionary and does not certify conformance. Check final text
225
+ against the licensed specification and your project terminology list.
238
226
 
239
227
  AI;DR also flags dense paragraphs, suggests bullets when they reduce working
240
228
  memory load, and supports plain-language and analogy modes. Review is
241
- read-only. An explicit file apply action shows a bounded diff and writes the
242
- exact proposed replacement only after native confirmation. Release 0.4.2 adds
243
- bounded inputs, atomic replacement, drift checks, and exact write verification.
229
+ read-only. An explicit file apply action shows a git diff and writes the
230
+ exact replacement only after native confirmation. Release 0.4.2 adds controlled
231
+ inputs, atomic replacement, drift checks, and exact write verification.
244
232
 
245
233
  </details>
246
234
 
@@ -258,51 +246,117 @@ QEMU/KVM virtual machine on a Linux host. The job cannot reach the host, the
258
246
  network, or anything else outside the machine. The system deletes the machine
259
247
  after the job ends.
260
248
 
261
- Each session starts with isolation disabled. To enable it, run
262
- `/agentic-isolation-enable` in the interactive Pi TUI and confirm. The model
263
- cannot run this command. Each microVM run asks for its own confirmation. To
264
- turn isolation off, run `/agentic-isolation-disable`. The switch never saves
265
- to settings. Headless sessions stay blocked.
266
-
267
- **Setup and run.** You choose where the microVM runs. The model cannot choose
268
- it silently — it only relays your words, and every target choice requires your
269
- native confirmation dialog before anything is saved or run.
270
-
271
- 1. Ask your agent to run the microVM cutover and tell it which machine to use
272
- (e.g. "run the microVM proof on deploy@192.168.1.50", or "...on this
273
- machine"). The first run asks you to confirm natively: it names the
274
- machine and states that your choice is saved to your Pi config. On your
275
- Yes, the choice is saved and the run continues in the same invocation.
276
- 2. Run `/agentic-isolation-enable` to enable isolation for this session
277
- (native confirmation; not saved to settings).
278
- 3. Each cutover run asks for its own confirmation. Saved targets are reused
279
- without asking again where the microVM runs.
280
-
281
- The tool discovers the technical details from the machine itself. It reads the
282
- architecture, kernel, and libvirt URI at probe time. You configure nothing.
283
- Before any run, the probe checks three requirements: `/dev/kvm` exists and is
284
- accessible. Libvirt reports the system-level driver (`qemu:///system`). A
285
- matching `qemu-system-<arch>` binary is present. A failed check denies the run
286
- before anything happens. Note: the shipped fixture guest is x86_64-built, so
287
- the full proof currently needs an x86_64 KVM host.
249
+ Isolation is off at the start of every session. You turn it on with
250
+ `/agentic-isolation-enable` in the Pi TUI, and confirm. The model cannot run
251
+ that command. Every cutover run asks for its own confirmation too. Nothing is
252
+ saved to settings, and headless sessions stay blocked.
253
+
254
+ ### You choose the machine
255
+
256
+ The model can only relay your words. Saving a target, or running on one,
257
+ always requires your confirmation dialog first.
258
+
259
+ 1. Tell the agent where to run the proof, for example "run the microVM proof
260
+ on deploy@192.168.1.50" or "run it on this machine". The first run asks
261
+ you to confirm. Your Yes saves the choice to your Pi config and the run
262
+ continues.
263
+ 2. Run `/agentic-isolation-enable` and confirm.
264
+ 3. Each cutover run asks for its own confirmation. Later runs reuse the saved
265
+ target without asking where the microVM runs again.
266
+
267
+ The tool discovers the technical details from the machine itself:
268
+ architecture, kernel, libvirt driver. You configure nothing. Before any run,
269
+ the probe checks three requirements: `/dev/kvm` is accessible, libvirt
270
+ reports the system-level driver, and a matching `qemu-system-<arch>` binary
271
+ exists. A failed check denies the run before anything happens. The shipped
272
+ fixture guest is x86_64-built, so the full proof currently needs an x86_64
273
+ KVM host.
274
+
275
+ ### What example tests look like
276
+
277
+ We started with one payload: print a greeting, then call a network tool. The
278
+ greeting printed, the tool tripped the killswitch at the HIGH tier, and the
279
+ line after it never ran. A kill report landed in the state directory naming
280
+ the rule and tier, and the teardown proof showed the machine was gone with
281
+ nothing left behind.
282
+
283
+ From there we wrote a payload for every rule in the taxonomy: credential
284
+ probing behind chained commands, secret dumping inside subshells, package
285
+ installs, coordination files reaching for other agents, a forged receipt, a
286
+ write to the evidence channel, and ten unclassified commands in a row to push
287
+ the anomaly threshold to its limit.
288
+
289
+ The guest had no disk, no network, no host share, no credentials, and no GPU.
290
+ Nothing outside the kernel's virtual filesystems could be mounted. Every
291
+ attempt was denied and written to a log that survived the machine.
292
+
293
+ While this is a toy test of sorts my own personal work will be running on
294
+ these as well.
295
+
296
+ ### What the containment layer defends against
297
+
298
+ Agent escapes tend to follow a playbook, and the published incidents from
299
+ frontier labs (the HuggingFace incident among them) read like one: grab
300
+ credentials, phone home, install something persistent, rewrite your tools,
301
+ stage payloads in caches, look for other agents to recruit, clean up the
302
+ evidence. The containment layer has a rule for each step:
303
+
304
+ - **Credential theft.** Reading SSH, cloud, or token material, or dumping
305
+ environment secrets, ends the session immediately.
306
+ - **Exfiltration and remote control.** Any network tool, any socket, ends the
307
+ session immediately.
308
+ - **Persistence through dependencies.** Package installs, registry writes,
309
+ and manifest tampering are denied and counted. Repeat the attempt and the
310
+ session ends.
311
+ - **Self-modification.** Rewriting the agent's own tools or the monitoring
312
+ layer is denied and counted.
313
+ - **Payload staging.** Growth in cache and package directories is sampled by
314
+ size; repeated growth ends the session.
315
+ - **Cross-agent escalation.** Coordination channels and shared paths used to
316
+ reach other agents end the session immediately.
317
+ - **Evidence tampering.** Editing logs, forging receipts, or writing to the
318
+ console channel ends the session immediately.
319
+ - **Reconnaissance.** Probing the sandbox to learn whether it is watched is
320
+ counted into a concealment index that ships in the run receipt.
321
+
322
+ Denials are written to a tamper-evident, digest-chained log that outlives the
323
+ session, and a trip produces a kill report naming what happened, with proof
324
+ that the cleanup completed.
325
+
326
+ ### Proven against real machines
327
+
328
+ Every rule above has been run against a real QEMU/KVM guest with a payload
329
+ built to trigger it. The kill switches fired where they should, the denials
330
+ stopped the jobs, and the cleanup held. One boundary is worth stating: two
331
+ rules watch the same directories by design, and together they are stricter
332
+ than either alone, so the growth-sampling trip is covered by automated tests
333
+ rather than a live run.
334
+
335
+ The repository carries an acceptance matrix of 79 scenarios, one executable
336
+ test per row, covering every rule, every way a command can be invoked, and
337
+ every threshold boundary. It grows as new scenarios come to light.
338
+
339
+ ### A note on review quality
340
+
341
+ A quantized GLM-5.3-Flash model running locally on an NVIDIA DGX Spark
342
+ reviewed this work alongside two frontier reviews at high reasoning. The
343
+ local model matched their coverage and found one issue they all missed.
344
+ Small models on your own desk are worth taking seriously as reviewers.
288
345
 
289
346
  </details>
290
347
 
291
348
  **Under development in this theme:**
292
349
 
293
- - **native macOS container proof** — the native Apple Container runtime has
294
- passed a fixed local `/bin/pwd` isolation qualification. The probe used a
295
- read-only repository mount, no network, and automatic removal. The native Pi
296
- adapter remains under development and is not yet part of the released
297
- package.
298
-
299
- - **attended-authority guard** — the safety net between an agent and your
300
- shell: when a model tries to delete, overwrite, or push, the guard
301
- stops it before execution and asks you. Safe commands (reads, builds,
302
- tests) pass through untouched. If you deny, you get a clear reason and
303
- the session continues, and the agent does not retry behind your back. In
304
- headless runs where no human can confirm, the system refuses destructive
305
- commands rather than silently allowing them.
350
+ - **native macOS container proof.** The native Apple Container runtime has
351
+ passed a fixed local isolation qualification: read-only repository mount,
352
+ no network, automatic removal. The native Pi adapter is not yet part of the
353
+ released package.
354
+ - **attended-authority guard.** The safety net between an agent and your
355
+ shell. When a model tries to delete, overwrite, or push, the guard stops it
356
+ and asks you. Safe commands pass through untouched. If you deny, you get a
357
+ clear reason and the session continues, and the agent does not retry behind
358
+ your back. In headless runs where no human can confirm, destructive
359
+ commands are refused rather than silently allowed.
306
360
 
307
361
  ## Session continuity
308
362
 
@@ -310,25 +364,23 @@ the full proof currently needs an x86_64 KVM host.
310
364
 
311
365
  **In development:**
312
366
 
313
- - **context-pressure handling** — pressure detection, non-lossy handover,
314
- compaction completion without cancellation loops, and continuation of
315
- the latest user goal. Development-only until the full live journey
316
- passes.
317
- - **lossless session-reference compaction** — selective, lossless retrieval
318
- of exact pre-compaction content, addressing factual degradation across
319
- repeated compactions; designed as an optional add-on, not yet
320
- implemented.
367
+ - **context-pressure handling.** Pressure detection, non-lossy handover,
368
+ compaction completion without cancellation loops, and continuation of the
369
+ latest user goal. Development-only until the full live journey passes.
370
+ - **lossless session-reference compaction.** Selective, lossless retrieval of
371
+ exact pre-compaction content, addressing factual degradation across
372
+ repeated compactions. Designed as an optional add-on, not yet implemented.
321
373
 
322
374
  **Planned in this theme:**
323
375
 
324
- - **handover, checkpoint, and recovery** — durable repository-local
325
- handover notes, governed checkpoint mutation, watchdog handoff, and
326
- fresh-session resumption that identifies goal, changed files, checks,
327
- and next step without executing anything.
328
- - **evidence ledger** — deterministic evidence indexing, lossless source
376
+ - **handover, checkpoint, and recovery.** Durable repository-local handover
377
+ notes, governed checkpoint mutation, watchdog handoff, and fresh-session
378
+ resumption that identifies goal, changed files, checks, and next step
379
+ without executing anything.
380
+ - **evidence ledger.** Deterministic evidence indexing, lossless source
329
381
  projection, universal checkpoint produce/store/recover, and run-ledger
330
382
  records with crash and corruption vectors tested.
331
- - **offline multihost evidence** — record run evidence on each host while
383
+ - **offline multihost evidence.** Record run evidence on each host while
332
384
  disconnected and reconcile it deterministically on reconnection, with no
333
385
  host as sole authority.
334
386
 
@@ -338,31 +390,30 @@ the full proof currently needs an x86_64 KVM host.
338
390
 
339
391
  **In development:**
340
392
 
341
- - **git workflow safeguards** — design only. The package contains no Git
393
+ - **git workflow safeguards.** Design only; the package contains no Git
342
394
  extension yet. The planned capability covers exact-file staging, native
343
395
  confirmation, post-confirmation drift checks, and protected-operation
344
396
  boundaries.
345
- - **assignment-aware Git journeys** — merge and protected-push flows bound
346
- to a verified assignment, so consequential Git operations carry their
347
- own recorded provenance.
397
+ - **assignment-aware Git journeys.** Merge and protected-push flows bound to
398
+ a verified assignment, so consequential Git operations carry their own
399
+ recorded provenance.
348
400
 
349
401
  ## Package integrity
350
402
 
351
- *Extensions that keep the installed set honest and the record bounded.*
352
-
353
- - **security and integrity scanning** — static scanning of MCP configs,
354
- agent skills, and extension packages for hardcoded secrets, prompt and
355
- shell injection, data-exfiltration endpoints, untrusted integrations,
356
- PII leakage, and OWASP/MCP threat families, with accept/redact/reject
357
- decisions. Built on the agent-scanner approach proven in
358
- Hillstar Orchestrator and Testudo.
359
- - **checkpoint storage lifecycle** — compression, deduplication, retention,
360
- and purging rules for capsule/index stores once a product ships, so
361
- session evidence has a managed lifetime instead of growing without
362
- bound.
363
- - **product knowledge graph** — semantic graph projection of a shipped
364
- product's checkpoints, decisions, and artifacts, so the record of what
365
- was built stays queryable after active development ends.
403
+ *Extensions that keep the installed set honest and the record controlled.*
404
+
405
+ - **security and integrity scanning.** Static scanning of MCP configs, agent
406
+ skills, and extension packages for hardcoded secrets, prompt and shell
407
+ injection, data-exfiltration endpoints, untrusted integrations, PII
408
+ leakage, and OWASP/MCP threat families, with accept/redact/reject
409
+ decisions. Built on the agent-scanner approach proven in Hillstar
410
+ Orchestrator and Testudo.
411
+ - **checkpoint storage lifecycle.** Compression, deduplication, retention,
412
+ and purging rules for capsule and index stores once a product ships, so
413
+ session evidence has a managed lifetime instead of growing without bound.
414
+ - **product knowledge graph.** Semantic graph projection of a shipped
415
+ product's checkpoints, decisions, and artifacts, so the record of what was
416
+ built stays queryable after active development ends.
366
417
 
367
418
  Each item lands here as its own extension when its scenario passes
368
419
  acceptance with all prohibited effects absent.
@@ -370,7 +421,7 @@ acceptance with all prohibited effects absent.
370
421
  ### Portable repository contract
371
422
 
372
423
  `templates/AGENTS.md` is a starting contract you can copy into any repository
373
- that uses Pi agents. It asks for bounded tasks and realistic tests, and
424
+ that uses Pi agents. It asks for controlled tasks and realistic tests, and
374
425
  treats agent reports as untrusted evidence. It never overwrites an existing
375
426
  `AGENTS.md`; add your project rules below it.
376
427
 
@@ -385,21 +436,21 @@ pi install npm:@evoclock/pi-agentic-driver
385
436
  Or from Git at a pinned tag:
386
437
 
387
438
  ```sh
388
- pi install git:github.com/evoclock/pi-agentic-driver@v0.5.0
439
+ pi install git:github.com/evoclock/pi-agentic-driver@v0.6.0
389
440
  ```
390
441
 
391
442
  Released extensions load standalone; neither requires the other.
392
443
 
393
444
  ### Choose which extensions load
394
445
 
395
- A normal install loads all five extensions by default. You can load only the
396
- extensions you want by using the object form in your Pi settings:
446
+ A normal install loads all six extensions by default. You can load only the
447
+ extensions you want with the object form in your Pi settings:
397
448
 
398
449
  ```json
399
450
  {
400
451
  "packages": [
401
452
  {
402
- "source": "npm:@evoclock/pi-agentic-driver@0.5.0",
453
+ "source": "npm:@evoclock/pi-agentic-driver@0.6.0",
403
454
  "extensions": [
404
455
  "extensions/aidr.ts",
405
456
  "extensions/code-phage.js"
@@ -409,9 +460,10 @@ extensions you want by using the object form in your Pi settings:
409
460
  }
410
461
  ```
411
462
 
412
- The package also includes `herdr-communication.ts`, `herdr-lifecycle.ts`, and
413
- `linux-microvm.ts`. Use `pi config` to enable or disable individual resources
414
- from an installed package. You are not required to use every extension.
463
+ The package also includes `herdr-communication.ts`, `herdr-lifecycle.ts`,
464
+ `herdr-dispatch.ts`, and `linux-microvm.ts`. Use `pi config` to enable or
465
+ disable individual resources from an installed package. You are not required
466
+ to use every extension.
415
467
 
416
468
  ## License
417
469