@justjoshn/pi-pstack 0.15.36-pi.13 → 0.15.36-pi.14

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.15.36-pi.14] - 2026-11-04
+
+Each item below was checked against Cursor CLI 2026.10.22 with pstack and cursor-team-kit loaded, through live captures. `parity/pstack-native-parity-2026-11-04/` in the repository records the evidence and the decisions.
+
+- Add background shells: `bash_background` runs a command in the background, or after a foreground wait, writes `terminals/<id>.txt` with a status header and an exit footer, and sends a `kind: shell` notification when the command ends or prints a watched line. `AwaitShell` polls, waits for a pattern, or sleeps. pstack's babysit watcher, worktree-cleanup scan, PR review canvas server, and event-gated `/loop` wakes use them. The host section sends commands that can run for minutes to `bash_background`, because `bash` waits until a command ends.
+- Run the Linux read-only shell under bubblewrap with a seccomp filter that bubblewrap loads itself, so readonly subagents get a working shell on Ubuntu 24.04 and later. Writes, the network, and Unix sockets stay blocked. macOS keeps sandbox-runtime.
+- Tell the agent to run a loop's prompt once in the turn that arms it, as Cursor's loop skill does.
+- Remove `AskQuestion` from subagents.
+- State today's date in the host section.
+- Restore upstream text in the architect runner prompt and arena where the port had added instructions with no host reason.
+
 ## [0.15.36-pi.13] - 2026-11-04
 
 - Parse leading word intervals and preserve multiline prompts in `/loop`.

package/README.md

@@ -1,6 +1,6 @@
 # pstack for Pi (pi-pstack)
 
-pi-pstack is pstack 0.15.36 for Pi 1.5.0: rigorous agent workflows (`/poteto-mode` and its playbooks), the principle skills, and the review, research, and verification skills, plus the full soft-dependency team-kit set (`deslop`, `control-cli`, `control-ui`, CI/PR helpers, thermo-nuclear review, and the rest) vendored in so you do not install a separate team-kit package. A small extension provides the host features the skills call by name: `/name` skill commands, `/mode`, `/plan`, the `Task` subagent tool with local worktree workers, forks, and `agent_status`, `TodoWrite`, `AskQuestion`, `GenerateImage`, `SwitchMode`, the model rule, `/loop`, subscriptions and webhook routines, and `visualize`.
+pi-pstack is pstack 0.15.36 for Pi 1.5.0: rigorous agent workflows (`/poteto-mode` and its playbooks), the principle skills, and the review, research, and verification skills, plus the full soft-dependency team-kit set (`deslop`, `control-cli`, `control-ui`, CI/PR helpers, thermo-nuclear review, and the rest) vendored in so you do not install a separate team-kit package. A small extension provides the host features the skills call by name: `/name` skill commands, `/mode`, `/plan`, the `Task` subagent tool with local worktree workers, forks, and `agent_status`, background shells (`bash_background` and `AwaitShell`), `TodoWrite`, `AskQuestion`, `GenerateImage`, `SwitchMode`, the model rule, `/loop`, subscriptions and webhook routines, and `visualize`.
 
 ## Get set up
 
@@ -13,7 +13,7 @@ pi-pstack is pstack 0.15.36 for Pi 1.5.0: rigorous agent workflows (`/poteto-mod
    pi install ./extensions/pi-pstack
    ```
 
-   Pi does not install dependencies for a local package, so `bun install` (or `npm install` in `extensions/pi-pstack`) fetches `@anthropic-ai/sandbox-runtime` for the read-only shell (readonly subagents and `/plan`) and `yaml` for plan metadata. If sandbox-runtime is missing, a read-only shell command fails instead of running unsandboxed. On Linux the sandbox also needs `bubblewrap`, `socat`, and `ripgrep` (`sudo apt install bubblewrap socat ripgrep`), and Ubuntu 24.04 and later need the user-namespace change under Limits. macOS uses the built-in `sandbox-exec`. pi-pstack needs Node 22.19 or newer. To try it for one session without installing, run `pi -e ./extensions/pi-pstack`. To install the published package instead, run `pi install npm:@justjoshn/pi-pstack`.
+   Pi does not install dependencies for a local package, so `bun install` (or `npm install` in `extensions/pi-pstack`) fetches `yaml` for plan metadata and, for the macOS read-only shell (readonly subagents and `/plan`), `@anthropic-ai/sandbox-runtime`. On Linux the read-only shell runs `bubblewrap` from the system instead (`sudo apt install bubblewrap`), with no user-namespace change on Ubuntu 24.04 and later. Where no sandbox can start, a read-only shell command fails instead of running unsandboxed. macOS uses the built-in `sandbox-exec`. pi-pstack needs Node 22.19 or newer. To try it for one session without installing, run `pi -e ./extensions/pi-pstack`. To install the published package instead, run `pi install npm:@justjoshn/pi-pstack`.
    Installing loads pi-pstack's tools and system-prompt sections at once, but no skill runs until you invoke it. 61 workflow skills stay out of the model's automatic skill list. Setup, create-skill, and the team-kit shipping and review skills (`deslop`, `control-cli`, `control-ui`, CI and PR helpers, and the rest of that set) can load from your words alone.
 2. Run `/setup-pstack`. It lists the models the `Task` tool can use, asks for a reasoning budget, maps a model to each role, and writes the model rule. A new rule applies from the next request.
 3. Start real work with `/poteto-mode`, a goal, and a check that can pass or fail.
@@ -29,7 +29,7 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 | `/poteto-mode <task>` | The skill attaches to that one message. Every skill Pi loaded works this way: pstack's (`/how`, `/why`, `/arena`, `/interrogate`, `/principle-prove-it-works`, `/deslop`) and your own, such as a `/<handle>-mode` skill from `/automate-me`. `/skill:<name>` works too. |
 | `/mode poteto-mode [task]` | Keeps the skill in context on every turn until you leave the mode: the skill rides every request in its own system-prompt section, which Pi re-sends only when it changes. The first request after entry says the user entered the mode, later requests carry a reminder that names the skill file, and the request after `/mode off` or a switch to another mode says the user left it. The footer shows a badge with the skill's `icon` and `color` metadata, such as a yellow `♛ mode: poteto-mode` (other skills get `⚡`). `/mode off` exits and `/mode` reports. Any loaded skill can back a mode. |
 | `/plan [task]` | Plan mode: the agent researches with read-only tools (`read`, `grep`, `find`, `ls`, the sandboxed `bash_readonly`, `AskQuestion`, `TodoWrite`, `agent_status`, `Task`, whose launches run readonly: a fresh one runs here with no worktree, and a resume or fork stays where its agent ran, and `stop_agent`), asks its clarifying questions early, and presents the plan with `CreatePlan` (`plan`, `name`, `overview`, `todos`, `is_project`, `phases`). `CreatePlan` writes the plan file under `<pstack dir>/plans/` (`<name>-<8 hex>.plan.md`: the chat id in a comment, the todos as front matter, then the plan), one file per plan name in a chat. Todo dependencies and project phases stay in the file. Building imports the file's unfinished root todos into the session, including edits made during review. Worktree builders import their own lists before the first model request and retain the associated plan on resume. Later writable `TodoWrite` status updates synchronize those root todos without rewriting other metadata or the plan body. An omitted status imports as pending and is inserted when the todo is updated. A readonly resume keeps its todo changes inside the session. `edit` and `write` work on markdown files only, so the agent refines the plan in its file. After a run that saved a plan, an interactive session asks `Yes, build locally`, `Yes, build in cloud` (in a git repository: a background isolated worker builds it on its own branch), or `No, propose changes`. `/plan build` builds the saved plan too, and `/plan off` restores your tools. A bare `/plan` enters plan mode. The footer shows `plan`. |
-| `/loop 30m <prompt>` | Runs the prompt now, then again every 30 minutes from each fire, so a long run does not push the next tick out. A tick that comes due while a run is still going fires once when that run settles; several missed ticks still fire once. The interval can come first or last, written as `30m`, `10 minutes`, or `every 10 minutes`. Without an interval the agent picks each wake with the `Loop` tool, and the loop ends when it picks none and no background subagent is still running. Different prompts create independent loops. The same prompt replaces its schedule. `/loop` lists them. `/loop stop` ends the only loop, or `/loop stop <id>` selects one when several are running. Escape during a run ends the session's loops. `Loop` results include the loop ID in text and details; pass `loop_id` to wake, stop, or replace one of several loops. The prompt can be a skill command, such as `/loop 1h /poteto-mode run the audit tick`. When a playbook says to arm `/loop`, the agent starts it with the `Loop` tool. Intervals go up to 24 days. |
+| `/loop 30m <prompt>` | Runs the prompt now, then again every 30 minutes from each fire, so a long run does not push the next tick out. A tick that comes due while a run is still going fires once when that run settles; several missed ticks still fire once. The interval can come first or last, written as `30m`, `10 minutes`, or `every 10 minutes`. Without an interval the agent picks each wake with the `Loop` tool, and the loop ends when it picks none and no background subagent or background shell is still running. A run that waits on an event (CI finishing, a ref moving, a log line) starts a watcher with `bash_background`, whose notification wakes the agent, and keeps a long wake as the fallback. Different prompts create independent loops. The same prompt replaces its schedule. `/loop` lists them. `/loop stop` ends the only loop, or `/loop stop <id>` selects one when several are running. Escape during a run ends the session's loops. `Loop` results include the loop ID in text and details; pass `loop_id` to wake, stop, or replace one of several loops. The prompt can be a skill command, such as `/loop 1h /poteto-mode run the audit tick`. When a playbook says to arm `/loop`, the agent runs the prompt once in that turn and starts the loop with the `Loop` tool, whose first scheduled run comes after the interval or wake. Intervals go up to 24 days. |
 | `/routines` | Lists webhook routines with their URL, credential file, and status. |
 | `/setup-pstack` | Configures the per-role models. |
 | `/poteto-help <question>` | Answers a question about pstack and hands you a prompt to send. |
@@ -48,9 +48,9 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 | Subagent types | The built-in `generalPurpose` (default) and `explore` (a file-search specialist the caller tells how thorough to be, with `grep`, `find`, and `ls` on and no `Task`), then `poteto-agent` (a background delegate that reads poteto-mode first), `ci-watcher` (a background PR check watcher), `comment-sicko`, and `thermo-nuclear-code-quality-review`, the last four read from `agents/*.md`. Unknown types fail with the list. |
 | Models | A Pi model spec such as `claude-opus-5-5:xhigh` or `xai/grok-4.7:high`, model parameters such as `claude-opus-5-5[effort=high]` or `grok-4.7[fast=true]` (picks a listed `-fast` id of that model), `fast` for the parent model's listed `-fast` variant when it has one, else the parent model, or `inherit`, `inherit-parent`, `auto`, or nothing for the parent model. A model Pi does not list, or a thinking level the model does not support, fails with the allowed list. A bare model id that several providers offer resolves to the parent chat's provider when it offers that id, and otherwise fails with the choices. Older rules that wrote `claude-opus-5-5-xhigh` still resolve. The system prompt's `pstack_subagents` section lists the types, the parent model, and the models with their levels. |
 | Isolated workers (`environment: "cloud"`) | The subagent runs in a new git worktree at `<pstack dir>/workspaces/<workspace folder>/worktrees/<agent id>` on branch `pstack/<agent id>`, from `cloud_base_branch` (`origin/<branch>` when that remote-tracking ref exists, else a local branch or other ref) or your HEAD commit, so uncommitted changes do not reach it. The result and the card name the branch to merge, and `resume` and `fork` run in the same worktree. It fails clearly outside a git repository, in a repository with no commits, or when the base does not resolve. The worker shares the root chat's workspace state, so it sees the same projects, stores, and subagent transcripts. It also shares this machine's ports, processes, writable caches, simulators, and credentials. Assign separate ports, output directories, and writable caches to concurrent runtime lanes. `swarm` and `orchestrate` spawn worktree workers by default. |
-| `readonly: true` | The child gets `read`, `grep`, `find`, `ls`, `TodoWrite`, and a read-only `bash`, and no MCP. That shell runs each command in an OS sandbox ([`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime): `sandbox-exec` on macOS, bubblewrap on Linux) that blocks every file write and all network access, so `git log` works and `touch` or `curl` fail. Where no sandbox can start, the command fails rather than running unsandboxed. Readonly is not credential isolation. The child still inherits environment variables and can read credential files through its read tools. |
+| `readonly: true` | The child gets `read`, `grep`, `find`, `ls`, `TodoWrite`, and a read-only `bash`, and no MCP or background shell. That shell runs each command in an OS sandbox that blocks every file write, all network access, and Unix sockets, so `git log` works and `touch` or `curl` fail. On Linux it is `bubblewrap` with every namespace unshared, the filesystem bound read-only, and a seccomp filter that refuses `socket(AF_UNIX)` and `io_uring_setup`; on macOS it is [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime)'s `sandbox-exec` policy. Where no sandbox can start, the command fails rather than running unsandboxed. Readonly is not credential isolation. The child still inherits environment variables and can read credential files through its read tools. |
 | `TodoWrite` | `todos` with `id`, `content`, `status`, and `merge`. Its description says when to keep a list, the four states, and one task in progress at a time. The list follows the session branch, shows above the editor, and rides every request's system prompt. Plan-imported lists persist as branch entries. Their dependencies survive status-only updates, and matching plan-file statuses are synchronized. |
-| `AskQuestion` | `title`, and per question `id`, `prompt`, `options` (at least two, each `id`, `label`, optional `description`), and `allow_multiple`, through Pi's select dialog. It is for decisions only the user can make, and a recommended option goes first with `(Recommended)`. Every question ends with `Other: (type to answer)`; a typed answer comes back as `other` with its text. In print and JSON runs, including subagents, each question comes back skipped. |
+| `AskQuestion` | `title`, and per question `id`, `prompt`, `options` (at least two, each `id`, `label`, optional `description`), and `allow_multiple`, through Pi's select dialog. It is for decisions only the user can make, and a recommended option goes first with `(Recommended)`. Every question ends with `Other: (type to answer)`; a typed answer comes back as `other` with its text. In print and JSON runs each question comes back skipped. Subagents have no `AskQuestion`. |
 | Always-applied rules | The two team-kit rules are in `pstack_host` as their shipped text on every request, alongside the same rules as hidden skills. |
 | The model rule | `<pstack dir>/pstack-models.md`, plain Markdown with one line per role, added to every request's system prompt. A `pstack-models.mdc` from an earlier version is moved there once, without its frontmatter, and kept as `pstack-models.mdc.migrated`. |
 | Subscriptions | `subscribe_github_pr` (`scope` `pr` with `prUrl`, `repo` with `repo`, or `author` with `author` and `repo`) polls with `gh` every 60 seconds and wakes the chat when a PR's state, head, mergeability, review decision, reviews, or comments change, or when a check concludes or its conclusion changes; the first poll is a baseline. `subscribe_timer` takes a `name`, a `prompt`, and a 5-field `cron` or `delaySeconds`, either with `once`; `sessionStrategy` `wake_self` queues a wake for this owning session. With `new_session`, a live owner starts a background Task and receives its notification. An offline owner permits a detached run with a recorded outcome. Both reuse the model, thinking level, and project-trust decision the timer was created with. Re-subscribing an existing timer name returns `created: false`. `list_subscriptions` and `unsubscribe` manage them. The authoritative registry is `<pstack dir>/durable/<workspace>/subscriptions.json`. Any session in that workspace can list or cancel subscriptions. Session history does not recreate cancelled or completed subscriptions. Owner-directed events wait for the creating session rather than waking another workspace session. A detached run records its own final message, shown by `list_subscriptions`. A timer does not expire unless `expiresInHours` says so (at most 30 days); `0` means no expiry. A GitHub watch keeps a 7-day default because it is this port's own surface. |
@@ -60,6 +60,7 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 | `visualize` | `title`, `kind` (`bar` or `line`), `labels`, `series` (`name`, `values`), and `unit` render a Unicode chart in the result and write a standalone SVG to the session's artifacts folder. |
 | Transcripts | The system prompt names this workspace's Pi session directory, the current session file, and this workspace's subagent transcripts. |
 | `GenerateImage` | Generates an image (`description` of at least six words, `filename`, `reference_image_paths`, `aspect_ratio`) on Pi's image models through `ctx.modelRegistry.generateImages()`. It is offered when an image model is available (for example an OpenRouter image model), not to readonly subagents or in plan mode, and saves each image to the session's artifacts folder. Without an image model, the host section tells skills to draw a Mermaid diagram instead. |
+| Background shells | `bash_background` (`command`, `description`, `block_until_ms`, `notify_on_output` with `pattern`, `reason`, and `debounce_ms`, `working_directory`) runs a command in the background, or waits up to `block_until_ms` for it and then moves it there. Output goes to `<pstack dir>/workspaces/<workspace folder>/terminals/<shell id>.txt`, which starts with a header (pid, cwd, command, title, status, started_at, and running_for_ms, refreshed every 5 seconds) and ends with an exit footer. After the turn, a `<system_notification>` with a `kind: shell` task block arrives when the command finishes (`status: success`, `error` with `exit_code=N`, or `aborted`) and when a line matches `notify_on_output` (the first match at once, later ones counted and sent after each `debounce_ms` window, at least 5 seconds). `AwaitShell` (`shell_id`, `block_until_ms`, `pattern`) polls or waits on a job, or sleeps without one; seeing a job end there skips its notification. Print and JSON runs wait for their jobs before they exit. Ending the session stops running jobs. Readonly subagents and plan mode do not get these tools. |
 | `SwitchMode` | `target_mode_id` (`plan` or `agent`) and `explanation`. The agent proposes entering or leaving plan mode, and the switch happens only after you confirm it. Offered in interactive and RPC sessions. |
 
 Subagent transcripts are Pi sessions in `<pstack dir>/workspaces/<workspace folder>/subagents/`, with the agent ID in each file name, next to a small record that `resume`, `fork`, and `agent_status` read. Records belong to the main chat's shared workspace state, so the root chat can act on a descendant that ran in a worktree. Children inherit your installed extensions and MCP servers, and local ones run in your working directory. Give each local subagent that writes its own git worktree, or launch it with `environment: "cloud"`, because a child process does not isolate the filesystem. A child exits on its own if its parent Pi process dies.
@@ -78,7 +79,8 @@ Subagent transcripts are Pi sessions in `<pstack dir>/workspaces/<workspace fold
 - Depth limits apply to `Task`. A writable subagent can still start `pi` through `bash`, and that process is outside the depth limit and parent watchdog.
 - A child loads your installed extensions plus this package. If you run one checkout with `-e` while a different checkout of pi-pstack is installed, the child loads both and fails on duplicate tools; use one copy, or a separate `PI_CODING_AGENT_DIR`, as `live:e2e` does.
 - Subagents run headless in RPC mode, so an extension that asks for permission through a dialog cannot ask there.
-- The read-only shell sandboxes shell subprocesses only. Earlier macOS and Ubuntu CI runs do not verify the stricter Unix-socket policy. On Linux it needs `bubblewrap`, `socat`, and `ripgrep`. Ubuntu 24.04 and later restrict unprivileged user namespaces: either add an AppArmor profile that grants `userns` to `bwrap`, or run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts the restriction for every program on the machine. Unix sockets stay blocked because a host socket service can mutate files or access the network on a command's behalf. Linux also needs sandbox-runtime's bundled `apply-seccomp` helper and permission to create its nested user, PID, and mount namespaces. A missing helper or a namespace refusal blocks the shell command. The shell never falls back to permitting host sockets. Do not treat a readonly child as a credential boundary. Environment variables and readable credential files are still available to its read tools.
+- The read-only shell sandboxes shell subprocesses only. On Linux it needs `bubblewrap` that can create its user namespace (Ubuntu's default `bwrap` AppArmor profile allows that) on x86-64 or arm64; bubblewrap loads the seccomp filter itself, so no nested namespace is needed. A missing `bwrap`, another architecture, or a namespace refusal blocks the shell command. Unix sockets stay blocked because a host socket service can mutate files or access the network on a command's behalf, and the shell never falls back to permitting them. Do not treat a readonly child as a credential boundary. Environment variables and readable credential files are still available to its read tools.
+- A subagent's background shells stop when the subagent finishes, and its launch result says so, because a subagent is its own process. A print or JSON run waits for its background shells, with no timeout of its own, so a job that never ends keeps the run open.
 - Whether a model follows a playbook is the model's call.
 - Workspace folders follow Pi's session-folder naming, so two paths that differ only by `/` versus `-` share a folder. Resume and fork refuse an agent whose record names the other directory, except that a record created inside this workspace's own worktrees belongs to this workspace. Subscription reads and mutations also reject a registry owned by the other workspace.
 - The run lock that keeps one writer per agent ID names the process writing the transcript. A lock file without a readable pid counts as held; the error names the file to delete. `agent_status` shows such an agent as `idle`. A token-directory lease beside the PID file serializes stale-lock recovery. A dead process or an unreaped Linux zombie does not count as a live writer. Older installed versions without the lease do not participate in this protection.

package/docs/guide/01-setup.md

@@ -13,7 +13,7 @@ bun install
 pi install ./extensions/pi-pstack
 ```
 
-`pi install <path-to-pi-pstack>` loads the package in place, so keep the checkout where it is. To install the published package instead, run `pi install npm:@justjoshn/pi-pstack`. On Linux, the read-only shell also needs `bubblewrap`, `socat`, and `ripgrep`, as the package README explains. Start Pi, and the pstack commands appear in the `/` menu.
+`pi install <path-to-pi-pstack>` loads the package in place, so keep the checkout where it is. To install the published package instead, run `pi install npm:@justjoshn/pi-pstack`. On Linux, the read-only shell also needs `bubblewrap`, as the package README explains. Start Pi, and the pstack commands appear in the `/` menu.
 
 ## Pick your models
 

package/docs/parity-status.md

@@ -45,6 +45,20 @@ A live Cursor CLI session with both plugins loaded produced these contracts.
 
 Pi returns the child's final text with a transcript path and usage, and reports background completion as a `pstack/task` notification. The payload shape differs because the hosts are different; the observable workflow, a subagent result arriving after the parent turn, is preserved.
 
+## Repairs in 0.15.36-pi.14
+
+An independent audit on 2026-11-04 compared every reference file and probed Cursor CLI 2026.10.22 live. The repository's `parity/pstack-native-parity-2026-11-04/` holds the notes, decision log, inventory, and the scripts; `.audit/pstack-native-parity-2026-11-04/cursor/` holds the raw Cursor captures.
+
+- **Background shells.** Cursor's `Shell` runs a command in the background (`block_until_ms: 0`, or after the wait runs out), writes `terminals/<id>.txt` with a status header and an exit footer, notifies after the turn when the command ends (`kind: shell`) and on each `notify_on_output` match (the first at once, later ones counted per debounce window), and `AwaitShell` polls, waits for a pattern, or sleeps. pstack leans on it: babysit's "watcher output drives wakeups", worktree-cleanup's "background it", pr-review-canvas's "run this backgrounded", and the event-gated branch of Cursor's `/loop`. pi-pstack had no background shell. `bash_background` and `AwaitShell` now reproduce the captured texts, header layout (173 bytes for the probed job), and notification shapes. Two choices differ from one observation each. A job whose end `AwaitShell` saw sends no completion notice, as Cursor's AwaitShell description promises, though one Cursor run sent a duplicate. A subagent's jobs stop when the subagent ends, because a Pi subagent is its own process; Cursor ran the job on and reported it `aborted` to the parent.
+- **Linux read-only shell.** sandbox-runtime's seccomp helper needs a nested user namespace, which Ubuntu 24.04 and later refuse by default (`kernel.apparmor_restrict_unprivileged_userns=1`), so every readonly subagent on such a host had no shell. Cursor documents readonly as "no file edits, no state-changing shell commands", so read-only commands must work. Linux now runs `bwrap` directly with every namespace unshared, `/` bound read-only, and a generated seccomp filter (`bwrap --seccomp`) that refuses `socket(AF_UNIX)` and `io_uring_setup`. Writes, TCP, and Unix sockets stay refused; `git log` works. macOS keeps sandbox-runtime.
+- **`/loop` arming.** Cursor's loop skill runs the prompt once when the loop is armed. The host section and the `Loop` tool now say to do that in the arming turn; the first scheduled run still comes after the interval or wake.
+- **Subagents have no `AskQuestion`.** Cursor's generalPurpose subagent listed no such tool (`subagent-tools.jsonl`), and one asked to call it replied that it does not exist (`subagent-askquestion.jsonl`).
+- **Today's date.** Cursor's user info states "Today's date" in every chat (`context-paths.jsonl`). Pi's system prompt has no date, so `pstack_host` now states it in the same form.
+- **Long commands.** Cursor's `Shell` moves a command to the background after its 30-second foreground window. Pi's `bash` waits until the command ends, so the host section sends watchers, polling scripts, and servers to `bash_background`.
+- **Text.** The architect runner prompt is upstream's again, and arena drops a port-assignment sentence and a `cloud` instruction that no host difference required. Arena keeps upstream's `composer-*`/`cursor-grok-*` family rule.
+
+Observed, not changed: Cursor CLI 2026.10.22 does not load plugin rules (team-kit's two always-applied rules) or name an agent store or Projects in its context (`context-paths.jsonl`); pi-pstack keeps both, because pstack's text relies on them.
+
 ## Reconstruction repairs in 0.15.36-pi.13
 
 The repository's `parity/pstack-reconstruction-2026-11-04/` holds the reference inventory, baseline and treatment receipts, and decision log. These repairs do not establish that every workflow has been observed on both hosts.
@@ -119,7 +133,8 @@ These are not closed by extension code.
 - **Background workers stop when the chat exits.** A Pi subagent is a child process of the chat, so quitting or shutting the session stops the agents it started and reports how many. Whether a Cursor background subagent outlives its parent is unobserved; the CLI changelog says cancelling the prompt stops its subagents, and only the cloud-agent product promises work after the laptop closes. A `new_session` subscription fire is Pi's one detached path, and it starts a fresh run rather than continuing a subagent.
 - **A mode's skill rides the system prompt.** Cursor attaches the skill to the user message that enters the mode and keeps it durable in the conversation; its notices travel in user-message fields. Pi carries the skill and the notices in system-prompt sections, which reach the model on every request and survive compaction, so the model sees the same text in a different place.
 - **A fork needs an idle source.** Cursor exposes `fork` only on its internal and cloud-agent protos, never on the CLI Task schema, and no doc states whether a fork may start while the source runs. A Pi fork runs in the source's directory or worktree, so a running source is refused; the orchestrate playbook says to wait for its completion notification.
-- **Linux readonly shells require nested namespace support.** The stricter policy must block host Unix sockets as well as IP traffic and filesystem writes. On a host that refuses sandbox-runtime's seccomp helper, the command does not run. Earlier checks that permitted all Unix sockets are not evidence for this policy. Readonly also does not isolate environment credentials or files readable through the ordinary read tools.
+- **A subagent's background shells end with it.** Cursor runs a subagent inside the parent process, so a background shell it starts outlives the subagent's Task result and its notification reaches the parent (`subagent-bg-shell.jsonl`, status `aborted`). A Pi subagent is its own process, so its jobs stop when it finishes, and its launch result says so.
+- **Linux readonly shells need bubblewrap.** The policy blocks host Unix sockets as well as IP traffic and filesystem writes. bubblewrap must be able to create its user namespace (Ubuntu's `bwrap` AppArmor profile allows it); where it cannot, or on an architecture other than x86-64 or arm64, the command does not run. Readonly also does not isolate environment credentials or files readable through the ordinary read tools.
 - **Plan mode's restriction is stricter than the host's.** Cursor's plan mode keeps every tool and restricts by instruction: edit only markdown files, run only read-only commands. Pi enforces the same rules with a tool allowlist, markdown-only `edit` and `write`, and a sandboxed shell that also denies network, so `gh`, `curl`, and package queries can fail while planning. Allowing network in a read-only shell would also open a path for remote changes, so the sandbox keeps it closed.
 - **The plan review is a dialog, not a card.** Cursor renders the plan with a build menu. Pi shows the same three choices in a select dialog after the run that saved the plan, and "build in cloud" starts a background isolated worktree worker, Pi's counterpart to a cloud agent, rather than a remote VM.
 - **benny's default cadence still needs its owning session open.** `wake_self` timers and webhook routines park while the owner is offline. A timer or webhook routine created with `sessionStrategy: "new_session"` runs detached with no chat open, but a detached run is one-shot: it must do the work in that run, because a background `Task` ends with it. Cursor automations run in the cloud and can hand work to anything. So benny keeps `wake_self` by default and setup names the tradeoff before switching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justjoshn/pi-pstack",
-  "version": "0.15.36-pi.13",
+  "version": "0.15.36-pi.14",
   "description": "pstack 0.15.36 for Pi with its soft-dependency team-kit skills vendored in: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, SwitchMode, image generation, and visualize",
   "type": "module",
   "license": "MIT",

package/skills/architect/references/runner-prompt.md

@@ -1,6 +1,6 @@
 # Architect runner prompt
 
-The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates. Worktrees and scratch directories share the host machine. Use the distinct ports, output directories, and writable cache paths assigned in the brief for concurrent runtime candidates. Report a missing assignment before starting a conflicting process. If the design requires stronger machine isolation, report it as unavailable.
+The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates.
 
 You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first. That's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
 

package/skills/arena/SKILL.md

@@ -14,12 +14,12 @@ Every candidate gets the same prompt, so the prompt is the contract.
 
 1. State the artifact each candidate is producing.
 2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
-3. Pick the runners. Use the `arena runners` line in the model rule at the path the system prompt names. If the rule or that line is missing, default to one each on `claude-opus-5-5:xhigh` and `grok-4.7[effort=xhigh,fast=true]`. An `auto` or `inherit-parent` entry in this line means the parent model, so omit `model` for it. If the Task tool rejects a configured entry, run that seat on its family's default and say so. Families go by the model id after the provider: `claude-*` and `grok-*`. If the family has no default, or the Task tool rejects that default, use the closest valid slug of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `model` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section of the **poteto-mode** skill.
-4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill. Worktrees share this machine. Assign distinct ports, output directories, and writable cache paths for concurrent runtime candidates. If stronger machine isolation is required, report it as unavailable.
+3. Pick the runners. Use the `arena runners` line in the model rule at the path the system prompt names. If the rule or that line is missing, default to one each on `claude-opus-5-5:xhigh` and `grok-4.7[effort=xhigh,fast=true]`. An `auto` or `inherit-parent` entry in this line means the parent model, so omit `model` for it. If the Task tool rejects a configured entry, run that seat on its family's default and say so. Families go by the model id after the provider, by prefix: `claude-*`, and `grok-*` with `cursor-grok-*` and `composer-*`. A refused `composer-*` entry runs on `grok-4.7[effort=xhigh,fast=true]`. If the family has no default, or the Task tool rejects that default, use the closest valid slug of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `model` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section of the **poteto-mode** skill.
+4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.
 
 ## Phase B: Fan out
 
-Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected. When the project is a git repository, pass `environment: "cloud"` so each candidate runs in its own worktree; otherwise keep each candidate's writes under its own output path.
+Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected.
 
 If a candidate produces no output, proceed with N-1 and note the dropout.
 

package/src/ask.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { type Static, Type } from 'typebox';
+import { childIdentity } from './child-env.ts';
 import { canAsk } from './modes.ts';
 
 export const DONE_LABEL = '✓ Done selecting';
@@ -122,6 +123,8 @@ export function registerAskQuestion(pi: ExtensionAPI): void {
     parameters: AskParams,
     exposure: 'model-only',
     executionMode: 'sequential',
+    // Cursor's subagents have no AskQuestion: their owner, not a person, reads what they produce.
+    defaultActive: childIdentity.depth === 0,
     annotations: { readOnlyHint: true, openWorldHint: false },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       validateQuestions(params.questions);

package/src/background-shell.ts

@@ -0,0 +1,698 @@
+// Cursor's background shell: a command that keeps running while the agent works, an output file with a status
+// header and an exit footer, a notification when the command finishes or prints a watched line, and AwaitShell to
+// poll or wait. Texts follow what Cursor CLI 2026.10.22 returns and sends (parity/pstack-native-parity-2026-11-04).
+import { type ChildProcess, spawn } from 'node:child_process';
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, statSync, writeSync } from 'node:fs';
+import { constants } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { getShellConfig, truncateTail } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { isOneShot } from './modes.ts';
+
+export const SHELL_NOTICE_TYPE = 'pstack/shell';
+const BACKGROUND_TOOL = 'bash_background';
+const AWAIT_TOOL = 'AwaitShell';
+
+const FIELD_WIDTH = 9;
+const HEADER_REFRESH_MS = 5_000;
+const MIN_DEBOUNCE_MS = 5_000;
+const DEFAULT_AWAIT_MS = 30_000;
+const MAX_AWAIT_MS = 7_140_000;
+const KILL_GRACE_MS = 2_000;
+const FOLLOW_UP = 'Briefly inform the user about the task result and perform any follow-up actions (if needed).';
+
+type JobStatus = 'running' | 'succeeded' | 'failed' | 'aborted';
+type NoticeStatus = 'success' | 'error' | 'aborted';
+
+interface OutputWatch {
+  readonly regex: RegExp;
+  readonly source: string;
+  readonly reason: string;
+  readonly debounceMs: number;
+  occurrences: number;
+  /** Matches since the last notification, sent when the debounce window closes. */
+  unreported: number;
+  latest: string;
+  notices: number;
+  window: ReturnType<typeof setTimeout> | undefined;
+  partial: string;
+}
+
+interface ShellJob {
+  readonly id: string;
+  readonly pid: number;
+  readonly command: string;
+  readonly cwd: string;
+  readonly title: string;
+  readonly toolCallId: string;
+  readonly path: string;
+  readonly startedAt: number;
+  readonly fd: number;
+  readonly headerBytes: number;
+  readonly statusOffset: number;
+  readonly runningOffset: number;
+  readonly child: ChildProcess;
+  readonly watch: OutputWatch | undefined;
+  readonly listeners: Set<() => void>;
+  readonly done: Promise<void>;
+  /** Where the next output byte goes; the header is rewritten in place, so the file is never opened for append. */
+  size: number;
+  /** Where the output ends once the footer is written. */
+  bodyEnd: number | undefined;
+  status: JobStatus;
+  exitCode: number | undefined;
+  endedAt: number | undefined;
+  /** AwaitShell or a foreground wait saw the end, so no completion notification follows. */
+  observed: boolean;
+  /** Waits in progress (AwaitShell or a foreground wait); one of them reports the end instead of a notification. */
+  awaiting: number;
+  refresh: ReturnType<typeof setInterval> | undefined;
+}
+
+export interface ShellNotice {
+  kind: 'progress' | 'finished';
+  status: NoticeStatus;
+  taskId: string;
+  shellId: string;
+  title: string;
+  toolCallId: string;
+  detail?: string;
+  outputPath?: string;
+}
+
+const pad = (value: string) => value.padEnd(FIELD_WIDTH, ' ');
+
+/** The header Cursor writes: fixed-width status and running time, so both can be rewritten in place. */
+export function terminalHeader(fields: { pid: number; cwd: string; command: string; title: string; startedAt: number }): { text: string; statusOffset: number; runningOffset: number } {
+  const before = ['---', `pid: ${fields.pid}`, `cwd: ${JSON.stringify(fields.cwd)}`, `command: ${JSON.stringify(fields.command)}`, `title: ${JSON.stringify(fields.title)}`, 'status: '].join('\n');
+  const middle = `${pad('running')}\nstarted_at: ${new Date(fields.startedAt).toISOString()}\nrunning_for_ms: `;
+  const text = `${before}${middle}${pad('0')}\n---\n`;
+  const statusOffset = Buffer.byteLength(before);
+  return { text, statusOffset, runningOffset: statusOffset + Buffer.byteLength(middle) };
+}
+
+export function terminalFooter(exitCode: number, elapsedMs: number, endedAt: number): string {
+  return `\n---\nexit_code: ${exitCode}\nelapsed_ms: ${elapsedMs}\nended_at: ${new Date(endedAt).toISOString()}\n---\n`;
+}
+
+export function launchText(job: Pick<ShellJob, 'id' | 'pid' | 'command' | 'path'>): string {
+  return ['Background command started successfully.', `Shell ID: ${job.id}`, `PID: ${job.pid}`, `Command: ${job.command}`, `Output will be written to ${job.path}. Don't mention Shell ID to the user.`].join('\n');
+}
+
+export function movedText(job: Pick<ShellJob, 'id' | 'pid' | 'path'>, waitedMs: number, output: string): string {
+  return [
+    `The command did not complete in ${waitedMs}ms and was sent to the background.`,
+    `Shell ID: ${job.id}`,
+    `PID: ${job.pid}`,
+    `The output is being written to ${job.path}. Don't mention Shell ID to the user.`,
+    '',
+    'Output collected before backgrounding:',
+    '',
+    '```',
+    tail(output, job.path),
+    '```',
+  ].join('\n');
+}
+
+export function finishedText(exitCode: number, elapsedMs: number, output: string, path: string): string {
+  return [`Exit code: ${exitCode}`, '', 'Command output:', '', '```', tail(output, path), '```', '', `Command completed in ${elapsedMs} ms.`].join('\n');
+}
+
+function tail(output: string, path: string): string {
+  const result = truncateTail(output);
+  return result.truncated ? `[showing the last ${result.outputLines} of ${result.totalLines} lines; the full output is in ${path}]\n${result.content}` : output;
+}
+
+export function noticeText(notice: ShellNotice): string {
+  return [
+    '<system_notification>',
+    `The following task has ${notice.kind === 'finished' ? 'finished' : 'notified'}. If you were already aware, ignore this notification and do not restate prior responses.`,
+    '',
+    '<task>',
+    'kind: shell',
+    `status: ${notice.status}`,
+    `task_id: ${notice.taskId}`,
+    `title: ${notice.title}`,
+    `tool_call_id: ${notice.toolCallId}`,
+    ...(notice.detail === undefined ? [] : [`detail: ${notice.detail}`]),
+    ...(notice.outputPath === undefined ? [] : [`output_path: ${notice.outputPath}`]),
+    '</task>',
+    '</system_notification>',
+    FOLLOW_UP,
+  ].join('\n');
+}
+
+const firstMatchDetail = (watch: OutputWatch) => `Shell output has pattern /${watch.source}/. This is occurrence number ${watch.occurrences}. Matched text: ${watch.latest}. The title message is being displayed to the user.`;
+const laterMatchesDetail = (watch: OutputWatch) => `Shell output matched /${watch.source}/ ${watch.unreported} more times since the previous notification. The title message is being displayed to the user. Latest match: ${watch.latest}.`;
+
+function exitStatus(code: number | null, signal: NodeJS.Signals | null): { status: JobStatus; exitCode: number } {
+  if (signal !== null) return { status: 'aborted', exitCode: 128 + (constants.signals[signal] ?? 0) };
+  const exitCode = code ?? 1;
+  return { status: exitCode === 0 ? 'succeeded' : 'failed', exitCode };
+}
+
+function compile(pattern: string): RegExp {
+  try {
+    return new RegExp(pattern, 'm');
+  } catch (error) {
+    throw new Error(`Invalid pattern /${pattern}/: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function sessionEnv(ctx: ExtensionContext): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env, PI_SESSION_ID: ctx.sessionManager.getSessionId() };
+  const file = ctx.sessionManager.getSessionFile();
+  if (file !== undefined) env['PI_SESSION_FILE'] = file;
+  if (ctx.model !== undefined) {
+    env['PI_PROVIDER'] = ctx.model.provider;
+    env['PI_MODEL'] = ctx.model.id;
+  }
+  return env;
+}
+
+/** Process groups of running jobs, killed if this process exits before a session shutdown could stop them. */
+const liveGroups = new Set<number>();
+let exitHookInstalled = false;
+function trackGroup(pid: number): void {
+  liveGroups.add(pid);
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on('exit', () => {
+    for (const group of liveGroups) signalGroupId(group, 'SIGKILL');
+  });
+}
+
+function signalGroupId(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(process.platform === 'win32' ? pid : -pid, signal);
+  } catch {
+    // The process group is already gone.
+  }
+}
+
+const sleep = (ms: number, signal: AbortSignal | undefined) =>
+  new Promise<void>((done) => {
+    if (signal?.aborted === true) return done();
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', finish);
+      done();
+    }
+    signal?.addEventListener('abort', finish, { once: true });
+  });
+
+export interface ShellJobsOptions {
+  terminalsDir: (ctx: ExtensionContext) => string;
+  shellPath: () => string | undefined;
+}
+
+export interface StartRequest {
+  command: string;
+  cwd: string;
+  title: string;
+  toolCallId: string;
+  watch?: { pattern: string; reason: string; debounceMs?: number };
+}
+
+/** Every background shell this runtime started, and the notifications they owe the agent. */
+export function createShellJobs(options: ShellJobsOptions, deliver: (notice: ShellNotice) => void) {
+  const jobs = new Map<string, ShellJob>();
+  let nextId: number | undefined;
+
+  const allocateId = (dir: string): string => {
+    nextId ??= 100_000 + Math.floor(Math.random() * 800_000);
+    while (existsSync(join(dir, `${nextId}.txt`))) nextId += 1;
+    const id = String(nextId);
+    nextId += 1;
+    return id;
+  };
+
+  const writeAt = (job: ShellJob, text: string, position: number) => {
+    const bytes = Buffer.from(text, 'utf8');
+    writeSync(job.fd, bytes, 0, bytes.length, position);
+  };
+  const append = (job: ShellJob, text: string | Buffer) => {
+    const bytes = typeof text === 'string' ? Buffer.from(text, 'utf8') : text;
+    writeSync(job.fd, bytes, 0, bytes.length, job.size);
+    job.size += bytes.length;
+  };
+  const refreshRunning = (job: ShellJob) => writeAt(job, pad(String((job.endedAt ?? Date.now()) - job.startedAt)), job.runningOffset);
+  const notify = (job: ShellJob) => {
+    for (const listener of [...job.listeners]) listener();
+  };
+
+  const sendProgress = (job: ShellJob, watch: OutputWatch, detail: string) => {
+    watch.notices += 1;
+    deliver({ kind: 'progress', status: 'success', taskId: `${job.id}:task_progress:${watch.notices}`, shellId: job.id, title: watch.reason, toolCallId: job.toolCallId, detail, outputPath: job.path });
+  };
+  /** Trailing-edge debounce: the first match notifies at once, later ones in the window are counted and sent when it closes. */
+  const openWindow = (job: ShellJob, watch: OutputWatch) => {
+    watch.window = setTimeout(() => {
+      watch.window = undefined;
+      if (watch.unreported === 0) return;
+      sendProgress(job, watch, laterMatchesDetail(watch));
+      watch.unreported = 0;
+      openWindow(job, watch);
+    }, watch.debounceMs);
+    watch.window.unref();
+  };
+  const matchLine = (job: ShellJob, watch: OutputWatch, line: string) => {
+    const match = watch.regex.exec(line);
+    if (match === null) return;
+    watch.occurrences += 1;
+    watch.latest = match[0];
+    if (watch.window !== undefined) {
+      watch.unreported += 1;
+      return;
+    }
+    sendProgress(job, watch, firstMatchDetail(watch));
+    openWindow(job, watch);
+  };
+  const scan = (job: ShellJob, chunk: string, final: boolean) => {
+    const watch = job.watch;
+    if (watch === undefined) return;
+    const lines = (watch.partial + chunk).split('\n');
+    watch.partial = final ? '' : (lines.pop() ?? '');
+    for (const line of lines) if (line !== '' || final) matchLine(job, watch, line.replace(/\r$/, ''));
+  };
+  const flushWatch = (job: ShellJob) => {
+    const watch = job.watch;
+    if (watch === undefined) return;
+    scan(job, '', true);
+    if (watch.window !== undefined) clearTimeout(watch.window);
+    watch.window = undefined;
+    if (watch.unreported > 0) sendProgress(job, watch, laterMatchesDetail(watch));
+    watch.unreported = 0;
+  };
+
+  const finish = (job: ShellJob, status: JobStatus, exitCode: number, announce: boolean) => {
+    if (job.status !== 'running') return;
+    const endedAt = Date.now();
+    Object.assign(job, { status, exitCode, endedAt, observed: job.observed || job.awaiting > 0 });
+    if (job.refresh !== undefined) clearInterval(job.refresh);
+    writeAt(job, pad(status), job.statusOffset);
+    refreshRunning(job);
+    job.bodyEnd = job.size;
+    append(job, terminalFooter(exitCode, endedAt - job.startedAt, endedAt));
+    closeSync(job.fd);
+    if (announce) {
+      flushWatch(job);
+      if (!job.observed) {
+        const noticeStatus: NoticeStatus = status === 'succeeded' ? 'success' : status === 'failed' ? 'error' : 'aborted';
+        deliver({
+          kind: 'finished',
+          status: noticeStatus,
+          taskId: job.id,
+          shellId: job.id,
+          title: job.title,
+          toolCallId: job.toolCallId,
+          ...(noticeStatus === 'error' ? { detail: `exit_code=${exitCode}` } : {}),
+        });
+      }
+    } else if (job.watch?.window !== undefined) clearTimeout(job.watch.window);
+    notify(job);
+  };
+
+  const start = (ctx: ExtensionContext, request: StartRequest): ShellJob => {
+    if (!existsSync(request.cwd) || !statSync(request.cwd).isDirectory()) throw new Error(`Working directory ${request.cwd} does not exist.`);
+    const watchRegex = request.watch === undefined ? undefined : compile(request.watch.pattern);
+    const dir = options.terminalsDir(ctx);
+    mkdirSync(dir, { recursive: true });
+    const id = allocateId(dir);
+    const path = join(dir, `${id}.txt`);
+    const config = getShellConfig(options.shellPath());
+    const viaStdin = config.commandTransport === 'stdin';
+    const child = spawn(config.shell, viaStdin ? config.args : [...config.args, request.command], {
+      cwd: request.cwd,
+      env: sessionEnv(ctx),
+      detached: process.platform !== 'win32',
+      stdio: [viaStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    let spawnError: Error | undefined;
+    child.once('error', (error) => {
+      spawnError = error;
+    });
+    if (viaStdin) child.stdin?.end(request.command);
+    if (child.pid === undefined) throw new Error(`Could not start ${config.shell}${spawnError === undefined ? '' : `: ${spawnError.message}`}.`);
+    const startedAt = Date.now();
+    const header = terminalHeader({ pid: child.pid, cwd: request.cwd, command: request.command, title: request.title, startedAt });
+    const fd = openSync(path, 'w+');
+    let release: () => void = () => undefined;
+    const job: ShellJob = {
+      id,
+      pid: child.pid,
+      command: request.command,
+      cwd: request.cwd,
+      title: request.title,
+      toolCallId: request.toolCallId,
+      path,
+      startedAt,
+      fd,
+      headerBytes: Buffer.byteLength(header.text),
+      statusOffset: header.statusOffset,
+      runningOffset: header.runningOffset,
+      child,
+      watch:
+        request.watch === undefined || watchRegex === undefined
+          ? undefined
+          : {
+              regex: watchRegex,
+              source: request.watch.pattern,
+              reason: request.watch.reason,
+              debounceMs: Math.max(MIN_DEBOUNCE_MS, request.watch.debounceMs ?? MIN_DEBOUNCE_MS),
+              occurrences: 0,
+              unreported: 0,
+              latest: '',
+              notices: 0,
+              window: undefined,
+              partial: '',
+            },
+      listeners: new Set(),
+      done: new Promise<void>((resolveDone) => {
+        release = resolveDone;
+      }),
+      size: 0,
+      bodyEnd: undefined,
+      status: 'running',
+      exitCode: undefined,
+      endedAt: undefined,
+      observed: false,
+      awaiting: 0,
+      refresh: undefined,
+    };
+    append(job, header.text);
+    job.refresh = setInterval(() => refreshRunning(job), HEADER_REFRESH_MS);
+    job.refresh.unref();
+    const onData = (chunk: Buffer) => {
+      if (job.status !== 'running') return;
+      append(job, chunk);
+      scan(job, chunk.toString('utf8'), false);
+      notify(job);
+    };
+    child.stdout?.on('data', onData);
+    child.stderr?.on('data', onData);
+    child.on('error', (error) => {
+      if (job.status === 'running') append(job, `${error.message}\n`);
+      finish(job, 'failed', 127, true);
+      release();
+    });
+    child.on('close', (code, signal) => {
+      liveGroups.delete(job.pid);
+      const { status, exitCode } = exitStatus(code, signal);
+      finish(job, status, exitCode, true);
+      release();
+    });
+    trackGroup(job.pid);
+    jobs.set(id, job);
+    return job;
+  };
+
+  /** The command's output so far: the file between the header and the footer. */
+  const output = (job: ShellJob): string => {
+    const length = Math.max(0, (job.bodyEnd ?? job.size) - job.headerBytes);
+    const buffer = Buffer.alloc(length);
+    const fd = job.status === 'running' ? job.fd : openSync(job.path, 'r');
+    try {
+      readSync(fd, buffer, 0, length, job.headerBytes);
+    } finally {
+      if (fd !== job.fd) closeSync(fd);
+    }
+    return buffer.toString('utf8');
+  };
+  const fileSize = (job: ShellJob) => (job.status === 'running' ? fstatSync(job.fd).size : statSync(job.path).size);
+
+  /** Resolves when the job ends, prints, or `ms` passes, or the signal aborts. A job that ends meanwhile counts as observed. */
+  const change = (job: ShellJob, ms: number, signal: AbortSignal | undefined) =>
+    new Promise<void>((done) => {
+      if (job.status !== 'running' || signal?.aborted === true) return done();
+      job.awaiting += 1;
+      const timer = setTimeout(stop, ms);
+      function stop() {
+        clearTimeout(timer);
+        job.awaiting -= 1;
+        job.listeners.delete(stop);
+        signal?.removeEventListener('abort', stop);
+        done();
+      }
+      job.listeners.add(stop);
+      signal?.addEventListener('abort', stop, { once: true });
+    });
+
+  const awaitJob = async (shellId: string, waitMs: number, pattern: string | undefined, signal: AbortSignal | undefined): Promise<string> => {
+    const job = jobs.get(shellId.trim());
+    if (job === undefined) throw new Error(`Error awaiting task: No shell found for id ${shellId}`);
+    const regex = pattern === undefined || pattern === '' ? undefined : compile(pattern);
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      if (job.status !== 'running') {
+        job.observed = true;
+        return [`Task completed in ${(job.endedAt ?? Date.now()) - job.startedAt}ms with exit code: ${job.exitCode}.`, `output_file_path: ${job.path}`, `output_length: ${fileSize(job)}`].join('\n');
+      }
+      const matched = regex?.exec(output(job))?.[0];
+      const remaining = deadline - Date.now();
+      if (matched !== undefined || remaining <= 0 || signal?.aborted === true) {
+        const suffix = regex === undefined ? '' : matched === undefined ? ' Pattern did NOT match.' : ` Pattern matched: ${matched}`;
+        return [`Task still running after ${Date.now() - job.startedAt}ms...${suffix}`, `output_file_path: ${job.path}`, `output_length: ${fileSize(job)}`].join('\n');
+      }
+      await change(job, remaining, signal);
+    }
+  };
+
+  const signalGroup = (job: ShellJob, signal: NodeJS.Signals) => signalGroupId(job.pid, signal);
+
+  /** Session end: every running job is stopped and recorded as aborted, with no notification. */
+  const shutdown = () => {
+    for (const job of jobs.values()) {
+      if (job.status !== 'running') continue;
+      signalGroup(job, 'SIGTERM');
+      const kill = setTimeout(() => signalGroup(job, 'SIGKILL'), KILL_GRACE_MS);
+      kill.unref();
+      finish(job, 'aborted', 128 + constants.signals.SIGTERM, false);
+    }
+  };
+  return {
+    start,
+    output,
+    awaitJob,
+    change,
+    shutdown,
+    running: () => [...jobs.values()].filter((job) => job.status === 'running'),
+    stop: (job: ShellJob) => {
+      signalGroup(job, 'SIGTERM');
+      setTimeout(() => signalGroup(job, 'SIGKILL'), KILL_GRACE_MS).unref();
+    },
+  };
+}
+
+type ShellJobs = ReturnType<typeof createShellJobs>;
+
+const NotifyParams = Type.Object({
+  pattern: Type.String({ description: 'Regex pattern matched against each line of stdout/stderr output. Output redirected only to a file will not trigger it. Do not match all outputs.' }),
+  reason: Type.String({ description: '5 or less words describing why you are watching for this output. It titles the notification.' }),
+  debounce_ms: Type.Optional(Type.Number({ description: 'Milliseconds that must elapse between notifications. The minimum is 5000ms.' })),
+});
+
+const BackgroundParams = Type.Object({
+  command: Type.String({ description: 'The command to execute' }),
+  description: Type.Optional(Type.String({ description: 'Very short phrase naming what this command does; it titles the notifications about it. Avoid leading with verbs or using trailing periods' })),
+  block_until_ms: Type.Optional(
+    Type.Number({
+      description:
+        'How long to wait for the command in the foreground before moving it to the background, in milliseconds. 0 (the default) starts it in the background at once. A command that finishes within the wait returns its output and sends no notification.',
+    }),
+  ),
+  notify_on_output: Type.Optional(
+    Type.Object(NotifyParams.properties, { description: 'Optional output notification config. Each output line which matches the pattern will notify you. ONLY set this when the user explicitly requests monitoring.' }),
+  ),
+  working_directory: Type.Optional(Type.String({ description: 'The absolute path to the working directory to execute the command in (defaults to current directory)' })),
+});
+
+const AwaitParams = Type.Object({
+  shell_id: Type.Optional(Type.String({ description: 'Optional shell id to poll. If omitted, this tool sleeps for the full block_until_ms duration and then returns. Required when block_until_ms is 0.' })),
+  block_until_ms: Type.Optional(
+    Type.Number({
+      maximum: MAX_AWAIT_MS,
+      description: 'Max sleep time to block before returning (in milliseconds). Defaults to 30000ms. Set to 0 only together with shell_id, for a non-blocking status check of that shell. Must not exceed 7140000 (119 minutes).',
+    }),
+  ),
+  pattern: Type.Optional(
+    Type.String({
+      description:
+        'Block until the regex matches the stdout/stderr output (or the command completes). Matches anywhere in the shell output, not just new output. Does not match the output file header or footer. JavaScript regex syntax, compiled in multiline mode so ^ and $ match at line boundaries.',
+    }),
+  ),
+});
+
+const BACKGROUND_DESCRIPTION = [
+  'Run a shell command in the background, or wait up to block_until_ms for it in the foreground and then move it to the background. Use it for work that should keep running while you do other things: dev servers, watchers, slow scans and builds, and a watcher whose output should wake you. Use bash for ordinary commands.',
+  '',
+  'The result names a shell ID, a PID, and an output file. The file starts with a header (pid, cwd, command, title, status, started_at, running_for_ms, refreshed every 5000ms) and ends with a footer (exit_code, elapsed_ms, ended_at) once the command finishes. After your turn ends you are notified when the command finishes, and on each notify_on_output match. Do not wait for those: keep working or end your turn. Poll with AwaitShell only when you are blocked on this job. Stop a job with `kill <pid>`.',
+].join('\n');
+
+const AWAIT_DESCRIPTION = [
+  'Check or poll a backgrounded shell job. For work that does not have a shell id, you can omit the shell_id arg to sleep for the full `block_until_ms` duration (prefer this over sleeping in the shell). At the end of your turn, you will be notified about any unawaited jobs that completed. If you think a job completed (e.g. because you killed it), observe it with AwaitShell to skip the notification, because stale notifications can confuse the user.',
+  '',
+  'Prefer NOT to poll reflexively with AwaitShell. Multitask on independent work while backgrounded jobs run, or finish your turn and rely on the end-of-turn completion notification. Poll with AwaitShell only when one of the following is true:',
+  "- Your very next step is blocked on this specific job's result and you have no other productive work to do, OR",
+  '- The task requires close monitoring (see shell guidance below).',
+  '- NEVER USE THIS TO POLL OR WAIT VACUOUSLY FOR A SUBAGENT LAUNCHED WITH THE Task TOOL — rely on the end-of-turn completion notification instead (it is delivered as soon as the subagent finishes; guessing a wait time is inefficient).',
+  '- Shell: only poll with AwaitShell when the command requires close monitoring. Close monitoring means a long-running job that can silently hang, degrade, or need a course correction before it completes — e.g. training runs, eval runs, deployments, long builds, datagen pipelines, DB migrations, large data transfers. For fire-and-forget commands (tests, installs, dev servers/watchers, short scripts, etc.) the completion notification is enough — start them, keep working, and only poll with AwaitShell later if you end up blocked on the result.',
+  "- Shell sanity check (regardless of close monitoring): when you spawn a command directly into the background (`block_until_ms: 0`), do a single status check by reading the output file to confirm the command didn't fail to start. This is a one-shot smoke check, not a polling loop.",
+  '- Shell close-monitoring guidance (only applies in the close-monitoring case above):',
+  "  - HARD STOPPING CONSTRAINT: once you've decided to actively poll, don't stop until (a) the job terminates, (b) the command reaches a healthy steady state (only for non-terminating commands, e.g. dev server/watcher), or (c) the command is hung — follow the hang guidance below.",
+  '  - Waiting until a regex matches the output can be useful for e.g. known startup/status/error logs.',
+  "  - Size `block_until_ms` to the command's expected runtime. When waiting further, avoid round 5-minute waits: prefer slices of 60–270s (keeps prompt cache warm) or 1200s+ (one cache miss buys a long wait).",
+  '  - Output file header has `pid` and `running_for_ms` (updated every 5000ms).',
+  '  - When finished, footer with `exit_code` and `elapsed_ms` appears (regex only matches the body, not header/footer).',
+  '  - If the command is taking longer than expected and appears hung (use judgment based on command type), kill the process if safe to do so using the pid in the header. If possible, fix the hang and proceed.',
+].join('\n');
+
+interface AwaitDetails {
+  shellId?: string;
+  sleptMs?: number;
+}
+
+const SUBAGENT_NOTE = 'This subagent stops its background jobs when it finishes, so await any job whose result you need before you finish.';
+
+const clampWait = (value: number | undefined, fallback: number) => Math.min(MAX_AWAIT_MS, Math.max(0, Math.round(value ?? fallback)));
+
+function seconds(ms: number): string {
+  const value = ms / 1000;
+  return Number.isInteger(value) ? `${value}s` : `${value.toFixed(1)}s`;
+}
+
+export function shellNoticeCardText(message: { content: string | { type: string; text?: string }[]; details?: unknown }): string {
+  const notice = message.details as Partial<ShellNotice> | undefined;
+  if (notice?.title === undefined || notice.shellId === undefined) return typeof message.content === 'string' ? message.content : message.content.map((part) => part.text ?? '').join('');
+  const head = `${notice.title} · ${notice.kind === 'progress' ? 'output matched' : notice.status} · shell ${notice.shellId}`;
+  return notice.detail === undefined ? head : `${head}\n${notice.detail}`;
+}
+
+export interface BackgroundShellOptions {
+  terminalsDir: (ctx: ExtensionContext) => string;
+  /** One-shot runs that may wait at settle for their jobs, as Cursor's print mode does: print and JSON runs, not subagents. */
+  waitsForJobs: (ctx: ExtensionContext) => boolean;
+  /** A subagent's jobs end with it. */
+  endsWithTurn: boolean;
+}
+
+/** bash_background and AwaitShell, plus the notifications their jobs send. */
+export function registerBackgroundShell(pi: ExtensionAPI, options: BackgroundShellOptions): { hasRunningJobs: () => boolean } {
+  const pending: ShellNotice[] = [];
+  const arrivals = new Set<() => void>();
+  let mode: ExtensionContext['mode'] | undefined;
+  let retired = false;
+  const deliver = (notice: ShellNotice) => {
+    if (retired) return;
+    if (mode !== undefined && isOneShot(mode)) {
+      pending.push(notice);
+      for (const arrived of [...arrivals]) arrived();
+    } else pi.sendMessage({ customType: SHELL_NOTICE_TYPE, content: noticeText(notice), display: true, details: notice }, { triggerTurn: true, deliverAs: 'followUp' });
+  };
+  const nextArrival = () =>
+    new Promise<void>((done) => {
+      const arrived = () => {
+        arrivals.delete(arrived);
+        done();
+      };
+      arrivals.add(arrived);
+    });
+  const jobs: ShellJobs = createShellJobs(
+    {
+      terminalsDir: options.terminalsDir,
+      shellPath: () => {
+        const value = (pi.getSettings() as { shellPath?: unknown }).shellPath;
+        return typeof value === 'string' && value !== '' ? value.replace(/^~(?=$|\/)/, process.env['HOME'] ?? '~') : undefined;
+      },
+    },
+    deliver,
+  );
+
+  pi.registerMessageRenderer?.(SHELL_NOTICE_TYPE, (message) => new Text(shellNoticeCardText(message), 0, 0));
+  pi.on('session_start', (_event, ctx) => {
+    mode = ctx.mode;
+    retired = false;
+  });
+  // Cursor's print mode holds its exit for background shells and reports each notification as a turn.
+  pi.on('agent_before_settle', async (event, ctx) => {
+    if (!isOneShot(ctx.mode) || event.outcome === 'aborted') return undefined;
+    if (pending.length === 0 && (!options.waitsForJobs(ctx) || jobs.running().length === 0)) return undefined;
+    if (pending.length === 0) await nextArrival();
+    const ready = pending.splice(0);
+    if (ready.length === 0) return undefined;
+    return {
+      entries: [...event.entries, ...ready.map((notice) => ({ type: 'custom_message' as const, customType: SHELL_NOTICE_TYPE, content: noticeText(notice), display: true, details: notice }))],
+      continue: true,
+    };
+  });
+  pi.on('session_shutdown', () => {
+    retired = true;
+    pending.splice(0);
+    for (const arrived of [...arrivals]) arrived();
+    jobs.shutdown();
+  });
+
+  pi.registerTool({
+    name: BACKGROUND_TOOL,
+    label: 'bash (background)',
+    description: BACKGROUND_DESCRIPTION,
+    promptSnippet: 'Run a shell command in the background, with notifications when it finishes or prints a watched line',
+    parameters: BackgroundParams,
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+      const cwd = params.working_directory === undefined || params.working_directory.trim() === '' ? ctx.cwd : resolve(ctx.cwd, params.working_directory);
+      const title = params.description?.trim() || params.command.trim().split('\n')[0]?.slice(0, 80) || params.command;
+      const watch = params.notify_on_output;
+      const job = jobs.start(ctx, {
+        command: params.command,
+        cwd,
+        title,
+        toolCallId,
+        ...(watch === undefined ? {} : { watch: { pattern: watch.pattern, reason: watch.reason, ...(watch.debounce_ms === undefined ? {} : { debounceMs: watch.debounce_ms }) } }),
+      });
+      const blockMs = clampWait(params.block_until_ms, 0);
+      const details = { shellId: job.id, pid: job.pid, outputPath: job.path };
+      const note = options.endsWithTurn ? `\n${SUBAGENT_NOTE}` : '';
+      if (blockMs === 0) return { content: [{ type: 'text', text: `${launchText(job)}${note}` }], details };
+      const deadline = Date.now() + blockMs;
+      while (job.status === 'running' && Date.now() < deadline && signal?.aborted !== true) await jobs.change(job, deadline - Date.now(), signal);
+      if (signal?.aborted === true && job.status === 'running') {
+        jobs.stop(job);
+        throw new Error('The command was stopped because the call was cancelled.');
+      }
+      if (job.status !== 'running') {
+        job.observed = true;
+        return { content: [{ type: 'text', text: finishedText(job.exitCode ?? 1, (job.endedAt ?? Date.now()) - job.startedAt, jobs.output(job), job.path) }], details: { ...details, exitCode: job.exitCode } };
+      }
+      return { content: [{ type: 'text', text: `${movedText(job, blockMs, jobs.output(job))}${note}` }], details };
+    },
+  });
+
+  pi.registerTool({
+    name: AWAIT_TOOL,
+    label: 'AwaitShell',
+    description: AWAIT_DESCRIPTION,
+    promptSnippet: 'Poll or wait for a background shell job, or sleep',
+    parameters: AwaitParams,
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async execute(_toolCallId, params, signal): Promise<{ content: { type: 'text'; text: string }[]; details: AwaitDetails }> {
+      const waitMs = clampWait(params.block_until_ms, DEFAULT_AWAIT_MS);
+      const shellId = params.shell_id?.trim();
+      if (shellId === undefined || shellId === '') {
+        if (waitMs === 0) throw new Error('block_until_ms 0 needs shell_id: it checks one shell without waiting.');
+        const started = Date.now();
+        await sleep(waitMs, signal);
+        return { content: [{ type: 'text', text: `Slept for ${seconds(Date.now() - started >= waitMs ? waitMs : Date.now() - started)}.` }], details: { sleptMs: Date.now() - started } };
+      }
+      const text = await jobs.awaitJob(shellId, waitMs, params.pattern, signal);
+      return { content: [{ type: 'text', text }], details: { shellId } };
+    },
+  });
+
+  return { hasRunningJobs: () => jobs.running().length > 0 };
+}

package/src/index.ts

@@ -5,16 +5,17 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
 import { registerAskQuestion } from './ask.ts';
 import { aliasAutocomplete } from './autocomplete.ts';
+import { registerBackgroundShell } from './background-shell.ts';
 import { childIdentity } from './child-env.ts';
 import { registerGenerateImage } from './generate-image.ts';
 import { registerLoop } from './loop.ts';
 import { registerMode } from './mode.ts';
 import { canAsk, isOneShot } from './modes.ts';
-import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
+import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir, terminalsDir } from './paths.ts';
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
 import { migrateLegacyRule, modelsSection, readRule } from './rule.ts';
-import { alwaysAppliedRules, hostSection, subagentsSection } from './sections.ts';
+import { alwaysAppliedRules, hostSection, subagentsSection, todayText } from './sections.ts';
 import { registerSubscriptions } from './subscriptions/index.ts';
 import { type AgentDefinition, loadAgentDefinitions } from './task/agents.ts';
 import { registerAgentStatus } from './task/status.ts';
@@ -39,6 +40,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
   const activeTools = pi.getActiveTools();
   return {
     pstack_host: hostSection({
+      today: todayText(new Date()),
       packageRoot: PACKAGE_ROOT,
       skillsDir: SKILLS_DIR,
       skillNames: packageSkillNames(pi.getCommands()),
@@ -51,6 +53,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
       rootStoreDir: rootStoreDir(ctx.cwd, ctx.sessionManager.getSessionId(), childIdentity.rootStore),
       projectsDir: projectsDir(ctx.cwd),
       artifactsDir: artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()),
+      terminalsDir: terminalsDir(ctx.cwd),
       loopAvailable: !isOneShot(ctx.mode),
       questionsAvailable: canAsk(ctx),
       activeTools,
@@ -122,7 +125,15 @@ export default function piPstack(pi: ExtensionAPI): void {
       return undefined;
     },
   });
-  const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
+  // A readonly agent's shell is the sandboxed one, and a background job would run outside that sandbox.
+  const shells = childIdentity.readonly
+    ? undefined
+    : registerBackgroundShell(pi, {
+        terminalsDir: (ctx) => terminalsDir(ctx.cwd),
+        waitsForJobs: (ctx) => childIdentity.depth === 0 && (ctx.mode === 'print' || ctx.mode === 'json'),
+        endsWithTurn: childIdentity.depth > 0,
+      });
+  const loop = registerLoop(pi, { hasPendingWork: () => task.hasBackgroundWork() || shells?.hasRunningJobs() === true });
   const todos = registerTodoWrite(pi, childIdentity.readonly ? {} : { onWrite: plan.syncTodos });
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);

package/src/linux-readonly-sandbox.ts

@@ -0,0 +1,121 @@
+// The Linux read-only sandbox: bubblewrap with every namespace unshared, the whole filesystem bound read-only, and a
+// seccomp filter that refuses Unix sockets. bubblewrap installs the filter itself, so this needs no nested user
+// namespace, which hosts with kernel.apparmor_restrict_unprivileged_userns=1 (Ubuntu 24.04 and later) refuse.
+import { spawnSync } from 'node:child_process';
+import { accessSync, closeSync, constants, existsSync, mkdtempSync, openSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+const LD_ABS_W = 0x20;
+const JEQ_K = 0x15;
+const JGE_K = 0x35;
+const RET_K = 0x06;
+const SECCOMP_RET_ALLOW = 0x7fff_0000;
+const SECCOMP_RET_ERRNO_EPERM = 0x0005_0001;
+const SECCOMP_RET_KILL_PROCESS = 0x8000_0000;
+const X32_SYSCALL_BIT = 0x4000_0000;
+const AF_UNIX = 1;
+
+const ARCHES: Record<string, { audit: number; socket: number; ioUringSetup: number }> = {
+  x64: { audit: 0xc000_003e, socket: 41, ioUringSetup: 425 },
+  arm64: { audit: 0xc000_00b7, socket: 198, ioUringSetup: 425 },
+};
+
+const instruction = (code: number, jt: number, jf: number, k: number): Buffer => {
+  const bytes = Buffer.alloc(8);
+  bytes.writeUInt16LE(code, 0);
+  bytes.writeUInt8(jt, 2);
+  bytes.writeUInt8(jf, 3);
+  bytes.writeUInt32LE(k >>> 0, 4);
+  return bytes;
+};
+
+/**
+ * A classic BPF seccomp program: socket(AF_UNIX, ...) and io_uring_setup fail with EPERM, any other architecture or
+ * the x32 ABI kills the process, and everything else is allowed. Jumps are relative to the next instruction.
+ */
+export function seccompFilter(arch: string): Buffer {
+  const target = ARCHES[arch];
+  if (target === undefined) throw new Error(`the read-only shell has no seccomp filter for ${arch}`);
+  return Buffer.concat([
+    instruction(LD_ABS_W, 0, 0, 4), // 0: architecture
+    instruction(JEQ_K, 0, 8, target.audit), // 1: native → 2, otherwise → 10
+    instruction(LD_ABS_W, 0, 0, 0), // 2: syscall number
+    instruction(JGE_K, 6, 0, X32_SYSCALL_BIT), // 3: x32 → 10
+    instruction(JEQ_K, 0, 2, target.socket), // 4: socket → 5, otherwise → 7
+    instruction(LD_ABS_W, 0, 0, 16), // 5: low word of the first argument, the domain
+    instruction(JEQ_K, 2, 1, AF_UNIX), // 6: AF_UNIX → 9, otherwise → 8
+    instruction(JEQ_K, 1, 0, target.ioUringSetup), // 7: io_uring_setup → 9, otherwise → 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ALLOW), // 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ERRNO_EPERM), // 9
+    instruction(RET_K, 0, 0, SECCOMP_RET_KILL_PROCESS), // 10
+  ]);
+}
+
+const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+
+/** bubblewrap's arguments before the command: nothing is writable and nothing outside is reachable. */
+export function bwrapArgs(cwd: string): string[] {
+  return ['--new-session', '--die-with-parent', '--unshare-all', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--cap-drop', 'ALL', '--chdir', cwd, '--seccomp', '3'];
+}
+
+interface Sandbox {
+  bwrap: string;
+  filterPath: string;
+  shell: string;
+}
+
+/** The first executable `name` on PATH, so every command runs the bubblewrap the check ran. */
+function onPath(name: string): string | undefined {
+  for (const dir of (process.env['PATH'] ?? '').split(delimiter).filter((entry) => entry !== '')) {
+    const candidate = join(dir, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Not here; keep looking.
+    }
+  }
+  return undefined;
+}
+
+let verified: { sandbox: Sandbox } | { error: Error } | undefined;
+
+/** The checked sandbox, or the error that stopped it; either is kept, so a failed host never retries into a weaker state. */
+function verifiedSandbox(): Sandbox {
+  verified ??= (() => {
+    try {
+      return { sandbox: checkSandbox() };
+    } catch (error) {
+      return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  })();
+  if ('error' in verified) throw verified.error;
+  return verified.sandbox;
+}
+
+/** Writes the filter into a private directory and checks that bubblewrap can load it here. */
+function checkSandbox(): Sandbox {
+  const filter = seccompFilter(process.arch);
+  const bwrap = onPath('bwrap');
+  if (bwrap === undefined) throw new Error('bubblewrap (bwrap) is not available: no bwrap on PATH');
+  const dir = mkdtempSync(join(tmpdir(), 'pi-pstack-ro-'));
+  const filterPath = join(dir, 'unix-block.bpf');
+  writeFileSync(filterPath, filter, { mode: 0o400 });
+  const shell = existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh';
+  const fd = openSync(filterPath, 'r');
+  try {
+    const probe = spawnSync(bwrap, [...bwrapArgs('/'), '--', shell, '-c', 'exit 0'], { stdio: ['ignore', 'ignore', 'pipe', fd], encoding: 'utf8', timeout: 15_000 });
+    if (probe.error !== undefined) throw new Error(`bubblewrap (bwrap) could not run: ${probe.error.message}`);
+    if (probe.status !== 0) throw new Error(`bubblewrap could not start the read-only sandbox: ${probe.stderr.trim() || `exit ${probe.status}`}`);
+  } finally {
+    closeSync(fd);
+  }
+  return { bwrap, filterPath, shell };
+}
+
+/** The shell command that runs `command` inside the read-only sandbox, or an error when no sandbox can start. */
+export function linuxReadonlyCommand(command: string, cwd: string): string {
+  const { bwrap, filterPath, shell } = verifiedSandbox();
+  return `exec ${quote(bwrap)} ${bwrapArgs(cwd).map(quote).join(' ')} -- ${quote(shell)} -c ${quote(command)} 3< ${quote(filterPath)}`;
+}

package/src/loop.ts

@@ -258,7 +258,7 @@ function registerLoopTool(pi: ExtensionAPI, registry: LoopRegistry): void {
     name: 'Loop',
     label: 'Loop',
     description:
-      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
+      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Run the prompt once yourself in the turn that arms the loop; the first scheduled run comes after the interval or wake_in. Then confirm the interval, that the prompt already ran once, and when the first run comes. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
     promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
     parameters: LoopParams,
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },

package/src/paths.ts

@@ -75,6 +75,11 @@ export function artifactsDir(cwd: string, sessionId: string): string {
   return join(workspaceStateDir(cwd), 'artifacts', sessionId);
 }
 
+/** Background shell jobs' output files, `<shell id>.txt`, as Cursor keeps them in a workspace's terminals folder. */
+export function terminalsDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'terminals');
+}
+
 export function worktreesDir(cwd: string): string {
   return join(workspaceStateDir(cwd), 'worktrees');
 }

package/src/readonly-shell.ts

@@ -2,12 +2,14 @@ import { existsSync } from 'node:fs';
 
 import type { SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
 import { type BashSpawnContext, createBashTool, type ExtensionAPI, type ExtensionToolContext, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { linuxReadonlyCommand } from './linux-readonly-sandbox.ts';
 
 // Cursor's readonly subagent: "no file edits, no state-changing shell commands". The OS sandbox enforces it:
 // nothing may be written and no host may be reached, so a pipe, substitution, or pager cannot get around it.
+// Linux uses bubblewrap directly (linux-readonly-sandbox.ts); macOS uses sandbox-runtime's Seatbelt policy below.
 // denyWrite names the paths the sandbox makes writable for itself (/tmp/claude is a dependency default), and
 // denyRead drops the dependency's writable home defaults (~/.npm/_logs, ~/.claude/debug). Seatbelt is
-// last-match-wins with deny emitted after allow; on Linux bubblewrap binds deny last the same way.
+// last-match-wins with deny emitted after allow.
 // Unix sockets must stay blocked too: a host service can mutate files on a command's behalf.
 const READ_ONLY_POLICY: SandboxRuntimeConfig = {
   network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: false },
@@ -29,7 +31,7 @@ type Sandbox = typeof import('@anthropic-ai/sandbox-runtime')['SandboxManager'];
 let ready: Promise<Sandbox> | undefined;
 
 /**
- * Starts the sandbox once per process, loading it only in a readonly subagent: a local package install gets no
+ * Starts sandbox-runtime once per process, loading it only in a readonly subagent: a local package install gets no
  * dependency install, and everything else in the package works without it. A failure is kept, so no command ever
  * runs outside the sandbox.
  */
@@ -73,11 +75,7 @@ export function createReadonlyBashTool(name = 'bash'): ToolDefinition<BashParame
     description: `${base.description}${NOTE}`,
     async execute(toolCallId, params, signal, onUpdate, ctx: ExtensionToolContext) {
       // Fail closed: when the sandbox cannot start, the call fails here and nothing spawns.
-      const sandbox = await sandboxReady();
-      // The per-command policy re-states READ_ONLY_POLICY, so the command never inherits a policy another
-      // consumer left on the shared manager. Wrapping honors abort, and Pi's own shell operations then enforce
-      // the pre-spawn abort check, timeouts, and process-tree cleanup.
-      const command = await sandbox.wrapWithSandbox(params.command, undefined, READ_ONLY_POLICY, signal);
+      const command = process.platform === 'linux' ? linuxCommand(params.command, ctx.cwd) : await wrapped(params.command, signal);
       const bash = createBashTool(ctx.cwd, {
         ...(existsSync('/bin/bash') ? { shellPath: '/bin/bash' } : {}),
         spawnHook: (spawn: BashSpawnContext) => ({ ...spawn, command, env: strippedEnv(spawn.env) }),
@@ -87,10 +85,25 @@ export function createReadonlyBashTool(name = 'bash'): ToolDefinition<BashParame
   };
 }
 
+function linuxCommand(command: string, cwd: string): string {
+  try {
+    return linuxReadonlyCommand(command, cwd);
+  } catch (error) {
+    throw new Error(`no verified OS sandbox is available: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 /**
- * Releases the sandbox if it started. On Linux the sandbox's socat bridges keep the event loop alive, so a process
- * that used the shell never exits unless the sandbox is released.
+ * The per-command policy re-states READ_ONLY_POLICY, so the command never inherits a policy another consumer left on
+ * the shared manager. Wrapping honors abort, and Pi's own shell operations then enforce the pre-spawn abort check,
+ * timeouts, and process-tree cleanup.
  */
+async function wrapped(command: string, signal: AbortSignal | undefined): Promise<string> {
+  const sandbox = await sandboxReady();
+  return sandbox.wrapWithSandbox(command, undefined, READ_ONLY_POLICY, signal);
+}
+
+/** Releases sandbox-runtime if it started, so a process that used the shell can exit. */
 export async function releaseReadonlySandbox(): Promise<void> {
   const started = ready;
   ready = undefined;

package/src/sections.ts

@@ -6,6 +6,8 @@ import type { AgentDefinition } from './task/agents.ts';
 import { type AvailableModel, type ModelSpec, modelLabel } from './task/models.ts';
 
 export interface HostFacts {
+  /** Today's date as Cursor states it in its user info, such as "Wednesday Nov 4, 2026". */
+  today: string;
   packageRoot: string;
   skillsDir: string;
   skillNames: readonly string[];
@@ -18,6 +20,8 @@ export interface HostFacts {
   rootStoreDir: string;
   projectsDir: string;
   artifactsDir: string;
+  /** Background shell jobs' output files. */
+  terminalsDir: string;
   /** False in print and JSON runs, including subagents, which exit when they settle. */
   loopAvailable: boolean;
   /** False when nobody can answer a dialog (print and JSON runs, including subagents). */
@@ -29,7 +33,9 @@ export interface HostFacts {
 }
 
 const LOOP_LINE =
-  '- /loop: the user starts `/loop [interval] <prompt>`. When a playbook says to arm /loop, call the Loop tool with prompt plus interval (fixed cadence) or wake_in (agent-paced). Inside a loop, Loop with wake_in schedules the next run and stop: true ends it.';
+  '- /loop: the user starts `/loop [interval] <prompt>`. When a playbook says to arm /loop, run the prompt once now, in this turn, then call the Loop tool with prompt plus interval (fixed cadence) or wake_in (agent-paced); its first scheduled run comes after that interval or wake. Inside a loop, Loop with wake_in schedules the next run and stop: true ends it.';
+const EVENT_LOOP_SENTENCE =
+  " When the next run waits on an event (CI finishing, a ref advancing, a log line), start a watcher with bash_background that exits, or prints a line its notify_on_output pattern matches, when the event fires, and keep a long wake_in as the fallback heartbeat: the watcher's notification wakes you.";
 const NO_LOOP_LINE =
   '- /loop: this run ends when it settles (a subagent, or a print or JSON run), so it has no Loop tool and cannot arm a loop. Keep working until the goal is met, and name in the final reply anything the parent chat should loop on.';
 
@@ -52,6 +58,14 @@ export function alwaysAppliedRules(skillsDir: string): string[] {
   return bodies;
 }
 
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** The local date in Cursor's user-info form: weekday, short month, day, year. */
+export function todayText(date: Date): string {
+  return `${WEEKDAYS[date.getDay()]} ${MONTHS[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
+}
+
 const TASK_PARAMS = 'description, prompt, subagent_type, model, readonly, run_in_background, resume, fork, fork_turns, environment, cloud_base_branch, file_attachments';
 
 function todoLine(facts: HostFacts): string {
@@ -79,7 +93,7 @@ function agentToolsLine(tools: readonly string[]): string[] {
 export function hostSection(facts: HostFacts): string {
   const transcript = facts.sessionFile === undefined ? 'This chat is not persisted (--no-session), so it has no transcript file.' : `This chat's transcript is ${facts.sessionFile}.`;
   return [
-    `pstack runs here through the pi-pstack package at ${facts.packageRoot}.`,
+    `pstack runs here through the pi-pstack package at ${facts.packageRoot}. Today's date: ${facts.today}.`,
     `- <SKILLS> = ${facts.skillsDir}. "the X skill", "/X", and "principle-X" mean <SKILLS>/X/SKILL.md, even for skills hidden from automatic invocation; a delegate that needs poteto-mode reads <SKILLS>/poteto-mode/SKILL.md. Installed skills (${facts.skillNames.length}): ${facts.skillNames.join(', ')}.`,
     '- A <skill> block in a user message means the user attached that skill to this request. Follow its workflow from its first step, including the steps it says to take before answering, instead of answering directly.',
     `- Skill folders: project \`.pi/skills/\`, personal \`${join(facts.agentDir, 'skills')}/\`.`,
@@ -95,7 +109,12 @@ export function hostSection(facts: HostFacts): string {
     `- Files a tool makes for the user, such as visualize charts, go in ${facts.artifactsDir}.`,
     facts.loopAvailable ? SUBSCRIPTIONS_LINE : NO_SUBSCRIPTIONS_LINE,
     ...agentToolsLine(facts.activeTools),
-    facts.loopAvailable ? LOOP_LINE : NO_LOOP_LINE,
+    facts.loopAvailable ? `${LOOP_LINE}${facts.activeTools.includes('bash_background') ? EVENT_LOOP_SENTENCE : ''}` : NO_LOOP_LINE,
+    ...(facts.activeTools.includes('bash_background')
+      ? [
+          `- Background shells: bash_background runs a command in the background, or moves it there after block_until_ms, and writes its output to ${facts.terminalsDir}/<shell id>.txt. The first lines of that file hold pid, cwd, command, title, status, and running_for_ms (\`head -n 10 *.txt\` there lists every job), and a footer with exit_code appears when the command ends. A notification wakes you after your turn when a job finishes and on each notify_on_output match; AwaitShell polls or waits. Stop a job with \`kill <pid>\`. bash waits for its command to finish and never moves it to the background, so start anything that can run for minutes (a watcher, a polling script such as watch-pr without --status-only, a dev server) with bash_background.`,
+        ]
+      : []),
     facts.activeTools.includes('GenerateImage')
       ? '- Image generation: the GenerateImage tool, which saves each image to the artifacts folder below and shows it in its result.'
       : '- Image generation: no image model is configured, so this session has no GenerateImage tool. Say so and use a mermaid diagram or a table instead.',