@bastani/atomic 0.9.8 → 0.9.9-alpha.1

package/docs/workflows.md

@@ -249,6 +249,8 @@ Goal worker/reviewer prompts treat the objective and acceptance criteria as the
 
 The worker may claim readiness, but it cannot finalize completion. Workers start from an observable acceptance/contract matrix derived from the literal objective/acceptance criteria (one row per clause, each mapped to the concrete check that proves it), and are prompted to model states, transitions, and invariants explicitly when the work is stateful. Reviewer findings from the latest round are consolidated into a deduplicated cross-reviewer batch persisted in the round artifact (`consolidated_findings` in `review-round-latest.json`), and the next worker turn is instructed to plan and repair the whole batch — with durable regression evidence for reproduced findings — rather than fixing one finding per turn. Workers and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete checks plus an actual app/flow launch attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. Goal reviewers also look for any QA E2E video referenced by the ledger or receipt and must inspect the actual video before treating it as proof. Three reviewers independently inspect the ledger, worker receipt, repository state, and diff against `base_branch`; each starts in a clean, non-forked context, matching Ralph's reviewer context behavior, and every Goal reviewer uses Ralph's `reviewer-a` model chain with Claude Fable 5 as the primary model. Each reviewer is instructed to first derive its own adversarial check list from the literal contract — boundary/edge/negative probes plus state/transition/invariant probes — before relying on the worker receipt or worker-authored tests, and each returns structured JSON with findings, evidence, verification still remaining, and an optional blocker. A TypeScript reducer marks the goal complete when reviewer quorum approves via the `stop_review_loop` booleans, marks blocked only when the same dependency/tool blocker repeats for the blocker threshold, continues while quorum is missing (recording the reviewers' remaining work in the decision reason), and returns `needs_human` when `max_turns` is exhausted or worker execution fails, so the bounded loop always stops with an inspectable reason.
 
+At the start of every Goal review, each concurrent reviewer uses Intercom to initialize/check coordination and discover the sibling reviewers in the same workflow run. Before validation, reviewers communicate their plans and intended ownership, claim expensive or lock-prone checks, and serialize commands that can conflict in a shared checkout or environment, including full test suites, build or test commands, package-manager operations, browser/E2E sessions, migrations, and generated-artifact steps. They announce each coordinated check's start and completion, release every claimed resource and send siblings an explicit resource-release update, and share reusable command outcomes/evidence where appropriate. This operational coordination prevents collisions and duplicate conflicting work; it does not replace independent patch inspection, analysis, or each reviewer's own verdict.
+
 When Goal's reducer returns `needs_human`, `blocked`, or another incomplete status, the top-level workflow run is not reported as a successful completion. `/workflow status` and lifecycle notices surface it as blocked/failed according to the run's terminal condition. Atomic also preserves structured recoverable failure metadata from the run's blocking stage (`failedStageId`) or run-level failure metadata, so auth, rate-limit, and provider fallback exhaustion remains blocked/resumable even if the workflow later returns ordinary outputs instead of a reserved `status` value. Tolerated branch failures from non-fail-fast parallel work do not reclassify an otherwise completed run.
 
 Every Goal review round also persists an explicit convergence summary. Each reviewer record and review artifact distinguishes schema-parse status from the review verdict with `parsed`, `approved`, `stopReviewLoop`, `nextAction`, `finalActionRemaining`, and `diagnostics` fields; malformed or missing structured reviewer output is reported as a parse failure rather than as an ordinary finding/rejection. When `create_pr=true`, reviewers are told that PR/MR/review creation is a post-approval final action: if implementation and validation requirements are proven and only PR creation remains, the implementation can approve with `finalActionRemaining: true` and `nextAction: "pull-request"` instead of consuming another worker turn. The ledger's reducer decision repeats the same concise fields for the controller outcome, so a successful quorum records `approved: true`, `stopReviewLoop: true`, and `nextAction: "pull-request"` when `create_pr=true` (otherwise `"finish"`) before any final handoff runs.
@@ -295,6 +297,8 @@ Run examples:
 
 Each `ralph` run uses the raw `prompt` exactly as supplied as the operative objective for research, orchestration, and review, and stores `acceptance_criteria` as the immutable literal contract (defaulting to the prompt when omitted). Shared literal-contract prompt language forbids adding behaviors, restrictions, or error conditions beyond the prompt/acceptance criteria and requires surfacing conflicts with external knowledge; Ralph does not run an initial prompt-refinement stage. Each iteration transforms that raw prompt with `/skill:prompt-engineer Transform the following user request into a codebase and online research question which can be thoroughly explored: ...` (`research-prompt-refinement`), researches that transformed question with `/skill:research-codebase ...`, and writes the findings under `research/`. The research, orchestrator, and reviewer prompts carry `acceptance_criteria` next to the literal contract, so orchestrators should pass the ORIGINAL task text when launching follow-up Ralph runs from reviewer findings. The orchestrator starts from an observable acceptance/contract matrix derived from the literal prompt/acceptance criteria (one row per clause mapped to the concrete observable check that proves it) and is prompted to model states, transitions, and invariants explicitly when the work is stateful; it treats the research artifact as its primary implementation context, initializes/updates an OS-temp implementation notes file while generating verifiable evidence for any claims it records in the notes and reviewer artifacts, delegates implementation through sub-agents, repairs unresolved reviewer findings as one consolidated batch (with durable regression evidence for reproduced findings) rather than one finding per iteration, and asks two independent reviewers (`reviewer-a` and `reviewer-b`) to inspect the patch directly against `base_branch`. The reviewer fan-out runs reviewers on different primary model families (Claude Fable 5 and GPT-5.5 Codex, with shared fallbacks) so the adversarial review gets cross-model coverage instead of repeated passes from one model, and each reviewer is instructed to first derive its own adversarial check list from the literal contract — boundary/edge/negative probes plus state/transition/invariant probes — before relying on the implementation notes, orchestrator report, or worker-authored tests. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete checks plus an actual app/flow launch attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video (referenced in the implementation notes and surfaced as `qa_video_path`); reviewers receive that path and must inspect the actual video before treating it as proof. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review after reviewer approval. If reviewers find issues, the next `research-prompt-refinement` and research stages receive the review artifact path (whose `review-round-latest.json` now also carries a deduplicated cross-reviewer `consolidated_findings` batch) so follow-up research can address unresolved findings, and research stages fork from prior research session data when available. The loop stops only when both reviewers independently approve or `max_loops` is reached, so the bounded loop always stops with an inspectable review round. Ralph findings include the same `objective_alignment` classification used by Goal, and each reviewer derives a single authoritative `stop_review_loop` boolean from that evidence: `required_by_objective` findings mean `false` at any priority (P3 included, because severity labels alone never dismiss objective-relevant findings), `consistent_with_objective` P0/P1/P2 findings mean `false` while P3 remains a non-blocking nice-to-have, and `beyond_objective`/`contradicts_objective` findings are surfaced but non-blocking so they are not silently converted into new requirements. The loop gate approves deterministically on `stop_review_loop=true` plus a null `reviewer_error` (parse failures count as non-approval) without recomputing approval from the findings arrays. Ralph review decisions also include `requirements_traceability`, a clause-by-clause evidence map over every explicit prompt/acceptance-criteria requirement kept as audit evidence for deriving the flag; reviewers are explicitly told that process-only clauses (reviewer quorum, and the authorized post-approval PR/MR/review final action when `create_pr=true`) must never hold the flag at `false`. Worker-authored tests or snapshots passing are circular evidence unless tied to independent current-state proof. By default Ralph 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 `pull-request` 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; Ralph's own PR-creation instructions live in that final stage and run only after approval.
 
+At the start of every Ralph review, each concurrent reviewer uses Intercom to initialize/check coordination and discover the sibling reviewer in the same workflow run. Before validation, reviewers communicate their plans and intended ownership, claim expensive or lock-prone checks, and serialize commands that can conflict in a shared checkout or environment, including full test suites, build or test commands, package-manager operations, browser/E2E sessions, migrations, and generated-artifact steps. They announce each coordinated check's start and completion, release every claimed resource and send the sibling an explicit resource-release update, and share reusable command outcomes/evidence where appropriate. This operational coordination prevents collisions and duplicate conflicting work; it does not replace independent patch inspection, analysis, or each reviewer's own verdict.
+
 Each Ralph review artifact and `review-round-latest.json` includes a `convergence_decision` summary with `parsed`, `approved`, `stopReviewLoop`, `nextAction`, `finalActionRemaining`, and `diagnostics`. This makes malformed or missing structured reviewer output visible as a parse failure, separate from a parsed reviewer rejection or blocking finding. When `create_pr=true`, reviewers are told that PR/MR/review creation is a post-approval final action: if implementation and validation requirements are proven and only PR creation remains, the implementation can approve with `finalActionRemaining: true` and `nextAction: "pull-request"` instead of consuming another orchestration iteration. When both reviewers converge, the latest round records `approved: true`, `stopReviewLoop: true`, and `nextAction: "pull-request"` when `create_pr=true` (otherwise `"finish"`), and the implementation loop stops before the final handoff stage.
 
 Set `git_worktree_dir` when you want Ralph's worker 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`. Ralph 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`.
@@ -410,9 +414,9 @@ Named runs go to the background. Common controls:
 
 When a paused stage is resumed with a message, Atomic lets the stage answer that resume message, then (if the stage has not already finalized) injects `Continue where you left off. If you believe you are finished with your original task (or a redefined task if the user told you), stop.` into the same stage session before normal stage completion/readiness handling. This keeps interrupted work moving without asking you to manually type a second continuation prompt while also preventing stages that already finished their scoped work from overstepping.
 
-Durable `/workflow resume` preserves completed stage metadata and graph topology. When it reopens an unfinished stage session mid-chat, it uses the same continuation prompt shown above. Replayed `ctx.stage`, `ctx.task`, `ctx.chain`, `ctx.parallel`, and child-workflow checkpoints keep their original summaries, timing, session/model metadata, and parallel fanout parentage in status and graph views instead of appearing as freshly flattened replay nodes.
+Durable `/workflow resume` preserves completed stage metadata, active-stage elapsed time, and graph topology. While an LM stage or task is active, repeated durable checkpoints refresh its accumulated pause-adjusted duration even when its session file does not change. Each new Atomic process that reopens the unfinished session mid-chat starts from the latest saved baseline and uses the same continuation prompt shown above, so repeated process-boundary resumes keep status, graph, stored, and lifecycle duration cumulative without double-counting pauses from earlier process segments. Replayed `ctx.stage`, `ctx.task`, `ctx.chain`, `ctx.parallel`, and child-workflow checkpoints keep their original summaries, timing, session/model metadata, and parallel fanout parentage instead of appearing as freshly flattened replay nodes.
 
-Workflow stage sessions are marked as **internal** and excluded from the standard `/resume`, `atomic -r`, and `--continue` history so they do not clutter your interactive session picker. They remain resumable and inspectable through the workflow-specific commands and tool actions shown here (`/workflow resume`, `/workflow attach`, `workflow({ action: "status" | "stages" | "stage" | "resume" })`), which read the run/stage store and its `sessionFile` links directly. Passing a stage session's file path to `--session` still opens it explicitly. Legacy workflow sessions created before this marker behavior lack the signal and will continue to appear in the standard history until they age out.
+Workflow stage sessions and first-party subagent transcripts created inside them are classified as **internal** at creation and excluded from the standard `/resume`, `atomic -r`, `--continue`, and global history surfaces. Fork-context stages and subagents inherit the owning run/stage marker in their initial JSONL header, avoiding a briefly visible ordinary session. They remain resumable and inspectable through the workflow-specific commands and tool actions shown here (`/workflow resume`, `/workflow attach`, `workflow({ action: "status" | "stages" | "stage" | "resume" })`), which read the run/stage store and its `sessionFile` links directly. Passing a stage session's file path to `--session` still opens it explicitly. Classification requires exact `internal: true` plus complete run/stage metadata; malformed legacy markers and ordinary user forks remain in standard history. Legacy workflow sessions created before this marker behavior lack provable ownership and continue to appear until they age out.
 
 Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.editor`, and `ctx.ui.custom<T>` appear as awaiting-input nodes in the workflow graph viewer, not as chat modals — use `/workflow connect <run-id>` (or F2), then press Enter on the focused node or click a visible graph node directly to focus and open/attach it for local answers.
 
@@ -978,7 +982,7 @@ In non-interactive (`-p`, `--print`, or `--mode json`) sessions, named workflow
 /workflow reload
 ```
 
-Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Live `subagent` tool calls in stage chats use the same single, parallel, and chain progress widgets as main chat, including after exiting and re-attaching to an in-flight stage; press Ctrl+O (the `app.tools.expand` binding) to expand live detail for every child, including current tool activity and artifact paths. If an async/background subagent is running while the fullscreen workflow graph is open, the graph statusline mirrors the async summary so the background run remains visible; hide the graph with `h`/Ctrl+D or reconnect later to return to the full below-editor async widget. Press `ctrl+t` inside an attached stage chat to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore transcript or prompt scrolling. Archived read-only stage transcripts expose the same footer and copy-mode status, so their text can also be selected and copied; `esc` closes the transcript and `ctrl+d` returns to the graph. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated; killed runs are retained in live history/status for read-only inspection. Use `/workflow reload` after adding, editing, installing, or removing workflow resources or package manifest workflow entries and you want Atomic to rediscover them in-process. `/workflow status` lists all retained active and terminal top-level runs by default; implementation-owned nested child runs are flattened into their parent workflow rather than listed separately. `/workflow status --all` is retained as a compatibility alias.
+Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. While the workflow graph is active, vertical wheel/trackpad gestures pan it up and down, and horizontal gestures pan wide graphs left and right when the terminal exposes horizontal wheel events; these gestures remain scoped to the graph instead of leaking into the main chat or terminal scrollback. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Live `subagent` tool calls in stage chats use the same single, parallel, and chain progress widgets as main chat, including after exiting and re-attaching to an in-flight stage; press Ctrl+O (the `app.tools.expand` binding) to expand live detail for every child, including current tool activity and artifact paths. If an async/background subagent is running while the fullscreen workflow graph is open, the graph statusline mirrors the async summary so the background run remains visible; hide the graph with `h`/Ctrl+D or reconnect later to return to the full below-editor async widget. Press `ctrl+t` inside an attached stage chat to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore transcript or prompt scrolling. Archived read-only stage transcripts expose the same footer and copy-mode status, so their text can also be selected and copied; `esc` closes the transcript and `ctrl+d` returns to the graph. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated; killed runs are retained in live history/status for read-only inspection. Use `/workflow reload` after adding, editing, installing, or removing workflow resources or package manifest workflow entries and you want Atomic to rediscover them in-process. `/workflow status` lists all retained active and terminal top-level runs by default; implementation-owned nested child runs are flattened into their parent workflow rather than listed separately. `/workflow status --all` is retained as a compatibility alias.
 
 <p align="center"><img src="images/workflow-graph.png" alt="Workflow Graph Viewer" width="600" /></p>
 
@@ -1048,13 +1052,14 @@ Atomic workflows support **cross-session resumability** via a durable workflow b
 - **Durable `ctx.tool`**: `ctx.tool(name, args, fn)` runs TypeScript and caches the result by stable call order plus content hash of `name` + `args`. Repeated same-name/same-args calls are distinct within one workflow and replay in order after resume. DBOS-backed checkpoint writes are serialized and awaited before the tool returns, so a completed side effect is not exposed to workflow code before its checkpoint is durable; retry backoff observes workflow cancellation before later attempts run.
 - **Durable `ctx.ui`**: Completed `ctx.ui.input` / `confirm` / `select` / `editor` / `custom` responses are cached by prompt identity, including prompt kind, label/message, options, and call order so repeated prompts do not collide. On resume an already-answered prompt returns its cached response instead of re-asking the user, including `ctx.ui.custom` prompts that intentionally complete with `undefined`/void.
 - **Durable `ctx.stage` / `ctx.task` / `ctx.chain` / `ctx.parallel` / `ctx.workflow`**: Completed stage-like operations are recorded with stable replay keys. `ctx.chain` and `ctx.parallel` reuse the durable task primitive for each item, and child `ctx.workflow` calls checkpoint the completed child result at the parent workflow boundary with a dedicated replay-key counter so repeated same-child calls do not desync ordinal sequencing across resume. Schema-backed `ctx.stage(..., { schema }).prompt(...)` checkpoints preserve the parsed structured value, not just the rendered text. The live stage finalizer awaits durable writes before returning control where practical; if finalization fails, Atomic releases stage handles and concurrency limiter slots before reporting the finalization error instead of marking the workflow completed without a durable checkpoint. Workflow terminal status — including `ctx.exit` terminal states (`cancelled`, `blocked`, `skipped`) — is flushed to durable metadata before the run reports completion. On resume, cached operations are skipped and represented in the workflow graph as completed durable-replay nodes so status/overlay views still show progress.
-- **Session-file cache**: Because the default backend is persistent, top-level workflow metadata is mirrored as Atomic custom entries (`customType: "workflow.durable.checkpoint"`) in the session JSONL so a new session can discover resumable root workflows without scanning the durable store directly. Child workflows are hidden from this catalog. The durable backend remains the checkpoint source of truth; the session cache is a discovery index. `/workflow resume` refuses a cache-only entry as `stale` when a root workflow has session metadata but no checkpoint state in the durable backend, instead of silently re-running from scratch — re-run the workflow explicitly to start fresh.
+- **Session-file cache**: Because the default backend is persistent, top-level workflow metadata is mirrored as Atomic custom entries (`customType: "workflow.durable.checkpoint"`) in the session JSONL so a new session can discover resumable root workflows without scanning the durable store directly. Child workflows are hidden from this cache. The durable backend remains the checkpoint source of truth; the session cache is only a discovery index. `/workflow resume` refuses a cache-only resumable entry as `stale` instead of silently re-running from scratch. Completed inspection is cataloged separately from resumability and requires an authoritative completed backend handle, durable checkpoints, and at least one retained stage conversation. Each retained transcript must be a regular, parseable Atomic session file with prior message context; empty, malformed, header-only, missing, and directory paths are stale.
 - **Child side-effect scoping**: A child workflow launched via `ctx.workflow(child)` checkpoints its internal `ctx.tool`/`ctx.ui`/`ctx.stage` side effects under the parent (root) durable workflow, keyed by a stable child-boundary scope. If the parent is interrupted while a child is mid-flight, resuming the parent re-runs the child but replays the child's already-completed side effects from the root store instead of re-executing them (no split-brain per-run UUID checkpoints).
-- **Crash-safe file backend**: Default file-backed durability stores each root workflow in its own lock-protected JSON file under `~/.atomic/workflow-durable` instead of one shared state file. Completed/cancelled/non-resumable terminal workflow files are pruned, writes use `0700` directories and `0600` state/owner files where the platform supports chmod, and stale locks are reclaimed only when their owner marker belongs to a dead process. If Atomic cannot resolve `HOME`/`USERPROFILE`, it fails closed to in-memory durability instead of writing state under `/tmp`. Durable replay identities use a SHA-256 digest over canonical JSON so distinct tool/stage identities never collide.
+- **Crash-safe file backend**: Default file-backed durability stores each root workflow in its own lock-protected JSON file under `~/.atomic/workflow-durable` instead of one shared state file. Successful completed workflow files are retained for read-only inspection through `/workflow resume`; cancelled and explicitly non-resumable failed/blocked files are pruned. Writes use `0700` directories and `0600` state/owner files where the platform supports chmod, and stale locks are reclaimed only when their owner marker belongs to a dead process. If Atomic cannot resolve `HOME`/`USERPROFILE`, it fails closed to in-memory durability instead of writing state under `/tmp`. Durable replay identities use a SHA-256 digest over canonical JSON so distinct tool/stage identities never collide.
+- **Versioned compatibility cleanup**: File state, DBOS metadata/checkpoint envelopes, and session discovery entries share one durable format version. Current records remain resumable; records explicitly marked as the incompatible legacy v1 format are permanently removed from the file or DBOS backend before they can appear in resume selectors, completed catalogs, startup notices, or related listings. After compatibility preparation, matching restored/live run snapshots and notices are purged too, including when DBOS deletion fails, so failure fallbacks and live resume paths cannot restore or dispatch the row. Future-version, malformed, and unavailable records are hidden but preserved rather than guessed at, deleted, or overwritten; unsupported marked DBOS envelopes are not reinterpreted as raw legacy outputs. Cleanup is idempotent, and a failed DBOS deletion remains suppressed while a later discovery retries the permanent deletion.
 
 **Privacy and retention.** File and DBOS durability persist workflow inputs, completed `ctx.tool` outputs, answered `ctx.ui` responses, stage outputs, and stage-session paths as plaintext durable state so replay can skip completed work. Treat `~/.atomic/workflow-durable` and the configured DBOS database as sensitive. To opt out of cross-session checkpoint persistence for a session, start Atomic with `ATOMIC_WORKFLOW_DURABLE=0` (also accepts `false`, `off`, `memory`, or `in-memory`); workflows then use process-local in-memory durability and cannot be resumed after the process exits.
 
-The default file backend prunes completed, cancelled, and explicitly non-resumable failed/blocked workflow files when terminal status is recorded. Running, paused (quit), and recoverably failed workflows with checkpoint progress are retained indefinitely by design so crash recovery and `/workflow resume` remain available across sessions. Use `/workflow kill <id>` to mark a durable workflow cancelled/non-resumable and remove its file-backed state, or delete the corresponding `workflow-<encoded-id>.json` file under `~/.atomic/workflow-durable` if you intentionally want to discard abandoned resumable state outside Atomic.
+The default file backend retains running or paused workflows with a durable checkpoint or pending prompt, failed or blocked workflows unless explicitly marked `resumable: false`, and successful completed workflows with checkpoint progress. Completed state remains available so `/workflow resume` can reconstruct an immutable final graph and reopen retained stage transcripts without dispatching the workflow. Cancelled and explicitly non-resumable failed/blocked files are removed. Retained files contain the plaintext durable data described above; use `/workflow kill <id>` before completion when you want to cancel and remove a durable run, or delete the corresponding `workflow-<encoded-id>.json` file under `~/.atomic/workflow-durable` when you intentionally want to discard retained completed or abandoned state outside Atomic.
 
 **Resume after editing a workflow.** Replay identity is based on workflow id plus each `ctx.*` call's stable content hash and ordinal. Editing a workflow between quit/crash and resume can intentionally invalidate or shift checkpoints: changed prompts/arguments/stage names re-run, and inserted/reordered `ctx.*` calls may not match old ordinal checkpoints. Prefer finishing or killing old durable runs before deploying reordered workflow definitions; otherwise treat resume as best-effort from compatible checkpoint identities.
 
@@ -1087,23 +1092,31 @@ export default workflow({
 
 ### `/workflow resume` — cross-session resume selector
 
-The `/workflow resume` command mirrors `/resume` ergonomics and now uses the same Atomic session-selector tree chrome as `/resume` for its interactive picker. With no id, interactive sessions show one `/resume`-style searchable/threaded selector that lists both live/paused runs and compatible cross-session durable workflows together, so the user can choose from all resumable workflows in one view. The selector uses async DBOS hydration (`prepareDurableResumable`) so cross-session durable entries discovered from Postgres are included even when live runs exist. Dismissing the selector returns to chat without opening a second picker, and selecting a failed-but-resumable live run uses the normal continuation path rather than opening a read-only snapshot. On a successful durable resume, the overlay connects to the resumed run automatically (matching live resume behavior). Headless sessions print the filtered durable catalog and durable resume dispatch preserves the same non-interactive tool/UI restrictions as normal workflow dispatch. With a target id, Atomic first checks live runs in the current session; when the target id is not a live run, it falls back to the cross-session durable resume catalog and resumes by top-level workflow id, then opens the overlay. Resume re-dispatches the workflow with its cached inputs and the **original workflow id**, so completed `ctx.tool`, `ctx.ui`, stage/task/chain/parallel items, and child workflow boundaries return cached results instead of re-executing — DBOS-style replay without Postgres. Replayed stages preserve graph parent/frontier lineage so subsequent stages connect correctly. Empty string stage outputs are preserved distinctly from undefined/no-result during checkpointing. Stale session-cache entries with no matching durable backend handle are hidden from the selector because they came from older non-checkpointed workflow engines and cannot resume usefully. Durable `running`/`failed`/`blocked` rows whose workflow definition is no longer registered are also hidden from no-arg discovery, which keeps old test or pre-engine rows out of the picker without changing targeted `/workflow resume <id>` diagnostics. Stale cache entries for workflows the durable backend knows are terminal (completed/cancelled/non-resumable) are also suppressed, so terminal workflows cannot be resurrected from old JSONL cache metadata.
+The `/workflow resume` command mirrors `/resume` ergonomics and uses the same searchable/threaded Atomic session-selector chrome. With no id, it builds one deduplicated picker containing paused or recoverably failed live runs, compatible cross-session resumable runs, and authoritative successful completed runs. Atomic globally orders that picker newest-first: live rows use their latest run or stage activity, durable and completed rows use their latest durable update, and equal timestamps use workflow ID as a deterministic tie-breaker so source enumeration order cannot affect the result. Live rows take precedence over matching durable rows, and resumable durable rows take precedence over matching completed rows. Completed rows use the existing green `✓ completed` visual language. Durable catalogs are asynchronously hydrated from DBOS when configured even when live rows exist, stale cache-only data is filtered, and actively executing runs remain excluded to prevent double dispatch. A selector mount failure closes cleanly instead of leaving the command pending.
+
+Only entries using the current durable format are selectable. An explicitly legacy durable row is cleaned from its authoritative backend during discovery, so an old session-cache entry cannot make it appear loadable. Unknown or future formats stay hidden without destructive migration; upgrade Atomic to a version that understands them instead of editing their stored data.
+
+Selecting a paused, failed, blocked, or crash-recovery target follows the existing resume path unchanged: Atomic re-dispatches the workflow with its cached inputs and the **original workflow id**, so previously completed `ctx.tool`, `ctx.ui`, stage/task/chain/parallel items, and child workflow boundaries replay from durable checkpoints rather than executing again. Selecting a completed target follows a separate open path. Atomic reconstructs a completed run/stage snapshot from authoritative checkpoints and opens the detail/chat overlay without calling the durable resume dispatcher or re-running workflow stages, tools, tasks, prompts, or workflow code.
+
+Completed detail state is read-only. A retained stage transcript can still be opened and continued conversationally: the stage's Atomic session is reopened lazily and a new follow-up is appended to that chat only. Follow-up chat does not change the completed run or durable handle back to `running`, does not replay workflow side effects, and does not make the completed workflow resumable.
+
+When Atomic starts with an existing session or resumes one, it shows an informational notice for root workflows referenced by that session whose authoritative durable state is resumable: `running`/`paused` entries need checkpoint progress or a pending prompt, while `failed`/`blocked` entries are eligible unless they explicitly set `resumable: false`. Completed, cancelled, zero-progress running/paused, nested-child, explicitly non-resumable failed/blocked, and stale cache-only entries without durable backend state are omitted. Current and legacy checkpoint entry shapes are recognized only to associate a workflow with the restored session; the authoritative durable catalog supplies its current name and eligibility. The notice provides `/workflow resume <id>` commands, and the command validates the current workflow registry again before dispatch.
 
 ```text
-/workflow resume                       # Show resumable workflows (live + durable)
-/workflow resume <workflow-id-or-prefix>  # Resume by top-level id; completed checkpoints replay
+/workflow resume                          # Mixed picker: resumable + completed
+/workflow resume <workflow-id-or-prefix> # Resume unfinished work or open completed detail/chat
 ```
 
-The selector displays workflow rows through the same `/resume` tree UI and lists only **inactive, resume-applicable** workflows: paused (quit) or recoverably-failed durable runs with checkpoint progress, plus any live paused/failed runs. Actively-running workflows are hidden from the selector — resuming one that is already executing (in this or another session) would double-dispatch, so `/workflow resume <running-id>` is refused with an intuitive error pointing at `/workflow connect` (to attach) or `/workflow kill` (to clear a stuck run). Quitting the CLI/panel flips the durable handle from `running` to `paused`, which is what makes a workflow re-enter the resumable set; a fresh dispatch or durable resume flips it back to `running`. Running/paused durable rows appear only after the workflow has at least one durable checkpoint or pending checkpointable prompt, so a just-started workflow with no resumable state does not clutter the picker. Eligible LM stages also write their Atomic/Pi session metadata as soon as the stage session opens; on durable resume, Atomic reopens that exact session file and sends `Continue` instead of replaying the original workflow prompt, so repeated quit/resume cycles append to the active LM chat rather than duplicating prompts or emptying prior chats. Completed tool/UI/stage checkpoints still replay all-or-nothing, and successful completion marks the durable handle `completed`, prunes the file-backed state for that workflow, and removes the row once the whole workflow reaches the end. Quitting the CLI is treated as a resumable process boundary rather than explicit workflow cancellation, so durable-progress workflows remain available to `/workflow resume`; use `/workflow kill` when you want a workflow removed as cancelled/non-resumable. If no resumable workflows remain after filtering, interactive `/workflow resume` still opens the same empty selector rather than printing an error, matching `/resume` behavior. In fresh sessions, Atomic scans workflow-specific `workflow.durable.checkpoint` JSONL history for discovery, but the durable backend remains authoritative: cache rows without backend checkpoint state are treated as old incompatible metadata and are hidden instead of prompting a stale resume failure. File-backed durability is enabled by default under `~/.atomic/workflow-durable`, so `/workflow resume` can discover cross-session workflows without any setup.
+Explicit full IDs take precedence, while prefixes resolve across live, resumable durable, and completed targets as one namespace. Ambiguous prefixes use the existing-style ambiguity diagnostic. A completed backend row with no checkpoints or no usable retained stage conversation is hidden from the picker; an explicit target reports that it is stale or missing required durable checkpoint/session data. A completed run remains inspectable when at least one stage has a usable transcript; missing, empty, directory, context-empty, or partially malformed transcript paths are omitted from stage chat attachment. Validation uses the final retained transcript for a repeated stage replay key, so an obsolete superseded checkpoint path does not hide an otherwise valid completed run. Reopening inspection refreshes a changed authoritative retained-chat handle. Session-cache-only rows are likewise hidden because the backend is authoritative. Cancelled, killed, non-resumable failed, and other terminal non-success states are never added. Normal `/resume`, `atomic -r`, and `--continue` behavior for internal workflow stage sessions is unchanged.
 
 ### Cancellation, failure, and retry semantics
 
 | Scenario | Behavior |
 | --- | --- |
 | **Workflow killed/cancelled** | Marked `cancelled` in durable state and excluded from `/workflow resume` discovery. Start a new workflow run if you intentionally want to retry cancelled work. |
-| **Stage failure (recoverable)** | Workflow marked `failed` but remains in the resumable list. `/workflow resume <id>` continues from the last completed checkpoint. |
-| **Stage failure (non-recoverable)** | Workflow marked `failed`, not resumable. |
-| **Process crash** | Workflow remains `running` in durable state. On next session start, it appears in the resumable selector. Resume re-executes from the last completed checkpoint. |
+| **Stage failure (recoverable)** | Workflow marked `failed` or `blocked` and remains resumable by default. `/workflow resume <id>` continues from the last completed checkpoint unless durable metadata explicitly sets `resumable: false`. |
+| **Stage failure (non-recoverable)** | Workflow marked `failed` or `blocked` with `resumable: false`, so it is excluded from resume discovery. |
+| **Process crash** | Workflow remains `running` in durable state. On next session start, it appears in resume discovery when it has a durable checkpoint or pending prompt. Resume re-executes from the last completed checkpoint. |
 | **`ctx.tool` retry** | When `retriesAllowed: true`, the tool function is retried with exponential backoff. Cancellation is checked before each attempt and during retry backoff, so later attempts do not run after the workflow is cancelled. After exhausting retries, the error propagates and the workflow fails. |
 | **`ctx.ui` pending prompt** | If a UI prompt was not answered before interruption, resume leaves off on that prompt — the user must answer it to continue. |
 
@@ -1115,7 +1128,7 @@ File-backed durability is the default and requires no setup. For production-grad
 export DBOS_SYSTEM_DATABASE_URL="postgresql://user:password@localhost:5432/atomic_dbos_sys"
 ```
 
-When `/workflow resume` lists or resumes a DBOS-backed workflow in a fresh process, Atomic first hydrates its in-memory replay mirror from DBOS. Checkpoints are stored as structured DBOS outputs containing the checkpoint kind, id, tool argument hash, UI prompt hash, stage replay key, and completed output, so replay can skip completed `ctx.tool`, `ctx.ui`, `ctx.stage`, `ctx.task`, `ctx.chain`, `ctx.parallel`, and `ctx.workflow` work without relying on prior in-process state. Atomic updates the in-memory replay mirror for awaited DBOS checkpoints only after DBOS accepts the write, and root metadata is mirrored as versioned DBOS records where the latest timestamp wins during hydration. Older DBOS records that contain only a raw output are still read as generic stage checkpoints.
+When `/workflow resume` lists or resumes a DBOS-backed workflow in a fresh process, Atomic first hydrates its in-memory replay mirror from DBOS. Checkpoints are stored as structured, versioned DBOS outputs containing the checkpoint kind, id, tool argument hash, UI prompt hash, stage replay key, and completed output, so replay can skip completed `ctx.tool`, `ctx.ui`, `ctx.stage`, `ctx.task`, `ctx.chain`, `ctx.parallel`, and `ctx.workflow` work without relying on prior in-process state. Atomic updates the in-memory replay mirror for awaited DBOS checkpoints only after DBOS accepts the write, and root metadata is mirrored as versioned DBOS records where the latest timestamp wins during hydration. Unmarked raw-output checkpoint records remain readable as generic stage checkpoints when their workflow has compatible current metadata; marked envelopes with unsupported versions are ignored rather than decoded as raw output.
 
 The default file backend needs no environment variable or database. It writes one lock-protected JSON state file per root workflow in `~/.atomic/workflow-durable`, making cross-session `/workflow resume` immediately available on a normal Atomic install while avoiding shared-state growth across unrelated workflows.
 
@@ -1207,6 +1220,8 @@ Direct mode supports top-level/default options and per-task options such as `con
 
 For large fan-outs, prefer `outputMode: "file-only"` so the parent result contains compact file references instead of full output. Treat intercom payloads from async direct runs as user-visible workflow output.
 
+Worktree isolation is an explicit runtime option, not a property inferred from task text. Natural-language instructions to create or use a worktree do not enable runner isolation, and `cwd` only selects the starting directory; a write-capable direct run without a worktree option executes in that checkout. Set `worktree: true` for runner-managed temporary per-task worktrees, or set `gitWorktreeDir` for a runner-managed reusable same-repository worktree. Invalid, empty, foreign-repository, or conflicting worktree requests fail with an actionable diagnostic rather than falling back to the invoking checkout. For independent task queues, prefer one run per item with its own reusable worktree instead of a monolithic chain rooted in the primary checkout.
+
 ## Fast Inference for Workflow Stages
 
 Workflow stages can opt into faster, higher-priority inference on supported providers so multi-stage runs finish sooner. This is currently delivered through Codex fast mode.
@@ -1902,7 +1917,7 @@ Workflow stages inherit the active host session directory only when the host is
 
 Workflow stages use the same upstream-compatible `bash` tool as normal Atomic sessions. If `bash` is enabled for a stage, commands run through the configured shell with the stage process permissions; workflow options no longer include a command-level allow/deny field for shell text. Use `tools`/`noTools` to expose or hide shell access, prefer narrower custom tools for repeatable operations, and run workflows inside a container, VM, or other sandbox when command allowlisting or stronger isolation is required.
 
-`gitWorktreeDir` selects a reusable Git worktree root for `ctx.stage`, `ctx.task`, `ctx.chain`, and `ctx.parallel`. If the path is missing, Atomic creates it with `git worktree add --detach <path> <baseBranch>`; if it exists, it must be a same-repository worktree root. The default stage cwd becomes the matching cwd inside the worktree and preserves the invoking repo-relative subdirectory. Explicit `cwd` still wins; relative `cwd` values resolve from the worktree cwd, while absolute `cwd` values are used as provided. `gitWorktreeDir` is mutually exclusive with `worktree: true`: use `gitWorktreeDir` for named/reusable worktrees and `worktree: true` for temporary direct-mode worktrees that are cleaned up after the run. Atomic caches reusable worktree setup within a workflow run, retries one transient timeout from read-only Git repository probes, and reports the exact Git command, cwd, timeout, elapsed time, exit status/signal, and spawn error details when preflight fails.
+`gitWorktreeDir` selects a reusable Git worktree root for `ctx.stage`, `ctx.task`, `ctx.chain`, and `ctx.parallel`. If the path is missing, Atomic creates it with `git worktree add --detach <path> <baseBranch>`; if it exists, it must be a same-repository worktree root located outside the invoking checkout. The invoking checkout itself, nested targets inside it, and missing targets whose symlinked parent resolves inside it are rejected before Git creates or reuses a worktree. The default stage cwd becomes the matching cwd inside the worktree and preserves the invoking repo-relative subdirectory. An explicit absolute `cwd` inside the invoking repository is remapped to the corresponding location inside the selected worktree; an absolute `cwd` already inside that worktree is preserved. Relative values resolve from the worktree cwd and cannot escape it. Any `cwd` that would escape either lexically or through a symlink fails before the stage session starts instead of silently running elsewhere. Runner-managed reusable-worktree relative direct output paths follow the effective worktree cwd and cannot traverse or follow symlinks outside the selected worktree. Temporary-worktree relative direct outputs are persisted under distinct per-task runner-owned temporary artifact directories before cleanup so returned artifacts remain readable, including with `outputMode: "file-only"`; they likewise cannot escape their output root, and Atomic rejects a pre-existing symlink or junction at the trusted artifact root. Explicit absolute outputs and nonblank explicit `chainDir` locations remain caller-selected, while blank `chainDir` values are treated as omitted. `gitWorktreeDir` is mutually exclusive with `worktree: true`: use `gitWorktreeDir` for named/reusable worktrees and `worktree: true` for temporary direct-mode worktrees that are cleaned up even when startup fails before the workflow callback. Temporary isolation defaults to the runner invocation cwd when a task cwd is omitted, and relative task cwd values resolve from that invocation cwd. Atomic caches reusable setup by canonical repository and target identity within a workflow run, independent of equivalent path spelling or `baseBranch`, and revalidates the selected checkout identity before reuse, retries one transient timeout from read-only Git repository probes, and reports the exact Git command, cwd, timeout, elapsed time, exit status/signal, and spawn error details when preflight fails. Worktrees provide checkout and cwd isolation, not an operating-system security sandbox; use a container, VM, or another OS-enforced boundary for untrusted code that can race or mutate arbitrary filesystem paths.
 
 To bind user inputs to a workflow-wide worktree default, set `worktreeFromInputs` in `workflow({...})`:
 

package/examples/extensions/custom-compaction.ts

@@ -1,64 +1,20 @@
 /**
- * Custom Compaction Deletion Policy Extension
- *
- * Verbatim Compaction is deletion-only: extensions cannot replace history with a
- * generated summary. This example shows how to provide an exact deletion request
- * before Atomic's internal planner runs. Atomic still validates the requested
- * entry IDs locally before appending a context_compaction entry.
- *
- * This policy deletes older, unprotected, successful bash execution entries once
- * they are large enough to matter. If no safe candidates are present, it returns
- * nothing and Atomic uses its default deletion planner.
- *
- * Usage:
- *   atomic --extension examples/extensions/custom-compaction.ts
+ * Offline custom compaction: extensions may replace the prepared region string
+ * before Atomic resolves model credentials. The runtime keeps the boundary and
+ * persists this text verbatim.
  */
-
-import type { ContextDeletionRequest, ExtensionAPI } from "@bastani/atomic";
-
-const MIN_BASH_OUTPUT_TOKENS = 250;
-const MAX_DELETIONS_PER_RUN = 12;
-
-export default function (pi: ExtensionAPI) {
-	pi.on("session_before_compact", async (event, ctx) => {
-		const { preparation, reason, mode } = event;
-		const candidates = preparation.transcript.entries
-			.filter((entry) => !entry.protected)
-			.filter((entry) => entry.message.role === "bashExecution" && entry.message.exitCode === 0)
-			.filter((entry) => entry.tokenEstimate >= MIN_BASH_OUTPUT_TOKENS)
-			.slice(0, MAX_DELETIONS_PER_RUN);
-
-		if (candidates.length === 0) {
-			if (ctx.hasUI) {
-				ctx.ui.notify("Custom compaction policy found no safe bash output to delete; using default planner", "info");
-			}
-			return;
-		}
-
-		const deletions: ContextDeletionRequest["deletions"] = candidates.map((entry) => ({
-			kind: "entry",
-			entryId: entry.entryId,
-			rationale: "Large successful bash output selected by custom compaction policy",
-		}));
-
-		if (ctx.hasUI) {
-			const tokenEstimate = candidates.reduce((sum, entry) => sum + entry.tokenEstimate, 0);
-			ctx.ui.notify(
-				`Custom compaction (${reason ?? "manual"}/${mode}): requesting ${deletions.length} deletion(s), about ${tokenEstimate.toLocaleString()} tokens`,
-				"info",
-			);
-		}
-
-		return {
-			deletionRequest: { deletions },
-		};
+import type { ExtensionAPI } from "@bastani/atomic";
+
+export default function customCompaction(pi: ExtensionAPI): void {
+	pi.on("session_before_compact", async (event) => {
+		const lines = event.preparation.region.lines;
+		if (lines.length === 0) return;
+		const kept = lines.filter((line, index) => index === 0 || /^\[(User|Assistant|Assistant thinking|Assistant tool calls|Tool result)\]: /.test(line));
+		if (kept.length === lines.length) return;
+		return { compactedText: kept.join("\n") };
 	});
 
-	pi.on("session_compact", async (event, ctx) => {
-		if (!ctx.hasUI || !event.fromExtension) return;
-		ctx.ui.notify(
-			`Custom compaction policy deleted ${event.result.stats.objectsDeleted} object(s)`,
-			"info",
-		);
+	pi.on("session_compact", async (event) => {
+		console.log(`Compacted ${event.result.stats.linesBefore} to ${event.result.stats.linesKept} lines (${event.result.rung})`);
 	});
 }

package/examples/extensions/handoff.ts

@@ -58,9 +58,8 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			// Gather the same active context Atomic would send to the model. This applies
-			// context_compaction deletion filters and treats retired summary-compaction
-			// records as archival metadata, not replacement conversation context.
+			// Gather the active provider context. Durable verbatim compaction boundaries
+			// are already reconstructed as a boundary message plus their kept tail.
 			const messages = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages;
 
 			if (messages.length === 0) {

package/npm-shrinkwrap.json

@@ -1,15 +1,15 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.8",
+	"version": "0.9.9-alpha.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.8",
+			"version": "0.9.9-alpha.1",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.8",
+				"@bastani/atomic-natives": "0.9.9-alpha.1",
 				"@bufbuild/protobuf": "^2.12.1",
 				"@earendil-works/pi-agent-core": "^0.80.6",
 				"@earendil-works/pi-ai": "^0.80.6",
@@ -515,16 +515,16 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.8",
-				"@bastani/atomic-natives-darwin-x64": "0.9.8",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.8",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.8",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.8",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.8"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.9-alpha.1",
+				"@bastani/atomic-natives-darwin-x64": "0.9.9-alpha.1",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.9-alpha.1",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.9-alpha.1",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.9-alpha.1",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.9-alpha.1"
 			},
 			"engines": {
 				"bun": ">=1.3.14",
@@ -532,8 +532,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -544,8 +544,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -556,8 +556,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -571,8 +571,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -586,8 +586,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -598,8 +598,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.8",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.8.tgz",
+			"version": "0.9.9-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.9-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.8",
+  "version": "0.9.9-alpha.1",
   "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.8",
+    "@bastani/atomic-natives": "0.9.9-alpha.1",
     "@bufbuild/protobuf": "^2.12.1",
     "@earendil-works/pi-agent-core": "^0.80.6",
     "@earendil-works/pi-ai": "^0.80.6",

package/dist/core/compaction/context-assistant-turns.d.ts

@@ -1,42 +0,0 @@
-import type { CompactableContentBlock, CompactableTranscript, CompactableTranscriptEntry } from "./context-compaction-types.js";
-export declare function assistantEntryHasThinkingContentBlock(entry: CompactableTranscriptEntry): boolean;
-export interface AssistantTurnEntry {
-    entryId: string;
-    role: string;
-    hasSignedThinking: boolean;
-    startsNewTurn: boolean;
-}
-export interface AssistantToolUseTurn {
-    entryIds: string[];
-    assistantEntryIds: string[];
-    signedThinkingEntryIds: string[];
-    active: boolean;
-}
-export type CompactableTranscriptDeletionTarget = {
-    readonly kind: "entry";
-    readonly entryId: string;
-} | {
-    readonly kind: "content_block";
-    readonly entryId: string;
-    readonly blockIndex: number;
-};
-export interface CompactableAssistantTurnAnalysis {
-    deletedEntryIds: ReadonlySet<string>;
-    deletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>;
-    turns: AssistantToolUseTurn[];
-}
-export declare function compactableContentBlockIsLlmVisible(entry: CompactableTranscriptEntry, block: CompactableContentBlock): boolean;
-export declare function transcriptEntryStartsNewTurn(entry: CompactableTranscriptEntry, deletedContentBlocks?: ReadonlySet<number>): boolean;
-export declare function isTranscriptEntryEffectivelyDeleted(entry: CompactableTranscriptEntry, deletedEntryIds: ReadonlySet<string>, deletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>): boolean;
-/** Shared adaptation from compactable transcript entries to logical assistant-turn inputs. */
-export declare function compactableTranscriptToAssistantTurnEntries(transcript: CompactableTranscript, deletedEntryIds: ReadonlySet<string>, deletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>): AssistantTurnEntry[];
-/** Analyze assistant turns after projecting a compactable transcript through deletion targets. */
-export declare function analyzeCompactableAssistantTurns(transcript: CompactableTranscript, targets: readonly CompactableTranscriptDeletionTarget[]): CompactableAssistantTurnAnalysis;
-/**
- * Analyze chronological LLM-visible entries as logical assistant tool-use turns.
- * Callers adapt each context-visible user-like message into `startsNewTurn`;
- * tool results remain in the current turn. A trailing input-only turn is omitted,
- * intentionally leaving the preceding assistant turn historical rather than active.
- */
-export declare function analyzeAssistantToolUseTurns(entries: readonly AssistantTurnEntry[]): AssistantToolUseTurn[];
-//# sourceMappingURL=context-assistant-turns.d.ts.map

package/dist/core/compaction/context-assistant-turns.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-assistant-turns.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/context-assistant-turns.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,MAAM,+BAA+B,CAAC;AAGvC,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAMhG;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,mCAAmC,GAC5C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F,MAAM,WAAW,gCAAgC;IAChD,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC9B;AAED,wBAAgB,mCAAmC,CAClD,KAAK,EAAE,0BAA0B,EACjC,KAAK,EAAE,uBAAuB,GAC5B,OAAO,CAIT;AAED,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,0BAA0B,EACjC,oBAAoB,GAAE,WAAW,CAAC,MAAM,CAAqB,GAC3D,OAAO,CAWT;AAED,wBAAgB,mCAAmC,CAClD,KAAK,EAAE,0BAA0B,EACjC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,EACpC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAC5D,OAAO,CAQT;AAED,8FAA8F;AAC9F,wBAAgB,2CAA2C,CAC1D,UAAU,EAAE,qBAAqB,EACjC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,EACpC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAC5D,kBAAkB,EAAE,CAStB;AAED,kGAAkG;AAClG,wBAAgB,gCAAgC,CAC/C,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,SAAS,mCAAmC,EAAE,GACrD,gCAAgC,CAmBlC;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,oBAAoB,EAAE,CAmB3G","sourcesContent":["import { messageStartsLlmUserTurn, userLikeContentBlockIsLlmVisible } from \"../messages.js\";\nimport type {\n\tCompactableContentBlock,\n\tCompactableTranscript,\n\tCompactableTranscriptEntry,\n} from \"./context-compaction-types.js\";\nimport { isAssistantThinkingBlockType, messageHasAssistantThinkingContentBlock } from \"../thinking-blocks.js\";\n\nexport function assistantEntryHasThinkingContentBlock(entry: CompactableTranscriptEntry): boolean {\n\treturn (\n\t\tentry.role === \"assistant\" &&\n\t\t(entry.contentBlocks.some((block) => isAssistantThinkingBlockType(block.type)) ||\n\t\t\tmessageHasAssistantThinkingContentBlock(entry.message))\n\t);\n}\n\nexport interface AssistantTurnEntry {\n\tentryId: string;\n\trole: string;\n\thasSignedThinking: boolean;\n\tstartsNewTurn: boolean;\n}\n\nexport interface AssistantToolUseTurn {\n\tentryIds: string[];\n\tassistantEntryIds: string[];\n\tsignedThinkingEntryIds: string[];\n\tactive: boolean;\n}\n\nexport type CompactableTranscriptDeletionTarget =\n\t| { readonly kind: \"entry\"; readonly entryId: string }\n\t| { readonly kind: \"content_block\"; readonly entryId: string; readonly blockIndex: number };\n\nexport interface CompactableAssistantTurnAnalysis {\n\tdeletedEntryIds: ReadonlySet<string>;\n\tdeletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>;\n\tturns: AssistantToolUseTurn[];\n}\n\nexport function compactableContentBlockIsLlmVisible(\n\tentry: CompactableTranscriptEntry,\n\tblock: CompactableContentBlock,\n): boolean {\n\tif (typeof block.llmVisible === \"boolean\") return block.llmVisible;\n\tconst rawContent = (entry.message as { content?: unknown }).content;\n\treturn Array.isArray(rawContent) && userLikeContentBlockIsLlmVisible(rawContent[block.blockIndex]);\n}\n\nexport function transcriptEntryStartsNewTurn(\n\tentry: CompactableTranscriptEntry,\n\tdeletedContentBlocks: ReadonlySet<number> = new Set<number>(),\n): boolean {\n\tif (entry.role === \"user\" || entry.role === \"custom\") {\n\t\tconst content = (entry.message as { content?: unknown }).content;\n\t\tif (typeof content === \"string\" || entry.contentBlocks.length === 0) {\n\t\t\treturn messageStartsLlmUserTurn(entry.message, deletedContentBlocks);\n\t\t}\n\t\treturn entry.contentBlocks.some(\n\t\t\t(block) => !deletedContentBlocks.has(block.blockIndex) && compactableContentBlockIsLlmVisible(entry, block),\n\t\t);\n\t}\n\treturn messageStartsLlmUserTurn(entry.message, deletedContentBlocks);\n}\n\nexport function isTranscriptEntryEffectivelyDeleted(\n\tentry: CompactableTranscriptEntry,\n\tdeletedEntryIds: ReadonlySet<string>,\n\tdeletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>,\n): boolean {\n\tif (deletedEntryIds.has(entry.entryId)) return true;\n\tconst deletedBlocks = deletedContentBlocks.get(entry.entryId);\n\treturn (\n\t\tentry.contentBlocks.length > 0 &&\n\t\tdeletedBlocks !== undefined &&\n\t\tentry.contentBlocks.every((block) => deletedBlocks.has(block.blockIndex))\n\t);\n}\n\n/** Shared adaptation from compactable transcript entries to logical assistant-turn inputs. */\nexport function compactableTranscriptToAssistantTurnEntries(\n\ttranscript: CompactableTranscript,\n\tdeletedEntryIds: ReadonlySet<string>,\n\tdeletedContentBlocks: ReadonlyMap<string, ReadonlySet<number>>,\n): AssistantTurnEntry[] {\n\treturn transcript.entries.map((entry) => ({\n\t\tentryId: entry.entryId,\n\t\trole: entry.role,\n\t\thasSignedThinking: assistantEntryHasThinkingContentBlock(entry),\n\t\tstartsNewTurn:\n\t\t\t!isTranscriptEntryEffectivelyDeleted(entry, deletedEntryIds, deletedContentBlocks) &&\n\t\t\ttranscriptEntryStartsNewTurn(entry, deletedContentBlocks.get(entry.entryId)),\n\t}));\n}\n\n/** Analyze assistant turns after projecting a compactable transcript through deletion targets. */\nexport function analyzeCompactableAssistantTurns(\n\ttranscript: CompactableTranscript,\n\ttargets: readonly CompactableTranscriptDeletionTarget[],\n): CompactableAssistantTurnAnalysis {\n\tconst deletedEntryIds = new Set<string>();\n\tconst deletedContentBlocks = new Map<string, Set<number>>();\n\tfor (const target of targets) {\n\t\tif (target.kind === \"entry\") {\n\t\t\tdeletedEntryIds.add(target.entryId);\n\t\t\tcontinue;\n\t\t}\n\t\tconst blockIndexes = deletedContentBlocks.get(target.entryId) ?? new Set<number>();\n\t\tblockIndexes.add(target.blockIndex);\n\t\tdeletedContentBlocks.set(target.entryId, blockIndexes);\n\t}\n\treturn {\n\t\tdeletedEntryIds,\n\t\tdeletedContentBlocks,\n\t\tturns: analyzeAssistantToolUseTurns(\n\t\t\tcompactableTranscriptToAssistantTurnEntries(transcript, deletedEntryIds, deletedContentBlocks),\n\t\t),\n\t};\n}\n\n/**\n * Analyze chronological LLM-visible entries as logical assistant tool-use turns.\n * Callers adapt each context-visible user-like message into `startsNewTurn`;\n * tool results remain in the current turn. A trailing input-only turn is omitted,\n * intentionally leaving the preceding assistant turn historical rather than active.\n */\nexport function analyzeAssistantToolUseTurns(entries: readonly AssistantTurnEntry[]): AssistantToolUseTurn[] {\n\tconst groups: Array<Omit<AssistantToolUseTurn, \"active\">> = [];\n\tlet current: Omit<AssistantToolUseTurn, \"active\"> | undefined;\n\n\tfor (const entry of entries) {\n\t\tif (entry.startsNewTurn || current === undefined) {\n\t\t\tcurrent = { entryIds: [], assistantEntryIds: [], signedThinkingEntryIds: [] };\n\t\t\tgroups.push(current);\n\t\t}\n\t\tcurrent.entryIds.push(entry.entryId);\n\t\tif (entry.role !== \"assistant\") continue;\n\t\tcurrent.assistantEntryIds.push(entry.entryId);\n\t\tif (entry.hasSignedThinking) current.signedThinkingEntryIds.push(entry.entryId);\n\t}\n\n\tconst activeIndex = groups.length - 1;\n\treturn groups\n\t\t.map((turn, index) => ({ ...turn, active: index === activeIndex }))\n\t\t.filter((turn) => turn.assistantEntryIds.length > 0);\n}\n"]}

package/dist/core/compaction/context-assistant-turns.js

@@ -1,87 +0,0 @@
-import { messageStartsLlmUserTurn, userLikeContentBlockIsLlmVisible } from "../messages.js";
-import { isAssistantThinkingBlockType, messageHasAssistantThinkingContentBlock } from "../thinking-blocks.js";
-export function assistantEntryHasThinkingContentBlock(entry) {
-    return (entry.role === "assistant" &&
-        (entry.contentBlocks.some((block) => isAssistantThinkingBlockType(block.type)) ||
-            messageHasAssistantThinkingContentBlock(entry.message)));
-}
-export function compactableContentBlockIsLlmVisible(entry, block) {
-    if (typeof block.llmVisible === "boolean")
-        return block.llmVisible;
-    const rawContent = entry.message.content;
-    return Array.isArray(rawContent) && userLikeContentBlockIsLlmVisible(rawContent[block.blockIndex]);
-}
-export function transcriptEntryStartsNewTurn(entry, deletedContentBlocks = new Set()) {
-    if (entry.role === "user" || entry.role === "custom") {
-        const content = entry.message.content;
-        if (typeof content === "string" || entry.contentBlocks.length === 0) {
-            return messageStartsLlmUserTurn(entry.message, deletedContentBlocks);
-        }
-        return entry.contentBlocks.some((block) => !deletedContentBlocks.has(block.blockIndex) && compactableContentBlockIsLlmVisible(entry, block));
-    }
-    return messageStartsLlmUserTurn(entry.message, deletedContentBlocks);
-}
-export function isTranscriptEntryEffectivelyDeleted(entry, deletedEntryIds, deletedContentBlocks) {
-    if (deletedEntryIds.has(entry.entryId))
-        return true;
-    const deletedBlocks = deletedContentBlocks.get(entry.entryId);
-    return (entry.contentBlocks.length > 0 &&
-        deletedBlocks !== undefined &&
-        entry.contentBlocks.every((block) => deletedBlocks.has(block.blockIndex)));
-}
-/** Shared adaptation from compactable transcript entries to logical assistant-turn inputs. */
-export function compactableTranscriptToAssistantTurnEntries(transcript, deletedEntryIds, deletedContentBlocks) {
-    return transcript.entries.map((entry) => ({
-        entryId: entry.entryId,
-        role: entry.role,
-        hasSignedThinking: assistantEntryHasThinkingContentBlock(entry),
-        startsNewTurn: !isTranscriptEntryEffectivelyDeleted(entry, deletedEntryIds, deletedContentBlocks) &&
-            transcriptEntryStartsNewTurn(entry, deletedContentBlocks.get(entry.entryId)),
-    }));
-}
-/** Analyze assistant turns after projecting a compactable transcript through deletion targets. */
-export function analyzeCompactableAssistantTurns(transcript, targets) {
-    const deletedEntryIds = new Set();
-    const deletedContentBlocks = new Map();
-    for (const target of targets) {
-        if (target.kind === "entry") {
-            deletedEntryIds.add(target.entryId);
-            continue;
-        }
-        const blockIndexes = deletedContentBlocks.get(target.entryId) ?? new Set();
-        blockIndexes.add(target.blockIndex);
-        deletedContentBlocks.set(target.entryId, blockIndexes);
-    }
-    return {
-        deletedEntryIds,
-        deletedContentBlocks,
-        turns: analyzeAssistantToolUseTurns(compactableTranscriptToAssistantTurnEntries(transcript, deletedEntryIds, deletedContentBlocks)),
-    };
-}
-/**
- * Analyze chronological LLM-visible entries as logical assistant tool-use turns.
- * Callers adapt each context-visible user-like message into `startsNewTurn`;
- * tool results remain in the current turn. A trailing input-only turn is omitted,
- * intentionally leaving the preceding assistant turn historical rather than active.
- */
-export function analyzeAssistantToolUseTurns(entries) {
-    const groups = [];
-    let current;
-    for (const entry of entries) {
-        if (entry.startsNewTurn || current === undefined) {
-            current = { entryIds: [], assistantEntryIds: [], signedThinkingEntryIds: [] };
-            groups.push(current);
-        }
-        current.entryIds.push(entry.entryId);
-        if (entry.role !== "assistant")
-            continue;
-        current.assistantEntryIds.push(entry.entryId);
-        if (entry.hasSignedThinking)
-            current.signedThinkingEntryIds.push(entry.entryId);
-    }
-    const activeIndex = groups.length - 1;
-    return groups
-        .map((turn, index) => ({ ...turn, active: index === activeIndex }))
-        .filter((turn) => turn.assistantEntryIds.length > 0);
-}
-//# sourceMappingURL=context-assistant-turns.js.map