pi-async
Pi extension for async shell tasks: background/delayed runs, output-matching watches, a settle hold for interactive sessions and a structural headless backstop for pi -p, plus a TUI task rail — completion notifications wake your session.
Package details
Install pi-async from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-async- Package
pi-async- Version
0.5.0- Published
- Nov 19, 2026
- Downloads
- 1,800/mo · 904/wk
- Author
- zzjcool
- License
- MIT
- Types
- extension
- Size
- 517 KB
- Dependencies
- 0 dependencies · 2 peers
Pi manifest JSON
{
"extensions": [
"./extensions/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-async
Pi extension for running shell commands asynchronously with bounded output capture, completion notifications, and a task panel.
Tasks run in the session working directory — the directory pi is currently in, not the directory the pi process was started from. Every task records its cwd, so delayed tasks and /reload recovery keep the directory they were submitted from.
Install
Install the package from npm with Pi's package manager:
pi install npm:pi-async
Local path (the other form of the same command, for a checkout):
pi install /path/to/pi-async
For development, load the extension directly:
pi -e ./extensions/index.ts
Tools and commands
The extension registers five tools by default (plus one opt-in tool):
| Tool | Purpose |
|---|---|
async_run |
Start a background or delayed shell command. |
async_logs |
Read bounded, ANSI-stripped captured output (merged / stdout / stderr). |
async_status |
List tasks and their current state. |
async_extend |
Renew a running task: move its reminder and/or hard-timeout deadline. Never kills. |
async_kill |
Terminate a task and its process group. |
async_wait (opt-in) |
Wait for task completion or return a notReady result on timeout. Registered only when the host sets PI_ASYNC_EXPOSE_WAIT=1. |
async_logs, async_extend, async_kill (and async_wait where it is exposed) accept a task name as
well as a task id. Ambiguous names are rejected with the candidate ids listed; unknown ids/names are an
error instead of a silent success. async_status is the read-only exception: its name argument is a
case-insensitive substring filter over the list (see Notifications).
async_wait is not registered by default: a completion notification wakes the session, so the blocking
collect step is opt-in. If a stale registration is still called while the switch is off, it answers
available: false with the reason and the enabling variable instead of throwing.
How the model finds these tools
Every registered tool carries a one-line promptSnippet, so the host lists all of them in the system
prompt's tools section — async_run is not the only entry point the model can see.
async_run additionally ships four promptGuidelines in the system prompt: when to reach for it instead
of bash, that ending a turn with running tasks is expected (the completion notification wakes the
session), that name + async_logs beat re-running a command, and that independent long commands should
be launched together in one batch and collected in a single pass. While async_wait is not exposed, a
fifth guideline says so and points at async_logs instead.
The procedural detail — when not to use async at all, how to plan a batch of independent long
commands up front, check-writing discipline, watch semantics, legion collection —
ships as an Agent Skill (skills/async-tasks/SKILL.md, advertised through resources_discover), so it
costs one routing line until the task actually needs it.
Two runtime nudges close the gap that a static prompt cannot:
- after a foreground
bashcall of 60 s or more — or atail -f/until/watch/sleep Nshaped command — the tool result gets one extra line suggestingasync_run. When the host does not report a wall time, the extension times the call fromtool_execution_startinstead of guessing; - while tasks are active, one
<async-state>line is appended before each request (nothing is injected when idle, and an unchanged state is not repeated). Its closing sentence follows the per-task truth: a task started withnotifyOnCompletion: false(ortriggerOnCompletion: false) is markedno-notify, and when nothing can wake the session the line says so instead of promising a notification.
The general rule lives in the system prompt once; a receipt only adds the exception for that call
(willNotify: false / willWake: false plus a one-line hint). Both nudges are advisory and best-effort;
PI_ASYNC_NUDGE=0 disables them.
Tool notes:
async_run:modeisbackground(default) ordelayed(requiresdelayMs;delayMsis rejected on any other mode). There is no blocking run: the call returns a receipt (taskId/name/status/mode/outputHint), the command keeps running, and the result is read later withasync_logsor delivered by the completion notification.async_status: defaults to active (running/pending) tasks.includeHistory: truelists up tolimit(1–50, default 50) tasks sorted newest first; an explicitstatusalso sorts newest first.statusandname(case-insensitive substring) filter the list.delayedEnvvalues are masked as"***". Snapshots exposenotified,outputConsumed,notifyAttempts,cwd,timeoutAt, andwatchDeadline. A delayed task that fails to start (missingcwd, rejectedenvkey, spawn error) is finalized asfailed(exit 1) and records the cause inmetadata.startError.async_logs:streamselects the merged capture or a single stream;maxBytesis capped at 50 KiB. A missing output file returnsmissing: trueinstead of throwing; paths outside the data directory are refused.async_kill: returnskillKind,alreadyTerminal,processAliveand, when the kill could not be confirmed,warning.
| Command / key | Action |
|---|---|
/async |
Open the task panel. The panel is a singleton: running it again while open only shows an Async panel is already open notice and does not stack another overlay — the open panel refreshes itself from registry events plus a 1 Hz ticker, so a running task's output is live while you watch it. |
/async-clear |
Clear completed-task history badges. |
↑ / ↓ / j / k |
Select tasks; in task details, scroll output (new output does not move a view you scrolled up). |
Enter |
Open selected task details: the detail body gives the command's stdout the height that command and metadata do not take, at least 8 rows (on a short terminal the command and metadata collapse into … (+K lines) instead), labelled output (live): while the task still runs. |
h |
Toggle history in the task list. |
x (or K) |
Kill a running task (press again to confirm). |
R |
Rerun the selected task command in that task's original cwd. |
c |
Show the captured output file path as a toast. Nothing is copied: pi exposes no clipboard API, so there is no copy action. |
Esc |
Close rail-clicked details; return from list-opened details to the list. |
q |
Close the panel. |
The rail's first row summarizes running, pending, elapsed, completed, and failed/killed task counts; pending and failed/killed counts are shown only when nonzero. The rail is not filtered by mode: background and delayed runs both appear there and count as running until they end. Mouse support (wheel, click) exists only in fullscreen / alt-screen TUI mode — pi only enables mouse reporting there; in regular mode use /async and the keyboard. The panel and rail are only enabled in the main Pi TUI session; RPC, print, and child contexts retain the tool surface without TUI entrypoints.
Configuration
| Environment variable | Default | Description |
|---|---|---|
PI_ASYNC_MAX_OUTPUT_BYTES |
20971520 (20 MiB) |
Maximum captured output per task; exceeding it terminates the task with output_cap. |
PI_ASYNC_MAX_TASKS |
32 |
Maximum concurrent running and pending tasks. |
PI_ASYNC_EXPOSE_WAIT |
off |
Set 1 to also register async_wait (the blocking collect tool). Unset, the tool surface is the default five and completion notifications do the waking. |
PI_ASYNC_ENV_INHERIT |
safe |
Child env policy: safe strips credential-like variables and rejects dangerous explicit keys; all restores full inheritance (explicit dangerous-key overrides are still rejected in every policy); none passes only a minimal allowlist (PATH, HOME, SHELL, TERM, LANG, LC_*, TMPDIR, USER). |
PI_ASYNC_SETTLE_GUARD |
on |
Set 0 to disable the settle guard entirely (no agent_before_settle reminder, no agent_settled backstop). |
PI_ASYNC_NUDGE |
on |
Set 0 to disable the runtime context nudges (the long-command hint and the <async-state> line). |
PI_ASYNC_HOLD |
on |
Set 0 to disable the settle hold entirely (no agent_before_settle handler is registered). |
PI_ASYNC_HOLD_MS |
600000 (10 min) |
Upper bound for one settle hold; ≤ 0 disables the feature (a negative value is not replaced by the default, and non-integer values fall back to the default). |
PI_ASYNC_HOLD_POLL_MS |
1000 |
How often the task list is re-read while the run is being held. |
PI_ASYNC_PRINT_WAIT |
on |
Set 0 to disable the headless (pi -p) backstop entirely (the process may exit while tasks still run — the 0.4.x behaviour). |
PI_ASYNC_PRINT_WAIT_MS |
600000 (10 min) |
Overall budget for the headless wait: wall clock from the first real wait, accumulated across turns and continuation requests (time spent in provider requests counts). |
PI_ASYNC_PRINT_POLL_MS |
500 |
How often the task list is re-read while a print run waits; a value below 50 falls back to the default (it is not clamped). |
PI_ASYNC_PRINT_MAX_CONTINUATIONS |
5 |
Forced provider requests the headless backstop may spend before it reports the still-running tasks and exits non-zero. 0 means "never wait-and-continue": first boundary with a running task already throttles. |
PI_ASYNC_FOOTER |
off |
Set 1 to also render a one-line task summary through the host's setStatus footer (only when the host exposes setStatus). The rail's first row is the default status surface. |
PI_ASYNC_RETENTION_MS |
604800000 (7 days) |
How long terminal-task artifacts are retained; union with RETENTION_COUNT. |
PI_ASYNC_RETENTION_COUNT |
100 |
Max newest terminal tasks kept per dataDir; union with RETENTION_MS. |
PI_ASYNC_RAIL_LINGER_MS |
30000 |
How long completed/failed/killed tasks stay on the rail before disappearing. |
Under the default safe policy, inherited variables matching *_API_KEY, *_TOKEN, *_SECRET, *_PASSWORD, *_CREDENTIAL*, plus AWS_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_SESSION_TOKEN, GITHUB_TOKEN, GH_TOKEN, and NPM_TOKEN are removed. npm_config_* keys whose name contains auth, token, or password (for example npm_config__authToken, which npm reads as a credential) are removed as well, so npm credentials exported by the parent shell do not leak into tasks; ordinary npm settings such as npm_config_registry still pass through. Passing a dangerous key explicitly through env (PATH, LD_PRELOAD, LD_LIBRARY_PATH, NODE_OPTIONS, BASH_ENV, ENV, SHELLOPTS, PYTHONPATH, GIT_SSH_COMMAND) throws instead of being silently ignored — under every policy, including all; the safety rule cannot be switched off. Ordinary keys may still be overridden.
For delayed tasks the submitted env is persisted to <taskId>.json (mode 0600) so the task can still start after /reload; the tool surface and the panel render its values masked as "***" (keys survive).
Notifications
Completion notifications are best-effort. pi.sendMessage returns void — the host is fire-and-forget and gives no acknowledgement, so pi-async sends once, never retries, and never rolls back. A "queued" notification means it was handed to the host, not that the model read it.
notifiedbecomes true only aftersendMessagereturns; a failure or a missing host API leavesnotified: falseand incrementsnotifyAttempts.- On
session_start, pi-async resends terminal tasks that are still unnotified and unconsumed (within 24 h and under 2 attempts), so a missed wake-up is retried once per session start. async_waitresults (where the tool is exposed) are marked consumed (outputConsumed), which suppresses the completion notification for those tasks to avoid chatter. On a hybrid timeout only the completed side is consumed; not-ready tasks are left alone.- One terminal event is told once, to exactly one consumer (CONTRACT §7.2).
async_wait(terminal rows),async_status(terminal rows it returns) andasync_logs(a task that already finished) latchconsumedAton the task; a consumed task never produces a completion notification —claimNotificationandresendUnnotifiedboth skip it. Only terminal rows latch: reading the partial output of a running task, or listing it asrunning, leaves its notification armed. - While a run is live, the notification is not queued at
finalize(): the send is decided at the run's next turn boundary, after every consumer had its chance. That is what stops the "late receipt" — in 0.4.2 a task collected withasync_waitmid-run still produced aasync-task-notification85–138 s later, because pi only enqueues a streaming followUp and delivers it once the model stops. If nobody consumed the result, the notification is still delivered exactly once at that boundary; when the session is idle it is sent immediately and wakes the session as before. - The delivery channel follows the run state (0.4.4). A live run gets
deliverAs: "steer", which the host drains at every turn boundary;followUpis drained only when the model stops asking for tool calls, so a busy parent used to push the notification to the end of the whole run (measured:finishedAt04:15:24.745 → injected 04:18:23.383, +178.6 s). An idle session keepsfollowUp+triggerTurn: true, which starts the wake-up run immediately. One terminal event is still enqueued at most once, no matter how many boundaries pass. async_statusexposesnotified/outputConsumed/consumedAt/notifyAttempts, so an agent can check whether it already received (or suppressed) a result.notifyOnCompletion: falseopts a task out entirely.- A delayed task whose start failed records
metadata.startError; the failure notification'sguidanceincludes it asStart error: ..., so the cause (missingcwd, rejectedenvkey, spawn failure) is visible without an extraasync_logscall. - A task killed by
taskTimeoutMsstayskilled, but its notification carriesguidance(growtaskTimeoutMsor usewatch) — it is the onekilledshape where the next step matters.completednotifications stay pure information.
Settle hold (default on)
Settling is what flips the terminal OSC 7501 status from working to done. When an interactive TUI
session reaches the end of a turn while async tasks that will wake it are still running, pi-async
holds the run at the agent_before_settle boundary instead of settling, so the run keeps reporting
working for the whole wait.
- Only wakeable
runningtasks are waited for:notifyOnCompletion !== falseandtriggerOnCompletion !== false.pendingtasks (amode: "delayed"run) are never held — theirdueAtcan be arbitrarily far away, so waiting for one would burn the whole budget at every turn end. The set is snapshotted when the boundary opens, so a task started while it waits is not waited for. - Bounded: at most
PI_ASYNC_HOLD_MSper run (default 600000 ms = 10 min, measured on a monotonic clock) and one hold per run (agent_startre-arms it). It never probes the host's message queue for notifications (those land onagent.followUpQueue, invisible toctx.hasPendingMessages()), but it does yield to the user: a lone Esc or a message you queued ends the hold immediately, and the run settles exactly as it would have without it — nothing is consumed, killed, or suppressed. - The user can always get out. pi awaits
agent_before_settlewith no timeout and cannot preempt it, and the run'sAbortSignalis already gone at this boundary — so Esc is observed through the raw terminal listener (onTerminalInput, lone\x1bonly; arrow/Alt sequences are left alone) and releases the hold in milliseconds instead of waiting for the budget. A message submitted while the hold waits (Enter queues it as steering) releases it on the next poll (~1 s), so the host can deliver your message on the next turn. Programmatic aborts that do not type Esc (an extension callingctx.abort(),/treenavigation) still cannot preempt the handler; see Known limitations. - It visibly moves. pi clears its own working row at
agent_end, i.e. before this boundary, so a hold would otherwise look like a frozen screen. While it waits, the rail's first row becomes the wait — a spinning⠋⠙⠹…frame every 250 ms, how long this turn has been held, andEsc stops waiting— and it hands row 0 back to the summary row in afinally. 0.4.8 removed the separate line the plugin used to paint above the editor: the two said the same thing in one terminal (0.4.4–0.4.7). The per-task detail (name · status · elapsed) is the rail's own task rows: repeating it in the waiting row made one terminal say the same thing three times (0.4.5). "The detail is on screen" is decided from what the rail paints right now, not from "a rail was registered earlier": the names are dropped only while the mounted rail lists every task the hold waits for. A host withoutsetWidget, a rail the host dropped, and a rail whose window does not cover those tasks all fall back to a hold-owned line that names them itself (name (status, elapsed),+N more) — the rail is re-installed on the next frame, so the two surfaces never go dark together, and exactly one waiting line is on screen either way (0.4.7/0.4.8). The footer linewaiting for N tasks <elapsed>(15 s cadence) is still written when the host exposessetStatus, but it is no longer the only sign of life. - When every task in the snapshot finished, the boundary returns one
async-task-settle-resultsdraft (name, status, exit code — never the output tail, useasync_logs) pluscontinue: true, so the outcome reaches the transcript even if the wake-up was dropped. That cannot loop: the next boundary sees only terminal tasks and returns nothing. - One terminal event, one announcement. While the hold waits, it owns the completion of the
tasks in its snapshot: their
async-task-notificationis not sent, the results draft is the single announcement, and those ids are latchednotifiedsoresendUnnotifiedcannot repeat it on the nextsession_start. This matters because pi only queues afollowUpwhile the run is streaming and delivers it once the model stops — so in 0.4.2 the draft arrived first and the notification a whole turn later, repeating an outcome the model had already acted on. Every hold exit that does not produce a draft (timeout, dispose, a throwing registry) releases the notifications instead, so nothing is ever swallowed. - The draft names each finished task by
name(falling back to the task id), which is exactly whatasync_logsaccepts, and still points atasync_logsrather than inlining a tail. - Only an interactive TUI session holds. A
printsession is served by a different mechanism — the headless backstop below deliberately keeps the process alive until running tasks finish — andrpcaborts under a client-side timeout, so neither of them may also hold. Legion child sessions keep their own bounded reminder channel. None of the three is affected by the hold. - While it waits the footer shows
waiting for N tasks <elapsed>, refreshed every 15 s, whenever the host exposessetStatus.Environment variable Default Description PI_ASYNC_HOLDonSet 0to disable the hold entirely (no handler is registered at all).PI_ASYNC_HOLD_MS600000(10 min)Upper bound for one hold; ≤ 0 disables the feature (a negative value is not replaced by the default; non-integer values fall back to the default). PI_ASYNC_HOLD_POLL_MS1000How often the task list is re-read while holding.
Start long-lived services (a dev server, a watcher you keep across turns) with
notifyOnCompletion: false: such a task is still running at every turn end, so with the default it
would hold every turn until PI_ASYNC_HOLD_MS.
Pressing Esc during a hold releases it within milliseconds: the raw terminal listener sees the lone
\x1b, the hold returns immediately, and pi then settles the aborted run (it suppresses the
continuation itself, so no extra provider request runs). Because the hold owns the terminal event, it
queues no notification for a task that finishes inside the wait, so an aborted run has nothing for
the host's clearAllQueues() to drop. A task that finishes after the Esc is not affected: its
notification is delivered normally and still wakes the session. If you had already queued text when
you pressed Esc, the host moves it back into the editor (restoreQueuedMessagesToEditor), so nothing
you typed is lost.
Headless (pi -p) — the process waits for the work
A print run is one prompt in, one answer out, then process.exit. Nothing in the host keeps that
process alive while a background task still runs, so pi-async does it structurally (0.5.0):
- When the run reaches the settle boundary in a print session with
runningtasks, the extension keeps the boundary open until they all finish (polled, no TUI). It then commits oneasync-task-print-resultsentry (name/status/exit only — never an output tail) and returnscontinue: true, so the host issues one more provider request. The model gets a real turn to read the result and its answer is whatpi -pprints — not an empty stdout after an early exit. - The wait reuses the completion-notification ownership relay, so a task finishing inside it is
announced exactly once (the results entry) and
notifiedis latched; nothing is lost or doubled. - It is bounded twice:
PI_ASYNC_PRINT_MAX_CONTINUATIONSforced turns (default 5) and one overallPI_ASYNC_PRINT_WAIT_MSwall-clock budget (default 10 min, accumulated from the first real wait — provider time between turns counts, so a long run may report a newly started task immediately instead of waiting for it; that is the intentional whole-process bound). Over budget the run is allowed to end, but not silently: stderr getspi-async: still running N async task(s) after C continuation(s) and Ts: <id> (<name>), …naming every taskId, and the process exits with code 1. - Only
runningtasks block the exit. Amode: delayedtask sits inpendingby definition (itsdueAtmay be an hour away), so it is scheduled work, not in-flight work — it survives on disk for the next session instead of burning the budget. agent_before_settlein print mode has no host timeout and Esc does not reach it; the two bounds above are what make that safe.PI_ASYNC_PRINT_WAIT=0disables the whole backstop (0.4.x behaviour).
The real-process proof lives in the repository: scripts/headless-smoke.sh wait starts a task that
outlives the model's turn and asserts the conclusion is what stdout carries; cap asserts the
non-zero exit plus the taskId line; off reproduces the pre-0.5.0 early exit.
Watches
- Conditions inside a group (
success_when,failure_when) are OR-ed: the first match wins. There is no AND mode; use one condition with a richerstdout_containsvalue if you need a conjunction. success_whenrecords completion without killing the process (task lifetime still belongs totaskTimeoutMs/async_kill);failure_when, blind exhaustion, and watch timeout all kill the process group.blind_checks(default 3) counts only infrastructure errors (e.g. the output file could not be read). "Not yet decidable" states — process still running, JSON not valid yet — stay pending and never accumulate blind checks.output_matchessees only the trailing 64K characters of output (UTF-16 code units, not bytes), so a marker far from the tail falls out of the window — anchor accordingly.stdout_contains/stderr_containsscan the captured stream, but every poll reads only the last 8 MiB, so anything older is invisible to every condition.output_matchescompiles with themflag, so^/$are line boundaries.
Data directory
Captured artifacts live per session:
- With a session manager:
<session dir>/pi-async/<sessionId>/ - Without one:
~/.pi/async/<pid>/
Each task writes <taskId>.json (atomically replaced metadata) plus <taskId>.output and its .stdout / .stderr sidecars. Files are created with mode 0600.
Do not point the data directory at a git-tracked path: captured output can contain credentials, tokens, or other secrets a command printed. Terminal-task artifacts are pruned by PI_ASYNC_RETENTION_MS ∪ PI_ASYNC_RETENTION_COUNT; non-terminal tasks are never pruned directly — orphan detection (configure() → reapOrphans()) first marks running tasks whose pid is gone as failed (failureKind: "lost") at startup, and marks pending delayed tasks as lost when their due time is older than PI_ASYNC_RETENTION_MS (the count setting does not apply to them). Pending delayed tasks still inside that window are restored with their remaining delay.
If the resolved data directory changes inside a live process, artifacts are copied to the new location; if migration fails, pi-async logs the error and keeps the old directory so no task is lost.
Legion child sessions
In a legion child session, collect task results before returning a verdict (async_status plus async_logs; async_wait too when PI_ASYNC_EXPOSE_WAIT=1 exposes it). The settle guard pushes a reminder into the model context before settling (up to 3 times, custom_message draft, continue: true), and an aborted run with active tasks gets a follow-up reminder on agent_settled. In the main session the same boundary produces one advisory draft (no forced re-run) saying that stopping with background work is fine, because its completion notification will wake the session. Notifications themselves remain best-effort (see above); see CONTRACT.md §6 for the frozen notification and collection requirements.
Known limitations
- Crash-durability is not guaranteed: metadata is atomically replaced, but captured output is not fsynced. After a crash, orphaned running tasks are marked
failed/loston the next start, and pending delayed tasks are restored with their remaining delay by whichever session next loads the same data directory (process identity does not matter). Recovery inside the same process is complete for/reload(cwd,taskTimeoutMsdeadline, and watch deadline are rebuilt from disk). - Cross-turn wake-up in legion children depends on the host delivering follow-up messages (upstream pi-legion issue #156); the extension does not patch Pi or legion.
- The settle hold keeps the OSC 7501 status in
workingand renders its live wait as the rail's first row (spinner + elapsed +Esc stops waiting) because pi cleared the built-in working row atagent_end. Esc releases the hold through the raw terminal listener; a programmatic abort that produces no Esc keystroke (an extension callingctx.abort(),/treenavigation →await session.abort()) still cannot preempt an awaitingagent_before_settlehandler — pi'sAgentBeforeSettleEventcarries no AbortSignal andemitBoundarydoes not race the handler (runner.js:767-814). Such a call waits up toPI_ASYNC_HOLD_MS; the hold still yields as soon as the user queues a message or the tasks finish. Input itself is never frozen — text submitted during a hold is queued as steering. - Because a hold keeps the run busy,
waitForIdle()waits for it too: a command thatawait session.abort()without an Esc keystroke waits up toPI_ASYNC_HOLD_MSwhile a hold is in progress (e.g./treenavigation —interactive-mode.js:4758→agent-session.js:1999). Esc itself is a keystroke, so it reaches the hold first and releases it;void abort()stays non-blocking. - TUI rail and panel are available only in the main TUI session, not in RPC/print/child contexts.
- In a print run a task that never finishes ends the process with a non-zero exit code and one stderr line naming the still-running taskIds (see Headless). The host still kills those process groups at shutdown, exactly as before.
- A
delayedtask is not waited for in print mode: it is pending, not in flight.
Development checks
npm run typecheck
npm test
npm run verify # typecheck + test (same gate as prepublishOnly)
npm run adoption # adoption report from real session JSONL (last 15 sessions)
npm pack --dry-run
scripts/headless-smoke.sh wait # real `pi -p` + scripted mock endpoint (also: cap, off)
npm run adoption reads ~/.pi/agent/sessions/*/*.jsonl (--dir / --limit / --json to change scope)
and prints the bash duration distribution, the foreground wall time it cost, the sleep-polling share, and
how many calls the shipped nudge would have flagged. Use it to compare a change instead of trusting the
anecdote in a review doc.
Container QA
Run the plugin inside a clean container against the local model endpoint:
cd test/docker
make run # start container + drop into pi (default: workbuddy/hy4-preview-ioa)
make smoke # L1 model reachable -> L2 tools advertised -> L3 a tool really runs
make qa-up && make qa-tui SCENARIO=s1 # deterministic TUI scenario
make run reuses an already-running container, so it never tears down your session.
The container QA setup itself lives in test/docker/ (not shipped in the npm
package). See its README in the repository for the two containers, the required
mounts, and why L3 must not be skipped.
Known upstream issue (print mode)
pi --print + background task completing after the agent settles: the wake happens but the woken
run's turn_end boundary fails with Extension error (<boundary>): turn_end could not resolve the persisted assistant entry ID (pi 1.2.0 core, reproduced identically with pi-background-tasks —
upstream issue https://github.com/earendil-works/pi/issues/11001). RPC mode (legion subagents) and
turn-internal waits are unaffected. It is still present on pi 1.5.2 for runs woken by a followUp
(visible on stderr with PI_ASYNC_PRINT_WAIT=0); the 0.5.0 headless backstop avoids that path because
it owns the terminal event and continues in-run.