@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/utils/version-check.js

@@ -1,5 +1,5 @@
 import { compare, valid } from "semver";
-import { ENV_OFFLINE, ENV_SKIP_VERSION_CHECK, PACKAGE_NAME, getEnvValue } from "../config.js";
+import { ENV_OFFLINE, ENV_SKIP_VERSION_CHECK, getEnvValue, PACKAGE_NAME } from "../config.js";
 const LATEST_VERSION_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;
 /**
@@ -29,7 +29,7 @@ export function isNewerPackageVersion(candidateVersion, currentVersion) {
     return candidateVersion.trim() !== currentVersion.trim();
 }
 export async function getLatestPiRelease(options = {}) {
-    if (getEnvValue(ENV_SKIP_VERSION_CHECK) || getEnvValue(ENV_OFFLINE))
+    if (getEnvValue(ENV_OFFLINE))
         return undefined;
     const response = await fetch(LATEST_VERSION_URL, {
         headers: {
@@ -40,16 +40,18 @@ export async function getLatestPiRelease(options = {}) {
     if (!response.ok)
         return undefined;
     const data = (await response.json());
-    if (typeof data.version !== "string" || !data.version.trim()) {
+    if (typeof data.version !== "string" || !data.version.trim())
         return undefined;
-    }
     const packageName = typeof data.name === "string" && data.name.trim() ? data.name.trim() : undefined;
-    return { version: data.version.trim(), packageName };
+    const note = typeof data.note === "string" && data.note.trim() ? data.note.trim() : undefined;
+    return { version: data.version.trim(), packageName, ...(note ? { note } : {}) };
 }
 export async function getLatestPiVersion(options = {}) {
     return (await getLatestPiRelease(options))?.version;
 }
 export async function checkForNewPiVersion(currentVersion) {
+    if (getEnvValue(ENV_SKIP_VERSION_CHECK))
+        return undefined;
     // Dev builds always read the versionless `0.0.0` placeholder, which is older
     // than any published release, so the registry check would always nag. Skip it
     // (and the network call) for source-tree/dev runs.

package/dist/utils/version-check.js.map

@@ -1 +1 @@
-{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { compare, valid } from \"semver\";\nimport { ENV_OFFLINE, ENV_SKIP_VERSION_CHECK, PACKAGE_NAME, getEnvValue } from \"../config.ts\";\n\nconst LATEST_VERSION_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\n/**\n * The versionless placeholder stamped on `main` and read from source-tree dev\n * runs (`bun packages/coding-agent/src/cli.ts`). Real releases never carry it —\n * `scripts/cut-release.ts` materializes the actual version on the tag commit —\n * so encountering it means this is a dev build that should not be compared\n * against the published registry version.\n */\nconst DEV_VERSION_PLACEHOLDER = \"0.0.0\";\n\nexport function isDevVersion(version: string): boolean {\n\treturn version.trim() === DEV_VERSION_PLACEHOLDER;\n}\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = valid(leftVersion.trim());\n\tconst right = valid(rightVersion.trim());\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\treturn compare(left, right);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (getEnvValue(ENV_SKIP_VERSION_CHECK) || getEnvValue(ENV_OFFLINE)) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { name?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName = typeof data.name === \"string\" && data.name.trim() ? data.name.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(options))?.version;\n}\n\nexport async function checkForNewPiVersion(currentVersion: string): Promise<string | undefined> {\n\t// Dev builds always read the versionless `0.0.0` placeholder, which is older\n\t// than any published release, so the registry check would always nag. Skip it\n\t// (and the network call) for source-tree/dev runs.\n\tif (isDevVersion(currentVersion)) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tconst latestVersion = await getLatestPiVersion();\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9F,MAAM,kBAAkB,GAAG,8BAA8B,YAAY,SAAS,CAAC;AAC/E,MAAM,gCAAgC,GAAG,KAAK,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAExC,MAAM,UAAU,YAAY,CAAC,OAAe;IAC3C,OAAO,OAAO,CAAC,IAAI,EAAE,KAAK,uBAAuB,CAAC;AACnD,CAAC;AAQD,MAAM,UAAU,sBAAsB,CAAC,WAAmB,EAAE,YAAoB;IAC/E,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,gBAAwB,EAAE,cAAsB;IACrF,MAAM,UAAU,GAAG,sBAAsB,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;IAC5E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,UAAU,GAAG,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,gBAAgB,CAAC,IAAI,EAAE,KAAK,cAAc,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAO,GAA2B,EAAE;IAC5E,IAAI,WAAW,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAE/C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,kBAAkB,EAAE;QAChD,OAAO,EAAE;YACR,MAAM,EAAE,kBAAkB;SAC1B;QACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,gCAAgC,CAAC;KAClF,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAEnC,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA0D,CAAC;IAC9F,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAC/E,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrG,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9F,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAO,GAA2B,EAAE;IAC5E,OAAO,CAAC,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,cAAsB;IAChE,IAAI,WAAW,CAAC,sBAAsB,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1D,6EAA6E;IAC7E,8EAA8E;IAC9E,mDAAmD;IACnD,IAAI,YAAY,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,CAAC;QACJ,MAAM,aAAa,GAAG,MAAM,kBAAkB,EAAE,CAAC;QACjD,IAAI,aAAa,IAAI,qBAAqB,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,CAAC;YAC3E,OAAO,aAAa,CAAC;QACtB,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;AACF,CAAC","sourcesContent":["import { compare, valid } from \"semver\";\nimport { ENV_OFFLINE, ENV_SKIP_VERSION_CHECK, getEnvValue, PACKAGE_NAME } from \"../config.ts\";\n\nconst LATEST_VERSION_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\n/**\n * The versionless placeholder stamped on `main` and read from source-tree dev\n * runs (`bun packages/coding-agent/src/cli.ts`). Real releases never carry it —\n * `scripts/cut-release.ts` materializes the actual version on the tag commit —\n * so encountering it means this is a dev build that should not be compared\n * against the published registry version.\n */\nconst DEV_VERSION_PLACEHOLDER = \"0.0.0\";\n\nexport function isDevVersion(version: string): boolean {\n\treturn version.trim() === DEV_VERSION_PLACEHOLDER;\n}\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = valid(leftVersion.trim());\n\tconst right = valid(rightVersion.trim());\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\treturn compare(left, right);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(options: { timeoutMs?: number } = {}): Promise<LatestPiRelease | undefined> {\n\tif (getEnvValue(ENV_OFFLINE)) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { name?: unknown; version?: unknown; note?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) return undefined;\n\tconst packageName = typeof data.name === \"string\" && data.name.trim() ? data.name.trim() : undefined;\n\tconst note = typeof data.note === \"string\" && data.note.trim() ? data.note.trim() : undefined;\n\treturn { version: data.version.trim(), packageName, ...(note ? { note } : {}) };\n}\n\nexport async function getLatestPiVersion(options: { timeoutMs?: number } = {}): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(options))?.version;\n}\n\nexport async function checkForNewPiVersion(currentVersion: string): Promise<string | undefined> {\n\tif (getEnvValue(ENV_SKIP_VERSION_CHECK)) return undefined;\n\t// Dev builds always read the versionless `0.0.0` placeholder, which is older\n\t// than any published release, so the registry check would always nag. Skip it\n\t// (and the network call) for source-tree/dev runs.\n\tif (isDevVersion(currentVersion)) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tconst latestVersion = await getLatestPiVersion();\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/docs/changelog.mdx

@@ -3,6 +3,28 @@ title: "Changelog"
 description: "What's new in Atomic"
 ---
 
+<Update label="July 31, 2026">
+
+## Pi 0.83.0 parity
+
+- **One door prints a stored credential.** `atomic auth print-api-key --model <model>` and `atomic auth print-bearer-token --model <model>` hand a configured credential to an external client. The credential is all that reaches stdout — warnings, provider selection, refresh notices, and help go to stderr — `--model` is required, and each failure has its own exit code, with stdout empty on every non-zero exit. `--min-expiry` accepts `ms`, `s`, `m`, or `h`, defaults to `30m`, and is a usage error on `print-api-key`, which has no expiry to wait for. See [Usage](/usage#credential-commands) and [Security](/security#credential-export).
+- **Extensions can read the session's model scope.** `ctx.scopedModels` reports the models scoped to the current session — the set `/scoped-models` shows — resolved at access time and correct under the isolated engine. It reports the scope and cannot widen it: the accessor is read-only, and every read hands back a frozen copy of the array, its entries, and their models, so neither pushing an entry nor swapping one in place reaches the session. `ScopedModel` and `ExtensionScopedModels` are exported so an extension can name what it read. See [Extensions](/extensions#ctxmodelregistry--ctxmodel--ctxscopedmodels).
+- **An unrecognised stop reason is now an error.** A provider that ends a turn with a terminal reason the mapping does not know surfaces a provider error naming the raw value instead of an ordinary successful stop, so a new truncation or safety signal is visible rather than silent. Streaming partials carry the new `pending` reason until the terminal event replaces it; a stream that ends still `pending` is an error. See [Providers](/providers#stop-reasons) and [Custom Providers](/custom-provider#stop-reasons).
+- **OAuth tokens refresh before they expire.** A stored token with under five minutes of validity left is refreshed rather than used, so a long turn does not start on a credential that dies mid-request. The refresh runs under the `auth.json` lock and re-checks expiry inside it, so concurrent sessions sharing one credential file refresh it once between them. See [Providers](/providers#token-refresh).
+- **Remote OpenRouter logins have a way through.** When the browser cannot reach the loopback callback — over SSH, or on a headless host — the OpenRouter login accepts the final redirect URL, or the authorization code alone, pasted into the prompt. See [Providers](/providers#subscriptions).
+
+</Update>
+<Update label="July 26, 2026">
+
+## Pi 0.82.1 parity
+
+- **Constrained tool sampling is public end to end.** Extensions and SDK tools can request strict JSON Schema (`prefer` or `require`) or OpenAI Lark/regex grammars. Atomic preserves exact optional-property identity during public inspection, and typed RPC model listings expose all four enforcement flags through optional `ModelInfo.compat`. Unsupported models never claim required enforcement. See [Extensions](/extensions#constrained-sampling), [Models](/models#constrained-tool-sampling), and [RPC](/rpc#get_available_models).
+- **Authentication and flagship catalogs expanded.** `/login openrouter` uses provider-owned browser PKCE with optional key minting, `/login kimi-coding` uses device authorization with automatic refresh, and isolated engine-only extension OAuth now supports safe descriptor discovery, correlated UI callbacks/cancellation, transactional engine persistence/refresh/rollback/logout, and no credential or executable-function transport. Intentional Escape/Ctrl+C/native-abort cancellation is quiet; genuine provider, network, token, storage, and refresh failures remain visible. Claude Opus 5 is available through Anthropic and Bedrock, while bearer-only `ANTHROPIC_AUTH_TOKEN` remains selectable across normal and isolated/RPC catalogs without emitting an API key or `x-api-key`. See [Providers](/providers) and [Custom Providers](/custom-provider#oauth-support).
+- **Catalogs and model configuration stay resilient.** Remote catalogs use ETag revalidation and accept empty `304` responses, newer bundled data beats stale overlays, and a validated persisted llama.cpp catalog remains selectable when the first online refresh after restart fails while Atomic still reports the original error; a later success replaces it. Opening `/model` reloads layered legacy `.pi` then primary `.atomic` configuration. See [Models](/models#catalog-freshness-and-precedence) and [llama.cpp](/llama-cpp).
+- **Bash integrations are session-aware and stream precisely.** Commands receive Atomic and exact Pi session/model environment aliases; unsaved sessions omit the file path. Direct RPC bash streams request-correlated stdout/stderr deltas, targeted/legacy cancellation, one terminal response, and exactly-once starting-session persistence across new/switch/import/fork/clone replacement; RPC shutdown drains active owners. See [Environment Variables](/environment-variables#bash-session-environment) and [RPC](/rpc#bash).
+- **Coding-agent parity fixes landed.** Custom message renderers receive `outputPad` in normal and isolated rendering; summaries use fresh routing IDs without prompt-cache writes; complete literal IDs win before thinking-suffix/glob parsing; unavailable scoped entries remain removable; shared async Ctrl+G editing uses a private exact `prompt.md`, configured/environment/platform precedence, and recursive cleanup across main and extension editors; `/copy` falls back after `wl-copy` failure; explicit update checks bypass startup-skip settings; configured agent directories own TUI logs; and context discovery ignores directories named like context files.
+
+</Update>
 <Update label="July 18, 2026">
 
 ## Model catalogs and provider authentication
@@ -19,7 +41,7 @@ See [SDK](/sdk) and [Custom providers](/custom-provider).
 ## Pi 0.80.6 compatibility
 
 - **Synced through upstream Pi 0.80.6.** Atomic and its bundled extensions now use the 0.80.6 Pi runtime packages, including signed empty Anthropic thinking preservation, request-wide GPT-5.4/5.5 long-context pricing, and corrected GPT-5.6 catalog/backend metadata.
-- **Model controls are current.** Atomic accepts `max` wherever the active model advertises it, applies `models.json` overrides to matching extension-registered models and built-ins, and loads legacy `.pi` plus primary `.atomic` layers during normal CLI startup. Disjoint override IDs survive, exact primary entries replace complete legacy entries, and removed catalog IDs fall back instead of being synthesized on resume. See [Models](/models).
+- **Model controls are current.** Atomic accepts `max` wherever the active model advertises it, applies the active agent directory's single `models.json` overrides to matching extension-registered models and built-ins, and falls back instead of synthesizing removed catalog IDs on resume. See [Models](/models).
 - **Custom pricing tiers are preserved.** Custom `models.json` entries and extension providers can declare complete request-wide `cost.tiers`; matching `modelOverrides` can update scalar rates without losing inherited tiers or replace/clear the tier array explicitly. See [Models](/models#request-wide-cost-tiers) and [Custom Providers](/custom-provider#usage-and-cost).
 - **Safer session and tool behavior.** Invalid explicit bash timeouts fail instead of being clamped; missing exact session IDs warn before creation; lax null or omitted message content is normalized; auth writes surface persistence failures; Windows context traversal terminates at drive roots; and duplicate fork selections are ignored. See [Tools](/tools) and [Usage](/usage).
 - **More reliable streaming and binaries.** Visible custom messages stay before the live assistant row, standalone Linux clipboard reads can fall back to xclip with correctly packaged native bindings, caller-relative `TMPDIR` paths work from external directories, and `--skip-deps` tolerates a missing optional clipboard wrapper.
@@ -54,7 +76,7 @@ See [SDK](/sdk) and [Custom providers](/custom-provider).
 
 - **0.8.14 is the stable promotion of the 0.8.14 prerelease.** It keeps the upstream Pi sync, bundled workflow documentation refresh, and bundled subagent guidance updates from the prerelease.
 - **Synced with upstream Pi patches.** Atomic's coding-agent fork is now aligned with upstream Pi patches since v0.75.4 and bundles Pi libraries at 0.75.5.
-- **Bundled workflow docs are current.** The docs now describe Ralph's final PR-preparation phase, deep-research report artifacts, and newer workflow inspection/control actions such as `stages`, `stage`, `transcript`, `send`, `pause`, and `reload`. See [Workflows](/workflows).
+- **Bundled workflow docs are current.** The docs now cover current workflow inspection and control actions such as `stages`, `stage`, `transcript`, `send`, `pause`, and `reload`. See [Workflows](/workflows).
 - **Bundled subagent guidance is easier to find.** Atomic now documents how to use bundled subagents for delegation, background work, nested fanout boundaries, model fallbacks, and custom agent guardrails. See [Subagents](/subagents).
 
 ## Fixes

package/docs/compaction.md

@@ -2,13 +2,15 @@
 
 LLMs have finite context windows. Atomic reduces transcript context with **verbatim line compaction** while preserving an exact count of recent context-visible messages as ordinary messages. Branch summarization is a separate, intentionally lossy feature used only when navigating away from a branch.
 
-Compaction runs entirely locally with the active session model; no external compaction service is involved. The model only selects which lines to delete — Atomic reconstructs the retained text mechanically, so surviving lines are never rewritten.
+Compaction runs entirely locally; no external compaction service is involved. It normally uses the active session model. If that model cannot rank the lines — a rate limit, a quota exhaustion, a provider error, a context overflow, or an empty plan — Atomic *borrows* the next model from your configured `fallbackModels` for that one planner request. **A configured fallback model may therefore receive the compaction transcript**, and it is sent with that provider's own credentials. Borrowing never changes the session's model or thinking level. The model only selects which lines to delete — Atomic reconstructs the retained text mechanically, so surviving lines are never rewritten.
 
 ## Overview
 
 | Mechanism | Trigger | Model output | Durable result |
 |---|---|---|---|
 | Verbatim compaction | `/compact`, RPC `compact`, or automatic threshold/overflow recovery | Bare `start,end` deletion records (one per line) | A `CompactionEntry` whose `summary` is mechanically reconstructed transcript text |
+| Planner fallback borrowing | Any terminal planner outcome on the current planner model | Same deletion records, from a configured `fallbackModels` entry | The same `"planned"` boundary, with `details.plannerModel` naming the borrowed model |
+| Fresh context window | Load-bearing compaction after every configured model failed | *(none — no model call)* | A `CompactionEntry` with `details.rung: "fresh"` |
 | Branch summarization | Optional `/tree` navigation | Generated summary prose | A `BranchSummaryEntry` |
 
 There is one context-compaction door: `compact`.
@@ -62,7 +64,7 @@ The effective parameters appear in extension events and successful results:
 | `preserve_recent` | `2` | Exact number of newest context-visible messages protected client-side |
 | `query` | Last visible user message | Relevance focus for deciding which older lines to retain |
 
-`preserve_recent` counts context-visible messages without aligning the boundary to a user turn. An assistant message or tool result may therefore begin the kept tail. A value of `0` protects no messages and makes the entire active transcript compactable. If `query` is absent, Atomic derives it from the last visible user message.
+`preserve_recent` counts context-visible messages without aligning the boundary to a user turn. An assistant message or tool result may therefore begin the kept tail. Because such a tail can start or end mid-turn, the kept messages are not replayed as structured message blocks: they are serialized with the same transcript grammar as the compacted region and appended to the end of the boundary string, so the whole boundary reaches the provider as one message. Serialization of the kept tail is lossless — tool results keep their full text instead of being truncated at 16k characters, and images stay attached as image blocks rather than becoming `[image]` markers — so protected content is preserved, not merely summarized. A value of `0` protects no messages and makes the entire active transcript compactable. If `query` is absent, Atomic derives it from the last visible user message.
 
 Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`:
 
@@ -86,21 +88,80 @@ Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`
 - **Threshold:** automatic compaction starts when estimated context usage exceeds the effective input budget minus `reserveTokens`. Atomic checks both completed responses and the prospective next-turn context after tool results have been appended. A post-tool crossing is compacted before the active Pi tool loop sends its follow-up provider request.
 - **Overflow:** an actual provider context overflow compacts and then retries the interrupted turn.
 
-Exactly the configured recent-message tail is outside the compactable region; Atomic does not force the final logical turn to remain outside it. Pressing Escape while compaction is active cancels it like other session operations. In isolated interactive mode, cancellation and host UI response frames use an independent RPC control lane, so they can reach the engine while the ordinary `compact` request is still pending instead of waiting behind it. Atomic writes a backup snapshot immediately before appending a compaction boundary.
+Exactly the configured recent-message tail is outside the compactable region; Atomic does not force the final logical turn to remain outside it. After successful automatic compaction, input queued before compaction started resumes automatically once the active run becomes idle; pressing Escape is not required to release it. Pressing Escape while compaction is active cancels it like other session operations. In isolated interactive mode, cancellation and host UI response frames use an independent RPC control lane, so they can reach the engine while the ordinary `compact` request is still pending instead of waiting behind it. Atomic writes a backup snapshot immediately before appending a compaction boundary.
 
-The post-tool check stays inside the active Pi loop: it runs at most one ordinary verbatim compaction attempt for that completed tool turn, returns the rebuilt context to the loop, and never calls or schedules `agent.continue()`. Normal context reconstruction preserves provider tool-call/result protocol validity. Below-threshold tool turns follow the unchanged request path. Because the same active run resumes without emitting another `agent_start`, the interactive TUI replaces the compaction loader with its working spinner as soon as successful mid-turn compaction ends; streaming feedback therefore resumes immediately without waiting for another user interaction.
+Manual compaction is single-flight. A manual request made while another manual compaction is still in flight joins that run and receives its result instead of starting a second model call, so it emits no extra `compaction_start`/`compaction_end` pair and appends no extra boundary; `abortCompaction()` (Escape) still cancels the single owning run for every waiter. A manual request made while an automatic compaction is in flight is rejected immediately with an "automatic compaction is already in progress" error rather than racing it. In the interactive TUI, `/compact` typed while any compaction is active is refused with a warning; it is not queued, because queueing would only defer a duplicate compaction. Ordinary text typed during compaction is still queued as usual.
 
-## One-pass planning and failure behavior
+The post-tool check stays inside the active Pi loop: it runs the rung ladder once for that completed tool turn, returns the rebuilt context to the loop, and never calls or schedules `agent.continue()`. Normal context reconstruction preserves provider tool-call/result protocol validity. Below-threshold tool turns follow the unchanged request path. Because the same active run resumes without emitting another `agent_start`, the interactive TUI replaces the compaction loader with its working spinner as soon as successful mid-turn compaction ends; streaming feedback therefore resumes immediately without waiting for another user interaction.
 
-Atomic asks the active session model, at the active reasoning level and through the normal session stream/provider wrapper, to rank every eligible line in one global pass and apply one threshold. The entire compactable region is sent in exactly one classifier request; it is never split into chunks. Manual, threshold, and overflow compaction all calculate the line target directly from the prepared `compression_ratio`. Explicit protected lines form a hard keep floor.
+## Planning rungs and failure behavior
 
-The request uses the same provider path and failure handling as pi's summary compaction. Provider/API errors, overflow, abort, malformed output, or empty/unusable safe ranges fail after that one request. These failures write no compaction entry and schedule no continuation. During the post-tool preflight, failure or cancellation also stops the active loop before its follow-up provider request, is surfaced through the normal compaction lifecycle, and is not admitted to ordinary provider retry or model fallback. There is no semantic retry, critical rung, deterministic fallback, or deterministic target correction.
+Atomic asks a planner model, at the inherited session reasoning level and through the normal session stream/provider wrapper, to rank every eligible line in one global pass and apply one threshold. The entire compactable region is sent in one classifier request; it is never split into chunks. Manual, threshold, and overflow compaction all calculate the line target directly from the prepared `compression_ratio`. Explicit protected lines form a hard keep floor.
 
-A syntactically valid usable result is accepted once after safety-only normalization, even when it deletes fewer lines or tokens than requested. Atomic never adds or restores model-selected deletions to force a target. During overflow recovery, the existing one-shot compact-and-retry continuation may therefore surface unresolved overflow naturally. During a post-tool preflight, Atomic likewise does not add a second compaction strategy or attempt; if the rebuilt context is still known to exceed the provider's hard input limit, it refuses to send the follow-up request and reports the limit failure clearly.
+**The planner sends no output cap.** Only the provider's own context clamp bounds the response, so reasoning tokens cannot crowd out the deletion records. The reasoning level is inherited from the session and is never modified between attempts; a `model:level` suffix on a `fallbackModels` entry sets the level for that candidate only.
+
+Each planner attempt ends in exactly one typed outcome:
+
+| Outcome | Meaning | What happens next |
+|---|---|---|
+| ranked | Valid deletion records | Boundary written, `rung: "planned"` |
+| recovered | A length-truncated response with usable complete records | Boundary written silently, `rung: "planned"` |
+| overflowed | The planner request itself exceeded the context window, including a silent overflow that arrives as an ordinary `stop` or `length` completion whose usage already exceeds the window — classified before the response text is parsed, so valid-looking records or truncation recovery cannot mask it | The oldest region lines are withheld and the *same* model retried, repeatedly, until no strictly smaller view remains; the withheld head becomes a deterministic deletion |
+| rateLimited | A limit failure. `category` says which one — `rate_limited` for `429`/rate limit/overloaded/any `5xx`, `quota` for quota, billing, or usage-limit exhaustion — and `exhausted` separately reports whether a retry was actually scheduled | Advance to the next configured model |
+| unusable | Malformed output, no usable safe ranges, or reasoning starvation (`starved`) | Advance to the next configured model |
+| providerError | Any other provider or transport failure | Advance to the next configured model |
+
+Each trimmed retry halves the remaining suffix, so the walk is finite, and each view
+derives its own keep target from `compression_ratio`. Carrying the original
+whole-preparation target into a smaller view would ask it to keep every visible
+line — a request for zero deletions, whose obedient empty answer then hits the
+zero-usable-ranges rejection. The planner
+door returns validated line numbers, so no unvalidated model output leaves it,
+and the runner still validates once more before writing a boundary.
+
+Generic usage-limit wording, such as `The usage limit has been reached`, is
+classified as quota exhaustion (`exhausted: false`). That is a deliberate local
+addition rather than a copy of pi-ai's tables: pi-ai lists it in neither its
+retryable nor its non-retryable set, so it never spends a backoff, and reporting
+it as transient throttling would claim a retry budget that was never used.
+
+Unavailable credentials are ladder control flow, not an early failure. If the
+session model has no usable credentials, no request is attempted for it, that
+candidate is marked attempted, and a configured fallback with its own working
+credentials can still rank the lines. A load-bearing caller with no usable
+credentials anywhere still reaches the credential-free fresh rung; a recoverable
+caller reports the original authentication error and writes nothing.
+
+`settings.retry` still governs transport attempts *within* one candidate, with its existing backoff. When a candidate is exhausted, Atomic borrows the next entry from `settings.fallbackModels`, resolving that candidate's own credentials. Each candidate is tried at most once per compaction run, in configured order, keyed by `provider/model:thinkingLevel`. That walk is one monotonic pass over the configured list. Each position is inspected at most once — whether it fails to resolve to a model, has no usable credentials, duplicates an earlier identity, or yields a planner — so the order can never rewind to an earlier entry even if the registry or its credentials later change.
+
+Borrowing never mutates the session: no `agent.state.model` write, no model-change or thinking-level entry, no system-prompt refresh, no `model_changed`/`model_select`/`model_fallback_start`, and no `agent.continue()`. After compaction returns, `session.model` is exactly what it was before, and the main chat's own fallback bookkeeping is untouched.
+
+When every configured model is exhausted, what happens depends on how much the caller can afford to lose:
+
+| Call site | Urgency | Can borrow a model | Can start a fresh context window |
+|---|---|---|---|
+| `/compact`, `ctx.compact()`, `session.compact()`, RPC `compact` | recoverable | yes | no |
+| Threshold auto-compaction | recoverable | yes | no |
+| Overflow recovery | load-bearing | yes | yes |
+| Post-tool preflight | load-bearing | yes | yes |
+
+A recoverable compaction fails honestly: it writes no compaction entry, schedules no continuation, and reports the typed cause through `compaction_end`. Manual compaction's recoverable urgency is fixed at the door: `session.compact()` projects only compaction parameters, so no runtime property on a caller-supplied object can raise it to `load_bearing` and reach the destructive rung. A load-bearing compaction always completes, falling through to the **fresh context window** rung described below.
+
+A syntactically valid usable result is accepted once after safety-only normalization, even when it deletes fewer lines or tokens than requested. Atomic never adds or restores model-selected deletions to force a target. During overflow recovery, the existing one-shot compact-and-retry continuation may therefore surface unresolved overflow naturally.
+
+### The fresh context window rung
+
+`startNewContextWindow` is total: no provider, no credentials, no network, no failure mode. A region below the planner minimum reaches it only when the context is already known not to fit — overflow recovery, or a post-tool preflight whose projected context is over the provider hard input limit — because no planner change could make such a region rankable. A post-tool threshold crossing that still fits is a safe no-op instead: no boundary, no planner call, and the follow-up request proceeds unchanged. Clearing a context that fits would destroy conversation for nothing. It discards the compactable region and any prior durable summary, keeps explicit protected spans, and keeps the `preserve_recent` protected tail — dropping the tail only when the tail **alone** exceeds the provider hard input limit, in which case the boundary persists `firstKeptEntryId: null`. It emits the whole region as one deletion range and hands it to the same validation and reconstruction path as every other rung, so retained lines stay byte-identical.
+
+A committed fresh boundary stays visible even when the following provider hard-input-limit gate reports its own error: `compaction_end` carries `result` and `errorMessage` independently, and the boundary is shown before the status. The fresh rung destroys conversation, so it is loud: the boundary reads `✻ Context cleared (compaction degraded)` instead of `✻ Context compacted`, in the main chat and in attached workflow stage chat alike, and `details.rung` records `"fresh"` durably. The precise cause stays in the `0600` diagnostic sidecar.
+
+The ladder guarantees that *compaction* completes. It does not guarantee the *turn* succeeds: if every configured model is rate limited, the follow-up request will be too. What it buys is that a compaction failure does not additionally destroy the turn, that a healthy fallback model rescues quality when one exists, and that the retry starts from a small context.
+
+During a post-tool preflight, Atomic still gates the rebuilt context: if it is known to exceed the provider's hard input limit even after compaction, Atomic refuses to send the follow-up request and reports the limit failure clearly. The fresh rung's tail-dropping rule exists so that gate is reachable rather than hollow.
 
 ### Length-truncated response recovery
 
-When the planner model's output is truncated by `max_tokens` (indicated by `stopReason: "length"`), Atomic silently recovers complete newline-terminated deletion records from the truncated response. A deterministic line parser validates each completed line (those followed by a newline) against the strict `start,end` grammar. The final fragment after the last newline is always discarded — even if it looks syntactically complete — because EOF may have cut a multi-digit integer (e.g. `300,30` could have intended `300,305`). If any completed line has invalid syntax or zero usable records survive validation, recovery fails and the normal `RangePlanError` path applies.
+When the planner model's output is truncated at the provider's own limit (indicated by `stopReason: "length"`), Atomic silently recovers complete newline-terminated deletion records from the truncated response. Atomic sends no `max_tokens` of its own, so this reflects the provider's context clamp rather than a caller-imposed cap. A deterministic line parser validates each completed line (those followed by a newline) against the strict `start,end` grammar. The final fragment after the last newline is always discarded — even if it looks syntactically complete — because EOF may have cut a multi-digit integer (e.g. `300,30` could have intended `300,305`). If any completed line has invalid syntax or zero usable records survive validation, the attempt becomes an `unusable` outcome and the ladder advances.
 
 Example of truncated output:
 
@@ -114,19 +175,19 @@ Recovery yields `120,180` and `6,40`; discards `300,` without guessing. The plan
 
 Successful partial recovery is an ordinary successful compaction: no warning, banner, toast, or special status copy appears. The UI shows the normal spinner then `✻ Context compacted`.
 
-For operational observability, a private recovery diagnostic sidecar is written beside persisted sessions with `0600` permissions. It records the full raw response, stop reason, usage, request `maxTokens`, model metadata, recovered range count, and recovery category. The sidecar path is never surfaced in the success UI, error messages, or user-visible status. In-memory sessions and sidecar write failures do not affect the successful recovery.
+For operational observability, a private recovery diagnostic sidecar is written beside persisted sessions with `0600` permissions. It records the full raw response, stop reason, usage (including `usage.reasoning`), the request `maxTokens` (now always absent, since no cap is sent), model metadata, recovered range count, and recovery category. The sidecar path is never surfaced in the success UI, error messages, or user-visible status. In-memory sessions and sidecar write failures do not affect the successful recovery.
 
 ### Planner failure diagnostics
 
-For a persisted session, a failed planner call writes a JSON sidecar beside the session JSONL and includes its path in the `RangePlanError`, for example:
+For a persisted session, each failed planner attempt writes its own JSON sidecar beside the session JSONL and carries the path on the typed outcome. When a recoverable compaction exhausts every configured model, the resulting `RangePlanError` includes that path, for example:
 
 ```text
-Compaction range planning returned malformed output (diagnostic: /path/session-compaction-diagnostic-….json)
+Compaction range planning returned malformed output (diagnostic: /path/session-compaction-diagnostic-1785222000000-019fa7….json)
 ```
 
-The private sidecar uses `0600` permissions where supported and records the full planner response text, stop reason, provider error, usage, request `maxTokens`, timestamp, failure category, and non-secret model metadata. It does not record API keys, request headers, the planner prompt, or the numbered transcript request. The raw response itself may contain sensitive text if the model echoed input, so treat the sidecar with the same care as its adjacent session file.
+The private sidecar uses `0600` permissions where supported and records the full planner response text, stop reason, provider error, usage, the request `maxTokens` (absent — no cap is sent), timestamp, failure category, and non-secret model metadata for **the model that made that attempt**, so a run rescued by a fallback leaves per-model evidence. It does not record API keys, request headers, the planner prompt, or the numbered transcript request. The raw response itself may contain sensitive text if the model echoed input, so treat the sidecar with the same care as its adjacent session file.
 
-Diagnostic categories distinguish malformed output, valid output with no usable ranges, provider errors, and stream failures. In-memory sessions do not create sidecars. If the diagnostic write fails, Atomic preserves the original error and classification rather than replacing the planner failure.
+Diagnostic categories distinguish malformed output, valid output with no usable ranges, provider errors, stream failures, reasoning starvation (`starved`), transient rate limiting (`rate_limited`), quota exhaustion (`quota`), and context overflow (`context_overflow`) — overflow is a distinct typed outcome in code, so it is distinct in the durable record too rather than folded into a generic provider failure. When a *borrowed* fallback model produces the accepted ranking, a separate `<session>-compaction-success-<timestamp>-<id>.json` sidecar records that model and its effective thinking level, so a rescued run leaves evidence for both the model that failed and the model that succeeded. Quota, billing, and usage-limit exhaustion get their own `quota` category, so they stay distinguishable from transient throttling in the durable record and not only in provider text. A limit record additionally sets `rateLimitExhausted`, derived from observed retry activity: `true` only when a retry was actually scheduled, and `false` for quota or for a throttled request under a disabled or zero retry budget. Atomic classifies the whole HTTP `5xx` class as rate limiting, which is a local broadening — pi-ai lists only selected statuses, so it may schedule no backoff for one Atomic types this way, and `rateLimitExhausted` reports that fact rather than assuming it. Every sidecar filename carries both a timestamp and a per-attempt identifier, and is created exclusively, so two attempts inside the same millisecond — routine across overflow trims or a fast fallback walk — cannot overwrite each other's evidence. In-memory sessions do not create sidecars. If the diagnostic write fails, Atomic preserves the original classification rather than replacing the planner outcome.
 
 Interactive main chat and attached workflow stage chat treat `compaction_end` as the authority for cancellation and failure UI. A failed or cancelled `/compact` stops its spinner, shows the event-provided status or diagnostic path without a duplicate stack trace, writes no boundary, and leaves the session usable for another `/compact` attempt or a normal follow-up turn.
 
@@ -155,7 +216,20 @@ A successful run appends the existing pi-style `type:"compaction"` entry shape:
 }
 ```
 
-A `compaction` entry is active only when `details.strategy === "verbatim-lines"`. On rebuild, Atomic emits a visible custom-role boundary message containing the durable `summary`, followed by the original messages beginning at `firstKeptEntryId`. When no pre-boundary context-visible message is retained—such as with `preserve_recent: 0`—`firstKeptEntryId` is `null`. Messages appended after the boundary are always replayed. The boundary is converted to a user-role provider message and shown in the TUI as a collapsible compaction card.
+`details.rung` is one of `"planned"` (a model ranked the lines — the session model **or** a borrowed fallback, including silent partial recovery), `"extension"` (a `session_before_compact` override), or `"fresh"` (the compactable conversation was discarded and a new context window started). `details.plannerModel` is present **only** when a borrowed fallback model ranked the lines:
+
+```json
+"details": {
+  "strategy": "verbatim-lines",
+  "promptVersion": 3,
+  "rung": "planned",
+  "plannerModel": {"provider": "openai", "id": "gpt-5.1", "thinkingLevel": "high"}
+}
+```
+
+There is no format-version bump and no new entry type. Both `"fresh"` and `plannerModel` are additive: they are absent on every existing entry and on any compaction that used the session model, so old readers are unaffected. A `"fresh"` boundary that had to drop the `preserve_recent` tail persists `firstKeptEntryId: null`.
+
+A `compaction` entry is active only when `details.strategy === "verbatim-lines"`. On rebuild, Atomic emits one visible custom-role boundary message: the durable `summary` with the kept tail—the entries from `firstKeptEntryId` up to the boundary—serialized and concatenated onto its end. The tail is never restored as separate assistant/tool-result blocks, so a tail that starts or ends mid-turn cannot produce out-of-order provider blocks; images inside the tail ride along as image blocks on that same boundary message. When no pre-boundary context-visible message is retained—such as with `preserve_recent: 0`—`firstKeptEntryId` is `null` and the boundary carries the `summary` alone. Messages appended after the boundary are always replayed as real messages. The boundary is converted to a user-role provider message and shown in the TUI as a collapsible compaction card.
 
 Resume does not rerun planning or re-derive deletions: the exact compacted string and nullable tail boundary are already in JSONL. Existing records with a string `firstKeptEntryId` keep their original resume behavior. Legacy `context_compaction` logical-deletion records and old `compaction` summary records without the discriminator are inert archival data. Their historical omissions are not reapplied when an old session resumes.
 
@@ -185,8 +259,9 @@ After persistence, Atomic emits an observe-only event:
 
 ```typescript
 pi.on("session_compact", async (event) => {
-  console.log(event.result.rung, event.result.stats);
-  console.log(event.compactionEntry.details.strategy); // "verbatim-lines"
+  console.log(event.result.rung, event.result.stats);   // rung: "planned" | "extension" | "fresh"
+  console.log(event.result.plannerModel);               // set only when a fallback model was borrowed
+  console.log(event.compactionEntry.details.strategy);  // "verbatim-lines"
   console.log(event.fromExtension);
 });
 ```
@@ -365,6 +440,12 @@ pi.on("session_before_tree", async (event, ctx) => {
 
 See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
 
+## Summary request isolation
+
+Verbatim planning and branch summarization are standalone provider requests. Each receives a fresh routing session ID instead of reusing the chat's provider-affinity ID, and sets cache retention to `none` so it cannot write summary/planner prompts into the main prompt cache. Neither sends a `max_tokens` of its own. Existing API-key, header-only `ANTHROPIC_AUTH_TOKEN`, custom-header, abort, and bounded retry behavior still applies. These controls affect provider request routing/cache writes only; successful results are persisted through the normal Atomic session lifecycle.
+
+**Isolation is per model, not per session.** When compaction borrows a fallback model, that request is built with the borrowed candidate's own API key, headers, and base URL; the session model's credentials are never sent to another provider. The corollary is a real data-flow change: **a model listed in `settings.fallbackModels` may receive the compaction transcript.** The list is user-authored, so the set of providers that can see it is yours to control — remove an entry if you do not want it to see transcript content.
+
 ## Settings
 
 Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json` (legacy `.pi` paths are also supported):
@@ -381,7 +462,9 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `enabled` | `true` | Enable automatic Verbatim Compaction. |
-| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when completed-response usage or a prospective post-tool context exceeds the model's effective input budget minus this reserve. |
+| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when completed-response usage or a prospective post-tool context exceeds the model's effective input budget minus this reserve. It is an **input-side** reserve only and never caps planner output. |
+
+Compaction has no configuration key of its own for fallback borrowing: it reuses `settings.fallbackModels`, the same ordered `provider/model[:thinkingLevel]` list that main-chat model fallback walks. With no `fallbackModels` configured, compaction behaves as before: one planner model, then either an honest failure (recoverable) or a fresh context window (load-bearing).
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
 

package/docs/custom-provider.md

@@ -13,7 +13,6 @@ See these complete provider examples:
 
 - [`examples/extensions/custom-provider-anthropic/`](https://github.com/bastani-inc/atomic/tree/main/packages/coding-agent/examples/extensions/custom-provider-anthropic)
 - [`examples/extensions/custom-provider-gitlab-duo/`](https://github.com/bastani-inc/atomic/tree/main/packages/coding-agent/examples/extensions/custom-provider-gitlab-duo)
-- Built-in reference: `packages/cursor/` registers the experimental first-party Cursor provider with OAuth, model mapping, and a native `streamSimple` adapter without a local proxy.
 
 ## Table of Contents
 
@@ -313,9 +312,15 @@ After registration, users can authenticate via `/login corporate-ai`.
 
 Existing extension OAuth definitions keep their `login`, `refreshToken`, `getApiKey`, and optional `modifyModels` methods. OAuth refresh is serialized so concurrent requests do not overwrite each other's credentials.
 
+In isolated interactive mode, extension code and executable OAuth methods remain in the engine process. Atomic transports only the JSON-safe provider description (`id`, `name`, `loginLabel`, and `usesCallbackServer`) to the terminal process; it never serializes provider functions or acquired credentials and does not load the extension a second time in the frontend. `loginLabel` replaces the login dialog title, while `usesCallbackServer: true` exposes a redirect-URL paste field that races the browser callback. The engine executes the provider's login closure and correlates browser URLs, device codes, progress/info messages, prompts, selections, and manual-code callbacks with the originating login.
+
+After acquisition, the engine owns serialized credential persistence and logout. It publishes the authenticated provider against its already-loaded snapshot as soon as persistence succeeds; dynamic catalog and ambient-availability refreshes run separately under the model selector's deadline and never extend the login transaction. Logout similarly publishes stored-credential removal without invoking `refreshModels`; Atomic gives the provider's local remaining-auth probe a short deadline so extension code cannot keep the dialog open. The frontend applies the returned snapshot only after the engine transaction succeeds. Escape or Ctrl+C cancels only the matching login and leaves the prior credential/catalog intact. Built-in OAuth and direct, non-isolated extension OAuth use the same persistence and cancellation semantics; later provider registrations continue to override earlier registrations by ID.
+
+Intentional cancellation is quiet, including native `AbortError`, an aborted signal or its exact reason, nested abort causes, and the legacy exact `Login cancelled` error. Provider denial, timeout, network/protocol errors, malformed responses, token exchange failures, and storage failures remain visible. Catalog-refresh failures are reported by `/model` while cached models remain selectable; they do not turn a persisted login into a failed transaction.
+
 ## Dynamic model catalog refresh
 
-Providers whose catalogs change at runtime can add `refreshModels`. Atomic calls it during the asynchronous model refresh used by the model picker and authentication flows:
+Providers whose catalogs change at runtime can add `refreshModels`. Atomic calls it during the model picker's bounded asynchronous refresh, independently of authentication completion:
 
 ```typescript
 pi.registerProvider("corporate-ai", {
@@ -414,7 +419,7 @@ function streamMyProvider(
         totalTokens: 0,
         cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
       },
-      stopReason: "stop",
+      stopReason: "pending",
       timestamp: Date.now(),
     };
 
@@ -423,12 +428,20 @@ function streamMyProvider(
       stream.push({ type: "start", partial: output });
 
       // Make API request and process response...
-      // Push content events as they arrive...
+      // Push content events as they arrive, and set output.stopReason from the
+      // terminal event. A reason your provider sends that you do not map must
+      // become an error, not a silent "stop".
+      if (output.stopReason === "pending") {
+        throw new Error("Provider stream ended without a stop reason");
+      }
+      if (output.stopReason === "error" || output.stopReason === "aborted") {
+        throw new Error(output.errorMessage || "An unknown error occurred");
+      }
 
       // Push done event
       stream.push({
         type: "done",
-        reason: output.stopReason as "stop" | "length" | "toolUse",
+        reason: output.stopReason,
         message: output
       });
       stream.end();
@@ -465,6 +478,21 @@ Push events via `stream.push()` in this order:
 
 The `partial` field in each event contains the current `AssistantMessage` state. Update `output.content` as you receive data, then include `output` as the `partial`.
 
+### Stop Reasons
+
+`StopReason` is `"pending" | "stop" | "length" | "toolUse" | "error" | "aborted"`.
+
+Start the partial message at `"pending"`. It is the reason every in-flight message carries, and it says the terminal event has not arrived yet — it is not a default standing in for `"stop"`. Set the real reason when the provider says the turn ended, then push `done` with it.
+
+Two checks belong immediately before `done`:
+
+- a stream that reached the end while still `"pending"` never received a terminal event, so raise rather than report a stop that did not happen;
+- `"error"` and `"aborted"` are failures, so raise them with `output.errorMessage` and let the `catch` push an `error` event.
+
+`done` accepts only `"stop"`, `"length"`, and `"toolUse"`, which is exactly what those two checks leave, so the `as "stop" | "length" | "toolUse"` cast older implementations used is no longer needed.
+
+Map each raw reason your provider can send onto one of the five terminal values, and **raise on one you do not recognise** rather than falling back to `"stop"`. This is what the built-in providers do: an unmapped reason becomes a provider error naming the raw value, so a new truncation or safety signal is visible instead of arriving as a turn that looks like it finished normally. The optional `rawStopReason` field on `AssistantMessage` is where the provider's own string belongs when you want to keep it.
+
 ### Content Blocks
 
 Add content blocks to `output.content` as they arrive:
@@ -653,9 +681,6 @@ interface ProviderModelConfig {
   /** Default/effective context window size in tokens. */
   contextWindow: number;
 
-  /** Optional selectable context-window sizes in tokens. */
-  contextWindowOptions?: readonly number[];
-
   /** Maximum output tokens. */
   maxTokens: number;
 
@@ -668,12 +693,17 @@ interface ProviderModelConfig {
     supportsDeveloperRole?: boolean;
     supportsReasoningEffort?: boolean;
     supportsUsageInStreaming?: boolean;
+    supportsStrictMode?: boolean;
+    supportsOpenAIGrammarTools?: boolean;
+    /** Atomic alias for supportsOpenAIGrammarTools. */
+    supportsGrammarTools?: boolean;
     maxTokensField?: "max_completion_tokens" | "max_tokens";
     requiresToolResultName?: boolean;
     requiresAssistantAfterToolResult?: boolean;
     requiresThinkingAsText?: boolean;
     requiresReasoningContentOnAssistantMessages?: boolean;
     thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
+    supportsStrictTools?: boolean;
     chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
     cacheControlFormat?: "anthropic";
     sendSessionAffinityHeaders?: boolean;
@@ -689,4 +719,6 @@ The `cost` shape is equivalent to `Model<Api>["cost"]`. Base rates and every tie
 `openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`.
 `cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user/assistant text content.
 
+Capability flags are enforcement claims, not preferences. `supportsStrictMode` controls strict JSON-schema tools for OpenAI-compatible APIs; Anthropic/Bedrock use `supportsStrictTools`; `supportsOpenAIGrammarTools` controls OpenAI Lark/regex custom tools. Atomic also accepts `supportsGrammarTools` as a compatibility alias and synchronizes it to the canonical OpenAI name; when both disagree, the canonical field wins. Leave these fields unset/false unless the endpoint and selected model actually preserve and enforce the corresponding request shape. See [Extensions](/extensions#constrained-sampling) for exact `constrainedSampling` modes.
+
 For `openai-responses` providers, set `compat.sessionAffinityFormat` to `"openai"` for `session_id` plus `x-client-request-id`, `"openai-nosession"` to omit `session_id` while retaining `x-client-request-id`, or `"openrouter"` for `x-session-id`. Responses-compatible providers may also set `supportsToolSearch` when they support deferred tool loading.

package/docs/development.md

@@ -7,16 +7,15 @@ See [AGENTS.md](https://github.com/bastani-inc/atomic/blob/main/AGENTS.md) for a
 ```bash
 git clone https://github.com/bastani-inc/atomic
 cd atomic
-bun install
-bun run typecheck
-bun run check:file-length
+npm ci --ignore-scripts
+npm run typecheck
 ```
 
-This monorepo uses Bun for development commands; avoid npm/yarn/pnpm except for npm registry publishing. Run package scripts from the monorepo root or package directory with Bun, for example:
+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
-bun run test:unit
-bun run --cwd packages/coding-agent build
+npm run test:unit
+npm run build --workspace=@bastani/atomic
 ```
 
 Atomic keeps the caller's current working directory when launched from development wrappers.
@@ -61,17 +60,17 @@ Set `ATOMIC_TIMING=1` when profiling startup. Normal interactive launches print
 ## Testing
 
 ```bash
-bun run typecheck                 # Type-check the monorepo
-bun run check:file-length         # Enforce the tracked TS/JS/Rust 500-line limit
-bun run test:unit                 # Run unit tests
-bun run test:integration          # Run integration tests
-bun run test:all                  # Run all tests
-# Run package Vitest tests
-bun run --cwd packages/coding-agent test -- test/specific.test.ts
+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 test --workspace=@bastani/atomic -- test/specific.test.ts
+# Run its Bun-hosted half. Required: the SQLite selector tests load bun:sqlite,
+# which the shipped binary has and Node does not.
 ```
 
-The file-length gate scans tracked `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, and `.rs` files via `git ls-files`, falls back to a recursive walk outside Git, and counts physical lines with a no-final-newline correction. Only generated/vendored path globs (`node_modules`, `dist`, `target`, `binaries`, `.git`, `vendor`, minified bundles, and the bundled third-party `packages/workflows/skills/impeccable/**` skill) plus first-five-line generated markers are excluded.
-
 ## Deterministic installs
 
 `@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:

package/docs/docs.json

@@ -18,8 +18,10 @@
           "quickstart",
           "usage",
           "providers",
-          "security",
+          "environment-variables",
+          "llama-cpp",
           "containerization",
+          "security",
           "settings",
           "keybindings",
           "sessions",
@@ -37,7 +39,15 @@
           "prompt-templates",
           "themes",
           "packages",
-          "models",
+          {
+            "group": "Models",
+            "pages": [
+              "models",
+              "models/model-selection",
+              "models/pareto-efficiency",
+              "models/artificial-analysis-index"
+            ]
+          },
           "custom-provider"
         ]
       },

package/docs/environment-variables.md

@@ -0,0 +1,37 @@
+# Environment Variables
+
+Atomic accepts environment variables for configuration, provider credentials, and subprocess context. Atomic-prefixed application variables take precedence over their legacy Pi aliases when both are set.
+
+## Application configuration
+
+| Atomic variable | Legacy alias | Purpose |
+|---|---|---|
+| `ATOMIC_CODING_AGENT_DIR` | `PI_CODING_AGENT_DIR` | Agent/config directory; default `~/.atomic/agent` |
+| `ATOMIC_CODING_AGENT_SESSION_DIR` | `PI_CODING_AGENT_SESSION_DIR` | Session directory; `--session-dir` takes precedence |
+| `ATOMIC_PACKAGE_DIR` | `PI_PACKAGE_DIR` | Package directory override |
+| `ATOMIC_OFFLINE` | `PI_OFFLINE` | Disable startup network operations |
+| `ATOMIC_SKIP_VERSION_CHECK` | `PI_SKIP_VERSION_CHECK` | Skip automatic startup version checks; explicit self-update still checks |
+| `ATOMIC_TELEMETRY` | `PI_TELEMETRY` | Enable/disable install/update telemetry |
+| `ATOMIC_REDUCED_MOTION` | `PI_REDUCED_MOTION` | Use static reduced-motion presentation |
+
+`PI_CACHE_RETENTION=long` is a provider/upstream prompt-cache option and intentionally has no Atomic-prefixed alias. `VISUAL` and `EDITOR` select the Ctrl+G external editor when `externalEditor` is unset.
+
+## Provider credentials
+
+Provider keys include `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `GEMINI_API_KEY`, AWS/Bedrock credentials, and the variables listed in [Providers](/providers#environment-variables-or-auth-file). `ANTHROPIC_AUTH_TOKEN` is a distinct header-only bearer credential for Anthropic-compatible gateways: Atomic sends `Authorization: Bearer …` without requiring or inventing an API key, including normal turns, isolated execution, branch summaries, and Verbatim Compaction. Custom headers remain independent.
+
+## Bash session environment
+
+Every built-in, factory-created, direct, foreground/background, workflow-stage, and isolated bash execution receives one execution-time snapshot:
+
+| Atomic variable | Exact Pi alias | Value |
+|---|---|---|
+| `ATOMIC_SESSION_ID` | `PI_SESSION_ID` | Active session ID |
+| `ATOMIC_SESSION_FILE` | `PI_SESSION_FILE` | Active JSONL file; omitted for unsaved/ephemeral sessions |
+| `ATOMIC_PROVIDER` | `PI_PROVIDER` | Active provider; omitted when no model is selected |
+| `ATOMIC_MODEL` | `PI_MODEL` | Active model ID; omitted when no model is selected |
+| `ATOMIC_REASONING_LEVEL` | `PI_REASONING_LEVEL` | Active reasoning level |
+
+Atomic clears these ten reserved names before overlaying the current snapshot, preventing stale metadata from another session or workflow stage. Unrelated inherited/caller variables remain intact. The snapshot is taken when execution begins, so a resumed session or later model change is reflected. SDK `createBashTool()` exposes it by default; set `exposeSessionEnvironment: false` to opt out.
+
+See [Using Atomic](/usage#environment-variables) and [RPC direct bash](/rpc#bash) for execution and streaming behavior.