pi-background-tasks 0.1.0 → 0.3.0

package/PUBLISHING.md

@@ -12,12 +12,14 @@ This package is ready for both npm publishing and standalone git publishing.
 
 ```bash
 cd packages/pi-background-tasks
+npm run test
+npm run test:full
 npm run smoke
 npm pack --dry-run
 npm view pi-background-tasks name version --json
 ```
 
-At creation time, `npm view pi-background-tasks` returned 404, so the unscoped name appeared available.
+`pi-background-tasks` is already published; bump `package.json` before each npm publish.
 
 ## Publish to npm
 
@@ -30,8 +32,8 @@ npm publish --access public
 Pi install smoke after publish:
 
 ```bash
-pi -e npm:pi-background-tasks@0.1.0 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.1.0
+pi -e npm:pi-background-tasks@0.3.0 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.3.0
 ```
 
 ## Publish to git
@@ -42,19 +44,19 @@ Because Pi git package installs treat the repository root as the package root, d
 cd packages/pi-background-tasks
 git init
 git add .
-git commit -m "Initial pi-background-tasks package"
+git commit -m "Release pi-background-tasks"
 git branch -M main
 git remote add origin git@github.com:ismailsaleekh/pi-background-tasks.git
 git push -u origin main
-git tag v0.1.0
-git push origin v0.1.0
+git tag v0.3.0
+git push origin v0.3.0
 ```
 
 Pi install smoke after git tag:
 
 ```bash
-pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
+pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
 ```
 
 ## pi.dev/packages

package/README.md

@@ -2,44 +2,78 @@
 
 Claude-Code-like explicit background shell task manager for [Pi](https://pi.dev/).
 
-This package adds tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, a `/tasks` manager UI, and completion notifications that can wake the agent when LLM-launched work finishes.
+This package adds named, tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, task-owned context-window/token/tool-use/model telemetry, explicit Pi-agent telemetry wrapping for tasks marked as agents, a focused footer-dock task manager, `/tasks` fallback UI, and completion notifications that can wake the agent when LLM-launched work finishes.
 
 ## Install
 
 From npm after publish:
 
 ```bash
-pi install npm:pi-background-tasks@0.1.0
+pi install npm:pi-background-tasks@0.3.0
 ```
 
 From git after pushing this package to its standalone repository and tagging:
 
 ```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
 ```
 
 For project-local install:
 
 ```bash
-pi install -l npm:pi-background-tasks@0.1.0
+pi install -l npm:pi-background-tasks@0.3.0
 ```
 
 ## Commands
 
-- `/bg <command>` — start a tracked background shell command.
+- `/bg [--agent] [--name "Task name"] <command>` — start a named tracked background shell command. Use `--agent` only when the command launches an LLM/agent.
 - `/jobs` — list running and recent completed/failed/killed tasks.
 - `/logs <id> [maxBytes]` — show bounded tail output and full output path.
 - `/kill <id>` — stop a running task.
-- `/tasks` or `/bg-tasks` — open the interactive task manager UI.
+- `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
+- `/bg-clear` — clear finished background-task footer notices.
+
+## Footer dock UX
+
+When tasks are active or unseen completions/failures exist, Pi shows a compact footer status:
+
+```text
+bg 2 running · Shift↓
+bg 1 running · 1 failed · Shift↓ · /bg-clear
+bg 2 done · Shift↓ · /bg-clear
+```
+
+Press `Shift+Down` to open the focused bottom dock. Arrow keys are captured only while the dock is focused. Each task row shows the latest context-window usage reported by that specific background task, for example `ctx 21.0%/200k`; tasks that do not report their own context show `ctx —` rather than the parent Pi session's usage. Background Pi-agent tasks also surface the LLM model they ran (`model gpt-5.5` in the compact row, fully-qualified such as `openai-codex/gpt-5.5` in the detail view), cumulative token usage (`tok 1.6k`), and tool-use counts (`tools 2/1 failed`) in the dock and detail view; missing model/token/tool telemetry is omitted in rows and shown as “not reported by this background task” in details. When a background command is explicitly marked as an agent and invokes a print/json child agent such as `pi -p ...` through the normal shell command name, the extension wraps that child Pi process with `--mode json`, parses real assistant usage/tool execution events, and emits task-owned telemetry automatically — including the model reported by the child assistant turns.
+
+Finished-task badges intentionally remain visible until acknowledged. The reliable clear path is `/bg-clear`, which works in every terminal and clears finished background-task footer notices without opening the dock. `Ctrl+Alt+C` is still registered as an optional terminal-dependent fallback shortcut, but the footer advertises `/bg-clear` because some macOS terminals do not transmit `Ctrl+Alt+C` distinctly.
+
+Dock controls:
+
+| Key | Action |
+|---|---|
+| `Shift+Down` | Open focused background-task dock |
+| `/bg-clear` | Clear finished-task footer notices from the main UI |
+| `Ctrl+Alt+C` | Optional terminal-dependent shortcut for `/bg-clear` |
+| `↑` / `↓` | Select task |
+| `PageUp` / `PageDown` | Page task list |
+| `Enter` / `→` | Inspect logs/details |
+| `←` | Return from details to list |
+| `h` | Toggle recent history |
+| `k` | Stop selected running task |
+| `a` / `K` | Stop all running tasks, with confirmation |
+| `r` | Refresh detail tail |
+| `R` | Rerun selected command |
+| `c` | Show copyable output path |
+| `x` / `Esc` / `q` | Close dock |
 
 ## LLM tools
 
-- `bg_run` — start long-running commands without blocking the conversation.
+- `bg_run` — start named long-running commands without blocking the conversation.
 - `bg_status` — inspect one task or all recent tasks.
 - `bg_logs` — read bounded task output.
 - `bg_kill` — stop a running task.
 
-`bg_run` defaults to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. User-launched `/bg` jobs are display-only by default.
+`bg_run` requires a concise `name` for the footer dock, the shell `command`, and required `isAgent: boolean`. Set `isAgent: true` only when the background task launches an LLM/agent process (for example `pi -p ...` or `pi --mode json ...`); set `isAgent: false` for scripts, tests, dev servers, sleeps, and ordinary shell commands. It defaults to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. Tasks marked with `isAgent: true` that launch print/json child Pi agents through the normal shell command name are telemetry-wrapped; set `PI_BG_DISABLE_PI_TELEMETRY=1` only when raw Pi stdout is required. The task snapshot and metadata expose `isAgent`, `contextUsage` (latest reported child assistant turn), cumulative `tokenUsage` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`), cumulative `toolUsage` (`total`, `failed`, `byName`), and `model` (the LLM identifier reported by the child assistant turns, preferring the fully-qualified `provider/model` form) when reported by the child task. User-launched `/bg` jobs are display-only by default unless `--agent` is provided; UI reruns preserve the original task's `isAgent` value.
 
 ## Runtime files
 
@@ -61,9 +95,34 @@ These are runtime artifacts and should remain gitignored.
 - Running tasks are cleaned up on Pi session shutdown/reload.
 - Cross-Pi-restart process reattachment and Ctrl+B backgrounding of already-running foreground tools are intentionally out of scope.
 
-## Development smoke
+## Development and QA
+
+Default QA gate:
+
+```bash
+npm run test
+```
+
+Smoke and release checks:
 
 ```bash
 npm run smoke
 npm run pack:dry-run
 ```
+
+Full interactive QA gate:
+
+```bash
+npm run test:full
+```
+
+The suite includes typecheck, unit, SDK, RPC, component, package, PTY/TUI, and scripted-provider coverage for the focused dock, lifecycle safety, and completion follow-up behavior.
+
+Note: the repo QA standard requires exhaustive coverage of every public behavior and plausible edge case. `TEST_PLAN.md` tracks the current coverage matrix and any future edge-case additions.
+
+This package follows the repo-wide Pi extension QA standard documented in:
+
+- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
+- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
+- [`TEST_PLAN.md`](TEST_PLAN.md)
+- [`TESTING.md`](TESTING.md)

package/TESTING.md

@@ -0,0 +1,116 @@
+# pi-background-tasks Testing
+
+This package follows the repo-wide Pi extension QA standard:
+
+- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
+- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
+- [`TEST_PLAN.md`](TEST_PLAN.md)
+
+## Current commands
+
+Default gate:
+
+```bash
+npm run test
+```
+
+This runs:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:sdk
+npm run test:rpc
+npm run test:component
+npm run test:package
+```
+
+Full interactive gate:
+
+```bash
+npm run test:full
+```
+
+This runs the default gate plus:
+
+```bash
+npm run test:pty
+npm run test:agent-loop
+```
+
+Smoke/release checks:
+
+```bash
+npm run smoke
+npm run pack:dry-run
+```
+
+Current smoke:
+
+```bash
+pi --no-extensions -e ./extensions/background-tasks.ts --offline --no-tools --no-session -p "/jobs"
+```
+
+Smoke proves loadability only; completion requires `npm run test`, `npm run test:full`, and `npm run pack:dry-run`.
+
+## Required isolated environment
+
+Automated tests run with isolated temp project/agent/session directories and should use:
+
+```bash
+PI_OFFLINE=1
+PI_SKIP_VERSION_CHECK=1
+PI_TELEMETRY=0
+CI=1
+```
+
+Tests must not use the user's real `~/.pi/agent`.
+
+## Coverage summary
+
+Implemented coverage includes:
+
+- tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill`, including required `isAgent` schema/runtime validation, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
+- commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` discovery, happy paths, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
+- shortcut/UI: component coverage for focused dock list/detail/key handling, empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
+- runtime files: output and metadata files under `.pi/tasks/`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, real child `pi --mode json` tool-event parsing, split/large telemetry ingestion, metadata after completion/failure, local tarball install contents
+- safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup, process-group kill fallback, Windows child-kill behavior, SIGKILL escalation, duplicate finalization/notification races, metadata/notification failure handling, and pruning
+- agent loop: deterministic scripted-provider coverage for actual `bg_run` completion follow-up turns, `/bg` display-only behavior, `notifyOnCompletion:false`, and failed-task notification error fields
+- package: manifest, docs, `pi.extensions`, peer dependency/import parity, packed runtime files, tarball-install smoke, and artifact exclusion
+
+## PTY notes
+
+`test:pty` uses `/usr/bin/expect` to drive a real pseudo-terminal. It verifies:
+
+- `/tasks` and `/bg-tasks` open the focused dock and close with `x`.
+- A named `/bg` task appears in the dock when opened with xterm `Shift+Down` (`ESC [ 1 ; 2 B`).
+- Secondary dock keys work in a real TUI: arrows, page keys, detail/back, history, stop selected, stop-all confirmation, rerun, output path, and failed/unread history surfacing.
+
+The detail-view `Model:` line and the compact `model <id>` dock row are also exercised deterministically by the component layer (`tests/component/background-tasks-manager.test.ts`), which is the lowest reliable layer for dock rendering.
+
+### Terminal keyboard-protocol negotiation
+
+`pi` enables the Kitty keyboard protocol at startup by emitting `ESC[>7u ESC[?u ESC[c` and briefly intercepts stdin until that negotiation completes. The expect harness therefore must not key on a bare `>` (which matches the `ESC[>7u` push instantly and fires input before pi is listening); instead it waits for the steady-state status marker `(auto)`, answers the keyboard-protocol query (`ESC[?0u`, i.e. legacy keyboard) and the device-attributes query (`ESC[?1;2c`), and settles briefly before sending keys. This makes legacy keystrokes reach pi deterministically rather than racing the 150 ms negotiation fallback.
+
+### Interactive-stdin capability probe
+
+`test:pty` begins with a one-shot probe (`ptyInputSupported()`) that spawns a minimal raw-mode Node stdin reader under the same `/usr/bin/expect` driver and checks that a sent byte is received. Some hosts cannot deliver stdin to a raw-mode Node TUI through expect (a plain `cat` receives input but Node `process.stdin` does not). On such hosts every PTY case is skipped with a loud reason instead of failing; where stdin is deliverable the full interactive dock scenarios run for real. The deterministic SDK/RPC/component layers remain the authoritative gates in `npm run test` either way.
+
+## Artifact policy
+
+Use package-local or repo-level artifacts if future snapshot/log persistence is needed:
+
+```text
+artifacts/pi-extension-tests/pi-background-tasks/
+├── summary.json
+├── rpc-events.jsonl
+├── tui-ansi.log
+├── screen.normalized.txt
+└── snapshots/
+```
+
+Normalize volatile values before snapshotting: task IDs, session IDs, PIDs, timestamps, durations, temp paths, and `.pi/tasks/<session-pid>/...` run directories.
+
+## Remaining full exhaustive coverage work
+
+The Lane A residual hardening items and the explicit `isAgent` agent-vs-script classification are now covered by default unit/SDK gates plus full PTY and scripted-provider gates. `TEST_PLAN.md` remains the source of truth for future edge-case additions, especially any new telemetry surfaces added after this baseline.

package/TEST_PLAN.md

@@ -0,0 +1,98 @@
+# pi-background-tasks Test Plan
+
+This package follows:
+
+- [`../EXTENSION_PACKAGE_STANDARD.md`](../EXTENSION_PACKAGE_STANDARD.md)
+- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
+- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
+
+## Package
+
+| Field | Value |
+|---|---|
+| Package | `pi-background-tasks` |
+| Extension entrypoint | `extensions/background-tasks.ts` |
+| Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` |
+| Public tools | `bg_run`, `bg_status`, `bg_logs`, `bg_kill` |
+| Shortcuts | `Shift+Down`; optional fallback `Ctrl+Alt+C` |
+| Custom UI | footer status + focused bottom dock overlay |
+| Custom provider | no |
+| Runtime files/state | `.pi/tasks/<session-id>-<pid>/<task-id>.output`, `.pi/tasks/<session-id>-<pid>/<task-id>.json` |
+
+## Required gates
+
+| Gate | Command | Required in default `npm run test`? | Status |
+|---|---|---:|---|
+| Typecheck | `npm run typecheck` | yes | implemented |
+| Unit | `npm run test:unit` | yes | implemented |
+| SDK | `npm run test:sdk` | yes | implemented |
+| RPC | `npm run test:rpc` | yes | implemented |
+| Component | `npm run test:component` | yes | implemented |
+| Package | `npm run test:package` | yes | implemented |
+| PTY/TUI | `npm run test:pty` | full gate | implemented (answers pi's Kitty keyboard-protocol negotiation; auto-skips with a loud reason on hosts that cannot deliver raw-mode Node stdin via `/usr/bin/expect`) |
+| Scripted provider | `npm run test:agent-loop` | full gate | implemented |
+| Pack dry run | `npm run pack:dry-run` | release gate | implemented |
+| Smoke | `npm run smoke` | no | implemented; load-only |
+
+## Feature coverage matrix
+
+| Feature | Public surface | Unit | SDK | RPC | Component | PTY | Package | Scripted provider | Notes |
+|---|---|---:|---:|---:|---:|---:|---:|---:|---|
+| Start background command from UI command | `/bg` | yes |  | yes |  | yes |  |  | Unit covers `--name` and `--agent`; RPC/PTY start real processes. |
+| List tasks | `/jobs` |  |  | yes |  |  |  |  | RPC asserts running and killed task rows. |
+| Show bounded logs | `/logs <id> [maxBytes]` | yes |  | yes |  |  |  |  | Unit covers bounded reads; RPC verifies output/path. |
+| Kill running task | `/kill <id>` |  | yes | yes |  |  |  |  | SDK tool and RPC slash command. |
+| Open task manager fallback | `/tasks`, `/bg-tasks` |  |  | discovery | yes | yes |  |  | Component covers dock; PTY covers `/tasks` and `/bg-tasks`. |
+| Start background command from LLM tool | `bg_run` | yes | yes |  |  |  |  | yes | SDK starts named commands, verifies required `isAgent` schema/runtime behavior, and scripted provider verifies agent-loop tool calls with `isAgent:false` for scripts. |
+| Inspect task status | `bg_status` |  | yes |  |  |  |  |  | SDK polls exact IDs and validates shutdown state. |
+| Read task logs | `bg_logs` | yes | yes |  |  |  |  |  | SDK verifies content. |
+| Stop task from LLM tool | `bg_kill` |  | yes |  |  |  |  |  | Covers running kill and already-finished loud failure. |
+| Completion notification | custom message `background-task-notification` | yes | yes |  | renderer via typecheck |  |  | yes | Unit covers duplicate/failing notification paths; SDK verifies XML/details; scripted provider verifies real follow-up turns, display-only `/bg`, `notifyOnCompletion:false`, and failed-task error fields. |
+| Footer status | `ctx.ui.setStatus` |  | load path + clear command/shortcut + mixed states/focused label |  | render semantics | yes |  |  | SDK verifies `/bg-clear` hint, failed/stopped/done combinations, running combinations, and focused label; PTY verifies Shift+Down dock path after footer-visible task. |
+| Explicit agent classification | required `bg_run.isAgent`, `/bg --agent`, task metadata | yes | yes |  |  |  |  | yes | `isAgent:true` is required only for LLM/agent tasks and enables Pi-agent telemetry wrapping when the command invokes plain `pi`; `isAgent:false` is required for scripts/non-agents and prevents wrapping even if the command text looks like `pi -p ...`. |
+| Per-task context usage | task row/detail + `bg_status`/metadata/notification snapshots | yes | yes |  | yes |  |  |  | SDK verifies task-owned telemetry is captured, explicitly marked background `pi` invocations are wrapped to emit telemetry, and parent `ctx.getContextUsage()` is not used; component verifies list/detail rendering plus `ctx —` placeholder. |
+| Per-task token usage | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | SDK verifies cumulative input/output/cache read/cache write/total token usage from explicit telemetry, fake `isAgent:true` wrapped child events, and real child `pi --mode json` with scripted provider; component verifies row/detail rendering. |
+| Per-task tool-use counts | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | SDK verifies total/failed/by-name tool counts from fake and real child Pi `tool_execution_start/end` events, including failed tools; component verifies row/detail rendering. |
+| Per-task agent model | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | Unit verifies `formatModelSummary`/snapshot-list rendering and telemetry ingestion of `model`; SDK verifies the model is captured from explicit telemetry, fake `isAgent:true` wrapped child `message_end` events (qualified `provider/model`), and a real child `pi --mode json` run (bare child model re-qualified from `--model`), plus that non-agent tasks report no model; component verifies compact `model <id>` row, fully-qualified `Model:` detail, and the “not reported by this background task” placeholder. |
+| Focused dock list | overlay component |  |  |  | yes | yes |  |  | Selection/actions/history tested; PTY covers arrows, page keys, ordering with multiple tasks, failed/unread badges, and `/bg-tasks` fallback. |
+| Focused dock detail | overlay component |  |  |  | yes |  |  |  | Tail read, output box, return-to-list tested. |
+| Dock stop selected | `k` |  |  |  | yes |  |  |  | Component. |
+| Dock stop all | `a`/`K` |  |  |  | yes | yes |  |  | Component and PTY confirmation. |
+| Dock rerun | `R` |  |  |  | yes | yes |  |  | Component plus PTY running/completed/failed/killed rerun paths. |
+| Dock close | `x`/`Esc`/`q` |  |  |  | yes | yes |  |  | Component + PTY. |
+| Shortcut opens dock | `Shift+Down` |  | registration |  |  | yes |  |  | PTY sends xterm `ESC [ 1 ; 2 B`. |
+| Clear finished notices | `/bg-clear`, optional `Ctrl+Alt+C` fallback |  | yes | yes |  |  |  |  | `/bg-clear` is the canonical terminal-independent path and is advertised in the footer. SDK invokes the slash-command handler and verifies fallback shortcut registration; RPC verifies `/bg-clear` clears finished notices; finished notices remain until explicit clear. |
+| Runtime output files | `.pi/tasks/...output` | yes | yes |  |  |  |  |  | SDK asserts existence. |
+| Runtime metadata files | `.pi/tasks/...json` | yes | yes |  |  |  |  |  | SDK asserts shape/status/name/context usage; registry unit tests cover metadata failure/update ordering. |
+| Timeout kills task | `timeoutSeconds` |  | yes |  |  |  |  |  | SDK. |
+| Output cap kills task | `PI_BG_MAX_OUTPUT_BYTES` |  |  | yes |  |  |  |  | RPC runs with a low cap and asserts failed status/log notice. |
+| Shutdown cleanup | `session_shutdown` | yes | yes |  |  |  |  |  | SDK asserts multiple running tasks become killed; registry tests cover shared stop/wait behavior. |
+| Process lifecycle/races | registry core | yes | yes | yes |  | yes |  | yes | Unit tests cover process-group fallback, Windows fallback, SIGKILL escalation, duplicate finalization/notification races, notification/metadata failures, pruning, malformed telemetry, split telemetry chunks, and large telemetry records above the old 16KiB buffer; SDK/RPC cover runtime spawn/timeout/output-cap/shutdown; scripted provider covers wakeup integration. |
+| Package manifest | `package.json` |  |  |  |  |  | yes |  | Keywords, `pi.extensions`, files. |
+| Pack contents | `npm pack --dry-run` |  |  |  |  |  | yes |  | Runtime files included. |
+
+## Residual hardening coverage
+
+Lane A residual hardening is now covered by automated tests. No remaining hardening-only gaps are intentionally left open in this plan. Future feature work should add new rows instead of weakening these gates.
+
+| Hardened area | Coverage |
+|---|---|
+| Extracted process registry | `src/core/registry.ts` has direct unit coverage for state transitions and injected spawn/kill/platform behavior. |
+| Agent/script classification | Unit tests cover `isAgent:true` wrapping, `isAgent:false` non-wrapping, `PI_BG_DISABLE_PI_TELEMETRY`, and non-interceptable path-qualified `pi`; SDK verifies required tool schema/runtime validation and real marked Pi telemetry. |
+| Process lifecycle/races | Unit tests cover duplicate error/close finalization, output-cap races, duplicate-notification prevention, waiter resolution via stop paths, metadata failure logging, and notification failure reset. |
+| Process-tree kill safety | Unit tests cover POSIX process-group kill, child fallback, both-fail loud errors, SIGTERM idempotency, SIGKILL escalation, and Windows child-kill/shell invocation. |
+| Pruning | Unit tests cover oldest-finished pruning while preserving running tasks. |
+| Completion follow-up turns | `test:agent-loop` registers a deterministic scripted provider and verifies `bg_run` wakeup default, `/bg` display-only default, `notifyOnCompletion:false`, failed notification error fields, and real follow-up provider calls. |
+| PTY secondary keys | `test:pty` covers arrows, page keys, `a`/`K`, `R`, `c`, `/bg-tasks`, failed/unread badges, multiple-task ordering, and rerun paths for running/completed/failed/killed tasks. |
+| Footer/status combinations | SDK tests cover failed/stopped/done/running combinations, explicit clear, and focused label. |
+
+## Acceptance checklist
+
+- [x] `npm run test` passes offline in isolated temp dirs.
+- [x] `npm run test:full` validates baseline real TUI/PTY behavior.
+- [x] `npm run pack:dry-run` passes.
+- [x] README claims and all plausible edge cases are exhaustively mapped in this test plan.
+- [x] Every listed edge case has automated coverage at the lowest reliable layer.
+- [x] No real LLM/API/network dependency in default tests.
+- [x] No dependency on user/global `~/.pi/agent` for SDK/RPC/PTY tests.
+- [x] Volatile output is normalized in snapshot-style assertions where applicable.