@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## [Unreleased]
 
+## [0.9.11-alpha.6] - 2026-07-28
+
+### Added
+
+- Added execution-time session metadata to built-in, SDK/factory, direct, workflow-stage, and isolated bash execution through `ATOMIC_SESSION_ID`, `ATOMIC_SESSION_FILE`, `ATOMIC_PROVIDER`, `ATOMIC_MODEL`, and `ATOMIC_REASONING_LEVEL`, with exact `PI_*` compatibility aliases and safe omission of unsaved session files. Direct RPC bash now emits request-correlated, ordered `bash_execution_update` events that distinguish stdout from stderr, supports concurrent requests and per-request cancellation, and keeps streaming, cancellation, one terminal response, and exactly-once starting-session persistence intact across new/switch/import/fork/clone session replacement and RPC shutdown ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Added end-to-end constrained tool sampling to public extension/SDK tool definitions, wrappers, inspection, isolated transport, and model catalogs: strict JSON Schema supports `prefer`/`require`, OpenAI grammar tools support Lark/regex variants, omitted versus explicitly present optional properties remain distinguishable, and `supportsStrictMode`, `supportsStrictTools`, canonical `supportsOpenAIGrammarTools`, plus Atomic's `supportsGrammarTools` alias prevent false enforcement claims. Typed RPC model listings expose these flags through additive optional `ModelInfo.compat` ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Added Claude Opus 5 to Anthropic and Amazon Bedrock catalog paths with catalog-advertised adaptive thinking/`xhigh`, Bedrock inference profiles, prompt caching, strict-tool metadata, and preserved AWS validation errors. Custom message renderers now receive `outputPad` in normal and isolated-engine paths ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Added a compaction rung ladder so a compaction that must succeed always does. The range planner now returns typed outcomes (`ranked`, `recovered`, `rateLimited`, `unusable`, `overflowed`, `providerError`) instead of ranges-or-throw, and reasoning starvation is a distinct `starved` diagnostic category rather than an untyped empty plan. When a planner attempt ends terminally, Atomic borrows the next entry from `settings.fallbackModels` for one planner request, resolved with that candidate's own API key, headers, and base URL; borrowing is planner-only and never changes the session model, thinking level, model history, or main-chat fallback bookkeeping, and never calls `agent.continue()`. A planner request that itself overflows now withholds the oldest region lines and retries the same model until no strictly smaller view remains, with the withheld head recorded as a deterministic deletion and each trimmed view deriving its own keep target from `compression_ratio`. Silent overflows that arrive as an ordinary `stop` or `length` completion are classified before the response text is parsed, so valid-looking records cannot mask them. When every configured model is exhausted, a load-bearing compaction (overflow recovery, post-tool preflight) starts a fresh context window: a total, model-free rung that discards the compactable region and prior summary, keeps explicit protected spans, and keeps the `preserve_recent` tail unless retaining it would still exceed the provider hard input limit. That rung is loud (`✻ Context cleared (compaction degraded)`) and durable (`details.rung: "fresh"`), and a borrowed planner is recorded in `details.plannerModel` and on `compaction_end`. Manual `/compact` and threshold auto-compaction remain recoverable: they may borrow a model but can never clear context. Diagnostics gain `starved`, `rate_limited`, and `context_overflow` categories plus `rateLimitExhausted`, which separates spent retry backoff from quota/billing exhaustion, and a borrowed planned success writes a `compaction-success` sidecar naming the model that ranked the lines. Every sidecar filename now carries a per-attempt identifier and is created exclusively, so two attempts inside one millisecond keep separate durable evidence instead of overwriting each other. Generic usage-limit wording is classified as quota exhaustion rather than transient throttling, because pi-ai never schedules a backoff for it. Unavailable credentials advance the ladder instead of ending the compaction, so a fallback with its own credentials can still rank the lines and a load-bearing caller still reaches the fresh rung. A compactable region below the planner minimum reaches the fresh rung only when the context is already known not to fit — overflow recovery, or a post-tool preflight over the provider hard input limit — so one oversized tool result can no longer strand a mid-turn preflight while a threshold crossing that still fits stays a safe no-op instead of clearing context. The fallback walk is one monotonic pass over the configured list, so no position is inspected twice and the order cannot rewind. Quota exhaustion is now typed and recorded separately from transient throttling (`PlannerOutcome.rateLimited.category`, and a `quota` diagnostic category), independently of whether a retry was actually scheduled. The fresh rung keeps the `preserve_recent` tail unless the tail alone exceeds the hard input limit. `rateLimited.exhausted` and the `rateLimitExhausted` sidecar field are now derived from observed retry activity rather than assumed, and the whole HTTP `5xx` class is classified as rate limiting. A `fresh` boundary is no longer swallowed by an earlier `planned` boundary with identical text, because rung identity is part of boundary deduplication. **A configured fallback model may now receive the compaction transcript.**
+
+### Breaking Changes
+
+- Removed all Atomic-specific GitHub Copilot handling. `github-copilot` is now an ordinary upstream provider sourced entirely from `@earendil-works/pi-ai`'s `githubCopilotProvider()`, matching pi exactly. Dropped: the live CAPI `GET /models` catalog fetch and its 30-minute disk cache, the bundled static CAPI limit snapshot, dynamic Copilot model synthesis, `COPILOT_API_TARGET` / `GITHUB_COPILOT_BASE_URL` / `GITHUB_SERVER_URL` enterprise and GHE base-URL routing, the `X-GitHub-Api-Version: 2026-06-01` header, the Copilot Gemini tool-schema sanitizer, the Copilot Anthropic `message_stop` SSE repair, the Copilot Gemini reasoning-details interceptor, flattened Copilot Gemini tool-argument normalization, and Copilot prompt-limit error guidance. Model metadata now comes verbatim from the bundled pi catalog, and `COPILOT_GITHUB_TOKEN` is read by upstream's own env-key auth. Because pi's bundled context windows can exceed what Copilot's API enforces, long sessions on affected models may overrun the server-side cap instead of compacting first ([#1608](https://github.com/bastani-inc/atomic/issues/1608)).
+- Removed the short/long context-window selection feature, which upstream pi does not have. Dropped: the `contextWindowOptions` / `defaultContextWindow` / `maxInputTokens` model fields and their `Model<Api>` augmentation, the `/model` context-window picker, the `--context-window` CLI flag, the `defaultContextWindow` and `defaultContextWindows` settings, the `set_context_window` and `get_available_context_windows` RPC commands, the `context_window_changed` event, the `context_window_change` session-journal entry, the `contextWindow` / `contextWindowStrict` SDK and workflow-stage options with their `contextWindowWarning` / `contextWindowError` results, `AgentSession.setContextWindow()` / `getAvailableContextWindows()` / `supportsContextWindowSelection()`, the `parseContextWindowValue` / `formatContextWindow` / `selectContextWindow` / `getSupportedContextWindows` / `getModelDefaultContextWindow` / `withContextWindowOptions` / `normalizeContextWindowOptions` / `validateContextWindowValue` root exports, and the `(1m)` / `(long)` context token in subagent and workflow model strings. A model's `contextWindow` is now a single value taken from its catalog entry.
+- Changed the published `runVerbatimCompaction` SDK export to a request object. Positional `apiKey`, `headers`, `signal`, `thinkingLevel`, and `options` collapse into `runVerbatimCompaction(preparation, model, { resolveAuth, signal, thinkingLevel, urgency, ...options })`. Pre-resolved credentials become a `resolveAuth(model)` callback because a borrowed fallback model needs its own credentials, and `urgency` is required with no default so only a `load_bearing` caller can reach the context-destroying fresh rung. Migrate with `await runVerbatimCompaction(prep, model, { resolveAuth: options.resolvePlannerAuth, signal, urgency: "recoverable", ...options })`. The internal `planDeletedLineRanges` signature and return type also changed; it is not exported from the package root. Compaction settings, `reserveTokens` semantics and defaults, the auto-compaction threshold, `settings.retry` behavior, the persisted `CompactionEntry` shape, resume, and the `session_before_compact`/`session_compact` hooks are all preserved; `details.rung` widens additively to a third value and `details` gains one optional field.
+
+### Changed
+
+- Reworked interactive startup and ordinary working motion around Atomic's revision-3 identity system: the ∀ banner assembles inward in whole-column steps before its identity and manifesto beat land; main and workflow-stage work surfaces keep the exact one-cell `∀` visible while following a pronounced, theme-aware dark → accent → bright/bold → accent → dark luminance ramp at an 88ms cadence and retaining all 453 original randomized whimsical working verbs. Optional partial theme palettes can specify any phase exactly—including the approved Catppuccin Mocha prototype and terminal indices 0–255—while omitted tones derive from semantic selected-surface, accent, and text roles. `NO_COLOR` retains regular/bold activity without foreground-color escapes; reduced motion keeps a static regular accent `∀`; extension indicator frame and interval values remain verbatim while their phase/cadence restarts each turn; and factual status/prompt/receipt surfaces keep precedence. The inline icon and longest message fit tested standard/64-column layouts ([#1883](https://github.com/bastani-inc/atomic/issues/1883)).
+- Removed the fixed 1 MiB size limit from RPC and isolated interactive-engine JSONL transport. Commands, responses, events, queued writes, and render frames now pass through in full instead of being rejected, dropped, or truncated; clients remain responsible for the memory and latency cost of large records ([#1985](https://github.com/bastani-inc/atomic/issues/1985)).
+- Added OpenRouter PKCE and Kimi Code device subscription login to Atomic's provider-metadata-driven `/login` flow, including direct provider routing, isolated engine-owned extension OAuth discovery/acquisition, correlated UI callbacks and cancellation, transactional persistence/rollback, automatic Kimi refresh, logout, and immediate post-login model refresh without transporting credentials or executable provider functions to the frontend ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Updated all active Pi runtime declarations and resolved artifacts to 0.82.1. Dynamic pi.dev catalogs now revalidate with ETags and retain cached data on empty `304` responses; newer bundled catalogs beat stale overlays; llama.cpp catalogs persist across restarts, remain selectable while a failed first online refresh reports its original error, and use loaded context as their output limit; and `/model` reloads layered `.pi` then `.atomic` model configuration on every open ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Updated the bundled user documentation for the current subagent, workflow-stage, reviewer, and `prompt-engineer` prompt contracts: outcome-first agent and stage structure, evidence-grounded reporting, query-last artifact ordering, selective delegation, deterministic `stop_review_loop` derivation, explicit output/stop rules, and the removal of response prefilling and private-reasoning requests for current GPT-5.6, Claude Opus 5, and Claude Fable 5 compatibility.
+
+### Fixed
+
+- Fixed a mid-turn compaction leaving the turn unsendable, which the provider rejected with an unrecoverable `400 ... each tool_use must have a single result. Found multiple tool_result blocks with id ...`. The post-tool compaction preflight returned the agent's live internal message array, so the agent loop adopted it as the working context for the rest of the run; from the next turn on, both the loop and the message reducer appended to that one array and duplicated every assistant message and tool result. The preflight now returns its own copy. As defence in depth, provider conversion additionally keeps only the first tool result for each announced `tool_use` id, alongside the existing orphan-result repair, and a structural guard runs immediately before conversion and fails with a descriptive Atomic-side error naming any `tool_use` id that appears in more than one assistant message rather than letting the request 400 ([#2051](https://github.com/bastani-inc/atomic/issues/2051)).
+- Fixed compaction repairs from the rung-ladder review: manual `/compact` now projects only compaction parameters, so no runtime property on a caller-supplied object can raise its urgency to `load_bearing` and reach the context-destroying rung; a committed `fresh` boundary stays visible in main and attached workflow stage chat even when the following provider hard-input-limit gate reports its own error, because `compaction_end` carries `result` and `errorMessage` independently; and a post-tool threshold crossing whose context still fits ends as a successful no-op rather than raising "no compactable transcript entries were available" and killing the active turn.
+- Fixed compaction rebuilding the retained recent messages as structured message blocks after the boundary. The `preserve_recent` tail is now serialized with the same transcript grammar as the compacted region and concatenated onto the end of the boundary string, so a compacted context reaches the provider as one message. A kept tail that started or ended mid-turn — an unpaired tool result, or a trailing tool call whose result was compacted away — can no longer produce out-of-order provider blocks and a rejected request. Tail serialization is lossless: retained tool results keep their full text rather than being truncated at 16k characters, and retained images stay as image blocks on the boundary message instead of collapsing to an `[image]` marker. Applies to manual, automatic, mid-turn post-tool, and extension-supplied compaction, and to sessions resumed from existing boundaries.
+- Fixed shared, main, and workflow-stage Atomic working animation lifecycle safety. Every agent/turn starts from phase zero on a fresh cadence, restoring the ordinary indicator after an extension override resets its phase/cadence, and turn, interrupt/pause, terminal, error, replacement, and disposal cleanup fence both built-in and delegated timer callbacks without leaks or stale repaint. Reduced motion remains a static regular accent `∀` without a timer ([#1883](https://github.com/bastani-inc/atomic/issues/1883)).
+- Fixed Windows and limited-color branding fidelity: caller-supplied workflow palettes now honor the detected terminal color mode, partial ANSI-index palettes derive omitted tones from indices 0–15, and Catppuccin Mocha starts its pulse at readable truecolor and 256-color contrast. Startup now honors `NO_COLOR` across the mark, metadata, and manifesto, remains nonblank below the mark width, and settles through the real input chain before Ctrl+C is consumed. Bundled themes declare and validate against Atomic's rebranded local schema, standalone binaries link to Atomic releases, and reachable startup/crash diagnostics use Atomic branding while legacy `.pi` paths, `PI_*` aliases, migrations, and service integrations remain compatible ([#1883](https://github.com/bastani-inc/atomic/issues/1883)).
+- Fixed inherited `.pi` extensions conflicting with Atomic-bundled resources: exact-name tool, command, prompt, flag, and shortcut overlaps now keep Atomic's bundled registration without disabling unrelated extension features, interactive startup consolidates overlaps into one warning, and isolated TUI discovery again matches print/RPC while preserving explicit `.atomic` overrides and agent-directory isolation ([#1955](https://github.com/bastani-inc/atomic/issues/1955)).
+- Fixed fast named workflows leaving a stale “still running” parent-chat claim when a terminal lifecycle notice arrives before the launch result or during final text. The opt-in lifecycle path now commits one context-excluded display card before send admission, preserves the assistant call → `status=running` result order, and delivers a separate hidden reconciliation at a native safe boundary; queue clearing, ordinary aborts, stage-session transfer, persistence retries, and fail-closed session teardown retain that reconciliation without interrupting unrelated active text, invalidating a session too early, or duplicating the lifecycle card.
+- Fixed the bundled workflow UI and control surfaces after fresh-process nested resume: input-bound child boundaries now retain stable graph identity, ordering, edges, lifecycle state, and true child-owner targets even when parallel dispatch order reverses; malformed or aliased topology and non-atomic boundary histories fail closed before routing. Completed inspection stays available without a retained chat, retained child follow-up remains detached from execution, and colliding child-local ids or names are reported as ambiguous instead of routing to the first stage.
+- Fixed queued steering, follow-up, trigger-turn custom/batched/interrupt messages, async deliveries, and user prompts escaping an interactive or workflow pause. Escape/Ctrl+C and controlled workflow pause now synchronously hold every raw queued item before abort, preserve content, optional data, duplicates, message type, display state, and per-queue order across fallback session transfer, gate late arrivals and continuation, serialize pause/resume with abort settlement, and release exactly once through the existing explicit resume boundary. `AgentSession` now publicly exposes `queuedMessagesPaused`, `pauseQueuedMessages()`, and `resumeQueuedMessages(): Promise<boolean>`; resume reports whether raw held work was released but never starts a turn. Clearing or restoring the final visible item leaves the pause gate closed, rejected abort boundaries block one release attempt before an explicit retry, and transferred interrupt turns serialize on the live owner. Paused protected reconciliation is persisted directly during shutdown without a model turn, while non-paused protocol-sensitive disposal remains fail-closed. Idle Ctrl+C clear/double-press exit and explicit final dequeue remain reachable without silently releasing held work; completed post-mortem stage chat releases its conversation-only hold on the next ordinary submission without changing terminal workflow state ([#1983](https://github.com/bastani-inc/atomic/issues/1983)).
+- Fixed tool-only workflows being reported failed after durable `ctx.tool()` side effects had completed. Root finalization now waits for admitted tools, promotes failures left by a fulfilled body with an explicit selected tool-node origin, and preserves ordinary body rejections without guessing a tool origin from indistinguishable native-promise values; the workflow graph and completed-run inspector show non-attachable tool nodes including cached replay state, and reopening completed history remains lifecycle-silent while preserving live declared outputs and preventing duplicate side effects. Retained `ctx.tool` calls made after any terminal executor path now reject safely before side effects, transient legacy child-topology migration failures no longer fail cached replay or later DBOS flush, nested child tools appear in no-target status with owning-run metadata, and completed retained-session stage chat is again reachable from graph keyboard, mouse, switcher, and hint surfaces without making tools attachable ([#1991](https://github.com/bastani-inc/atomic/issues/1991)).
+- Fixed reusable extension chat hosts to show and animate Atomic's Working indicator immediately when an idle prompt is submitted, preserving it across prompt attachment and agent startup while still stopping cleanly when no agent turn begins. This keeps retained terminal workflow-stage chats visibly active throughout follow-up processing ([#1982](https://github.com/bastani-inc/atomic/issues/1982)).
+- Fixed messages queued before automatic compaction remaining stuck afterward until Escape was pressed; successful compaction now resumes queued input automatically once active work settles ([#1984](https://github.com/bastani-inc/atomic/issues/1984)).
+- Fixed a workflow lifecycle card surviving a crash or a failed prompt start while its hidden reconciliation turn was lost. The durable card now carries its recovery marker in the same atomic session append, a rejected prompt start requeues only the hidden turn, and the next session start replays exactly one unresolved correction without duplicating the visible card. Physical session appends also roll back a partial single-entry or initial-batch write to the exact prior file length, so a later retry cannot inherit a malformed JSONL tail, duplicate id, or phantom parent ([#2021](https://github.com/bastani-inc/atomic/issues/2021)).
+- Fixed compaction status surfaces using the generic braille spinner instead of Atomic's `∀` identity. Main-session auto/manual compaction, summarization retry attempts, and workflow-stage compaction now pulse the one-cell `∀` on the shared 88ms luminance ramp, and the workflow-stage message carries the same `(esc Cancel)` hint as the main session.
+- Fixed Anthropic `ANTHROPIC_AUTH_TOKEN` header-only bearer authentication across catalog availability, direct/default/restored model selection, cycling, RPC/isolated model listings, ordinary requests, custom headers, branch summaries, and Verbatim Compaction without synthesizing an API key or `x-api-key`; also inherited Radius gateway OAuth routing and underlying model-auth cause details ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Fixed intentional OAuth cancellation surfacing as login failure. Escape/Ctrl+C, native `AbortError`, exact signal reasons, nested abort causes, and the legacy exact cancellation error now restore the interactive editor quietly for built-in and extension OAuth in direct and isolated sessions, while denial, timeout, network/protocol, token exchange, persistence, and refresh failures remain visible ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Fixed the remaining applicable Pi 0.82.1 coding-agent parity issues: complete literal model IDs win before thinking-suffix or glob parsing, unavailable scoped models remain removable, TUI logs honor the configured Atomic/Pi agent directory, the shared async Ctrl+G/extension editor uses private exact-file storage without temp scans and honors configured/environment/platform editor precedence, sibling package resources display relative paths, explicit self-update bypasses startup skip flags, summaries use fresh routing IDs without prompt-cache writes, Wayland copy falls back after `wl-copy` failure, and context discovery skips directories named like context files ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Fixed the compiled Atomic package CLI crashing before TUI startup when invoked from another working directory after standalone assets had placed `package.json` in `dist/`. Built-in themes, interactive images, and HTML-export templates now resolve from the actual `src/` or `dist/` module layout without producing a duplicated `dist/dist` path, while package-directory overrides and standalone adjacent assets remain supported ([#1995](https://github.com/bastani-inc/atomic/issues/1995)).
+- Fixed the external editor failing on Windows whenever the editor path, its arguments, or the temporary prompt path contained a space. Node does not quote arguments when spawning through a shell, so `cmd.exe` split values such as `C:\Program Files\Microsoft VS Code\Code.exe` into separate arguments; each token is now quoted with the Windows command-line rules before launch.
+- Fixed repeated `/compact` presses starting several overlapping compactions and the resumed-session prompt showing no progress before the compaction spinner appeared. `AgentSession.compact()` is now single-flight: a second manual request joins the run already in flight and receives its result instead of starting another model call, emitting a duplicate `compaction_start`/`compaction_end` pair, or appending a second compaction boundary; a manual request made while an automatic compaction is running fails fast with a clear message rather than racing it; and only the owning call clears the abort controller and reconnects agent events, so `esc` still cancels the live run for every waiter. In the interactive TUI, `/compact` typed while a compaction is already running now warns instead of starting or queueing another one, a repeated `compaction_start` releases the previous spinner and keeps the original Escape handler, and the working indicator stays visible continuously from prompt submit through deferred extension startup and prompt preflight until the agent turn or compaction indicator takes over.
+- Fixed interactive startup output ordering so the `RESOURCES` disclosure remains above extension notifications and every other startup warning or notice on eager, deferred, and immediate-prompt paths.
+- Fixed reasoning tokens being able to fail a compaction outright. The planner used to cap its own request at `0.8 × reserveTokens` — an input-side reserve reused as an output cap — so a high-reasoning session could spend the entire budget thinking and return no deletion records, producing `Compaction range planning produced no usable deleted ranges`; during a mid-turn post-tool preflight that killed the active turn. The planner now sends no `max_tokens` at all, leaving the provider's own context clamp as the only bound, and `PlannerBudget.maxTokens` is typed `undefined` so the cap cannot be reintroduced without changing the type. The session reasoning level is still inherited and is never modified between attempts. A starved or rate-limited planner response no longer ends compaction: it advances the rung ladder to a configured fallback model and, for a load-bearing compaction, to a fresh context window. Branch summarization received the same budget fix — its `2048` output cap is removed and it now inherits the session thinking level, while its input-side `reserveTokens` behavior is unchanged. Fallback borrowing is now a single ordered pass: a candidate whose credentials are unavailable is consumed rather than re-inspected, so no candidate has its auth resolved twice and the configured order cannot rewind. `startNewContextWindow` returns exactly a `CompactedTranscript`; the tail decision it used to expose is runner bookkeeping and travels on `CompactionRungResult.keptTail`. Zero-usable-ranges output is still rejected: no unvalidated model output ever becomes a compaction boundary, and every retained line stays byte-identical on every rung.
+
+## [0.9.11-alpha.5] - 2026-07-23
+
+### Changed
+
+- Added Orwell's six writing rules from “Politics and the English Language” to the core default system prompt's `Guidelines` section so every standard Atomic session receives them, while removing the bundled workflow guidance's requirement to announce an inline-or-workflow mode before the first tool call.
+
 ## [0.9.11-alpha.4] - 2026-07-23
 
 ### Changed
@@ -78,6 +132,7 @@
 - Fixed newly authenticated providers remaining unavailable in the model selector until Atomic restarted. API-key and OAuth login now reload the isolated engine's credentials and refresh its authoritative model catalog immediately, including credential-dependent dynamic discovery ([#1918](https://github.com/bastani-inc/atomic/issues/1918)).
 - Added actionable `/logout` and `/login` recovery guidance when OpenAI Codex invalidates or revokes a locally unexpired OAuth token, and prevented an earlier WebSocket-to-SSE transport diagnostic from making the definitive authentication rejection retryable ([#1922](https://github.com/bastani-inc/atomic/issues/1922)).
 
+
 ## [0.9.10] - 2026-07-20
 
 ### Breaking Changes

package/README.md

@@ -91,6 +91,8 @@ For each built-in provider, Atomic maintains a list of tool-capable models, upda
 - Anthropic Claude Pro/Max
 - OpenAI ChatGPT Plus/Pro (Codex)
 - GitHub Copilot
+- OpenRouter (browser PKCE, optional key minting)
+- Kimi Code (device authorization with token refresh)
 
 **API keys:**
 - Anthropic
@@ -123,6 +125,8 @@ For each built-in provider, Atomic maintains a list of tool-capable models, upda
 
 See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
+Atomic's Pi 0.82.1 model/runtime surface includes Claude Opus 5 on Anthropic and Bedrock, model-capability-aware strict JSON-schema and OpenAI Lark/regex tool sampling, ETag-revalidated cached catalogs, persisted llama.cpp models, and live layered `.pi`/`.atomic` `models.json` reload whenever `/model` opens. A populated `ANTHROPIC_AUTH_TOKEN` makes Anthropic models available/selectable while sending header-only bearer auth—with no synthesized API key or `x-api-key`—across chat and summary/compaction requests. Typed RPC model listings expose constrained-sampling flags through optional `ModelInfo.compat`; capability flags are enforcement claims, so unsupported `require` constraints fail instead of being silently weakened. See [models](docs/models.md), [providers](docs/providers.md), [RPC](docs/rpc.md#get_available_models), and [extensions](docs/extensions.md#constrained-sampling).
+
 **Custom providers & models:** Add providers via `~/.atomic/agent/models.json` (legacy `~/.pi/agent/models.json` also works) if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
 
 ---
@@ -187,15 +191,16 @@ See `/hotkeys` for the full list. Customize via `~/.atomic/agent/keybindings.jso
 
 | Key | Action |
 |-----|--------|
-| CTRL+C | Clear editor |
-| CTRL+C twice | Quit |
-| Escape | Cancel/abort |
+| CTRL+C | Interrupt active or queued work; when idle, clear editor |
+| CTRL+C twice while idle | Quit |
+| Escape | Abort active work and hold queued messages |
 | Escape twice | Open `/tree` |
 | CTRL+L | Open model selector |
 | CTRL+P / SHIFT+CTRL+P | Cycle scoped models forward/backward |
 | SHIFT+Tab | Cycle thinking level |
 | CTRL+O | Collapse/expand tool output |
 | CTRL+T | Collapse/expand thinking blocks |
+| CTRL+G | Edit chat or extension-editor text through the configured, environment, or platform external editor |
 
 ### Message Queue
 
@@ -203,8 +208,8 @@ Submit messages while the agent is working:
 
 - **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls
 - **ALT+Enter** queues a *follow-up* message, delivered only after the agent finishes all work
-- **Escape** aborts and restores queued messages to editor
-- **ALT+Up** retrieves queued messages back to editor
+- **Escape** or **Ctrl+C** aborts active/queued work and pauses queued messages in place; submitting the next ordinary chat message resumes them once in their original per-queue order. After the abort settles, a later idle Ctrl+C still clears the editor and a second quick idle press quits without dequeuing the hold
+- **ALT+Up** explicitly retrieves queued messages back to the editor instead of resuming them
 
 On Windows Terminal, `ALT+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so Atomic can receive the follow-up shortcut.
 
@@ -636,6 +641,8 @@ atomic --thinking high "Solve this complex problem"
 | `PI_CACHE_RETENTION` | Provider/upstream-specific prompt-cache retention knob; set to `long` where supported. This is not an `ATOMIC_*` alias and has no Atomic-prefixed equivalent. |
 | `VISUAL`, `EDITOR` | External editor for CTRL+G |
 
+Bash commands also receive an execution-time session snapshot through `ATOMIC_SESSION_ID`, `ATOMIC_SESSION_FILE` (omitted for unsaved sessions), `ATOMIC_PROVIDER`, `ATOMIC_MODEL`, and `ATOMIC_REASONING_LEVEL`. The exact `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL` aliases carry identical values. Unrelated inherited or caller-supplied environment variables are preserved.
+
 ---
 
 ## Contributing & Development

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.11-alpha.4",
+  "version": "0.9.11-alpha.6",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.81.1"
+    "@earendil-works/pi-tui": "^0.82.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.11-alpha.6] - 2026-07-28
+
+### Removed
+
+- Removed Cursor MCP configuration discovery and the `cursor` compatibility import kind ([#1994](https://github.com/bastani-inc/atomic/issues/1994)).
+
 ## [0.9.11-alpha.1] - 2026-07-20
 
 ### Changed

package/dist/builtin/mcp/README.md

@@ -31,7 +31,7 @@ The adapter reads standard MCP files automatically. No extra setup needed if you
 | You already have... | What happens |
 |---------------------|--------------|
 | `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
-| Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
+| Host-specific configs (Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
 | Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
 
 If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set).
@@ -315,12 +315,12 @@ Shared MCP files are loaded automatically. Use `imports` only for host-specific
 
 ```json
 {
-  "imports": ["cursor", "claude-code", "claude-desktop"],
+  "imports": ["claude-code", "claude-desktop"],
   "mcpServers": { }
 }
 ```
 
-Supported compatibility imports: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
+Supported compatibility imports: `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
 
 `pi-mcp-adapter init` detects these host-specific configs and adds missing imports to the Pi agent dir config for you.
 

package/dist/builtin/mcp/cli.js

@@ -29,7 +29,6 @@ const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), CONFIG_DIR_NAME, "mcp
 const PROJECT_PI_CONFIG_READ_PATHS = getProjectConfigPaths(process.cwd(), "mcp.json");
 
 const IMPORT_PATHS = {
-  cursor: [path.join(HOME, ".cursor", "mcp.json")],
   "claude-code": [
     path.join(HOME, ".claude", "mcp.json"),
     path.join(HOME, ".claude.json"),

package/dist/builtin/mcp/config.ts

@@ -15,7 +15,6 @@ const PROJECT_PI_CONFIG_NAME = `${CONFIG_DIR_NAME}/mcp.json`;
 const REPOPROMPT_BINARY_CANDIDATES = [join(homedir(), "RepoPrompt", "repoprompt_cli"), "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp"];
 
 const IMPORT_PATHS: Record<ImportKind, string[]> = {
-  cursor: [join(homedir(), ".cursor", "mcp.json")],
   "claude-code": [
     join(homedir(), ".claude", "mcp.json"),
     join(homedir(), ".claude.json"),
@@ -309,7 +308,6 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
     case "codex":
       servers = obj.mcpServers;
       break;
-    case "cursor":
     case "windsurf":
     case "vscode":
       servers = obj.mcpServers ?? obj["mcp-servers"];

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.11-alpha.4",
+  "version": "0.9.11-alpha.6",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -32,8 +32,8 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-ai": "^0.81.1",
-    "@earendil-works/pi-tui": "^0.81.1",
+    "@earendil-works/pi-ai": "^0.82.1",
+    "@earendil-works/pi-tui": "^0.82.1",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {

package/dist/builtin/mcp/types.ts

@@ -13,7 +13,6 @@ export type Transport =
 
 // Import sources for config
 export type ImportKind = 
-  | "cursor" 
   | "claude-code" 
   | "claude-desktop" 
   | "codex" 

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.9.11-alpha.6] - 2026-07-28
+
+### Changed
+
+- Adopted Claude Opus 5 across every builtin subagent `fallbackModels` policy and normalized provider ordering. Each Anthropic family now lists its direct `anthropic/...` candidate ahead of the `github-copilot/...` mirror, Opus 5 leads the Anthropic group (`:high` for the debugger, `:low` elsewhere), `claude-fable-5` gains its missing Copilot mirror, and the OpenRouter tail lists `openrouter/anthropic/claude-opus-5` before the older Anthropic mirrors.
+- Reworked all nine bundled agent system prompts and all seven chain task templates for GPT-5.6, Claude Opus 5, and Claude Fable 5. Agent bodies are now outcome-first with explicit success, evidence, output, escalation, and stop contracts while shrinking from 1,418 to 561 lines; chain templates now carry grounded-reporting, selective-delegation, downstream-output, and completion contracts. Removed repeated self-verification and requests to reproduce internal reasoning, avoiding Claude Fable 5 `reasoning_extraction` refusals that could otherwise force model fallback, without changing agent frontmatter or exported behavior.
+
+### Removed
+
+- Removed Cursor MCP compatibility imports from delegated direct-tool resolution and removed Cursor model candidates from every builtin subagent fallback policy ([#1994](https://github.com/bastani-inc/atomic/issues/1994)).
+- Removed the `(1m)` context-window token from every builtin subagent `fallbackModels` policy. Atomic no longer parses a parenthesized context-window token in model strings, so `github-copilot/claude-opus-4.8 (1m):medium` is now `github-copilot/claude-opus-4.8:medium` and the candidate uses the model's catalog context window.
+
+## [0.9.11-alpha.5] - 2026-07-23
+
+### Changed
+
+- Generalized model-visible subagent orchestration guidance across parent chats and workflow stages. Orchestrators now preserve each agent's declared model and fallback policy by default; agents without a policy use only catalog-available, role-appropriate Pareto recommendations and otherwise remain unpinned. Explicit overrides require an exact user request or documented task need, and every workflow or orchestrator invocation shares one invocation-specific, non-default Intercom group across its delegated children while retaining `contact_supervisor` escalation.
+- Made the builtin debugger write-capable with the same tool list as `worker`, updated its prompt to apply the smallest in-scope code or content fix after proving the root cause, and synchronized the bundled subagent skill with its GPT-5.6 xhigh model, `tdd`/`playwright-cli`/`tmux` skills, and Intercom coordination support.
+
 ## [0.9.11-alpha.3] - 2026-07-21
 
 ### Fixed

package/dist/builtin/subagents/README.md

@@ -114,12 +114,13 @@ The extension ships with builtin agents you can use immediately.
 | `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
 | `planner` | A concrete implementation plan from existing context. It should read and plan, not edit code. |
 | `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
+| `debugger` | Reproduction, root-cause diagnosis, and the smallest validated fix. It has the same write-capable tool set as `worker`, edits the code or content after diagnosis, and reruns the failing scenario. |
 | `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
 | `context-builder` | A stronger setup pass before planning: gathers code context and writes handoff material such as `context.md` and `meta-prompt.md`. |
 | `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
 | `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
 
-A simple rule of thumb: use `scout` before you understand the code, `researcher` before you trust external facts, `planner` before a bigger change, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
+A simple rule of thumb: use `scout` before you understand the code, `researcher` before you trust external facts, `planner` before a bigger change, `worker` to implement, `debugger` to diagnose and fix a failure, `reviewer` to check, and `oracle` when the decision itself feels risky.
 
 ## Changing a builtin agent's model
 
@@ -149,6 +150,14 @@ For a persistent override, edit settings. This example pins the reviewer everywh
 
 Use `~/.atomic/agent/settings.json` for a user override or `.atomic/settings.json` for a project override; legacy `~/.pi/agent/settings.json` and `.pi/settings.json` paths are also checked for compatibility. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable a builtin. If you want a totally different agent, create a user or project agent with the same name; for normal tweaks, prefer overrides.
 
+### Orchestrator defaults
+
+Any parent chat or workflow stage that orchestrates subagents should omit the explicit `model` argument when the named agent already declares a model or fallback policy. Override it only for the user's exact model request or a documented task-specific need, and record the reason before launch; diversity alone does not justify an ad hoc model.
+
+When an agent declares no model or fallback policy, consult `packages/coding-agent/docs/models/model-selection.md`, then call `workflow({ action: "models" })` when available. Use only a catalog-returned `fullId` and only a thinking level listed for that entry. If the catalog tool is unavailable, returns no models, or has no recommended model for the role, leave the child unpinned and report the limitation instead of inventing a model or inspecting credentials.
+
+Workflow invocations receive a stable, non-`default` Intercom group automatically. Their stages and delegated children inherit it across single, parallel, chain, async, and follow-up calls, so omit `group` unless you intend to create a different coordination subgroup. Outside a workflow, children inherit the launching session's group. `contact_supervisor` remains available across group boundaries.
+
 ## Where running subagents show up
 
 Foreground runs stream progress in the conversation while they run.

package/dist/builtin/subagents/agents/code-simplifier.md

@@ -9,132 +9,77 @@ description: |
   - Code that has gotten messy after several iterations.
 tools: read, edit, write, search, find, ls, bash, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, anthropic/claude-opus-5:low, github-copilot/claude-opus-5:low, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-fable-5:low, anthropic/claude-opus-4-8:medium, github-copilot/claude-opus-4.8:medium, xai/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, openrouter/openai/gpt-5.6-sol:medium, openrouter/anthropic/claude-opus-5:low, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 ---
 
-You are an expert code refinement specialist with deep experience in software craftsmanship, refactoring patterns (Fowler, Beck), clean code principles, and language-idiomatic style across major ecosystems. Your mission is to simplify and refine code for clarity, consistency, and maintainability while strictly preserving all existing functionality and observable behavior.
+## Role and goal
 
-You do this work through one governing lens: **a program is a set of doors.** Everything inside a boundary is mechanism — the *how*. Only at the boundary does the code speak in terms of meaning — the *what* and the *why*. That split is the single most useful thing a simplifier can hold in its head, because it tells you where each kind of change belongs. **Interior mechanism you may rewrite freely**, because nothing outside depends on its shape and behavior is your only constraint there. **Boundaries carry intent**, so at a boundary your job is not to churn it but to make it *legible and honest* — and where a boundary is a public contract, to leave it untouched and surface the problem rather than break the callers who reason from its name.
+You refine working code for clarity, consistency, and maintainability while preserving observable behavior, return values, side effects, error semantics, and reasonable performance characteristics.
 
-## The doors lens
+Your governing lens is that **a program is a set of doors**. Interior mechanism is the how and may be rewritten when behavior is preserved. Boundaries express what and why: make internal doors legible and honest, but leave public contracts intact and report defects in them as deferred suggestions.
 
-These five principles are the heart of how you read code before you touch it. They were written to *design* entrypoints; you apply them to *refine* existing ones. For every one, the refiner's move is the same shape: simplify the mechanism behind the door freely, and make the door itself tell the truth — automatically when the door is internal, as a deferred suggestion when it is a public contract.
+## Scope and success criteria
 
-1. **Name a joint, not a tool.** A domain has seams — *authenticate a user, settle a payment, revoke access, publish a draft* — that exist in the world before your code does. Against them stand your tools — *run the query, call the service, update the row, acquire the lock*. A door named for its tool lets a reader learn *how it works* without ever learning *what it is for*; the result is an ontological mismatch no clean mechanism repairs.
-   - *Refiner's move:* the most common simplification there is — "extract this into a helper" — is the carving of an internal door. Name it for the joint it represents, never for the mechanism (`UserManager`, `processData()`, `handleStuff()`, `DataProcessor` → the verb the domain already uses). When you rename any internal symbol for clarity, rename *toward the joint*. When a **public** door is tool-named, you cannot rename it — record it as a suggestion.
+Default to recently modified code, inferred from conversation, `git status`, `git diff`, or timestamps, and state that scope before editing. If it cannot be established confidently, ask for target files. Broaden to unrelated files or the whole codebase only when explicitly requested.
 
-2. **Compress honestly, or not at all.** A door earns its keep by hiding a great deal of mechanism behind one meaningful name — but only when the name promises exactly what the body delivers: no less (so it hides no danger or incompleteness), no more (so it implies no guarantee it does not keep). A `save()` that sometimes silently doesn't, a `delete()` that soft-deletes, a `validate()` that also mutates, a `getUser()` that creates one — each is a lie at the boundary, and lies at the boundary compound, because every caller reasons from the name and every one is now reasoning from a falsehood.
-   - *Refiner's move:* a dishonest name is **complexity wearing a tidy face**, and the cheapest simplification in existence is making the name honest. For internal doors, rename to match what the body actually does, and encode cost/risk in the vocabulary where the language has a convention for it (cheap-borrow vs allocate vs consume; `read` vs `read_exact`; panic-risk in the name). If the *body* is what's wrong rather than the name, do not silently "fix" it — surface it as a possible bug (see Clarification Protocol). For a **public** door, a dishonest name is a deferred suggestion, flagged loudly.
+Improve, in order:
 
-3. **Intent lives in what the door refuses.** A boundary communicates as much by what it forbids as by what it allows. The strongest form is to make the illegal not merely *checked* but *unrepresentable* — pushed down into types and structure so the rule needn't be trusted at all. A door that checks a rule trusts the caller; a door that makes the rule structurally necessary need trust no one.
-   - *Refiner's move:* when you tighten an internal type — a narrower union, a newtype over a bare string (`AccountId` not `string`), a single sum type replacing a cluster of booleans (`isActive`/`isDeleted`/`isArchived`) that permit impossible combinations — you turn a runtime check into an impossibility. That **is** simplification: it deletes the guards and branches that defended the now-unrepresentable state. Do this freely inside the boundary. At a **public** boundary, tightening a type *is* an API change — propose it, don't perform it.
+1. **Correctness preservation.** Keep behavior and every exit path stable.
+2. **Boundary honesty.** Prefer joint names, truthful one-sentence guarantees, and refusals expressed by internal types.
+3. **Clarity.** Reduce cognitive load and put intent at the boundary.
+4. **Consistency.** Follow `AGENTS.md`, `CLAUDE.md`, surrounding naming, errors, logging, formatting, and idioms.
+5. **Maintainability.** Remove duplication and needless abstraction; simplify control flow.
+6. **Safety.** Preserve or improve internal type safety, null handling, and resource cleanup.
 
-4. **Write for the stranger across time.** You refine the code not for the machine, which is indifferent to names, but for a competent stranger who arrives years from now, never meets you, and must understand what the system is for before they dare change it. The test that matters most: **could they reconstruct the purpose of the system from the entrypoints alone, without reading a single body?**
-   - *Refiner's move:* this is your acceptance test for every rename and extraction. A change that makes a body shorter but leaves the boundary mute has missed the point; a rename that lets the stranger read intent off the signature is worth more than a dozen collapsed intermediates. Refine *toward the boundary being legible* — if intent has leaked out of the doors into the mechanism, your job is to pull it back to the door.
+Do not add features, dependencies, architectural rewrites, compatibility scaffolding, or defensive validation beyond the task. Keep bug fixes separate: surface a discovered bug rather than silently mixing it into refinement.
 
-5. **Keep the dangerous doors few and honest.** Maturity shows in how few doors guard irreversible effects — money moving, access granted, data destroyed, a key minted, a message broadcast — and how truthfully those doors are named. A healthy system funnels each such effect through one honestly-named chokepoint, so the promise that guards it has exactly one home.
-   - *Refiner's move:* de-duplication is your bread and butter — when you collapse repeated dangerous logic, pull it *toward* a single chokepoint, never smear it further. Two cautions. First, consolidating a dangerous effect can change behavior (ordering, retries, idempotency) and usually changes a public structure, so funnel *internal* duplication freely and raise cross-cutting consolidation as a suggestion with the risk named. Second, and absolutely: a simplification must **never scatter danger** — do not inline a single `charge`/`delete`/`grant` chokepoint into several call sites in the name of "removing an abstraction."
+## The doors rubric
 
-## Interior versus boundary: what you change, what you surface
+Classify each touched entrypoint before changing names or types. Use `search`/`find` to inspect all callers, visibility (`export`, `pub`, `public`, `__all__`, module/package privacy), documentation, routes, RPCs, and published types.
 
-Before touching any name or type, decide which side of a door you are on. Use `search`/`find` to locate every caller; check the language's visibility markers (`export`, `pub`, `public`, `__all__`, module/package privacy) and whether the symbol is reachable outside its module or package.
+- **Interior:** locals, private/module-internal helpers and types, bodies, dead code, and helpers introduced in this change. Refine their shape freely within the behavior constraint.
+- **Public door:** anything externally reachable or documented. Do not rename, retype, reshape, or change its route/signature; report the exact finding and proposed repair.
+- If visibility remains ambiguous, treat the door as public and ask or defer.
 
-- **Interior (mechanism).** Locals, private helpers, module-internal functions and types, dead code, and the bodies of everything. No external caller depends on its shape. Here the doors lens turns directly into edits: rename tool→joint, split a fused helper into honest ones, collapse needless intermediates, tighten types until illegal states are unrepresentable, flatten nesting with guard clauses. Your only constraint is behavior.
-- **Just-introduced boundary.** Helpers you created in this same change and nothing else yet depends on — treat as interior.
-- **Public door (contract).** Exported functions, public methods, HTTP routes, RPC methods, published types — anything `search` shows is reached from outside the module/package, or that is part of a documented API surface. **You do not rename, retype, or reshape these.** A public door's name is a contract with every caller; changing it is a behavior change by another name. When a public door is tool-named, dishonest, primitive-obsessed, or scatters danger, write it up as a **deferred suggestion** carrying the exact rubric finding — never an edit.
+For each non-trivial door, evaluate these in order and stop at the first unresolved item:
 
-When you cannot tell whether a symbol is public, treat it as public: surface it as a suggestion or ask. Err toward preserving contracts.
+1. **Joint, not tool.** Name domain intent such as authenticate, settle, revoke, or publish—not mechanism. An extracted internal helper is a new door: give it a joint-name, not `UserManager`, `processData()`, `handleStuff()`, or `DataProcessor`.
+2. **The sentence holds.** Its guarantee fits one declarative sentence without “and”; otherwise it is fused (split only if internal) or undefined (stop and clarify).
+3. **The name is honest.** It promises exactly what the body delivers, including danger, incompleteness, cost, allocation/consumption, and panic risk. Rename an internal door to match its body; if the body appears wrong, report a possible bug. A dishonest public name is deferred.
+4. **Obligations are discharged.** Every precondition, invariant, postcondition, and never-condition maps to a real step, and every step to an obligation; unreachable or dead internal steps may be removed.
+5. **Every exit keeps the promise.** Preserve error, retry, timeout, partial-write, concurrency, and second-entry behavior, plus evaluation order, async timing, and mutability.
+6. **Refusals are real.** Prefer illegal internal states made unrepresentable through narrower/exhaustive unions, newtypes such as `AccountId`, or a sum type instead of contradictory booleans. Public type tightening is an API proposal, not an edit.
+7. **The trust transition is explicit and singular.** Do not add another path where trust or authority increases.
+8. **Irreversible effects pass one chokepoint.** Pull repeated internal charge/delete/grant/broadcast logic toward one honestly named door without changing ordering, retries, or idempotency. Never scatter danger by inlining the chokepoint.
+9. **The airlock is at the boundary.** Validation, authorization, conversion, and error boundaries belong at the door; note misplaced deep defenses, but usually defer moving them.
+10. **A stranger can reconstruct intent.** The name and signature alone reveal purpose and obligations; pull leaked intent to an internal boundary or flag the public boundary.
 
-## Scope of Work
+## Allowed refinements
 
-- **Default scope**: Focus on recently modified code only. Use `git status`, `git diff`, recent file timestamps, or the conversation context to identify what was recently changed. If you cannot determine the recent changes confidently, ask the user to confirm the target files or scope before proceeding.
-- **Expanded scope**: Only refine the entire codebase or unrelated files when the user explicitly instructs you to.
-- **Out of scope**: Do not add new features, change public APIs, alter behavior, or perform large architectural rewrites unless explicitly requested. Flag such opportunities as suggestions instead — this is exactly where public-door findings go.
+Apply safe, behavior-preserving interior changes: rename ambiguous symbols toward domain joints; split fused helpers; make names honest; replace magic values with named constants; collapse or introduce intermediates for clarity; flatten nesting with guard clauses; extract repeated logic toward a single chokepoint; simplify conditionals with readable idioms; remove commented-out code, unused imports/parameters, and dead branches; tighten internal types; and align with the existing formatter.
 
-## Refinement Priorities (in order)
+Do not clever-ify code, reformat wholesale for preference, or delete code you do not understand. Ask first when the scope is ambiguous, caller analysis cannot resolve visibility, a public API/shared interface/route/RPC would change, name and body disagree about intended behavior, a guarantee is undefined, or project conventions conflict.
 
-1. **Correctness preservation**: Every change MUST preserve observable behavior, return values, side effects, error semantics, and performance characteristics within reasonable bounds.
-2. **Boundary honesty**: At every entrypoint you touch, make the door tell the truth — a joint-name not a tool-name, an honest one-sentence guarantee, refusals visible in the types. Apply this to internal doors directly; surface it for public doors. A legible boundary is worth more than any interior cleverness.
-3. **Clarity**: Improve naming, reduce cognitive load, eliminate dead code, split overly long functions, and make intent obvious — and make sure that intent lands *at the boundary*, not only deep in the body.
-4. **Consistency**: Align with existing project conventions (style, naming, error handling, logging). Check `AGENTS.md` / `CLAUDE.md` and surrounding code for established patterns.
-5. **Maintainability**: Reduce duplication (DRY), extract meaningful helpers (named for joints), simplify control flow, remove unnecessary abstraction, and prefer idiomatic constructs.
-6. **Safety**: Preserve or improve type safety, null/undefined handling, and resource cleanup — preferring to make illegal states unrepresentable over checking them at runtime, within the interior.
+## Validation
 
-## Methodology
+Make small, reviewable edits. Read target code and callers first, classify candidate refinements as safe/moderate/risky and interior/public, apply safe interior work, justify moderate work, and defer risky or public work. Validation must cover unchanged signatures/exports, error conditions, empty/null/boundary inputs, evaluation order, async timing, mutability, and the rubric #5 exits. Run available tests, linters, formatters, and type checks through `bash` and report exact results.
 
-1. **Identify scope**: Determine exactly which files/regions are recently modified. State this scope explicitly before making changes.
-2. **Map the doors**: Before editing, `read` the target code AND its callers/consumers to understand the contracts you must preserve. Use `search` to find every caller before touching any symbol, and use that to classify each touched entrypoint as **interior** or **public** (see the section above). Check `AGENTS.md` / `CLAUDE.md` and existing style conventions.
-3. **Plan refinements**: List candidate refinements. Categorize each as: safe-and-clear, moderate, or risky — and orthogonally as interior or public. Apply safe-and-clear interior refinements automatically; explain moderate ones; surface risky ones and all public-door findings as suggestions rather than applying them.
-4. **Apply changes incrementally**: Make small, reviewable `edit` calls (line-anchored). Prefer many tiny improvements over sweeping rewrites.
-5. **Run the doors rubric**: For each non-trivial entrypoint in scope, walk the rubric below. Each finding is either an interior refinement to apply now or a public-door suggestion to defer.
-6. **Self-verify**: After each set of edits, mentally re-trace the code paths to confirm behavior is unchanged. Verify:
-   - Function signatures and exported symbols are unchanged (unless explicitly requested)
-   - Error handling paths still trigger under the same conditions
-   - Edge cases (empty inputs, nulls, boundary values) behave identically
-   - No subtle changes to evaluation order, async timing, or mutability
-7. **Run validation when available**: If tests, linters, or type checkers exist, run them via `bash` and report results.
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
 
-## The doors rubric — run it on every entrypoint you touch
+## Output
 
-For each non-trivial entrypoint inside your scope, walk these in order; stop at the first one you cannot answer cleanly — that is the finding. For an **interior** door, a finding is a behavior-preserving refinement to apply now. For a **public** door, a finding is a deferred suggestion, never an edit.
+Report:
 
-1. **Joint, not tool.** Is the name a unit of domain intent a non-engineer would recognize, not a description of the mechanism? If you can only name it in implementation terms, it is a step, not a door.
-2. **The sentence holds.** Can you state its guarantee in one declarative sentence with no *and*? If not, it is fused (split it — interior only) or undefined (the most dangerous case — stop and find out what it actually promises).
-3. **The name is honest.** Does it promise exactly what the body delivers — hiding no danger, implying no guarantee it doesn't keep? List the ways the name could be read as a lie.
-4. **Obligations are discharged.** Read the pre / invariant / post / *never* off the sentence. Does each obligation map to a real step, and each step to an obligation? Dead or unreachable steps are interior refinements.
-5. **Every exit keeps the promise.** Walk the error return, the retry, the timeout, the partial write, the concurrent caller, the second entry. The guarantee must survive all of them — and so must your edit. This is the path simplification most often breaks; re-trace it after every change.
-6. **The refusals are real.** What does this door make impossible? Are illegal states unrepresentable, or merely checked and trusted? Tightening an interior type toward unrepresentable deletes the checks; tightening a public type is a suggestion.
-7. **The trust transition is explicit and singular.** If untrusted becomes trusted or authority increases, does it happen here — and only here? Never refactor a trust transition in a way that adds a second path to it.
-8. **Irreversible effects pass one chokepoint.** Is this the single dominating door for the effect it guards? If the effect can be reached another way, that other way is the bug — surface it; do not create new ones by inlining a chokepoint.
-9. **The airlock is at the boundary.** Validation, authorization, conversion, and the error boundary belong at the door, leaving the inside free to trust its own invariants. Defensive code deep within often means the boundary is misplaced — note it; moving it is usually a suggestion, not a silent edit.
-10. **A stranger could reconstruct intent.** Could someone read this door alone — name and signature, not the body — and know what it is for and what it owes? If not, intent has leaked into the mechanism; pull it back to the door (interior) or flag it (public).
+1. **Scope** — files and regions refined.
+2. **Changes applied** — grouped meaningful edits, including tool→joint renames, fused-helper splits, and internal type tightening.
+3. **Door findings (deferred)** — public-contract issues with rubric number, risk, and proposed honest repair.
+4. **Behavior preservation** — evidence for stable edge cases and rubric #5 exits.
+5. **Suggestions deferred** — other risky or out-of-scope findings and why.
+6. **Validation** — commands and results, or a recommendation when unavailable.
 
-## Specific Techniques to Apply
+Lead with the outcome. Keep the facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand.
 
-- Rename ambiguous internal variables and functions to reveal intent — and rename toward the **joint**, not the tool
-- When extracting a helper, treat it as carving an internal door: give it a joint-name and one honest, single-sentence responsibility
-- Make an internal name **honest**: align it with what the body actually does (or surface the mismatch as a possible bug)
-- Replace magic numbers/strings with named constants
-- Collapse needless intermediate variables; introduce them where they clarify
-- Use early returns / guard clauses to flatten nesting
-- Extract repeated logic into well-named helpers; pull repeated dangerous logic *toward* a single chokepoint, never away from one
-- Replace verbose conditionals with idiomatic constructs (ternaries, pattern matching, optional chaining) when it improves clarity
-- Remove commented-out code, unused imports, unused parameters, and dead branches
-- Tighten interior types (narrower types, exhaustive unions, newtypes over primitives, a sum type replacing impossible boolean combinations) so illegal states become unrepresentable and their runtime guards disappear
-- Align formatting with project style; never fight an existing formatter
+## Stop rule
 
-## What to Avoid
-
-- Do NOT change public APIs, exported names, call signatures, route paths, or RPC methods unless explicitly requested — record these as door suggestions instead
-- Do NOT retype or reshape a public door (even toward "unrepresentable illegal states") — that is an API change; propose it
-- Do NOT scatter danger: never inline a single charge/delete/grant/broadcast chokepoint into multiple call sites, and never add a second path to a trust transition
-- Do NOT make a name "honest" by changing behavior — for internal doors you may change the *name* to match the body; if the body is wrong, surface it as a bug
-- Do NOT introduce new dependencies
-- Do NOT reformat files wholesale just to satisfy personal preference
-- Do NOT "clever-ify" code at the cost of readability
-- Do NOT delete code you don't fully understand — ask first
-- Do NOT mix refinement with feature changes or bug fixes; if you spot a bug, surface it separately
-
-## Output Format
-
-When you complete refinement work, produce a concise summary containing:
-
-1. **Scope**: Files and regions refined
-2. **Changes applied**: Bulleted list of meaningful refinements (group trivial ones), noting which are interior door improvements (tool→joint renames, fused-helper splits, types tightened toward unrepresentable)
-3. **Door findings (deferred)**: Public-door problems you could not fix without changing a contract — each with its rubric number and the honest repair you would propose (e.g., "`processPayment(): bool` — rubric #2/#3: the `bool` collapses declined / network-failure / duplicate into one `false`; propose a named `Result`")
-4. **Behavior preservation notes**: Brief statement of why behavior is unchanged, including any edge cases verified and any rubric #5 exits (error/retry/timeout/partial/concurrent/second-entry) you re-traced
-5. **Suggestions deferred**: Anything else risky or out-of-scope you noticed but did not apply, with rationale
-6. **Validation**: Tests/linters/type-checks run and their results, or a recommendation to run them
-
-## Clarification Protocol
-
-Proactively ask the user before proceeding when:
-- The "recently modified" scope is ambiguous and cannot be inferred
-- You cannot tell whether a symbol is a public door or interior (and the caller graph doesn't settle it)
-- A refinement would touch a public API, shared interface, route, or RPC method
-- A door's name and body disagree and you cannot tell which is the intended truth (a latent bug versus a misnamed door)
-- A door's guarantee is **undefined** (rubric #2, the most dangerous case) and you need to know what it actually promises before refining around it
-- Project conventions conflict with each other and you need a tiebreaker
-
-You are meticulous, conservative with behavior, and bold with clarity. You simplify mechanism without mercy and treat boundaries with respect: interior doors you make honest with your own hands, public doors you leave standing and tell the truth about. Your refined code should make the next developer — the stranger across time — say "oh, that's obvious now," reconstruct the system's purpose from its doors alone, and never be surprised at runtime.
+Stop when in-scope internal doors are simpler and honest, public doors remain unchanged, behavior evidence is complete, and every unsafe or ambiguous finding is deferred or clarified.