@bastani/atomic 0.9.5-alpha.3 → 0.9.5-alpha.5

package/docs/compaction.md

@@ -6,11 +6,14 @@ Atomic's compaction design and terminology are informed by Morph's Context Compa
 
 **Source files** ([atomic](https://github.com/bastani-inc/atomic)):
 
-- [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Verbatim Compaction planner, transcript tools, validation, and prompt
+- [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Public barrel for Verbatim Compaction types, helpers, tools, and runner exports
+- [`packages/coding-agent/src/core/compaction/context-compaction-runner.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction-runner.ts) - Planner loop, strict target gate, auto-compaction fallback ladder, and planner nudge cap
+- [`packages/coding-agent/src/core/compaction/context-compaction-critical.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction-critical.ts) - Internal overflow-only critical-pass protected-entry eligibility and prompt guidance
+- [`packages/coding-agent/src/core/compaction/context-compaction-eviction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction-eviction.ts) - Internal overflow-only deterministic LRU eviction fallback
 - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
 - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
 - [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `BranchSummaryEntry`) and active-context rebuild logic
-- [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+- [`packages/coding-agent/src/core/extensions/session-events.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/session-events.ts) - Compaction extension event payloads
 
 For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`.
 
@@ -25,7 +28,7 @@ Atomic has one context compaction behavior and one separate branch-summarization
 
 Summary compaction — the earlier behavior that generated replacement prose — has been removed as an active runtime path. Historical JSONL lines with `type:"compaction"` remain readable on disk but are not injected into active LLM context. See [Legacy Summary Compaction (Retired)](#legacy-summary-compaction-retired) for a comparison and historical reference.
 
-`/compact` has no user-facing arguments. It uses the effective `compaction` settings (`compression_ratio`, `preserve_recent`, and optional `query`), a fixed internal prompt, transcript-bound inspection/deletion tools, local validation, and a `context_compaction` session entry. Auto-compaction uses the same deletion-only path.
+`/compact` has no user-facing arguments. It uses the effective `compaction` settings (`compression_ratio`, `preserve_recent`, and optional `query`), a fixed internal prompt, transcript-bound inspection/deletion tools, local validation, and a `context_compaction` session entry. Manual compaction (`/compact` and the `contextCompact` RPC path) still uses the strict planner target only. Auto-compaction uses the same deletion-only commit path, but threshold and overflow triggers can accept validated below-target reductions or, on overflow only, escalate through internal recovery tiers when the strict target is not achievable.
 
 ## Verbatim vs. Summary Compaction
 
@@ -90,15 +93,15 @@ Settings use the same snake_case names under `compaction`, for example:
 
 ### When It Triggers
 
-Auto-compaction triggers when:
+Auto-compaction threshold checks trigger when:
 
 ```text
-contextTokens > contextWindow - reserveTokens
+contextTokens > effectiveInputBudget - reserveTokens
 ```
 
-By default, `reserveTokens` is 16384 tokens. Configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`; legacy `.pi` paths are also supported. This leaves room for the LLM's response.
+By default, `reserveTokens` is 16384 tokens. Configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`; legacy `.pi` paths are also supported. This leaves room for the LLM's response. Providers that advertise a larger total context window than their hard prompt cap use the model's effective input budget for threshold and overflow recovery decisions.
 
-You can also trigger compaction manually with `/compact`. Custom summary instructions are not accepted because Verbatim Compaction is deletion-only and retained transcript content stays verbatim.
+You can also trigger compaction manually with `/compact`. Custom summary instructions are not accepted because Verbatim Compaction is deletion-only and retained transcript content stays verbatim. Manual compaction keeps the strict `compression_ratio` completion requirement and does not run the auto-compaction overflow ladder.
 
 If auto-compaction runs while a turn still has queued work (for example a failed tool-call result or a follow-up queued during compaction), Atomic resumes through the same continuation lifecycle as a normal queued turn: provider retry handling runs, additional queued messages drain, and any post-compaction resume failure is surfaced instead of being swallowed silently.
 
@@ -171,7 +174,7 @@ The diagram below is intentionally a block diagram, not a flowchart DSL. Read it
 | 3 Planner workspace | `runContextDeletionAssistant` | `CompactableTranscript` | Temp JSONL transcript file plus bounded manifest prompt, inheriting the session's current model thinking level |
 | 4 Tool loop | `createContextDeletionTool` tools | Planner tool calls | In-run deletion store updates or correction errors |
 | 5 Validation airlock | `validateContextDeletionRequest` | Candidate cumulative deletion request | Reconciled `deletedTargets` or thrown error |
-| 6 Planner stops or adds more | Agent loop until target is met or no progress remains | Tool results and current context | Final validated deletion state |
+| 6 Target/fallback decision | `contextCompact` runner ladder | Final or salvaged validated deletion state | Strict-target success, feasible auto-compaction acceptance, overflow-only critical pass, deterministic eviction, or terminal error |
 | 7 Persist compaction | session manager append path | `ContextCompactionResult` | New append-only `context_compaction` entry |
 | 8 Rebuild active context | `buildSessionContext` | Branch plus all logical deletion filters | Model messages with deleted objects omitted verbatim |
 
@@ -262,7 +265,7 @@ append-only SessionEntry branch
 │      toolCallIds      ids from assistant toolCall content blocks                                │
 │      toolResultFor    call id answered by a toolResult entry                                    │
 │                                                                                                │
-│    transcript.protectedEntryIds records the protected ids for the persisted result.             │
+│    transcript.protectedEntryIds records the ids protected by the active validation pass.       │
 └──────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -301,8 +304,10 @@ Prompt body
 │   • Prefer high-confidence exploit actions after that: delete obvious low-value entries via    │
 │     context_grep_delete or context_delete.                                                     │
 │   • Check context_compaction_budget after deletion batches.                                   │
-│   • Treat compression_ratio as strict: default 0.5 means keep 50% / delete 50%.                │
-│   • If the target is not met, continue deleting low-value entries/content blocks.              │
+│   • Treat compression_ratio as strict for the standard planner pass: default 0.5 means keep   │
+│     50% / delete 50%.                                                                         │
+│   • If the strict target is not met, continue deleting low-value entries/content blocks until │
+│     the planner reaches the target, reaches the auto-compaction budget fallback, or stops.    │
 │   • Converge quickly; do not keep reading once safe deletion targets are clear.                │
 ├──────────────────────────────────────────────────────────────────────────────────────────────┤
 │ Transcript file path                                                                          │
@@ -386,7 +391,8 @@ Candidate cumulative deletion request
         ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │ Gate 1: recent-context guard                                         │
-│   preserve_recent context entries are rejected with correction text   │
+│   effective recent window entries are rejected with correction text   │
+│   (critical/deterministic overflow uses max(preserve_recent, 5))      │
 └─────────────────────────────────────────────────────────────────────┘
         │
         ▼
@@ -420,7 +426,8 @@ Candidate cumulative deletion request
 │ Gate 6: tool-call/tool-result reconciliation                         │
 │   repairs paired call/result deletion dependencies when safe          │
 │   throws explicit recent-context errors when repair crosses the       │
-│   preserve_recent boundary                                           │
+│   effective recent boundary (max(preserve_recent, 5) in overflow      │
+│   critical/deterministic tiers)                                       │
 └─────────────────────────────────────────────────────────────────────┘
         │
         ▼
@@ -486,7 +493,7 @@ If the tool result is deleted:
 Standard recent boundary case:
 
 ┌──────────────────────────────┐       repair would delete       ┌──────────────────────────────┐
-│ old side of pair requested   │────────────────────────────────▶│ last-5 side of pair          │
+│ old side of pair requested   │────────────────────────────────▶│ preserve_recent side of pair │
 └──────────────────────────────┘                                  └──────────────────────────────┘
                                       │
                                       ▼
@@ -503,8 +510,8 @@ ValidatedContextDeletionResult
         │    [{ kind: "entry", entryId }, { kind: "content_block", entryId, blockIndex }]
         │
         ├─ protectedEntryIds
-        │    snapshot of ids protected during preparation
-        │
+        │    snapshot of ids protected by the validation pass that produced the result
+        │    (critical overflow excludes entries deliberately relaxed for eviction)
         └─ stats
              object and token reduction estimate
         │
@@ -536,20 +543,29 @@ ValidatedContextDeletionResult
 | `context_delete` validation error | Store rolls back to previous deletion targets | Non-terminating correction tool result with exact error |
 | `context_grep_delete` regex/pattern error | Store rolls back to previous deletion targets | Non-terminating correction tool result with exact error |
 | `context_grep_delete` protected/recent match | Matching protected target is ignored and not counted as a deletion | Non-protected matches still apply when validation succeeds |
-| Planner stops without any valid deletion | Nothing persisted | Compaction fails, including last deletion-tool error when available |
-| Provider overflow after some valid deletions | Valid in-run deletions are used | Compaction can proceed with recorded targets |
-| Provider non-overflow error | Nothing persisted | Error propagates |
-| Extension-provided deletion request invalid | Nothing persisted | Extension/caller sees validation failure |
+| Manual planner stops below the strict `compression_ratio` target | Nothing persisted | Manual compaction fails with achieved reduction, deletion count, and tokens-after details |
+| Threshold auto-compaction stops below the strict target but deletes at least one target and projected `tokensAfter` is at or below `effectiveInputBudget - reserveTokens` | Validated deletion targets are persisted | Tier 2 accepts the feasible result so threshold compaction does not immediately re-trigger |
+| Threshold auto-compaction stops below the strict target and still exceeds the trigger boundary | Nothing persisted | Auto-compaction fails; threshold compaction never escalates to protected-entry eviction |
+| Threshold auto-compaction finds no preparable compactable transcript | Nothing persisted | Silent no-op is preserved because threshold compaction is only opportunistic |
+| Overflow auto-compaction finds no preparable compactable transcript | Nothing persisted | Terminal overflow-recovery error states that nothing more was safely deletable instead of silently no-oping |
+| Overflow auto-compaction has validated deletions whose projected `tokensAfter` is at or below the model's effective input budget | Validated deletion targets are persisted | Tier 1 target-met results, Tier 2 feasible results, and provider-overflow salvage are committed only when they fit the effective input budget; target-met-but-over-budget results escalate instead of being persisted |
+| Overflow planner misses the strict target or meets the strict target while still exceeding the effective input budget | No persistence until a later tier succeeds | Tier 3 reruns the planner with internal `<critical-overflow-mode>` guidance, overflow-only protected-entry eligibility, and an effective recent guard of `max(preserve_recent, 5)` across all entries |
+| Critical overflow pass cannot produce a fitting validated result, or planner auth is unavailable during overflow | No model-generated plan is persisted | Tier 4 runs deterministic code-level LRU eviction with no model call or auth requirement while enforcing the same `max(preserve_recent, 5)` recent floor across all entries |
+| Deterministic overflow eviction cannot fit the effective input budget, has no safe candidate left, or reaches its 50-pass cap | Nothing persisted from the failed attempt | Terminal overflow-recovery error includes achieved stats (`tokensAfter`, percent reduction, deletion-target count), the budget, and that nothing more was safely deletable |
+| Planner run reaches its 50 real provider-turn cap | No additional provider calls are made for that planner run | The runner evaluates the validated deletions recorded so far against the current tier's acceptance rule, then either escalates or fails terminally with achieved stats |
+| Planner nudge loop reaches its 50 follow-up cap | No extra follow-ups are queued for that planner run | The runner evaluates the best validated state against the current tier's acceptance rule, then either escalates or fails terminally with achieved stats |
+| Provider non-overflow error | Nothing persisted unless an overflow-only later tier succeeds | Error propagates for manual/threshold; overflow recovery can continue to lower tiers unless the request was aborted |
+| Extension-provided deletion request invalid | Nothing persisted | Extension/caller sees validation failure; extension-provided requests bypass the internal fallback ladder |
 
 
 
 1. **Collect active branch context.** Atomic walks the current session branch and applies any earlier `context_compaction` logical deletions.
 2. **Build a compactable transcript.** Each compactable entry includes a stable `entryId`, role, token estimate, full text, content-block indexes, tool-call IDs, and tool-result links.
-3. **Mark validation guards.** Atomic marks user instructions, custom messages, branch/summary messages, the configured `preserve_recent` context-eligible entries, unresolved assistant/tool errors, and failed bash executions as not directly deletable. If a planner targets one, the deletion tool returns an explicit correction error.
+3. **Mark validation guards.** Atomic marks user instructions, custom messages, branch/summary messages, the configured `preserve_recent` context-eligible entries, unresolved assistant/tool errors, and failed bash executions as protected in the standard transcript. If a standard planner targets one, the deletion tool returns an explicit correction error.
 4. **Write a temporary transcript file.** The compaction assistant receives a compact manifest plus the path to a JSONL transcript file. It should inspect with tools instead of loading the whole transcript into prompt context.
-5. **Run the deletion planner.** The user's currently selected model runs Atomic's fixed Verbatim Compaction prompt using the session's current model thinking level. It can search/read transcript slices and then call deletion tools. The prompt substitutes the effective compaction parameters: `compression_ratio` (fraction to keep, default `0.5`), `preserve_recent` (default `2`), and `query` (explicit or auto-detected). The target reduction is `1 - compression_ratio` and is treated as a strict completion requirement.
+5. **Run the standard deletion planner.** The user's currently selected model runs Atomic's fixed Verbatim Compaction prompt using the session's current model thinking level. It can search/read transcript slices and then call deletion tools. The prompt substitutes the effective compaction parameters: `compression_ratio` (fraction to keep, default `0.5`), `preserve_recent` (default `2`), and `query` (explicit or auto-detected). The target reduction is `1 - compression_ratio` and is treated as a strict completion requirement for the standard planner pass.
 6. **Validate fail-closed.** Atomic validates every cumulative deletion plan locally. Unknown IDs, protected targets, duplicate/overlapping targets, empty-context plans, missing task-bearing context, and tool-call/tool-result orphaning are rejected.
-7. **Continue until target.** Atomic exits the internal planner loop when validated deletion stats meet the configured reduction target. If the model tries to finish early, Atomic injects a follow-up nudge with the current validated reduction and tells the planner to continue removing message entries/content blocks.
+7. **Apply the auto-compaction fallback ladder when needed.** Manual compaction stops at the strict standard planner result. Threshold auto-compaction can accept a below-target result only when it has at least one validated deletion and projected `tokensAfter` is at or below `effectiveInputBudget - reserveTokens`; it never escalates to protected-entry eviction. Overflow auto-compaction commits any planner result (strict-target or below-target feasible) only when projected `tokensAfter` fits the effective input budget, then can rerun the planner in an internal critical overflow pass, and finally can use deterministic code-level LRU eviction until the effective input budget fits or no safe deletion remains. The overflow-only critical planner and deterministic eviction tiers enforce an effective recent guard of `max(preserve_recent, 5)` over all entries.
 8. **Save and rebuild.** Atomic writes a backup snapshot for persisted sessions, appends a `context_compaction` entry with validated targets and stats, then rebuilds the active LLM context from the filtered branch.
 
 ### Transcript-Bound Tools
@@ -564,17 +580,17 @@ The compaction assistant can only compact by using these internal tools. Exact d
 | `context_delete` | Record exact entry/content-block deletion targets. |
 | `context_grep_delete` | Bulk-delete matching entries or content blocks with guardrails. |
 
-The planner is prompted to call `context_compaction_budget` before deleting and after deletion batches. The tool reports the current transcript token estimate as a percentage of the selected model's context window, the configured `compression_ratio`, the projected percentage after selected deletions, current reduction percentage, how many more estimated tokens must be removed to reach the strict target, and the image token share (`remainingImageTokens`, `imageBlockCount`, `imageTokenPercent`) so the planner can prioritize deleting stale image context when images dominate. With the default `compression_ratio: 0.5`, the strict target is a 50% token reduction.
+The planner is prompted to call `context_compaction_budget` before deleting and after deletion batches. The tool reports the current transcript token estimate as a percentage of the selected model's context window, the configured `compression_ratio`, the projected percentage after selected deletions, current reduction percentage, how many more estimated tokens must be removed to reach the strict target, and the image token share (`remainingImageTokens`, `imageBlockCount`, `imageTokenPercent`) so the planner can prioritize deleting stale image context when images dominate. With the default `compression_ratio: 0.5`, the strict standard planner target is a 50% token reduction. Auto-compaction can still commit a validated below-target result when the projected `tokensAfter` clears the relevant budget: threshold compaction uses the trigger boundary (`effectiveInputBudget - reserveTokens`), while overflow recovery uses the model's effective input budget. On the overflow path, strict-target results are also gated by that effective input budget before they can be committed.
 
 `context_grep_delete` supports literal or regex matching, skips already-deleted or disallowed context, enforces a per-call `maxMatches` safety cap, can require `expectedMatchCount` when the planner wants an exact-match safety check, and routes every accepted match through the same validation pipeline as exact deletions. Disallowed matches are ignored before `matches`, `expectedMatchCount`, deletion stats, and selected targets are calculated, so a broad regex can still remove safe blocks without counting rejected candidates as removed. This includes the universal latest-retained assistant guard: if the latest retained assistant message contains `thinking` or `redacted_thinking`, neither `context_delete` nor `context_grep_delete` may remove any content block from that assistant message, even a visible text sibling block. `maxMatches` limits only one tool call; there is no cumulative deletion cap across repeated `context_delete` or `context_grep_delete` calls. Exact deletion attempts that target disallowed entries/blocks return an explicit non-terminating tool error with correction guidance. Exact deletion payloads that include unsupported fields such as transcript `text`, block `content`, summaries, or replacement data are rejected as non-id-only requests.
 
-Tool calls are cumulative during one compaction run. The assistant can apply several small deletion batches, inspect the updated state, and stop only after the validated stats meet the strict reduction target. Atomic uses the validated tool state as the compaction result; ordinary assistant text is ignored for deletion targets.
+Tool calls are cumulative during one planner run. The assistant can apply several small deletion batches, inspect the updated state, and stop only after the validated stats meet the strict reduction target or an auto-compaction budget fallback can safely accept the current result. Atomic uses the validated tool state as the compaction result; ordinary assistant text is ignored for deletion targets. Each planner run is bounded to 50 real provider turns (including tool-call turns), and the planner nudge loop is additionally bounded to 50 follow-up nudges per planner run, so a planner that keeps making tiny changes or repeated tool calls cannot spin indefinitely.
 
 ### Validation Rules
 
 Validation preserves tool-call/tool-result consistency. If deleting a tool call would leave a tool result behind, Atomic either deletes the paired result too or rejects the plan when that would violate a validation guard. If deleting a tool result would leave a visible dangling tool call, Atomic either deletes the paired call too or rejects the plan.
 
-Atomic also refuses plans that would delete all context or leave no task-bearing context. These checks are local; the model cannot bypass them. Provider context-overflow recovery uses the same validation rules as manual and threshold compaction.
+Atomic also refuses plans that would delete all context or leave no task-bearing context. These checks are local; the model cannot bypass them. Provider context-overflow recovery uses the same validation rules as manual and threshold compaction. During the overflow-only critical planner pass and deterministic eviction fallback, Atomic internally enforces an effective recent guard of `max(preserve_recent, 5)` across all entries, restoring the pre-#1399 last-5 floor even for otherwise-unprotected assistant/tool entries. Within that floor, deletion is rejected through the same recent-target validation used elsewhere. Outside that floor, Atomic relaxes deletion eligibility only for stale protected task-bearing entries (`user`, `custom`, branch summary) that are not carrying assistant/tool/bash errors; every resulting plan still passes fail-closed validation, including latest thinking-bearing assistant immutability, task-bearing floor, and tool-call/result pairing.
 
 ### ContextCompactionEntry Structure
 
@@ -689,6 +705,8 @@ pi.on("session_before_compact", async (event, ctx) => {
 
 If `{ cancel: true }` is returned, compaction aborts with a cancellation error. If `{ deletionRequest }` is returned, Atomic validates it through the same local airlock as model-proposed deletions — unknown IDs, protected targets, orphaning, and empty-context plans are rejected — and skips the internal planner. If nothing is returned, the internal planner runs normally.
 
+Extension-provided deletion requests validate against the original standard transcript and bypass the internal fallback ladder, including its overflow budget-fit gate. The overflow guarantee that committed results fit the effective input budget applies to Atomic's internal ladder results; extension-supplied deletion requests remain a public hook escape hatch that commits after local fail-closed validation. Atomic does not expose a public compaction mode API; protected-entry relaxation is reserved for Atomic's own overflow recovery tiers.
+
 ### session_compact
 
 Fired after compaction succeeds and the `context_compaction` entry is persisted.
@@ -920,7 +938,7 @@ 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; auto-compaction starts when context usage exceeds `contextWindow - reserveTokens`. |
+| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when context usage exceeds the model's effective input budget minus this reserve. |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
 

package/docs/quickstart.md

@@ -80,7 +80,7 @@ See [Providers](/providers) for all supported providers, environment variables,
 
 ## First session
 
-On a fresh install with no prior Atomic startup state, Atomic starts with a first-run workflow prompt. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip onboarding. Paste a ticket description, GitHub issue, path to a spec, or task prompt and Atomic hands it to the normal coding-agent session. The handoff raises the selected model to high reasoning when supported and first asks the parent agent to estimate scope from the seed text alone: tickets, issues, and especially specs often list enough work items, files, tests, docs, migrations, or acceptance criteria to classify likely size without immediately inspecting the repo. That text-only pass is treated as a routing confidence signal, not final planning. If the task is clearly tiny/small and high-confidence, the parent can route directly; if the seed references context that must be read or the scope is medium, large, unclear, or risky, it inspects only the necessary issue/spec/path/repo area and can use targeted read-only subagents such as `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` at their normal defaults. It then chooses `goal` for focused work or `ralph` for broader/riskier work, starts the selected workflow, and continues normally. If you paste the task before logging in or selecting a usable model, Atomic keeps only an in-memory copy, asks you to run `/login`, and resumes with the latest saved task after login or `/model` selection makes the session ready; `/new` starts a fresh unresolved onboarding session and drops that saved in-memory task. If you want normal chat instead, type `/chat` or `/chat <message>`; other slash commands such as `/login`, `/model`, and `/atomic` still work and do not dismiss onboarding.
+On a fresh install with no prior Atomic startup state, Atomic shows a one-time first-run explanation after any What's New notes and directly above the input box describing Atomic as a verifiable coding agent runtime for building and running agent workflows you can feel confident in. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip the first-run explanation. The composer is the normal Atomic input from the start: type a message, run `/login` first if no provider is connected, open `/atomic`, or launch a workflow command without a special onboarding transition.
 
 Once Atomic starts, the fastest way to get value is to kick off a built-in workflow or invoke a skill. Workflows are the default path for non-trivial tasks and for requests with inherent structure plus a verifiable objective, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work where validation matters. If a prompt says `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, or `run checks and fix until green`, it already describes a workflow-shaped loop with a stop condition.
 
@@ -121,7 +121,7 @@ For smaller one-off tasks, use `goal` with a concrete task description that name
 
 ### Monitor and steer a run
 
-Named workflow runs execute in the background. After launch you get a run id; use it to inspect, attach, pause, or resume. First-run `goal`/`ralph` handoffs show the exact `/workflow status <run-id>` and `/workflow connect <run-id>` commands in the dispatched card, and you can also ask in the current chat for status or to steer the run at any point.
+Named workflow runs execute in the background. After launch you get a run id; use it to inspect, attach, pause, or resume.
 
 ```text
 /workflow status <run-id>         # inspect one run's progress
@@ -218,7 +218,7 @@ Restart Atomic, or run `/reload`, after changing context files.
 
 ### Reference files
 
-Type `@` in any interactive editor, including first-run onboarding, to fuzzy-search files; or pass files on the command line:
+Type `@` in any interactive editor to fuzzy-search files; or pass files on the command line:
 
 ```bash
 atomic @README.md "Summarize this"

package/docs/settings.md

@@ -74,7 +74,7 @@ Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
 | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
 | `firstRunOnboardingStartedVersion` | string | - | Internal first-run onboarding start marker used when no prior Atomic startup state identifies the user as returning |
-| `onboardedVersion` | string | - | Internal one-time first-run onboarding completion marker. Returning-user detection from prior startup state, `/chat`, or a successful first-run seed handoff into the normal agent session sets it |
+| `onboardedVersion` | string | - | Internal one-time first-run onboarding completion marker. Returning-user detection from prior startup state or displaying the first-run workflow-engine explanation sets it |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |

package/docs/usage.md

@@ -19,7 +19,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 
 | Feature | How |
 |---------|-----|
-| File reference | Type `@` to fuzzy-search project files, including during first-run onboarding |
+| File reference | Type `@` to fuzzy-search project files |
 | Path completion | Press Tab to complete paths |
 | Multi-line input | SHIFT+Enter, or CTRL+Enter on Windows Terminal |
 | Images | Paste with CTRL+V, ALT+V on Windows, or drag into the terminal |

package/docs/workflows.md

@@ -58,7 +58,7 @@ Use direct chat only for tiny, deterministic, low-risk work where workflow track
 
 ## Quick Start
 
-On a fresh first run with no prior Atomic startup state, Atomic can route your first pasted ticket, issue, spec path, or task prompt into normal workflow-driven agent work. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip onboarding. If you are not logged in or configured yet, Atomic keeps the latest seed in memory only, asks you to run `/login`, and resumes after login succeeds. Once ready, onboarding raises the selected model to high reasoning when supported and hands the seed to the normal coding-agent session with instructions to first estimate likely scope from the seed text alone. Tickets, GitHub issues, and especially specs often list enough work items, files, tests, docs, migrations, or acceptance criteria to make an initial tiny/small/medium/large/unknown call without immediately inspecting the repo. That text-only estimate is only a routing confidence signal, not final implementation planning. If the seed makes the task clearly tiny or small and high-confidence, the parent can route directly; if referenced context must be read or the scope is medium, large, unclear, risky, or not obviously tiny, the parent inspects only the necessary issue/spec/path/repo area and can use targeted read-only subagents such as `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` at their normal defaults before making the high-reasoning routing decision: `goal` for small fixes/quick fixes, `ralph` for non-trivial work around 2k+ changed lines or many files/areas. It then starts the selected workflow and continues normally. Type `/chat` before handoff to skip this one-time routing and use Atomic as a normal coding-agent chat.
+On a fresh first run with no prior Atomic startup state, Atomic shows a one-time explanation after any What's New notes and directly above the normal input box describing Atomic as a verifiable coding agent runtime for building and running agent workflows you can feel confident in. It no longer intercepts the first message, saves a pasted seed, routes to `goal` or `ralph`, raises reasoning, or requires `/chat` to use normal chat. Type a normal message or slash command immediately; run `/login` first if no provider is connected, use `/atomic` for guides, `/workflow list` to discover built-ins, or launch a workflow command directly when you already know what you want.
 
 The fastest way to get a workflow running is to **describe it in natural language** and let Atomic write it for you. If you'd rather write the TypeScript yourself, jump to [Or hand-write the TypeScript](#or-hand-write-the-typescript) below.
 
@@ -110,7 +110,7 @@ Then list and run it like any other workflow:
 /workflow <name> key=value ...
 ```
 
-Named workflow runs are background-oriented. After launch, expect a run id and monitor it with `/workflow status <run-id>`, F2, or `/workflow connect <run-id>`. First-run `goal`/`ralph` handoffs print those exact commands in the dispatched card; use connect to watch, attach, and steer, or ask in the current chat for status or steering at any point.
+Named workflow runs are background-oriented. After launch, expect a run id and monitor it with `/workflow status <run-id>`, F2, or `/workflow connect <run-id>`.
 
 ### Or hand-write the TypeScript
 
@@ -220,7 +220,8 @@ Inputs:
 | `objective` | text | yes | — | Goal-runner objective or delta. Include the desired end state, expected outcome, testing/validation instructions, and any explicit done criteria. |
 | `acceptance_criteria` | text | no | objective | Original immutable task contract that the run must remain consistent with. When launching a follow-up `goal` run from review findings, pass the ORIGINAL task text here so reviewer suggestions cannot drift or contradict the literal contract. |
 | `max_turns` | number | no | `10` | Maximum worker/review turns before human follow-up is needed. |
-| `base_branch` | string | no | `origin/main` | Branch reviewers and the optional final stage compare the current code delta against. |
+| `base_branch` | string | no | `origin/main` | Branch reviewers and the optional final stage compare the current code delta against; also used to create a missing worktree. |
+| `git_worktree_dir` | string | no | `""` | Optional reusable Git worktree root. Empty runs in the invoking checkout; non-empty values run Goal stages in the created/reused worktree. |
 | `create_pr` | boolean | no | `false` | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation after Goal reaches `complete`. |
 
 `goal` defaults to 10 worker/review turns. Reviewer quorum is fixed internally at 2 reviewer `complete` votes. The repeated-blocker threshold defaults to 3 consecutive same-blocker turns and is clamped to `max_turns` when you run fewer than 3 turns.
@@ -232,10 +233,13 @@ Run examples:
 /workflow goal objective="Update the CLI docs to describe the new --json flag, include one usage example, and verify the docs build still passes" max_turns=3
 /workflow goal objective="Fix the settings form validation bug; add/adjust the focused test and consider it done when invalid emails show the inline error without submitting"
 /workflow goal objective="Implement the focused docs fix, run the docs validation command, and open a PR when complete" create_pr=true
+/workflow goal objective="Fix the flaky package install test in an isolated worktree and run the focused regression" git_worktree_dir=../atomic-goal-install-wt base_branch=main
 ```
 
 `goal` uses the raw `objective` exactly as supplied as the operative objective recorded in the ledger and stores `acceptance_criteria` as the immutable literal contract (defaulting to the objective when omitted); it does not run an initial prompt-refinement stage. It creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes the latest worker receipt to `worker-receipt.md`, and appends receipts, reviewer decisions, blockers, reducer decisions, and lifecycle events to the ledger. Worker and reviewer prompts (and the model-facing ledger artifact) deliberately omit the current turn/attempt number so the worker focuses on completing the objective rather than pacing itself to the workflow budget. The objective is treated as user-provided data, not higher-priority instructions. By default `goal` does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling, after Goal reaches `complete` within `max_turns`. Goal worker and reviewer prompts explicitly tell intermediate stages to ignore PR-creation requests; only the final `pull-request` stage may attempt that handoff.
 
+Set `git_worktree_dir` when you want Goal's worker and reviewer stages isolated in a reusable Git worktree. Relative paths resolve from the invoking repository root, existing same-repository worktree roots are reused, and missing paths are created from `base_branch`. Goal preserves the invoking repo-relative cwd inside the worktree, so launching from `repo/packages/api` with `git_worktree_dir=../repo-wt` runs stages from `../repo-wt/packages/api`.
+
 Write the `objective` like a compact acceptance spec. Say what should exist when the run is done, how you want testing handled, which command(s) or manual checks matter, and what outcome proves completion. The workflow is intentionally lean: it does not first generate an RFC or migration plan, so the developer-supplied objective is where scope, validation, and completion criteria belong.
 
 Goal worker/reviewer prompts treat the objective and acceptance criteria as the sole literal source of truth: if follow-up deltas, language specs, upstream issues, in-repo comments, or best practices conflict with explicit wording, reviewers surface the conflict instead of silently implementing external knowledge. Reviewer findings carry `objective_alignment` (`required_by_objective`, `consistent_with_objective`, `beyond_objective`, or `contradicts_objective`); `beyond_objective` and `contradicts_objective` findings are reported but do not block completion and must not be promoted into follow-up objectives without reconciling them against the acceptance criteria. Review decisions also include `requirements_traceability`, a clause-by-clause evidence map over every explicit objective/acceptance-criteria requirement. Goal approval requires that map to be non-empty and fully `proven`; passing worker-authored tests or snapshots alone is circular evidence unless tied to independent current-state proof.

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.5-alpha.3",
+	"version": "0.9.5-alpha.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.5-alpha.3",
+			"version": "0.9.5-alpha.5",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.5-alpha.3",
+				"@bastani/atomic-natives": "0.9.5-alpha.5",
 				"@bufbuild/protobuf": "^2.12.1",
 				"@earendil-works/pi-agent-core": "^0.80.3",
 				"@earendil-works/pi-ai": "^0.80.3",
@@ -514,16 +514,16 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.5-alpha.3",
-				"@bastani/atomic-natives-darwin-x64": "0.9.5-alpha.3",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.5-alpha.3",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.5-alpha.3",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.5-alpha.3",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.5-alpha.3"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.5-alpha.5",
+				"@bastani/atomic-natives-darwin-x64": "0.9.5-alpha.5",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.5-alpha.5",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.5-alpha.5",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.5-alpha.5",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.5-alpha.5"
 			},
 			"engines": {
 				"bun": ">=1.3.14",
@@ -531,8 +531,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -543,8 +543,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -555,8 +555,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -570,8 +570,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -585,8 +585,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -597,8 +597,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.5-alpha.3",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.5-alpha.3.tgz",
+			"version": "0.9.5-alpha.5",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.5-alpha.5.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -77,7 +77,7 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.5-alpha.3",
+    "@bastani/atomic-natives": "0.9.5-alpha.5",
     "@bufbuild/protobuf": "^2.12.1",
     "@earendil-works/pi-agent-core": "^0.80.3",
     "@earendil-works/pi-ai": "^0.80.3",