@abdwhb-png/pi-test-harness 0.7.0

package/skills/pi-test-harness/references/mock-tools.md

@@ -0,0 +1,176 @@
+# Mock tools reference
+
+`mockTools` is the mechanism that lets your tests stay deterministic without faking Pi itself. The key insight: it intercepts `tool.execute()` for specific tool names, but everything around it — the tool registry, the hook pipeline, the event bus — runs for real.
+
+## The three handler forms
+
+`mockTools` is a `Record<string, MockToolHandler>`. Each value can be one of three shapes:
+
+```typescript
+type MockToolHandler =
+  | string                                                        // 1. static text
+  | ToolResult                                                    // 2. full result object
+  | ((params: Record<string, unknown>) => string | ToolResult);   // 3. dynamic function
+```
+
+### 1. Static string
+
+The simplest. Becomes `{ content: [{ type: "text", text: "<string>" }] }`.
+
+```typescript
+mockTools: {
+  bash: "command output here",
+}
+```
+
+Use this when the tool's params don't change the response, e.g. mocking `read` to a fixed string.
+
+### 2. Dynamic function
+
+Receives the params object and returns a string or a full `ToolResult`.
+
+```typescript
+mockTools: {
+  read: (params) => `contents of ${params.path}`,
+  bash: (params) => `$ ${params.command}\nfile1.txt\nfile2.txt`,
+}
+```
+
+Use this whenever the response should reflect what was asked. This is the shape that makes your mock feel realistic enough that test assertions on `result.text` are meaningful.
+
+### 3. Full ToolResult
+
+For precise control over `content`, `details`, error responses, etc.
+
+```typescript
+mockTools: {
+  write: {
+    content: [{ type: "text", text: "Written successfully" }],
+    details: { bytesWritten: 42 },
+  },
+}
+```
+
+Use this when your extension reads from `result.details` or when you need to return non-text content blocks.
+
+## What stays real, what gets faked
+
+This is the part that surprises people: **everything except `tool.execute()` keeps running.**
+
+| Layer                       | Mocked?         | Notes                                                             |
+| --------------------------- | --------------- | ----------------------------------------------------------------- |
+| Tool registration           | No              | Real `wrapToolsWithExtensions` pipeline                           |
+| `tool_call` hook            | No              | Fires through `AgentSession.beforeToolCall` — **including for mocked tools** |
+| `tool_result` hook          | No              | Fires through `AgentSession.afterToolCall`                                  |
+| Tool's own `execute()` body | Yes (if listed) | The mock handler runs instead                                     |
+| Event collection            | No              | Real event bus                                                    |
+
+Why this matters: if your extension registers a `tool_call` hook that blocks `bash` in plan mode, the block works correctly even when `bash` is mocked. The mock handler never runs (the block happens first), and the result will show `isError: true`.
+
+## Extension-registered tools run for real
+
+A common confusion: extension-registered tools **execute for real** unless they appear in `mockTools`. This is by design — it's how you test your own tool logic while keeping built-ins deterministic.
+
+So: if your extension registers `summarize_doc`, list only the *built-in* tools (`bash`, `read`, `write`, `edit`, etc.) in `mockTools`, and let `summarize_doc` execute its real implementation.
+
+```typescript
+const t = await createTestSession({
+  extensions: ["./src/index.ts"],   // registers summarize_doc
+  mockTools: {
+    // Built-ins: mocked so the test stays fast and offline
+    bash: (p) => `mock: ${p.command}`,
+    read: "mock contents",
+    write: "mock written",
+    edit: "mock edited",
+    // summarize_doc NOT listed → executes its real code
+  },
+});
+```
+
+## What to mock: a decision tree
+
+```
+Is this tool implemented by the extension under test?
+  Yes
+    -> DO NOT mock it. You want to test its real code.
+  No (it's a built-in or another extension)
+    -> Does the test depend on the tool's *output*?
+        Yes
+            -> Mock it with a realistic value (form 1 or 2).
+        No (test only depends on whether it was *called*)
+            -> Mock it with any placeholder; assert on
+               t.events.toolCallsFor(name) instead.
+```
+
+## Error propagation: `propagateErrors`
+
+When a **real** tool execution throws (i.e. a tool that's *not* in `mockTools`), you control how the harness handles it.
+
+| Value            | Behavior                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------- |
+| `true` (default) | Aborts the test immediately, with a diagnostic pointing at the exact playbook step             |
+| `false`          | Captures the error as a tool result with `isError: true`, allowing your extension to handle it |
+
+```typescript
+const t = await createTestSession({
+  propagateErrors: false,   // capture errors as results instead of aborting
+  // ...
+});
+```
+
+### When to use `propagateErrors: false`
+
+Use it whenever your extension is **supposed to** recover from tool failures. Examples:
+
+- A retry-with-backoff wrapper around `bash`.
+- A fallback path when `read` returns `ENOENT`.
+- An error message the assistant should paraphrase to the user.
+
+With `propagateErrors: false`, the playbook keeps running, and you can assert on `t.events.toolResultsFor("bash")[0].isError` to confirm the error reached your extension.
+
+### When to leave it true (default)
+
+Use the default when **real** tool errors mean a bug. The diagnostic the harness produces is excellent:
+
+```
+Error during tool execution at playbook step 3 (call "bash"):
+  ENOENT: no such file or directory '/foo/bar'
+  at Object.readFileSync (node:fs:...)
+
+This error was thrown by the real tool execution, not by the playbook.
+To capture errors as tool results instead of aborting, set:
+  createTestSession({ propagateErrors: false })
+```
+
+## Blocked tools: assert the event records
+
+When an extension's `tool_call` hook blocks a tool call, the canonical signals are the collected event records: `blocked: true` + `blockReason` on the `ToolCallRecord`, and `isError: true` + result text on the `ToolResultRecord`. Assert those — the package still exports `ToolBlockedError` for source compatibility, but a normal Pi 0.84 run through `AgentSession` does not promise to throw it.
+
+### Pattern A: assert via events after the fact
+
+```typescript
+await t.run(when("Try write", [
+  calls("bash", { command: "rm -rf /" }),
+  says("Done."),  // consumed regardless of block — the block becomes a result that feeds back into streamFn
+]));
+
+const result = t.events.toolResultsFor("bash")[0];
+expect(result.isError).toBe(true);
+
+// You can also confirm the block specifically via the call record:
+const call = t.events.toolCallsFor("bash")[0];
+expect(call.blocked).toBe(true);
+expect(call.blockReason).toMatch(/blocked by/i);
+```
+
+Note: the playbook **continues** after a block — the block surfaces as a tool result with `isError: true`, which feeds back into the next `streamFn` call, so subsequent `calls(...)` / `says(...)` still get consumed. Hook-block paths are classified as blocks (`blocked: true`) rather than test failures.
+
+### Combining `propagateErrors` with blocks
+
+Regardless of `propagateErrors`, the call record carries `blocked: true` and `blockReason: "..."` so you can assert the hook fired. With `propagateErrors: false`, blocked calls also surface as `isError: true` in the result record and the playbook continues. Do not rely on a `ToolBlockedError` throw from normal Pi 0.84 runs.
+
+## Common pitfalls
+
+- **Listing your extension's own tool in `mockTools`**. If you do, your tool's `execute()` never runs and you're testing nothing. Remove it.
+- **Expecting `calls(...)` to throw `ToolBlockedError` on a block**. Normal Pi 0.84 runs do not promise that throw; assert the canonical event records (`blocked`, `blockReason`, `isError`, result text) instead. If you want the playbook to keep flowing, set `propagateErrors: false` and read `.isError`.
+- **Mocking a tool the extension doesn't actually call**. The mock is harmless but adds noise; trim the list to what the test exercises.

package/skills/pi-test-harness/references/mock-ui.md

@@ -0,0 +1,170 @@
+# Mock UI reference
+
+Pi extensions interact with users via `ctx.ui.*` methods (`confirm`, `select`, `input`, `editor`, `notify`). In tests, those calls would block waiting for real input. `mockUI` controls what they "return" so you can drive extensions through their interactive code paths deterministically.
+
+Every UI call is also recorded for assertions afterwards via `t.events.uiCallsFor(name)`.
+
+## The full interface
+
+```typescript
+interface MockUIConfig {
+  confirm?: boolean | ((title: string, message: string) => boolean);
+  select?: number | string | ((title: string, items: string[]) => string | undefined);
+  input?: string | ((title: string, placeholder?: string) => string | undefined);
+  editor?: string | ((title: string, prefilled?: string) => string | undefined);
+}
+```
+
+Each field can be either a **static value** (returned for every call) or a **function** (computed per call). Static values are great for "always say yes" / "always pick the first option" defaults. Functions let you make different decisions based on the prompt context.
+
+## Defaults
+
+If you don't pass `mockUI` at all, these defaults apply:
+
+| Method   | Default                              |
+|----------|--------------------------------------|
+| `confirm`| `true` (accept all)                  |
+| `select` | `0` (first item)                     |
+| `input`  | `""` (empty string)                  |
+| `editor` | `""` (empty string)                  |
+
+In practice: if your extension calls `confirm` and you don't mock it, it returns `true` and the operation proceeds. This is convenient but can mask bugs where your extension shouldn't have called `confirm` at all.
+
+**Tip**: in tests that *shouldn't* trigger UI calls, explicitly set empty configs and assert `t.events.uiCallsFor("confirm")` has length 0 — that catches accidental prompts.
+
+## The four methods in detail
+
+### `confirm(title, message) → boolean`
+
+Yes/no confirmations.
+
+**Static form** — same answer every time:
+
+```typescript
+mockUI: {
+  confirm: false,   // deny all confirmations
+}
+```
+
+**Dynamic form** — different answer depending on the prompt:
+
+```typescript
+mockUI: {
+  confirm: (title, _message) => {
+    if (title.includes("Delete")) return false;
+    if (title.includes("Overwrite")) return false;
+    return true;
+  },
+}
+```
+
+### `select(title, items) → string`
+
+Picking from a list.
+
+**Static forms**: index or the item itself.
+
+```typescript
+mockUI: {
+  select: 0,                    // always pick first item
+  // or:
+  select: "staging",            // pick the matching item (must be exact)
+}
+```
+
+**Dynamic form**:
+
+```typescript
+mockUI: {
+  select: (_title, items) => items.find(i => i.includes("staging")),
+}
+```
+
+Returning `undefined` from a dynamic handler simulates "user selected nothing".
+
+### `input(title, placeholder?) → string`
+
+Free-text input.
+
+```typescript
+mockUI: {
+  input: "user input text",                                      // static
+  // or:
+  input: (title, _placeholder) => title.includes("name") ? "bob" : "x",
+}
+```
+
+### `editor(title, prefilled?) → string`
+
+Multi-line editor (typically opens `$EDITOR` in real Pi). Returns the edited content.
+
+```typescript
+mockUI: {
+  editor: "edited content",                                      // static
+  // or:
+  editor: (_title, prefilled) => `${prefilled}\n# Appended section\n`,
+}
+```
+
+## Pi 0.84 fire-and-forget methods
+
+Pi 0.84's `ExtensionUIContext` adds indicator/autocomplete methods that fire and forget — they return nothing, and the mock records their arguments instead of answering:
+
+- `setWorkingVisible(visible: boolean)` — show/hide the working indicator
+- `setWorkingIndicator(options?: { frames?: string[]; intervalMs?: number })` — set the working indicator animation; `frames: []` hides the indicator entirely, `frames: ["●"]` renders a static indicator, and omitting the argument restores the default spinner
+- `setHiddenThinkingLabel(label?: string)` — set the hidden-thinking label
+- `addAutocompleteProvider(provider)` — records the registration call; the provider is never invoked
+- `getEditorComponent()` — returns `undefined` by default; unlike mutation methods, this query is not recorded
+
+```typescript
+await t.run(when("Do work", [calls("start_task", {}), says("Working.")]));
+
+expect(t.events.uiCallsFor("setWorkingVisible")[0].args).toEqual([true]);
+expect(t.events.uiCallsFor("setWorkingIndicator")[0].args[0]).toEqual({ frames: ["●"], intervalMs: 500 });
+expect(t.events.uiCallsFor("setHiddenThinkingLabel")).toHaveLength(1);
+expect(t.events.uiCallsFor("addAutocompleteProvider")).toHaveLength(1);
+```
+
+The mock is typed as Pi 0.84's `ExtensionUIContext`, so a future Pi minor that adds a mandatory member breaks the typecheck instead of failing at runtime.
+
+## Asserting on UI calls
+
+All UI interactions are recorded in `t.events`:
+
+```typescript
+t.events.uiCallsFor("confirm")   // UICallRecord[]
+t.events.uiCallsFor("select")
+t.events.uiCallsFor("input")
+t.events.uiCallsFor("editor")
+t.events.uiCallsFor("notify")    // also collected, even though it's not mocked
+```
+
+Each record contains the call's title, the other arguments, and the `returnValue` the mock produced. This is how you prove your extension asked the right question and got the right shape of response.
+
+### Common assertions
+
+```typescript
+// My extension should ask for confirmation exactly once
+expect(t.events.uiCallsFor("confirm")).toHaveLength(1);
+
+// And the user answered with the expected response
+expect(t.events.uiCallsFor("confirm")[0].returnValue).toBe(false);
+
+// My extension should NOT have prompted for free-form input
+expect(t.events.uiCallsFor("input")).toHaveLength(0);
+```
+
+## When to override defaults
+
+| Situation                                                                  | Recommendation                                  |
+|----------------------------------------------------------------------------|--------------------------------------------------|
+| Test should never hit a UI prompt                                          | Assert `uiCallsFor(X)` len 0; don't bother with `mockUI` |
+| Test passes only if user denies a destructive op                          | `mockUI: { confirm: false }` + assert hit count  |
+| Extension branch depends on which option was selected                      | `mockUI: { select: "value" }` or dynamic handler |
+| Test exercises an `input` form                                             | `mockUI: { input: "value" }` — never accept the empty default for an actual input test |
+
+## Pitfalls
+
+- **Forgetting `notify` is recorded**. `notify` calls don't need mocking (they're outbound), but they show up in `uiCallsFor("notify")` and are very useful for asserting the user was warned about something.
+- **Static `select: 0` masking missing-item bugs**. If your extension's `select` didn't list the expected option, the mock silently returns whatever item is first. Assert on the *full call arguments* (`uiCallsFor("select")[0]`) if you care which options were presented.
+- **`input: ""` default hiding "did the extension read user input?" bugs**. If your extension is supposed to read input but accidentally skips it, the default-empty mock won't trip. Explicit non-empty input + subsequent assertion is the safer pattern.

package/skills/pi-test-harness/references/playbook-dsl.md

@@ -0,0 +1,209 @@
+# Playbook DSL reference
+
+The playbook replaces the LLM. Instead of calling a model, the Pi agent loop consumes scripted actions in order. The DSL is small — three builders and a couple of compositional tricks — but it's the heart of `pi-test-harness`, so this file is the most important reference.
+
+## Builders
+
+### `when(prompt, actions)`
+
+Defines a single conversation turn: the prompt you'll send and what the model does in response.
+
+```typescript
+when("Deploy the app", [
+  calls("bash", { command: "npm run build" }),
+  calls("bash", { command: "gcloud run deploy" }),
+  says("Deployed successfully."),
+])
+```
+
+- `prompt` is the user-side message that begins the turn.
+- `actions` is an ordered list of `calls(...)` and `says(...)`.
+- The harness serves actions to the agent loop one per `streamFn` call, in array order.
+- A turn ends when `says(...)` is consumed — `says` produces a final assistant message and signals turn end.
+
+### `calls(tool, params)`
+
+The model calls a tool. Pi's hooks fire normally, the tool executes (real or mocked per `mockTools`), and the result feeds back into the next `streamFn` call.
+
+```typescript
+calls("plan_mode", { enable: true })
+calls("bash", { command: "ls -la" })
+```
+
+`params` may be either an object literal or a function `() => params` for late binding (see "Late-bound params" below).
+
+Each `calls(...)` returns a builder you can chain `.then()` onto.
+
+### `says(text)`
+
+The model emits text. The agent turn ends.
+
+```typescript
+says("All done. The deployment is complete.")
+```
+
+`says` must be the last action in a turn — it produces the terminating assistant message.
+
+## Multi-turn conversations
+
+Pass multiple turns to `run()`:
+
+```typescript
+await t.run(
+  when("What files are in the project?", [
+    calls("bash", { command: "ls" }),
+    says("Found 3 files."),
+  ]),
+  when("Now read the README", [
+    calls("read", { path: "README.md" }),
+    says("Here's what it says..."),
+  ]),
+);
+```
+
+Each new `when(...)` is treated as a fresh user message; the model's prior text and tool calls remain in the session state for the next turn.
+
+## Late-bound params and `.then()`
+
+When one tool call produces a value that the next call needs, use `.then()` to capture the result, and pass a `() => params` function so the params are resolved at call time (after `.then()` has fired).
+
+The canonical pattern: a tool returns a generated ID in its text output, and the next tool needs that ID:
+
+```typescript
+let planId = "";
+
+await t.run(
+  when("Create and approve a plan", [
+    calls("plan_propose", {
+      title: "Send invoice",
+      steps: [
+        { description: "Send email", tool: "go-easy", operation: "send" },
+      ],
+    }).then((result) => {
+      // Extract the plan ID from the tool result text
+      planId = result.text.match(/PLAN-[a-f0-9]+/)![0];
+    }),
+    // Late-bound: params resolved at call time, after .then() has fired
+    calls("plan_approve", () => ({ id: planId })),
+    says("Plan approved and executing."),
+  ]),
+);
+
+expect(planId).toMatch(/^PLAN-/);
+```
+
+How it works:
+
+1. `plan_propose` runs, returns a result whose `.text` contains something like `Plan PLAN-a3f9c2 created`.
+2. `.then()` fires with the `ToolResultRecord`. Save the value to a test variable.
+3. The next `calls(...)` is given a function. The harness invokes it at call time — so `planId` is now populated, and the params object is what actually gets passed.
+
+This is the supported way to chain dependent calls. Without `.then()` + a function-returning params, you'd be stuck with whatever you pre-declared.
+
+## Real-world example: testing pi-planner
+
+A non-trivial extension that registers 8 tools, blocks writes in plan mode, and manages plan lifecycle:
+
+```typescript
+import {
+  createTestSession, when, calls, says, type TestSession,
+} from "@abdwhb-png/pi-test-harness";
+import * as path from "node:path";
+
+const EXTENSION = path.resolve(__dirname, "../../src/index.ts");
+const MOCKS = {
+  bash: (p: Record<string, unknown>) => `mock: ${p.command}`,
+  read: "mock contents",
+  write: "mock written",
+  edit: "mock edited",
+};
+
+describe("pi-planner", () => {
+  let t: TestSession;
+  afterEach(() => t?.dispose());
+
+  it("enters plan mode and proposes a plan", async () => {
+    t = await createTestSession({
+      extensions: [EXTENSION],
+      mockTools: MOCKS,
+    });
+
+    let planId = "";
+
+    await t.run(
+      when("Plan the deployment", [
+        calls("plan_mode", { enable: true }),
+        calls("plan_propose", {
+          title: "Deploy v2",
+          steps: [
+            { description: "Build",   tool: "bash",   operation: "build" },
+            { description: "Deploy",  tool: "gcloud", operation: "deploy" },
+          ],
+        }).then((r) => {
+          planId = r.text.match(/PLAN-[a-f0-9]+/)![0];
+        }),
+        says("Plan proposed."),
+      ]),
+    );
+
+    expect(planId).toMatch(/^PLAN-/);
+    expect(t.events.toolResultsFor("plan_mode")[0].text).toContain("enabled");
+    expect(t.events.uiCallsFor("notify")).toHaveLength(1);
+  });
+});
+```
+
+## Diagnostics: when the playbook doesn't match reality
+
+The harness auto-asserts that all playbook actions are consumed after `run()` completes. If script and reality disagree, you get one of two diagnostic shapes.
+
+### 1. Playbook exhausted unexpectedly
+
+```
+Playbook exhausted unexpectedly.
+  Consumed 2 action(s).
+  Last consumed: calls("bash", {"command":"ls"}) at step 2
+
+  The agent loop called streamFn but no more playbook actions were available.
+  This usually means a tool call produced an unexpected result that caused
+  additional streamFn calls (retries, error handling).
+```
+
+**What it means**: the agent loop called `streamFn` more times than your script expected. The most common causes:
+
+- A tool call produced an error, triggering automatic retry inside Pi.
+- A hook blocked a tool and Pi retried with a different action.
+- An extension spawned an extra `streamFn` call you didn't anticipate.
+
+**Fix**: read the diagnostic's "Last consumed" line to find where reality diverged. Either add the missing actions to your script, or change `mockTools` so the tool doesn't error / the hook doesn't fire.
+
+> **Do not confuse** this exhaustion diagnostic with the `propagateErrors: true` error diagnostic, which looks like:
+> ```
+> Error during tool execution at playbook step 3 (call "bash"):
+>   ENOENT: no such file or directory '/foo/bar'
+> ```
+> That one fires when a **real** (non-mocked) tool throws and `propagateErrors` is on. The exhaustion diagnostic above fires when the **script** and the agent loop disagree on how many actions exist. Different cause, different fix.
+
+### 2. Playbook not fully consumed
+
+```
+Playbook not fully consumed after run() completed.
+  Consumed 1 of 3 action(s).
+  Remaining:
+    - calls("write", {"path":"out.txt","content":"hello"})
+    - says("Done writing.")
+
+The agent loop ended before all playbook actions were used.
+This usually means a tool was blocked by a hook or returned early,
+causing fewer streamFn calls than expected.
+```
+
+**What it means**: a tool was blocked by an extension hook, or returned early, so Pi ended the turn before consuming everything you queued.
+
+**Fix**: if the block is *expected*, restructure your script so the unconsumed actions reflect what reality did (or wrap the call in a try/catch on `ToolBlockedError`). If the block is *unexpected*, the test just surfaced a real bug — investigate the hook.
+
+## Parallel tool calls (known intentional gap)
+
+Today the playbook emits one tool call per assistant message, which is deterministic and good for most extension tests. True Pi-side parallelism (multiple `toolCall` blocks in one assistant message) is not yet modeled. To test parallel tool execution you'd need a grouped/batched call action — flagged in the package's Testing Scope notes as a future addition, with results asserted by `toolCallId` rather than completion order.
+
+For now: if your extension's correctness depends on *parallel* rather than *sequential* tool execution, write a focused test that calls the extension's handler directly rather than driving it through the playbook.

package/skills/pi-test-harness/references/sandbox-install.md

@@ -0,0 +1,113 @@
+# Sandbox install verification reference
+
+`verifySandboxInstall` is the layer for **pre-publish** validation. It does a full real install of your package into a temp directory (no mocking) and confirms the package actually loads, registers its extensions/tools/skills, and (optionally) executes its tools end-to-end inside that real install.
+
+This catches a class of bugs that `createTestSession` cannot: broken `package.json` `exports` maps, missing `peerDependencies`, wrong `main`/`types`/`module` fields, files missing from `"files"`, ESM/CJS dual-publish issues. All of these can pass local tests while breaking the moment someone runs `npm install your-package`.
+
+## When to use it
+
+| Test layer                 | What it catches                                            |
+| -------------------------- | ---------------------------------------------------------- |
+| `createTestSession`        | Extension logic bugs (hook firing, tool behavior, events)  |
+| **`verifySandboxInstall`** | **Publishable-package bugs (broken install, bad exports)** |
+| `createMockPi`             | Subprocess-spawning extension bugs                         |
+
+Run `verifySandboxInstall` as a CI step before every publish, or locally as `npm run prepack` / `npm publish --dry-run`. At least [`marcfargas/pi-mf-extensions`](https://github.com/marcfargas/pi-mf-extensions) (pi-planner) uses this layer to test the plan lifecycle; check its CI for a concrete release-gate example.
+
+## Basic usage
+
+```typescript
+import { verifySandboxInstall } from "@abdwhb-png/pi-test-harness";
+
+const result = await verifySandboxInstall({
+  packageDir: "./packages/my-extension",
+  expect: {
+    extensions: 1,
+    tools: ["my_tool", "my_other_tool"],
+    skills: 0,
+  },
+});
+
+expect(result.loaded.extensionErrors).toEqual([]);
+expect(result.loaded.tools).toContain("my_tool");
+```
+
+What it does, step by step:
+
+1. Reads `package.json` from `packageDir`.
+2. Runs `npm pack` to produce a tarball exactly as `npm publish` would.
+3. Creates a temp directory.
+4. Runs `npm install <tarball>` inside the temp dir — a real install with real peer-dep resolution.
+5. Dynamically imports the installed package.
+6. Hands you the loaded state so you can assert extensions/tools/skills were registered.
+
+## Options
+
+| Option              | Type                              | Purpose                                           |
+| ------------------- | --------------------------------- | ------------------------------------------------- |
+| `packageDir`        | `string`                          | Path to the package (must contain `package.json`) |
+| `expect.extensions` | `number`                          | How many extensions should have loaded            |
+| `expect.tools`      | `string[]`                        | Required tool names                               |
+| `expect.skills`     | `number`                          | How many skills should have loaded                |
+| `smoke`             | `{ mockTools, script }`           | Optional in-sandbox playbook smoke test           |
+| `smoke.mockTools`   | `Record<string, MockToolHandler>` | Same as `createTestSession`'s `mockTools`         |
+| `smoke.script`      | `Turn[]`                          | Playbook turns (built with `when / calls / says`) |
+| `npmCommand`        | `string[]`                        | npm argv for `pack`/`install` (default `["npm"]`; use `["sfw", "npm"]` to route through Socket Firewall) |
+
+`npmCommand` lets a wrapper intercept the real release-gate commands: `verifySandboxInstall({ packageDir, npmCommand: ["sfw", "npm"] })` runs `sfw npm pack` / `sfw npm install`, keeping supply-chain checks on the actual `npm pack`/`npm install` calls.
+
+## Smoke test inside the sandbox
+
+Once the package is installed and loaded, you can drive it through a real playbook against the in-sandbox instance. This is the strongest possible signal short of a beta release: not only does the package install and load, its tools actually execute when called.
+
+```typescript
+import {
+  verifySandboxInstall,
+  when, calls, says,
+} from "@abdwhb-png/pi-test-harness";
+
+const result = await verifySandboxInstall({
+  packageDir: "./packages/my-extension",
+  expect: { extensions: 1 },
+  smoke: {
+    mockTools: {
+      bash: "ok",
+      read: "contents",
+      write: "written",
+      edit: "edited",
+    },
+    script: [
+      when("Test", [
+        calls("my_tool", { value: "test" }),
+        says("Works."),
+      ]),
+    ],
+  },
+});
+
+expect(result.loaded.extensionErrors).toEqual([]);
+expect(result.smoke.events.toolResultsFor("my_tool")).toHaveLength(1);
+```
+
+`result.smoke.events` exposes the same `TestEvents` API as `createTestSession`, so you can assert against events exactly as you would in an in-process test.
+
+## How this differs from `createTestSession`
+
+It's worth being explicit because the layers overlap conceptually but solve different problems:
+
+| Diagnostic question                                | Use                        |
+| -------------------------------------------------- | -------------------------- |
+| Does my extension's hook fire and block correctly? | `createTestSession`        |
+| Does the tool's logic do the right thing?          | `createTestSession`        |
+| **Does the package I'm about to publish install?** | **`verifySandboxInstall`** |
+| **Are the right files included in the tarball?**   | **`verifySandboxInstall`** |
+| **Do peer deps resolve in a clean install?**       | **`verifySandboxInstall`** |
+
+In practice, the natural split is: use `createTestSession` for the bulk of behavioral tests (it's fast, in-process, and exercises the extension under test directly), and reserve `verifySandboxInstall` for a single release-gate CI test (it's slower because it runs a real `npm pack` + `npm install`). The release gate catches things like forgetting to add a new tool's source file to the package's `"files"` list (which would make local `createTestSession` pass but a published package throw).
+
+## Common pitfalls
+
+- **Expecting `verifySandboxInstall` to mock anything by default.** It doesn't — only the optional `smoke` step uses mocks. The install + load itself is fully real.
+- **Putting `packageDir` as the package name instead of a path.** It's a directory path, not an npm spec.
+- **Expecting `tools` to be exhaustive.** If `expect.tools` lists `["my_tool", "my_other_tool"]` and your package also registers `my_third_tool`, the test still passes — but `my_third_tool` not being listed usually means you forgot to update the spec when you added a tool. Assert **all** tools.
+- **CI cost.** A real `npm pack` + `npm install` per test file is slow. Most projects run `verifySandboxInstall` exactly once, in a release-gate test, not in every test file.