@bastani/atomic 0.9.19-alpha.2 → 0.9.19-alpha.4

package/docs/development.md

@@ -8,15 +8,10 @@ See [AGENTS.md](https://github.com/bastani-inc/atomic/blob/main/AGENTS.md) for a
 git clone https://github.com/bastani-inc/atomic
 cd atomic
 npm ci --ignore-scripts
-npm run typecheck
+npm run build
 ```
 
-This monorepo runs a hybrid toolchain matching upstream pi: npm installs, builds, checks, and runs the vitest suites, while Bun compiles the release binaries and runs `scripts/*.ts`. Avoid yarn and pnpm. Run package scripts from the monorepo root or a package directory, for example:
-
-```bash
-npm run test:unit
-npm run build --workspace=@bastani/atomic
-```
+Use npm for installs, builds, checks, and Vitest suites. Bun compiles standalone binaries and runs repository TypeScript scripts. Do not use yarn, pnpm, or `bun install`.
 
 Atomic keeps the caller's current working directory when launched from development wrappers.
 
@@ -33,7 +28,7 @@ Configure via `package.json`:
 }
 ```
 
-Change `name`, `configDir`, and the `bin` field for your fork. The app-specific `<appName>Config` key is preferred; legacy `piConfig` remains a backwards-compatible shim. Atomic sets these to `atomic`, `.atomic`, and the `atomic` executable. Affects CLI banner, config paths, and environment variable names.
+Change `name`, `configDir`, and the `bin` field for your fork. These control the CLI banner, config paths, and environment variable names. Legacy `piConfig` remains a compatibility fallback.
 
 ## Path Resolution
 
@@ -53,88 +48,42 @@ Never use `__dirname` directly for package assets.
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 
-## Startup timing probes
-
-Use `scripts/perf/windows-startup/benchmark.ts` for Windows startup claims. It launches the ordinary bare `atomic` command through a real 120x40 ConPTY, feeds ordered output into `@xterm/headless`, and timestamps each receive with `process.hrtime.bigint()`. Complete first paint requires the final `Atomic v<version>` identity, the focused `❯ ` editor, and two identical settled frames at least one 80 ms animation interval apart. `dispatchMs` runs from the Enter write to the first byte observed by a raw TCP loopback provider. The headline `spawnToDispatchMs` is exactly `startupCompleteMs + dispatchMs`; `launchToProviderFirstByteMs` separately retains the contiguous launch-to-provider interval that also contains nonce typing and editor-echo wait. The provider request must contain the nonce and the normal tool schemas, and every accepted sample must pass `/workflow list` after the timed response. See [the benchmark README](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md) for artifact preparation, cache profiles, raw records, and summary commands.
-
-Do not use `time-to-first-frame` as settled-paint evidence, and do not substitute `launchToProviderFirstByteMs` for the contract sum. The first-frame mark records the host's first requested identity frame after the header is mounted; it does not prove terminal receipt, animation settlement, engine resource readiness, or provider readiness. `ATOMIC_STARTUP_BENCHMARK=1`, `--no-extensions`, and `--no-tools` are attribution controls only. They do not run the accepted full CLI path with bundled workflows, normal extensions, tools, and provider dispatch.
-
-The process-local lifecycle timing seams use monotonic nanoseconds and remain disabled until an internal diagnostic adapter installs a synchronous sink. With no sink, they do not read the clock, write output, or schedule work. External ConPTY and TCP marks remain authoritative. Startup now has several deliberate partial orders rather than one cross-process sequence:
-
-```text
-interactive host: process-entry → interactive-engine-spawn → engine-ready
-                  → tui-start → header-mounted → initialize engine-bound state
-                  → chat-output-release → interactive-input-handler-ready
-
-isolated child:   process-entry → engine-ready → engine-bound
-                  → engine-resources-ready
-
-external screen:  first-terminal-write → startup-coherent → startup-complete
-
-first turn:       interactive-first-submit → before-provider-request
-```
-
-The header and editor are mounted before the host waits for `engine-bound`; the child can therefore report binding while the host is applying its theme or requesting that frame. `engine-bound` means RPC control plus the mandatory minimal session are available. `engine-resources-ready` is a separate, generation-scoped child message sent only after a staged optional snapshot containing bundled extensions, tools, providers, skills, prompts, and themes commits. User prompts, extension commands, model/resource commands, session replacement, and tool-dispatching RPC calls wait for that gate. After a readiness failure, `/reload` bypasses the rejected gate to start a fresh transactional attempt; successful retry replaces the gate before later work proceeds. Escape cancels a first submission that is still waiting, so that continuation cannot dispatch later. `session_start` messages are queued against the candidate snapshot and released only after publication. Mandatory Intercom remains in the minimal runtime. A failed transactional candidate leaves host-managed settings, providers, tools, resources, event subscriptions, and system-prompt state unchanged, restores an unadmitted prompt draft exactly, and reports the generation failure once. Extension-owned objects stored with `sessionScopedExtensionState` are deliberately shared across reloads and are not cloned or rolled back.
-
-`engine-resources-ready` is recorded in the isolated engine process; host marks are recorded in the interactive process. The two process clocks are monotonic but must not be subtracted without an external synchronization protocol. `startup-coherent` and `startup-complete` describe internal render composition, not terminal receipt. The external VT predicates decide the reported first-paint marks.
-
-For package-manager installs under Node 22, Atomic enables Node's persistent module compile cache in both the host and isolated child and flushes the host cache before spawning the child. Explicit `NODE_COMPILE_CACHE` and `NODE_DISABLE_COMPILE_CACHE` settings pass through unchanged. This preserves Node's coverage opt-out and avoids forcing a new cache directory or a first-run-only precompile step. SEA, V8 snapshots, and package-install precompilation were not adopted because Atomic's dynamic ESM, native modules, workers, and first-run requirements do not provide a safe portable boundary.
-
-Compiled releases syntax-minify the shared CJS `app.js` sidecar without identifier minification and compile launchers with bytecode on all eight supported targets, including Windows x64 and ARM64. `bun run scripts/probe-windows-bytecode.ts` pins Bun 1.4.2, cross-compiles `bun-windows-x64-baseline` and `bun-windows-arm64` launchers, and verifies their PE machine types. Atomic observed a Bun 1.3.14 Windows startup crash in `llint_entry`, but Bun 1.4.0 already contains the embedded-bytecode alignment fix ([#26299](https://github.com/oven-sh/bun/pull/26299)) and integrity fallback ([#31961](https://github.com/oven-sh/bun/pull/31961)); the separate Bun 1.4.0 Windows report ([#40302](https://github.com/oven-sh/bun/issues/40302)) concerns a general standalone/JIT segfault and has not been shown to be bytecode-specific. Cross-compilation is not runtime validation: release candidates still require full-archive target-machine coverage of the TUI, workflows, tools, extensions, workers, and native add-ons, with Windows ARM64 validated on ARM64 hardware.
-
-Set `ATOMIC_TIMING=1` only for the older human-readable phase diagnostics. Normal interactive launches print that initial timing group before `interactiveMode.run()` starts the TUI loop, so later marks are not printed during ordinary sessions.
+For startup measurements, see the [Windows startup benchmark](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md). Internal timing marks do not prove terminal first paint.
 
 ## Testing
 
 ```bash
-npm run typecheck                 # Type-check the monorepo
-npm run test:unit                 # Run unit tests
-npm run test:integration          # Run integration tests
-npm run test:all                  # Run all tests
-npm run test:scripts              # Run the repository script tests under node --test
-# Run the package Vitest suite (Node-hosted)
+npm run check                    # Typechecks and published-shrinkwrap validation
+npm run test:unit                # Root unit tests
+npm run test:integration         # Root integration tests
+npm run test:all                 # All root test projects
+npm run test:scripts             # Repository script tests under Node
 npm run test --workspace=@bastani/atomic -- test/specific.test.ts
 ```
 
-Root Vitest projects install a fresh in-memory durable backend before every test.
-Durability initialization imports the backend and its process owner rather than
-preloading the DBOS factory or the Atomic host. A test that needs host prototype
-installers must import those real modules explicitly rather than depend on a
-side effect of shared setup. Test-local backend overrides still use the factory's
-injection seam, and the next test receives a fresh backend without resetting
-unrelated initialization or warning state. Keep the global artifact/native setups,
-default isolation, worker sizing and timeout budgets unchanged when measuring
-test cost. See the [CI measurements](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#current-critical-path-measured-september-5-2026)
-for local gains and the remaining hosted Linux/Windows validation.
-
-CI runs the complete root unit and integration suites in independent Linux and
-Windows jobs. Each builds its own native and package prerequisites; both required
-result gates wait for every work job and reject failures, cancellations and skips.
-This trades duplicated setup for earlier integration feedback without changing
-test isolation, coverage or retries.
+CI runs root unit and integration suites on Linux and Windows. See [CI documentation](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md) for job details and release procedures.
 
-## Deterministic installs
+### Installed package smoke test
 
-`@bastani/atomic` ships `packages/coding-agent/npm-shrinkwrap.json` so package-manager installs resolve the same dependency tree every time. Contributors working from a source checkout can validate that the checked-in shrinkwrap is up to date with:
+After building, run:
 
 ```bash
-bun run scripts/generate-coding-agent-shrinkwrap.mjs --check
+ATOMIC_REQUIRE_INSTALLED_NODE_SMOKE=1 npx vitest --run --project integration test/integration/installed-package-node-extensions.test.ts
 ```
 
-After updating dependencies, run `npm ci --ignore-scripts` and `npm audit`, regenerate the published tree with `npm run shrinkwrap:coding-agent`, and run `npm run check`. Audit the development tree as well as production dependencies. Keep the Vitest packages on the same patched 4.x release; updating only its mocker to 5.x does not preserve the runner contract. Compare shared provider SDK pins with upstream Pi, but retain exact versions required by the installed Pi packages rather than assuming Pi's current source manifests match its published packages.
-
-## Release security boundary
+This checks Node startup and builtin extension loading outside the checkout.
 
-Atomic's release bases remain at the `0.0.0` placeholder. `scripts/cut-release.ts` stamps the real version only on a detached tagged release commit. Tag creation runs an inert signal workflow; a separate `workflow_run` publisher loaded from protected `main` validates the exact upstream repository, source workflow/event/run, tag/SHA, immutable release-base trailers, and deterministic release tree. The privileged trigger checks out only protected workflow code: it treats the tag tree as data, exports it only after deterministic verification, and makes every read-only build verify the protected job's source checksum instead of checking out tag-selected code. Same-run artifact transport failures receive at most one retry after partial-download cleanup and still fail explicitly on the second error; verified source archives are streamed to tar over stdin for portable Windows drive-letter handling. Preparation restores the digest-verified source after documentation validation before producing artifacts. Release-source jobs configure no dependency cache, npm publication has OIDC without repository write, and GitHub Release creation has repository write without OIDC. Never move or recreate a failed release tag or dispatch the privileged publisher. See the repository's [CI/CD pipeline](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#release-pipeline) for trusted-publisher configuration.
+Atomic ships an npm shrinkwrap. After dependency changes, regenerate it with `npm run shrinkwrap:coding-agent` and validate with `npm run check`.
 
 ## Project Structure
 
-```
+```text
 packages/
-  coding-agent/ # Atomic CLI, agent loop, providers, TUI, and core runtime
-  workflows/    # First-party workflow extension bundled into Atomic
-  subagents/    # Built-in subagent orchestration and reusable agents
-  mcp/          # Built-in MCP adapter extension
-  web-access/   # Built-in web search and content extraction tools
-  intercom/     # Built-in cross-session coordination channel
+  ai/           # Atomic's LLM provider fork
+  coding-agent/ # CLI, interactive mode, and core runtime
+  workflows/    # Workflow execution
+  subagents/    # Subagent orchestration
+  mcp/          # MCP adapter
+  web-access/   # Web search and content extraction
+  intercom/     # Cross-session coordination
 ```

package/docs/docs.json

@@ -17,6 +17,7 @@
           "index",
           "quickstart",
           "usage",
+          "computer-use",
           "providers",
           "environment-variables",
           "llama-cpp",

package/docs/extensions.md

@@ -248,6 +248,8 @@ export default function (pi: ExtensionAPI) {
 
 Editable user, project, and package extensions and user workflows are loaded through [jiti](https://github.com/unjs/jiti), so TypeScript works without compilation. `/reload` uses content-hash invalidation across the complete imported file graph: an unchanged graph can reuse its evaluated factory, while a direct edit or a transitive dependency edit re-evaluates that extension's modules.
 
+Imports from Atomic's supplied core packages keep the running host's classes and shared state across `/reload`, including on Windows. The supported `@earendil-works/pi-coding-agent` compatibility import shares those exports with `@bastani/atomic`, so class comparisons and `instanceof` checks work across both names after reload. Edits to your extension and its imported local helpers still take effect; restart Atomic after updating Atomic itself.
+
 In Bun compiled or bundled single-file builds, Atomic's five fixed installed builtin extension bundles (workflows, subagents, MCP, web access, and Intercom) take a separate startup path. Atomic installs its live host-module bridge, imports each precompiled bundle natively once, and reuses the evaluated factory across `/reload`. This avoids jiti source reads, transforms, hashing, and graph manifests for immutable shipped code. A builtin bundle's module-scoped state is therefore **not** re-evaluated by `/reload` in those builds. This optimization is limited to exact installed entries of identity-verified Atomic packages; editable extensions and workflows retain the dynamic behavior above.
 
 If the factory returns a `Promise`, Atomic awaits it before continuing startup. That means async initialization completes before `session_start`, before `resources_discover`, and before provider registrations queued via `pi.registerProvider()` are flushed.
@@ -1072,7 +1074,7 @@ The workflows extension registers a publisher on activation and publishes this a
 | `workflow_stage_completed` | `WorkflowStageCompletedEvent`: the lifecycle envelope with a stage target whose status is `completed`. Shares the lifecycle event ID and cursor. Failed, skipped, cancelled, and killed outcomes do not produce this hook. |
 | `workflow_heartbeat` | `WorkflowHeartbeatEvent`: run/root/owner identity, `scheduledAt`, and `intervalMinutes`. Observation only, with no scheduler or cadence change. |
 
-Run control actions describe the caller's request: an already-aborted caller signal still emits `kill` after run registration, and a whole-run interrupt at a task-result checkpoint emits `interrupt` even though graceful suspension retains the existing paused outcome and `exitReason: "quit"`. A control event alone does not mean execution has drained.
+Run control actions describe the caller's request: an already-aborted caller signal still emits `kill` after run registration, and a whole-run pause at a task-result checkpoint emits `pause` while graceful suspension retains the paused outcome and `exitReason: "quit"`. A control event alone does not mean execution has drained.
 
 Use `ctx.observeWorkflowActivity` for status consumers. Registration captures a snapshot atomically with attaching the observer. Delivery is asynchronous, snapshot first, then FIFO updates. Each callback finishes before the next callback for that observer starts; a slow observer does not delay the publisher or other observers.
 
@@ -1197,6 +1199,8 @@ const response = await ctx.modelRegistry.complete(
 
 Use `getApiKeyAndHeaders()` only when an extension must inspect auth before dispatch; normal requests do not need to resolve or overlay auth themselves.
 
+OpenRouter Chat Completions and Anthropic Messages requests send `x-session-id` by default when `sessionId` is supplied and prompt caching is enabled. Set the model's `compat.sendSessionAffinityHeaders` to `false` to opt out, or set `cacheRetention: "none"` on the request to disable cache-related affinity. Explicit request headers override generated headers.
+
 `await ctx.modelRegistry.refresh(options)` returns `{ aborted, errors }`, not just completion. `errors` is a per-provider map, so extensions can report partial refresh failures; `aborted` reports cancellation. Host integrations that call `ModelRuntime.setRuntimeApiKey(providerId, apiKey, options)` must note that it records the runtime credential but does not refresh the catalog; call `refresh({ providers: [providerId], signal })` explicitly when a fresh catalog is needed.
 
 `ctx.scopedModels` is the read-only list of models scoped to the current session — the same set the `/scoped-models` command shows. It is resolved from the `--models` CLI flag and the `enabledModels` setting, matched against the available catalogue. It is empty when no scoping is configured, meaning every available model is usable. Each entry is `{ model, thinkingLevel? }`, where `thinkingLevel` is set only when a pattern pinned it (for example `anthropic/*:high`). Use it to populate a model picker that mirrors the built-in one instead of enumerating the whole catalogue.
@@ -2234,6 +2238,8 @@ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 
 ### Tool Definition
 
+`parameters` is required, including for no-argument tools (use `Type.Object({})`). Registration rejects missing, null, array, and primitive schema values before they can break a provider request. This checks the schema container, not its JSON Schema `type`: object-valued union and non-object-type schemas remain accepted and unchanged.
+
 ```typescript
 import { Type } from "typebox";
 import { StringEnum } from "@bastani/atomic";
@@ -2364,6 +2370,14 @@ pi.registerTool({
 });
 ```
 
+### Fireworks deferred tool loading
+
+Extensions making requests directly through `@bastani/pi-ai` can use native deferred tool loading with Fireworks `anthropic-messages` models. Supply the tool definitions in `context.tools` and record newly loaded tool names in the loader result's `addedToolNames` field. The provider serializes deferred definitions with `defer_loading` and inserts `tool_reference` content at the load point.
+
+Name the loader `ToolSearch` or `tool_search` to keep deferred schemas out of the initial prompt prefix. Other names work, but Fireworks includes the schemas in the prefix and loses that cache benefit. Fireworks GLM models and Kimi K3 still use Chat Completions; this feature does not change their routing.
+
+This is an AI SDK capability. Atomic's `pi.setActiveTools()` updates the active tool list but does not automatically populate `addedToolNames`. See the [AI SDK deferred tool-loading guide](https://github.com/bastani-inc/atomic/blob/main/packages/ai/README.md#fireworks-deferred-tools) for details.
+
 ### Overriding Built-in Tools
 
 Extensions can override built-in tools (`read`, `bash`, `powershell`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`) by registering a tool with the same name. Interactive mode displays a warning when this happens.

package/docs/herdr.md

@@ -1,55 +1,32 @@
 # Herdr
 
-Atomic includes a built-in Herdr reporter. In an eligible pane it reports agent, subagent, extension approval, and observed workflow activity using source `custom:atomic` and agent label `atomic`. No community extension is required.
+Atomic reports its status to [Herdr](https://herdr.dev) automatically when you launch it in a Herdr pane. No extra extension is required. The pane identifies the agent as `atomic`.
 
-## Prerequisites and environment
+For interactive terminal automation, pane isolation, and tool fallbacks, see [Computer use](/computer-use#terminal-automation-with-herdr). This page covers Atomic's automatic status integration.
 
-The CLI contract is based on Herdr **0.8.2, protocol 20**. Launch Atomic in a Herdr pane whose environment includes:
+## Setup
 
-| Variable | Required value |
-|---|---|
-| `HERDR_ENV` | Exactly `1` |
-| `HERDR_BIN_PATH` | Nonempty path to Herdr's executable CLI wrapper |
-| `HERDR_PANE_ID` | Nonempty owning pane ID |
-| `HERDR_SOCKET_PATH` | Nonempty server socket path |
-
-The reporter captures these values on activation, not at module import. It runs only when the extension context has `mode: "tui"` and `hasUI: true`. Print, JSON, RPC, no-UI, workflow-stage, and subagent contexts never claim a pane merely because they inherited its environment. Missing prerequisites, disabled reporting, or ineligible contexts create no reporter timer, subprocess, or workflow observation lease.
-
-## States and reasons
-
-The reporter uses interactive `input`, `agent_start`, `agent_settled`, `ui_prompt_start`, `ui_prompt_end`, live `workflow_lifecycle` events, the owning session's task subscription, and its `observeWorkflowActivity` stream. It does not infer execution from screen text or use `agent_end` as the idle boundary.
-
-Quiet work is still work: waiting for a provider response, tool completion, retry backoff, or another automatic continuation does not become `idle` because output stops. Repeated output-cap continuations remain part of the same owning prompt until the entire chain finishes. Reporting is lifecycle-driven, with no inactivity-to-idle timer or heartbeat requirement.
+Use Herdr 0.8.2 or newer and launch Atomic inside it. Herdr supplies the pane connection settings automatically; you do not need to configure them yourself.
 
-| Contribution | Reported state | Internal reason | Message |
-|---|---|---|---|
-| Agent executing without an open approval prompt | `working` | `executing` | None unless a workflow needs attention |
-| Owned subagent or shell task queued, running, or cancelling | `working` | `executing` | None unless a workflow needs attention |
-| Workflow execution, automatic continuation, retry, or stop-drain | `working` | Workflow's `executing`, `automatic_continuation`, `retrying`, or `stopping` | `Workflow needs attention` when a root is blocked or needs attention |
-| Approval prompt is the only remaining work, including an agent parked on that prompt | `blocked` | `awaiting_input` | `Waiting for approval` |
-| Workflow waiting for input, an active intervention, or budget approval, with no independent execution | `blocked` | Workflow's `awaiting_input` or `manual_intervention` | `Workflow needs attention` |
-| All observed workflows paused, no agent or prompt work | `idle` | `paused` | None |
-| Settled agent, no prompt, ready workflow source with no work | `idle` | `quiescent` | None |
-| Failed or blocked workflow whose executor has finished, with no pending prompt or budget approval | `idle` | `quiescent` | `Workflow needs attention` |
-| Workflow source `unavailable` or `recovering`, no known contribution | No new report | Unknown | None |
+The integration runs only for interactive Atomic sessions. It stays inactive outside Herdr and in print, JSON, or RPC mode.
 
-Independent workflow execution keeps the pane working even after the parent agent settles or while another contribution waits for approval. Reasons are internal reducer values, not extra CLI fields. Missing workflow knowledge is never treated as an empty ready snapshot, so an unavailable provider can leave the last reported state unchanged until a ready snapshot arrives.
+## Status indicators
 
-Standalone subagents and background shell tasks also keep the pane working after the parent settles. The reporter reads the owner's task snapshot on activation and follows task events until shutdown. Reload reattaches to existing tasks; one task completing, failing, or being cancelled cannot clear another task's activity. Settled tasks retained in `/tasks` do not count as running. Children never claim the pane or overwrite the parent's session identity.
-
-A failed review or cleanup can leave a workflow outcome marked `blocked` after execution ends. That outcome remains inspectable and retains `needsAttention`, but does not by itself keep the pane red. A pending decision or exhausted budget still reports `blocked`; independent execution still reports `working`. Reporting `idle` neither acknowledges the failure nor resumes it. The parent session retains pane ownership until it exits, so a child stopping does not call `release-agent` for the parent.
-
-Sending a message acknowledges currently observed workflow blocks for the pane indicator only. The next settled response can return to `idle` instead of repeatedly turning red for the same block; workflow states and budget approvals are not changed. Repeated activity snapshots do not re-arm that attention. A changed workflow activity or a new live block/prompt does, and open approval widgets remain blocking until answered. Extension-generated messages and automatic agent starts do not acknowledge blocks. This acknowledgement is local to the reporter and resets on reload or restart.
+| Status | Meaning |
+|---|---|
+| Working | Atomic, a workflow, a subagent, or a background shell command is still running. |
+| Blocked | Work needs your input or approval, and no independent work is running. |
+| Idle / Done | No work is running. Herdr may show a newly completed turn as Done. |
 
-Opening or closing the host-owned `/tasks` inspector or the `/agents` catalog is navigation and does not emit an approval span or change Herdr activity. Genuine extension approval prompts still report `blocked`. This follows [Herdr's custom-agent contract](https://herdr.dev/docs/integrations/#integrate-your-own-agent), which defines `blocked` as needing a user decision. [Prime Agent's reporter](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts) likewise observes explicit block notifications. Atomic retains its settled-event and workflow aggregation instead of copying Prime's retry grace timers.
+Quiet periods such as provider waits, retries, and tool execution still count as working. Background work keeps the pane working after Atomic finishes its response.
 
-`/workflow connect` and its run picker are also navigation. Opening, hiding, reopening, or closing the graph does not create an approval wait. Real workflow input waits and extension approvals still contribute their normal state, including while the graph is hidden.
+Opening `/tasks`, `/agents`, or `/workflow connect` does not count as an approval request. Neither does a subagent asking its supervisor for guidance. Actual permission requests and workflow budget approvals can show Blocked.
 
-Prompt notifications reach each observer without waiting for earlier observers to finish. A slow observer cannot delay Herdr's start until after the matching end and leave a false `blocked` state after the user has answered. Notification work never delays prompt display or answers.
+A failed workflow can remain marked blocked in Atomic after its execution ends, while the pane returns to Idle. Check the workflow details for its result; the pane indicator is not a success or failure verdict. Sending a message acknowledges existing workflow attention for the indicator, but does not resume the workflow or approve a budget increase.
 
-## Opt out
+## Disable the integration
 
-Set this in global `~/.atomic/agent/settings.json` or trusted project `.atomic/settings.json`, then reload or restart Atomic:
+Add this to `~/.atomic/agent/settings.json` or trusted project `.atomic/settings.json`, then reload or restart Atomic:
 
 ```json
 {
@@ -59,48 +36,20 @@ Set this in global `~/.atomic/agent/settings.json` or trusted project `.atomic/s
 }
 ```
 
-The default is `true`, subject to the environment and ownership gates. Project settings override global settings using the normal [settings precedence](/settings).
-
-## Reporter conflicts
-
-If the actually loaded extension paths contain `herdr-atomic-reporter` or the legacy Pi `herdr-agent-state`, the built-in reporter defers without claiming or observing. One `unsupported` diagnostic names the loaded reporter path. Merely having such a package on disk does not cause deferral. The selected community or legacy reporter determines workflow coverage in that mode; Atomic's built-in aggregation is inactive.
-
-## Ownership, delivery, and privacy
-
-One module-owned lease reports each pane. A successor fences and drains the predecessor before reporting, without sending `release-agent`. Sequence numbers use a clock seed and a process-level high-water mark, increasing across extension reloads, runner replacement, and clock rollback within that process. Genuine quit drains the current child and releases authority with a fresh sequence strictly greater than the last report sequence. Late predecessor callbacks cannot report or release a successor.
-
-Each reporter instance binds to an eligible session's `SessionManager` and its active extension runner before awaiting pane acquisition. Other sessions sharing the loaded instance cannot change its activity, prompts, or lifecycle. In particular, a child quitting cannot release the parent's pane or cancel its pending claim. A transactional reload starts a candidate runner with the same `SessionManager` before retiring the old runner. The candidate takes over the binding and remains the active runner after commit; old shutdown, activity, approval, and repeated start events cannot release or reclaim that binding. The owning runner's shutdown clears the binding before awaiting transport cleanup, allowing a subsequent eligible session to reuse the same already-loaded resource loader. The successor reserves its binding immediately but waits for predecessor retirement before reporting its own identity; neither delayed predecessor events nor completion of the old shutdown can clear the new binding.
-
-Candidate reporting stays staged until transactional preparation and provider publication succeed. A rejected reload leaves the live runner's pane claim, approval count, and workflow observation intact, so continued work and genuine quit still report normally. Rejected candidate callbacks cannot take ownership. After commit, the candidate claims the pane before the old runner's shutdown and before queued extension side effects run.
-
-Normal compaction retains the same session and reporter; subsequent work continues reporting without reclaiming authority. Resource reload and in-process session replacement preserve the existing Herdr registration and last reported state while workflow activity is recovering or unavailable. They do not unregister the running agent or invent an idle snapshot, so another prompt is not needed to keep the agent visible. Ready activity resumes normal reporting. Genuine quit releases the inherited registration even if the successor has not sent a report. A non-quit shutdown can restart the same runner if no successor has taken over; late callbacks from superseded runners remain fenced.
-
-The reporter invokes the CLI directly with an argument array, not a shell. It permits one child per pane at a time, keeps only the newest pending state, and uses a five-second timeout plus bounded output buffering. Transport errors produce bounded `spawn_failed`, `timeout`, or `protocol_rejected` diagnostics; obsolete ownership uses `stale_owner`. Errors do not become agent or workflow failures. Child stdout and stderr are never logged raw.
-
-Only the fixed messages in the table are sent. Prompt titles, tool arguments, provider error bodies, transcripts, and workflow outputs are not forwarded. The parent's session ID and, when available, native absolute session path accompany reports until the first successful CLI delivery per claim, using `--agent-session-id` and `--agent-session-path`. Later reports in that claim omit these flags. This is not a once-per-claim attempt: after a transport failure, later activity retries that identity; no retry timer is added. Child sessions do not replace that identity.
+Reporting is enabled by default. Project settings follow the normal [settings precedence](/settings).
 
-## Compatibility
+## Troubleshooting
 
-The reporter is tested against Herdr **0.8.2 (protocol 20)**; that is the minimum supported release. The rows below record the observed CLI and server behaviour the reporter is built on, and how Atomic responds.
+If Atomic does not appear in Herdr:
 
-| Herdr behaviour (0.8.2, protocol 20) | Observed | Atomic behaviour |
-|---|---|---|
-| Custom-source authority | A `custom:*` source authors semantic pane state. `custom:atomic` shows as agent `atomic`. | The built-in reporter uses `custom:atomic` and does not depend on Herdr's own agent detection. |
-| Equal or older `--seq` | Exit 0, silently ignored by the server. The CLI never reports a rejected stale sequence. | Each report uses `max(clock ms, previous + 1)`, tracked in a process-level high-water mark; ordering is enforced by Atomic rather than inferred from exit codes. |
-| Sequence high-water mark after release | Survives `release-agent`. A later report with a lower sequence, even from a new owner, is ignored. | New processes seed from the clock. Ordering across a process restart with a rolled-back clock, or against another reporter's higher sequence, is not promised. |
-| `release-agent` without `--seq` | Exit 0, no change. Release by a non-owner source is also ignored. | Release always carries a fresh sequence strictly greater than the last report sequence. Ownership checks prevent late predecessor releases from retiring a successor. |
-| `idle` after `working` | Surfaced as `agent_status: done`; `idle` on a fresh pane surfaces as `idle`. | Atomic reports `idle`. Consumers reading pane state must accept `idle` or `done` for the idle state. |
-| `--message` | Accepted, but not surfaced by `agent get` (`message: null`). | Only the fixed messages `Waiting for approval` and `Workflow needs attention` are sent. |
-| Session identity for custom sources | `--agent-session-id`, `--agent-session-path`, and `report-agent-session` are accepted, but `agent_session` stays `null`. | The parent session identity is reported once per claim as the documented contract. Retention and automatic restoration are not observable on 0.8.2. |
-| Missing or invalid environment | Not applicable: nothing is invoked. | If `HERDR_ENV` is not exactly `1`, or any of `HERDR_BIN_PATH`, `HERDR_PANE_ID`, `HERDR_SOCKET_PATH` is empty, the reporter never activates and allocates no timer, subprocess, or observation lease. |
-| Server not running | Exit 1 immediately with `server_not_running`; no hang. | The report is dropped with one bounded `protocol_rejected` diagnostic. A hung binary is killed after five seconds and reported as `timeout`. |
-| Older Herdr CLI | Not tested. Commands or flags used here may be rejected. | Rejections surface as bounded `protocol_rejected` or `spawn_failed` diagnostics. They never become agent or workflow failures, and no report is retried until later activity. Older releases are not claimed as compatible. |
+- Make sure you launched Atomic inside a Herdr pane, rather than in a separate terminal.
+- Check that Herdr is running and reporting has not been disabled in Atomic's settings.
+- Check for a loaded `herdr-atomic-reporter` or legacy Pi `herdr-agent-state` extension. Atomic defers to these reporters to avoid conflicts; disable the extra extension and reload to use the built-in integration.
 
-Additional limits on this release:
+For custom launchers, Herdr must provide `HERDR_ENV=1` and nonempty `HERDR_BIN_PATH`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` values. See [Herdr's integration guide](https://herdr.dev/docs/integrations/#integrate-your-own-agent).
 
-- Reporting is event-driven. This integration adds no reconnect polling or crash-cleanup guarantee.
-- Interactive project-trust decisions also use the prompt lifecycle, including startup/resume and `/trust`; silent saved-policy decisions do not create a block.
+Reloading or compacting a session should not remove Atomic from the pane. If status stops updating, check Herdr's connection and reload Atomic. Reporting failures do not stop your agent or workflow, and reconnect polling is not automatic.
 
-The full activity path, from a real workflow run through the host observation stream to the `herdr` CLI invocations, is covered by an integration test against a fake `herdr` executable that records argv. It checks the ordered `working → blocked → working → idle` reports and strictly increasing `--seq` values for a tool-only execution followed by a human-input prompt. The state table it exercises is in [Workflow activity for extensions](/workflows/operations#workflow-activity-for-extensions).
+## Privacy
 
-Workflow publication is a separate integration from this reporter. It consumes the host [workflow observation contract](/extensions#workflow-activity-and-lifecycle-hooks) without importing workflow scheduler internals.
+Atomic sends status, generic attention messages, and the parent session's ID and local session path to the local Herdr server. It does not send prompt text, tool arguments, transcripts, or workflow output. Session reporting alone does not guarantee automatic session restoration in Herdr.

package/docs/index.md

@@ -59,6 +59,7 @@ For the full first-run flow, see [Quickstart](/quickstart).
 
 - [Quickstart](/quickstart) - install, authenticate, and run a first session.
 - [Using Atomic](/usage) - interactive mode, slash commands, context files, and CLI reference.
+- [Computer use](/computer-use) - work in desktop apps, browsers, and terminals across macOS, Linux, and Windows.
 - [Providers](/providers) - subscription and API-key setup for built-in providers.
 - [Environment variables](/environment-variables) - Atomic/Pi aliases, provider credentials, and bash session metadata.
 - [Security](/security) - project trust, sandbox boundaries, and vulnerability reporting.

package/docs/intercom.md

@@ -119,7 +119,9 @@ See auth.ts:142-156.
 
 The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients never need raw sender or `replyTo` IDs. Idle recipients get a new turn immediately; busy interactive recipients receive the message once they go idle. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Atomic session history.
 
-A busy non-interactive recipient can refuse a message without interrupting its task. A successful `send` receipt acknowledges transport delivery, not acceptance by the recipient's model. The refusal carries the original reply thread: a waiting `ask` returns an error; otherwise the sender sees **Intercom delivery failed** feedback with a `Sent:` timestamp. That feedback bypasses the ordinary idle queue and does not trigger a standalone agent turn. During an active turn, protected delivery makes it visible and reconciles it at a protocol-safe boundary. Its wording describes the refused send, not the recipient's later activity.
+Working subagents and live workflow stages treat `send` and `ask` as a priority interrupt queue. The recipient's current model call or cancellable tool is cancelled immediately, and the message is processed next within the same task, session, and stage generation; Intercom never launches another task or repeats the original prompt. A tool that ignores cancellation finishes first, and completed side effects are kept rather than undone or replayed. This works with foreground and background subagents. Messages received during startup join the original task, multiple messages retain arrival order, and an ask keeps its exact reply correlation after the cancelled turn. Explicit `interrupt`, owner cancellation, host stop, and terminal children or closed stages still win over later input. Use an exact connected child name or full session ID from `intercom list`; subagents are not workflow-stage paths.
+
+A busy non-interactive recipient that is neither an admitted subagent nor a workflow stage can still refuse a message without interrupting its task. A successful `send` receipt acknowledges transport delivery, not acceptance by the recipient's model. The refusal carries the original reply thread: a waiting `ask` returns an error; otherwise the sender sees **Intercom delivery failed** feedback with a `Sent:` timestamp. That feedback bypasses the ordinary idle queue and does not trigger a standalone agent turn. During an active turn, protected delivery makes it visible and reconciles it at a protocol-safe boundary. Its wording describes the refused send, not the recipient's later activity.
 
 Atomic treats ordinary `intercom` as a mandatory runtime tool in main chat and every workflow model stage. Tool allowlists, exclusions, `noTools`, optional-extension restrictions, and reloads cannot unload or deactivate it. Restrictions on every other tool are unchanged, and `contact_supervisor` remains subagent-only. Tool registration is lightweight; broker connection and heavy initialization remain lazy until an Intercom surface is used.
 
@@ -137,6 +139,12 @@ The session list and ALT+M picker show connected agent sessions, not every open
 
 Name sessions with `/name` so they can target each other (for example `/name planner` and `/name worker`). If a session is unnamed, Intercom exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d-1111-4222-8333-123456789abc` so other sessions can still target it. That alias is not persisted as the session title, so resume pickers keep showing the transcript snippet instead of a generic name.
 
+### Troubleshooting initialization
+
+`Intercom heavy initialization failed; a later call will retry: …` means initialization can be attempted again on a later Intercom call. Interactive sessions show this as a yellow warning in the chat pane, without a console stack trace; non-interactive sessions (print, JSON, and RPC) retain console diagnostics. Terminal relay and cleanup failures appear as error notifications in interactive sessions.
+
+If initialization keeps failing, check the reported cause and `~/.atomic/agent/intercom/broker.log` (or the Intercom directory under `ATOMIC_CODING_AGENT_DIR`). Do not automatically resend an operation reported with an unknown delivery outcome; check with the recipient first.
+
 ## The intercom Tool
 
 | Parameter | Type | Description |
@@ -392,7 +400,7 @@ workflow({
 
 When neither `enabled` nor `delivery` is set, direct `parallel` runs default to `control-and-result` when Intercom is available; otherwise delivery is off. Treat Intercom payloads from direct runs as user-visible workflow output.
 
-While a workflow stage generation is open, incoming Intercom messages are admitted through the stage session's native steering/follow-up queue. Parallel child asks, sends, and supervisor requests use destination-side reservation and the exact-child probe/commit observation-yield handshake, so terminal stage close cannot overtake an admitted delivery. A destination-side admission failure returns a correlated actionable error to a blocking asker instead of waiting for the 10-minute reply timeout. Claimed single-child parent handoffs remain source-side terminal handoffs.
+While a workflow stage generation is open, incoming Intercom messages are admitted as priority input: the stage's current model call or cancellable tool is cancelled and the message is processed next in the same stage generation. Parallel child asks, sends, and supervisor requests use destination-side reservation and the exact-child probe/commit observation-yield handshake before that cancellation, so a child's own message releases the parent's foreground observation rather than cancelling the child, and terminal stage close cannot overtake an admitted delivery. A destination-side admission failure returns a correlated actionable error to a blocking asker instead of waiting for the 10-minute reply timeout. Claimed single-child parent handoffs remain source-side terminal handoffs.
 
 ### Subagent Control Notices
 
@@ -448,6 +456,10 @@ Config validation is strict: every field is checked, and if the file is not vali
 
 Intercom publishes live session status automatically: sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on completion. A configured `status` is appended as context instead of replacing the lifecycle status.
 
+Activity is not reply capability. Session rows include `replyCapability: live` or `terminal` when the host supplies it; terminal noninteractive children cannot answer asks even if activity says `idle`. Closed workflow generations show `closed · reply: post-mortem only` when a late-message router is present, or `closed · reply: unavailable` without one. Post-mortem routing still validates the retained conversation and can return a bounded error if it is unavailable; it never resumes workflow execution. Missing capability metadata is not a guarantee that an ask can succeed. Invocation/subgroup visibility and stale-ID rejection are unchanged.
+
+For a retained post-mortem conversation, use its exact Intercom session ID or the previously listed canonical stage path, including its final-stage-name variant. Alternate materialized run-ID paths resolve active stages through the workflow owner; they are not retained aliases after the stage completes. A stage marked `reply: unavailable` rejects an ask with guidance to contact a live stage or start new work with explicit context.
+
 ## Keyboard Shortcuts
 
 | Key | Action |

package/docs/models/evals.md

@@ -22,6 +22,8 @@ No single benchmark is the source of truth. Validate these inputs against Atomic
 
 Start here when a stage needs a model. Each row names a relevant benchmark and selected candidates, not a universal winner or a guarantee that the cheaper option stays close. "Measured" means the exact configuration named; a different effort level or agent is a different experiment.
 
+Practical workflow default: use `low` or `medium` for coding, and `high` or `xhigh` for code review, test design and failure analysis, where the configured model supports those levels. Run actual tests as tool calls, not model judgments. `max` is usually overkill and is not preferred in practice. These are starting recommendations, not conclusions that every benchmark proves; the rows below preserve the exact measured settings. See [role-based thinking effort](/models/model-selection#role-based-thinking-effort).
+
 | Task type | Benchmark to read | Selected measured candidates | Cost-conscious alternative |
 | --- | --- | --- | --- |
 | Implementing features and fixing bugs | September 3 Datacurve DeepSWE | Astra xhigh, Gemini 3.8 Flash high and Opus 5 max display 74% | Luna max 67% / $0.61; GLM-5.3-Flash max 63% / $0.24 |

package/docs/models/model-selection.md

@@ -29,6 +29,8 @@ If live results cannot be retrieved, use the dated docs snapshot and say it was
 
 The thinking level in brackets in the chart is the **measurement configuration used for that benchmark result**, not a universal workflow default. A score measured at `max` does not mean every stage using that model should use `max`; benchmark model identity and production thinking effort are separate choices. When authoring a workflow, choose effort from the stage role and cost of being wrong, then check the returned `availableThinkingLevels` for the configured catalog model.
 
+Practical default: use `low` or `medium` for coding, and `high` or `xhigh` for code review, test design and failure analysis, subject to catalog support. Run actual tests as tool calls. `max` is usually overkill and is not preferred in practice. These are starting recommendations to validate on your workflow, not a claim that lower effort reproduces the benchmark scores below.
+
 ## Pin model identity
 
 When a workflow needs an exact model, call `workflow({ action: "models" })` and pin a returned `fullId`. Do not pin a
@@ -112,25 +114,26 @@ Use this table when the user has not requested a thinking level. It is a product
 
 | Stage role | Default thinking level | Why |
 | --- | --- | --- |
-| Security, identity, adversarial challenge, final approval | `max` | A wrong judgment can create a high-risk false approval or waste a full downstream loop. |
-| Codebase mapping, lifecycle analysis, compatibility, planning, synthesis, triage, repair | `high` | These stages must resolve demanding uncertainty and preserve evidence across handoffs; routine synthesis may use `medium` when evidence quality holds. |
+| Coding, implementation, routine fixes | `low` or `medium` | Keep implementation fast; use review and tests to catch defects. |
+| Code review, test design, failure analysis, security, identity, adversarial challenge, final approval | `high` or `xhigh` | Spend more reasoning on finding defects, probing edge cases and judging evidence. |
+| Codebase mapping, lifecycle analysis, compatibility, planning, synthesis, triage | `high` | These stages must resolve demanding uncertainty and preserve evidence across handoffs; routine synthesis may use `medium` when evidence quality holds. |
 | User-impact review and final reporting | `medium` | Clear evidence-backed summaries usually do not need the deepest reasoning. |
 | Deterministic checks | No model call | Run typechecks, tests, schema checks, runtime probes, and artifact checks as durable tool nodes. |
 
-Reserve `max` for a high-cost-of-error role or an explicit user request. An explicit request wins over this role default, but the requested level still must appear in the configured catalog; do not invent an unsupported suffix. For each primary and fallback, choose a level for the same stage role independently. A fallback is not a reason to inherit `max` mechanically: use the role default at a supported level, choose another catalog model when needed, or leave the stage unpinned rather than guessing.
+`max` is an exception, not a role default. Consider it only when task-specific evidence justifies the extra effort or the user explicitly requests it. An explicit request wins over these defaults, but the requested level still must appear in the configured catalog; do not invent an unsupported suffix. For each primary and fallback, choose a supported level for the same stage role independently. If `xhigh` is unavailable, use `high` rather than automatically promoting to `max`; choose another catalog model or leave the stage unpinned if neither is supported.
 
 ## Scenario-based guidance
 
 Pick by the cost of being wrong in each role, not by raw accuracy. The AA evidence below was read on 2026-09-08; the Datacurve evidence remains the September 3 snapshot. See [Evals](/models/evals) for measurement settings, normalized Elo versus pass-rate units and source links.
 
-- **Reviewer / judgment gates.** Use `max` for a high-cost-of-error security, identity, adversarial or final-approval decision, subject to the configured model's supported efforts. No external benchmark here establishes security-review reliability. Claude Code + Fable 5.1 max with fallback and Claude Code + Opus 5 xhigh score 56% and 55% on SWE-Atlas-QnA, versus 51% for Codex + Astra max, but those harness-specific results need validation in Atomic.
+- **Reviewer / judgment gates.** Use `high` or `xhigh` for code review and approval decisions, subject to the configured model's supported efforts. No external benchmark here establishes security-review reliability. Claude Code + Fable 5.1 max with fallback and Claude Code + Opus 5 xhigh score 56% and 55% on SWE-Atlas-QnA, versus 51% for Codex + Astra max, but those harness-specific results need validation in Atomic.
 - **Codebase mapping / planner.** Start at `high`. For knowledge-work deliverables, Fable 5.1 max with fallback scores 58% normalized Elo on AA-Briefcase, Opus 5 max 57%, and GLM-5.3-Flash 48% at $0.25 per Index task. These are candidates, not measured repository-planning pass rates. Raise effort only for the role's cost of error or the user's request.
-- **Debugger / triage / repair.** Start at `high`. The new Terminal-Bench v4.0 is no longer flat near 90%: Astra xhigh scores 60%, Fable 5.1 xhigh with fallback 55%, Opus 5 max 49%, and Gemini 3.8 Flash high 20%. Keep Datacurve cost and steps as separate evidence; do not transfer its 74% Gemini result into this benchmark.
+- **Debugger / triage / repair.** Use `high` or `xhigh` for failure analysis and test design, then `low` or `medium` to implement a diagnosed fix. The new Terminal-Bench v4.0 is no longer flat near 90%: Astra xhigh scores 60%, Fable 5.1 xhigh with fallback 55%, Opus 5 max 49%, and Gemini 3.8 Flash high 20%. Keep Datacurve cost and steps as separate evidence; do not transfer its 74% Gemini result into this benchmark.
 - **Research / synthesis.** Use `high` for demanding reconciliation and `medium` for routine synthesis. Luna max scores 84% on AA-LCR at $0.18 per Index task, but its 7% non-hallucination rate counts partial answers or not attempted among non-correct responses, not all answers. Verify factual claims. Astra xhigh leads the displayed GDP.pdf rows at 32%; GLM-5.3-Flash and GLM-5.3 max score 72% and 70% non-hallucination.
 - **Orchestrator / worker / cheap loops.** Use AutomationBench-AA for SaaS tool workflows: Astra max 68%, GLM-5.3-Flash 60%, Luna max 50%. GLM-5.3-Flash and Luna remain budget candidates on the separately dated Datacurve frontier. Gemini 3.8 Flash's 166 steps and 143k output tokens in that snapshot argue against choosing workers on pass rate alone. Validate the tradeoff on the actual workflow.
-- **User-impact review / final reporting** — use `medium` for impact summaries and reports that preserve the evidence needed by the user. Do not spend `max` here unless the user explicitly requests it or the role has become a high-cost-of-error approval.
+- **User-impact review / final reporting.** Use `medium` for impact summaries and reports that preserve the evidence needed by the user. If the stage makes an approval decision, use the reviewer guidance instead.
 - **Design** — a quality-first domain not directly measured by these coding tables. Choose effort by the review or approval role. Fable 5.1's AA-Briefcase results make it a candidate for knowledge-work deliverables, not proof of product-design quality; evaluate it on the intended design tasks and do not carry Fable 5's DeepSWE row over to it.
-- **Interactive coding sessions** — use `high` for complex, multi-step coding and `medium` for routine edits; reserve `max` for a high-cost-of-error judgment or an explicit user request.
+- **Interactive coding sessions.** Use `low` or `medium` for implementation, switching to `high` or `xhigh` for code review, test design and failure analysis. Choose only levels supported by the configured model.
 - **Deterministic checks** — make typechecks, tests, schema validation, runtime probes, and artifact inspection tool nodes with no model call. Model self-report is not verification evidence.
 
 ## Related

package/docs/quickstart.md

@@ -218,7 +218,7 @@ Named workflow runs execute in the background. After launch you get the full run
 /workflow status                  # list this session's active and terminal runs
 /workflow connect <run-id>        # see agents working; chat with or steer each stage (F2 also opens latest)
 /workflow attach <run-id> <stage> # chat with one stage
-/workflow interrupt <run-id>      # pause resumably
+/workflow pause <run-id>          # pause resumably
 /workflow resume <run-id> "go"    # send a steer message and resume
 /workflow quit <run-id>           # pause gracefully and keep the run resumable
 ```

package/docs/sdk.md

@@ -795,7 +795,7 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 Specify which tools to expose by name:
 
-- Built-in tool names enabled by default: `read`, `bash`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`
+- Built-in tool names enabled by default: `read`, `bash`, `kill`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`
 - `find` discovers filesystem paths by glob; `search` searches file contents with regex patterns across files, directories, globs, and internal URLs.
 - `tools` is an allowlist: when provided, only the listed built-in, extension, and custom tool names are exposed, plus mandatory ordinary `intercom`.
 - `excludedTools` is a blocklist: matching built-in, extension, and custom tool names are omitted from the final registry and active tool set, except mandatory ordinary `intercom`. If both are provided, `tools` is applied first and `excludedTools` subtracts from it.
@@ -832,6 +832,14 @@ const { session } = await createAgentSession({
 Atomic's built-in `bash` tool matches upstream pi: when `bash` is enabled, commands execute through the configured shell with the Atomic process permissions. Use `tools`, `excludedTools`, or `noTools` to decide whether a session exposes the `bash` tool at all. Atomic no longer provides a command-level allow/deny option for `bash`; use an operating-system/container sandbox or a custom tool/extension when you need command allowlisting or stronger isolation.
 
 
+#### Waiting for existing shell tasks
+
+Both Bash and PowerShell factories accept `{ action: "wait", id: taskId, budgetMs: 1000 }` with a trusted `taskOwner` binding. No command is executed. `BashToolInput` and `PowerShellToolInput` distinguish command launches from existing-task waits; narrow by `action` before reading `command`.
+
+`budgetMs` is optional, finite, and non-negative. Omission uses the owner's command wait policy and zero polls. Results keep the `WaitOutcome` in `details.observation`, available exit information in `details.exitCode`, and retained output in text content. Failure and cancellation metadata remain in the settled observation. Yielded waits advance through bounded retained-output pages for the same owned task, even when the tool is recreated. Partial UTF-8 characters continue on the next page. Settled waits return all retained output again, subject to labelled gaps and truncation. Aborting the call releases only its observation. A binding from `AgentTaskHost.ownerBinding` also releases waits for incoming owner messages.
+
+Do not mix wait arguments with launch fields. Unknown or foreign IDs and unbound waits are rejected before execution hooks. Custom `operations.exec` does not provide existing-task ownership. See [Background tasks](/background-tasks) for examples and lifetime rules.
+
 #### PowerShell tool behavior
 
 `createPowerShellTool()` and `createPowerShellToolDefinition()` provide the same tool used by interactive sessions. When their default local operations execute on native Windows, they prefer `pwsh.exe`, fall back to `powershell.exe`, and throw a clear error when neither executable is available. `createLocalPowerShellOperations()` and `getPowerShellConfig()` are also exported for custom integrations. The PowerShell factories expose the current `ATOMIC_*` and legacy `PI_*` session snapshot by default; set `exposeSessionEnvironment: false` to opt out.
@@ -910,6 +918,8 @@ If you pass `tools`, include each custom or extension tool name you want enabled
 
 Factory-created `createBashTool()` instances receive the same execution-time `ATOMIC_SESSION_*`/`PI_SESSION_*` model and session snapshot as the built-in bash tool. Set `exposeSessionEnvironment: false` only when the subprocess must not receive it. `MessageRenderOptions.outputPad` is likewise passed to normal and isolated custom message renderers.
 
+Normal sessions also expose `kill({ id: taskId })` for their owned bash and PowerShell background tasks. Include `kill` when using a `tools` allowlist if the agent should be able to stop those tasks. The exported `createKillTool` and `createKillToolDefinition` factories accept `KillToolOptions.taskOwner`, a trusted execution-time callback returning the same owner binding used by shell launch. Without a binding they reject execution. The result details preserve the supervisor's `CancelReceipt`, including its decision, execution outcome, and cleanup state. See [Background tasks](/background-tasks#stop-a-shell-task-from-a-tool-call).
+
 #### Structured output final results
 
 `structured_output` is not registered in normal agent sessions by default. Add it only when a caller needs a machine-readable final-answer contract by registering the exported factory as a custom tool: