@bastani/atomic 0.9.8 → 0.9.9-alpha.1

package/docs/extensions.md

@@ -338,9 +338,9 @@ user sends another prompt ◄─────────────────
   └─► resources_discover { reason: "startup" }
 
 /compact or auto-compaction
-  ├─► compaction_start / compaction_end (deletion-only context compaction status)
-  ├─► session_before_compact (can cancel or provide a deletion request)
-  └─► session_compact (after the context_compaction entry is persisted)
+  ├─► compaction_start / compaction_end (verbatim line-compaction status)
+  ├─► session_before_compact (can cancel or provide compactedText)
+  └─► session_compact (after the compaction boundary is persisted)
 
 /tree navigation
   ├─► session_before_tree (can cancel or customize)
@@ -460,40 +460,36 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
 
 #### session_before_compact / session_compact
 
-Fired by `/compact` and auto-compaction. Compaction is deletion-only: extensions can cancel the run or return exact entry/content-block deletion targets for Atomic to validate locally. Extensions cannot return generated summaries.
+Fired by `/compact` and auto-compaction. Atomic prepares a protected recent tail and a numbered compactable region. Extensions may cancel or provide a complete, non-empty `compactedText` replacement for that region; they cannot move `firstKeptEntryId`. The override is persisted verbatim and works without provider credentials.
 
 ```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, reason, signal } = event;
-  const { transcript } = preparation;
+pi.on("session_before_compact", async (event) => {
+  const { preparation, branchEntries, parameters, reason, signal } = event;
 
-  // transcript.entries - compactable entries on the active branch
-  // transcript.protectedEntryIds - entries validation will reject if directly deleted
-  // transcript.tokensBefore - token estimate before compaction
-  // branchEntries - raw session entries on the current branch
+  // preparation.region.lines - unnumbered compactable transcript lines
+  // preparation.firstKeptEntryId - fixed start of the verbatim tail
+  // preparation.tokensBefore - whole-context token estimate
+  // parameters - compression_ratio, preserve_recent, query
+  // branchEntries - raw entries on the active branch
   // reason - "manual" | "threshold" | "overflow"
+  // preparation is a deep-frozen clone
 
   if (signal.aborted) return { cancel: true };
 
   // Cancel compaction:
   return { cancel: true };
 
-  // Or provide a deletion request. Atomic validates IDs, protected targets,
-  // tool-call/tool-result pairing, and non-empty remaining context before saving.
+  // Or replace only the prepared region. Whitespace-only text is rejected.
   return {
-    deletionRequest: {
-      deletions: [
-        { kind: "entry", entryId: "abc123", rationale: "Old successful command output" },
-        { kind: "content_block", entryId: "def456", blockIndex: 2, rationale: "Verbose obsolete log" },
-      ],
-    },
+    compactedText: preparation.region.lines.slice(0, 40).join("\n"),
   };
 });
 
-pi.on("session_compact", async (event, ctx) => {
-  // event.result - ContextCompactionResult with deletedTargets/protectedEntryIds/stats
-  // event.contextCompactionEntry - the saved context_compaction entry
-  // event.fromExtension - true if session_before_compact provided deletionRequest
+pi.on("session_compact", async (event) => {
+  // event.result - VerbatimCompactionResult (text, boundary, stats, parameters, rung)
+  // event.compactionEntry - saved CompactionEntry with strategy "verbatim-lines"
+  // event.fromExtension - true when session_before_compact provided compactedText
+  // Observe-only: errors are isolated after persistence.
 });
 ```
 
@@ -1049,15 +1045,15 @@ if (usage && usage.tokens > 100_000) {
 
 ### ctx.compact()
 
-Trigger Atomic's default Verbatim Compaction without awaiting completion. This is deletion-only Context Compaction: the internal planner searches/reads transcript slices, records exact entry/content-block deletion targets with transcript-bound tools, and Atomic applies only locally validated logical deletions. Retained transcript content stays unchanged. The approach is informed by Morph's Context Compaction write-up: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Use `compression_ratio`, `preserve_recent`, and `query` to tune the run, and `onComplete`/`onError` for follow-up actions.
+Trigger Atomic's verbatim line compactor without awaiting completion. The planner emits numbered deleted-line ranges only; Atomic validates them and reconstructs retained text mechanically. Use `compression_ratio` (fraction of compactable lines to keep), client-side `preserve_recent`, and `query` to tune the run, and `onComplete`/`onError` for follow-up actions.
 
 ```typescript
 ctx.compact({
-  compression_ratio: 0.5, // fraction to keep: 0.3 aggressive, 0.7 light
-  preserve_recent: 2,    // keep the last N context-eligible messages
+  compression_ratio: 0.5, // fraction of compactable lines to keep
+  preserve_recent: 2,    // keep recent messages and widen to a user-turn start
   query: "keep active migration details",
   onComplete: (result) => {
-    ctx.ui.notify(`Compaction deleted ${result.stats.objectsDeleted} objects`, "info");
+    ctx.ui.notify(`Compaction kept ${result.stats.linesKept}/${result.stats.linesBefore} lines`, "info");
   },
   onError: (error) => {
     ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
@@ -1065,7 +1061,7 @@ ctx.compact({
 });
 ```
 
-Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected. The `query` parameter guides relevance-based pruning inside that fixed prompt; it is not replacement summary text.
+The planner cannot author context text: only validated line ranges enter the mechanical reconstruction path. The `query` parameter guides relevance selection inside the fixed prompt; it is not replacement prose. Extensions that need an offline replacement can return `compactedText` from `session_before_compact`.
 
 ### ctx.getSystemPrompt()
 
@@ -2657,7 +2653,7 @@ All examples in [examples/extensions/](https://github.com/bastani-inc/atomic/tre
 | `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
 | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
 | **Compaction & Sessions** |||
-| `custom-compaction.ts` | Custom deletion-request compaction policy | `on("session_before_compact")` |
+| `custom-compaction.ts` | Offline compacted-text override | `on("session_before_compact")` |
 | `trigger-compact.ts` | Trigger compaction manually | `compact()` |
 | `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
 | `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |

package/docs/json.md

@@ -19,12 +19,12 @@ type AgentSessionEvent =
   | { type: "model_changed"; model: Model<Api>; previousModel: Model<Api> | undefined; source: "set" | "cycle" | "restore" }
   | { type: "thinking_level_changed"; level: ThinkingLevel }
   | { type: "context_window_changed"; contextWindow: number }
-  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: ContextCompactionResult | undefined; aborted: boolean; willRetry: boolean; unresolvedOverflow?: boolean; errorMessage?: string }
+  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: VerbatimCompactionResult | undefined; aborted: boolean; willRetry: boolean; unresolvedOverflow?: boolean; errorMessage?: string }
   | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
   | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
 ```
 
-`queue_update` emits the full pending steering and follow-up queues whenever they change. `session_info_changed`, `model_changed`, `thinking_level_changed`, and `context_window_changed` report interactive session metadata changes. `context_window_changed` carries the active token budget after `AgentSession.setContextWindow()` or branch navigation replay applies a branch-scoped `context_window_change`; branch replay does not add another session journal entry or write settings. `compaction_start` and `compaction_end` cover both manual and automatic Verbatim Compaction, Atomic's transcript-bound, deletion-only Context Compaction approach inspired by [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
+`queue_update` emits the full pending steering and follow-up queues whenever they change. `session_info_changed`, `model_changed`, `thinking_level_changed`, and `context_window_changed` report interactive session metadata changes. `context_window_changed` carries the active token budget after `AgentSession.setContextWindow()` or branch navigation replay applies a branch-scoped `context_window_change`; branch replay does not add another session journal entry or write settings. `compaction_start` and `compaction_end` cover manual and automatic verbatim line compaction: the model emits deleted ranges and Atomic mechanically reconstructs retained text.
 
 For automatic compaction, `compaction_end.willRetry === true` means the agent is retrying the interrupted turn after compaction; `AgentSession.prompt()` waits for that continuation before resolving. This includes overflow recovery and live threshold compaction for retry-worthy interrupted work such as output-token truncation or OpenAI Responses output-budget underflow errors. Generic provider `invalid_request_body` failures still compact with `willRetry: false` when threshold compaction is warranted. If the same-model compact-and-retry overflow path is exhausted, `compaction_end` includes `unresolvedOverflow: true` plus an `errorMessage` so orchestration layers can fallback to another model instead of treating the prompt as successful.
 

package/docs/rpc.md

@@ -414,7 +414,7 @@ Response:
 
 #### compact
 
-Run Atomic's default Verbatim Compaction to reduce token usage. This command has no prompt/config fields; send no custom instructions. The selected model runs Atomic's fixed internal planner with transcript-bound tools (`context_search_transcript`, `context_read_entry`, `context_delete`, and `context_grep_delete`); Atomic validates the cumulative deletion targets locally, appends a `context_compaction` entry, and rebuilds active context with surviving entries/content blocks reused verbatim. This deletion-only Context Compaction approach is informed by Morph's article: [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
+Run Atomic's verbatim line compactor. The selected session model receives a numbered transcript and returns JSON deleted ranges; Atomic validates them and mechanically reconstructs retained lines with `(filtered N lines)` markers. The command appends a durable `compaction` entry with `details.strategy: "verbatim-lines"`. Recent logical turns remain ordinary messages.
 
 ```json
 {"type": "compact"}
@@ -427,16 +427,24 @@ Response:
   "command": "compact",
   "success": true,
   "data": {
-    "promptVersion": 1,
-    "deletedTargets": [{ "kind": "entry", "entryId": "abc123" }],
-    "protectedEntryIds": ["user-task-entry"],
+    "compactedText": "[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.",
+    "firstKeptEntryId": "m7",
+    "tokensBefore": 150000,
+    "promptVersion": 2,
+    "parameters": {
+      "compression_ratio": 0.5,
+      "preserve_recent": 2,
+      "query": "fix the test"
+    },
+    "rung": "standard",
     "stats": {
-      "objectsBefore": 20,
-      "objectsAfter": 19,
-      "objectsDeleted": 1,
+      "linesBefore": 812,
+      "linesDeleted": 417,
+      "linesKept": 395,
+      "rangeCount": 63,
       "tokensBefore": 150000,
-      "tokensAfter": 120000,
-      "percentReduction": 20
+      "tokensAfter": 72000,
+      "percentReduction": 52
     },
     "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
   }
@@ -880,10 +888,8 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `tool_execution_end` | Tool completes |
 | `queue_update` | Pending steering/follow-up queue changed |
 | `context_window_changed` | Active context-window token budget changed |
-| `compaction_start` | Default Verbatim Compaction begins |
-| `compaction_end` | Default Verbatim Compaction completes |
-| `context_compaction_start` | Compatibility `context_compact` RPC begins |
-| `context_compaction_end` | Compatibility `context_compact` RPC completes |
+| `compaction_start` | Verbatim line compaction begins |
+| `compaction_end` | Verbatim line compaction completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
 | `extension_error` | Extension threw an error |
@@ -1059,16 +1065,20 @@ The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
   "type": "compaction_end",
   "reason": "threshold",
   "result": {
-    "promptVersion": 1,
-    "deletedTargets": [{ "kind": "entry", "entryId": "abc123" }],
-    "protectedEntryIds": ["user-task-entry"],
+    "compactedText": "[User]: fix the test\n(filtered 42 lines)",
+    "firstKeptEntryId": "m7",
+    "tokensBefore": 150000,
+    "promptVersion": 2,
+    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the test"},
+    "rung": "standard",
     "stats": {
-      "objectsBefore": 20,
-      "objectsAfter": 19,
-      "objectsDeleted": 1,
+      "linesBefore": 812,
+      "linesDeleted": 417,
+      "linesKept": 395,
+      "rangeCount": 63,
       "tokensBefore": 150000,
-      "tokensAfter": 120000,
-      "percentReduction": 20
+      "tokensAfter": 72000,
+      "percentReduction": 52
     }
   },
   "aborted": false,
@@ -1084,9 +1094,7 @@ If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` i
 
 If overflow recovery exhausts the same-model compact-and-retry attempt, `compaction_end` includes `"unresolvedOverflow": true` and an `errorMessage`. Workflow orchestration treats that signal as a context-length failure that can advance configured model fallback tiers.
 
-### context_compaction_start / context_compaction_end
-
-The compatibility RPC command `context_compact` emits these events. It uses the same deletion-only Verbatim Compaction path as `compact`, but reports the historical context-compaction event names. The result contains `deletedTargets`, `protectedEntryIds`, `stats`, `promptVersion`, and optional `backupPath`.
+There is no `context_compact` command; Atomic reports it as an unknown command. Use `compact`. Only `compaction_start` and `compaction_end` events are emitted.
 
 ### auto_retry_start / auto_retry_end
 

package/docs/sdk.md

@@ -126,8 +126,8 @@ interface AgentSession {
   // In-place tree navigation within the current session file
   navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }>;
 
-  // Verbatim Compaction (deletion-only Context Compaction)
-  compact(): Promise<ContextCompactionResult>;
+  // Verbatim line compaction
+  compact(options?: Partial<VerbatimCompactionParameters>): Promise<VerbatimCompactionResult>;
   abortCompaction(): void;
 
   // Abort current operation
@@ -138,7 +138,7 @@ interface AgentSession {
 }
 ```
 
-`compact()` accepts no custom summary instructions. It runs the same transcript-bound Verbatim Compaction planner as `/compact`: inspect transcript slices, record exact deletion targets, validate them locally, append a `context_compaction` entry, and rebuild active context with retained content unchanged.
+`compact()` serializes older context to numbered lines, asks the session model for JSON deleted ranges, validates them, and mechanically reconstructs a durable verbatim transcript string. It appends a `compaction` entry with `details.strategy: "verbatim-lines"`; the recent tail remains ordinary messages. The model never authors replacement context text.
 
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 

package/docs/session-format.md

@@ -146,7 +146,7 @@ interface BranchSummaryMessage {
 }
 ```
 
-Historical sessions may contain retired `compactionSummary` role messages from the old summary-compaction implementation. Atomic no longer produces them, they are not part of the active `AgentMessage` union, and they are not injected when active LLM context is rebuilt.
+`compactionSummary` is a historical message role that appears only in older session files; Atomic never produces it and treats historical occurrences as inert. Active verbatim boundaries are synthesized at rebuild time as visible `custom` messages with `customType: "compaction"`; `convertToLlm()` maps them to provider-facing user messages.
 
 ### AgentMessage Union
 
@@ -158,7 +158,7 @@ type AgentMessage =
   | BashExecutionMessage
   | CustomMessage
   | BranchSummaryMessage;
-// CompactionSummaryMessage was removed; it is no longer part of the active union.
+// compactionSummary appears only in older session files and is not part of the active union.
 ```
 
 ## Entry Base
@@ -190,12 +190,14 @@ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ pare
 {"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
 ```
 
-Sessions created by automated machinery (notably workflow stage sessions) carry an `internal` flag and optional `workflow` linkage so they can be excluded from the standard `/resume` history while remaining resumable through their owning workflow:
+Workflow-owned sessions carry both `internal: true` and complete `workflow` linkage. Atomic writes this classification before the transcript becomes visible wherever possible, including workflow stage forks and fresh/forked subagents. A session is excluded from normal resume history only when `internal` is the exact boolean `true` and `workflow.runId`, `workflow.stageId`, and `workflow.stageName` are all non-empty strings:
 
 ```json
 {"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","internal":true,"workflow":{"runId":"run-1","stageId":"stage-build","stageName":"build"}}
 ```
 
+Malformed, incomplete, workflow-only, or truthy non-boolean legacy markers remain visible in normal history. Atomic does not infer workflow ownership from `parentSession`, so ordinary user-created forks are unaffected. Valid workflow classification is inherited when an internal workflow transcript is branched or forked.
+
 ### SessionMessageEntry
 
 A message in the conversation. The `message` field contains an `AgentMessage`.
@@ -234,25 +236,27 @@ Emitted when the user selects a supported context-window size for the active mod
 
 ### CompactionEntry
 
-Retired summary-compaction entry. Atomic no longer produces this entry type, does not treat it as an active compaction boundary, and does not inject its generated summary into active LLM context. Historical JSONL files may still contain these lines for audit/export compatibility.
+Created by `/compact`, RPC `compact`, and automatic compaction. The `summary` field contains the mechanically reconstructed verbatim transcript string, not generated summary prose. `firstKeptEntryId` points to the first ordinary message retained after the boundary.
+
+An entry is active only when `details.strategy` is exactly `"verbatim-lines"`:
 
 ```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
+{"type":"compaction","id":"c1","parentId":"m9","timestamp":"2026-07-13T10:00:00.000Z","summary":"[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.","firstKeptEntryId":"m7","tokensBefore":51234,"details":{"strategy":"verbatim-lines","promptVersion":2,"rung":"standard","parameters":{"compression_ratio":0.5,"preserve_recent":2,"query":"fix the test"},"stats":{"linesBefore":812,"linesDeleted":417,"linesKept":395,"rangeCount":63,"tokensBefore":51234,"tokensAfter":24980,"percentReduction":51.2}}}
 ```
 
-Optional historical fields:
-- `details`: Legacy implementation-specific data
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
+On rebuild, Atomic emits the durable `summary` as a synthesized visible custom message, then emits original entries beginning at `firstKeptEntryId`. This exact string survives resume without rerunning a planner. `details.rung` is `"standard"`, `"critical"`, `"deterministic"`, or `"extension"`; `details.backupPath` is optional.
+
+Historical `compaction` records without `details.strategy: "verbatim-lines"` are retired summary-compaction records. They remain parseable and visible to audit/export tools but are inert in active LLM context.
 
-### ContextCompactionEntry
+### ContextCompactionEntry (Retired)
 
-Created by `/compact`, RPC compaction commands, and auto-compaction. Stores Atomic's default **Verbatim Compaction** data: validated logical deletion targets, not replacement text. The internal planner can search/read transcript slices and record exact entry/content-block targets with transcript-bound tools; Atomic validates those targets locally before saving. During `buildSessionContext()`, matching entries/content blocks are filtered from active LLM context while retained content remains verbatim. This deletion-only Context Compaction approach is informed by Morph's write-up at [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
+Older Atomic versions stored logical entry/content-block deletions in `type:"context_compaction"` records:
 
 ```json
-{"type":"context_compaction","id":"ctx12345","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:12:00.000Z","promptVersion":1,"deletedTargets":[{"kind":"entry","entryId":"b2c3d4e5"}],"protectedEntryIds":["a1b2c3d4"],"stats":{"objectsBefore":20,"objectsAfter":19,"objectsDeleted":1,"tokensBefore":50000,"tokensAfter":43000,"percentReduction":14},"backupPath":"/path/session.jsonl.2024-12-03T14-12-00-000Z.compact.bak"}
+{"type":"context_compaction","id":"ctx12345","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:12:00.000Z","promptVersion":1,"deletedTargets":[{"kind":"entry","entryId":"b2c3d4e5"}],"protectedEntryIds":["a1b2c3d4"],"stats":{"objectsBefore":20,"objectsAfter":19,"objectsDeleted":1,"tokensBefore":50000,"tokensAfter":43000,"percentReduction":14}}
 ```
 
-`deletedTargets` entries are either whole entries (`{ kind: "entry", entryId }`) or content blocks (`{ kind: "content_block", entryId, blockIndex }`). Content-block targets are not applied to retained assistant messages that contain `thinking` or `redacted_thinking`; those assistant messages are replay-sensitive for Anthropic-compatible extended-thinking providers and are restored as full content arrays during active context rebuild. The JSONL file remains append-only; this is logical deletion for active context rebuild.
+These records are archival and never produced or applied by current Atomic. When an old session resumes, previously hidden content may re-enter context until verbatim-line compaction creates an active boundary.
 
 ### BranchSummaryEntry
 
@@ -325,14 +329,12 @@ Entries form a tree:
 
 ## Context Building
 
-`buildSessionContext()` walks from the current leaf to the root, producing the message list for the LLM:
-
-1. Collects all entries on the active branch path
-2. Extracts current model, thinking level, and context-window settings
-3. Applies every `ContextCompactionEntry` logical deletion on that path, filtering targeted entries/content blocks from active context while leaving retained content unchanged
-4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
-5. Ignores retired `CompactionEntry` lines for active LLM context; they remain archival JSONL data only
+`buildSessionContext()` walks the active branch from root to leaf and replays model, thinking-level, and context-window changes. It selects the latest `compaction` entry whose `details.strategy` is `"verbatim-lines"`.
 
+- With no active boundary, normal message, custom-message, and branch-summary entries are emitted verbatim.
+- With a boundary, Atomic emits its durable string as a custom-role `customType:"compaction"` message, then original messages from `firstKeptEntryId` onward, including messages appended after the boundary.
+- If a corrupt/foreign boundary's `firstKeptEntryId` is absent, Atomic emits the boundary followed by post-boundary messages rather than resurrecting all older content.
+- Legacy `context_compaction` entries and non-verbatim `compaction` entries are skipped as inert archival records.
 ## Parsing Example
 
 ```typescript
@@ -351,10 +353,14 @@ for (const line of lines) {
       console.log(`[${entry.id}] ${entry.message.role}: ${JSON.stringify(entry.message.content)}`);
       break;
     case "compaction":
-      console.log(`[${entry.id}] Retired summary-compaction record: ${entry.tokensBefore} tokens summarized historically`);
+      if (entry.details?.strategy === "verbatim-lines") {
+        console.log(`[${entry.id}] Verbatim compaction: ${entry.details.stats.linesKept}/${entry.details.stats.linesBefore} lines kept`);
+      } else {
+        console.log(`[${entry.id}] Retired summary-compaction record`);
+      }
       break;
     case "context_compaction":
-      console.log(`[${entry.id}] Context compaction: ${entry.stats.objectsDeleted} objects deleted`);
+      console.log(`[${entry.id}] Retired logical-deletion compaction record`);
       break;
     case "branch_summary":
       console.log(`[${entry.id}] Branch from ${entry.fromId}`);
@@ -386,18 +392,31 @@ for (const line of lines) {
 Key methods for working with sessions programmatically.
 
 ### Static Creation Methods
-- `SessionManager.create(cwd, sessionDir?)` - New session
-- `SessionManager.open(path, sessionDir?)` - Open existing session file
-- `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
-- `SessionManager.inMemory(cwd?)` - No file persistence
-- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
+
+- `SessionManager.create(cwd, sessionDir?, options?)` - New session. Workflow-owned sessions require the pair `internal: true` and `workflow: { runId, stageId, stageName }`.
+- `SessionManager.open(path, sessionDir?)` - Open a specific session file directly, including an internal session.
+- `SessionManager.continueRecent(cwd, sessionDir?, options?)` - Continue the most recent regular session or create a new one. Pass `{ includeInternal: true }` only for workflow-specific recovery or diagnostics.
+- `SessionManager.inMemory(cwd?, options?)` - No file persistence
+- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?, options?)` - Fork a session from another project. Relevant `NewSessionOptions`, including valid workflow classification, are written in the initial header.
 
 ### Static Listing Methods
-- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
-- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
+
+- `SessionManager.list(cwd, sessionDir?, onProgress?, options?)` - List project sessions. Internal workflow sessions are excluded by default; pass `{ includeInternal: true }` to include them and expose their `SessionInfo.workflow` linkage.
+- `SessionManager.listAll(sessionDir?, onProgress?, options?)` - List sessions across projects, or from a custom session directory. The same `includeInternal` default and opt-in apply.
+
+Normal `/resume`, `atomic -r`, and `--continue` callers use the default filtering. Workflow-specific code can opt in without changing user-facing history:
+
+```typescript
+const stages = await SessionManager.list(cwd, sessionDir, undefined, { includeInternal: true });
+for (const stage of stages.filter((session) => session.internal)) {
+  console.log(stage.workflow?.runId, stage.workflow?.stageId, stage.path);
+}
+```
 
 ### Instance Methods - Session Management
-- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+
+- `newSession(options?)` - Start a new session. Options include `parentSession`, `internal`, and workflow run/stage linkage; classification requires a complete marker pair.
+- `markSessionInternal(workflow?)` - Apply valid workflow ownership to the current session, repairing malformed markers while preserving an existing valid marker.
 - `setSessionFile(path)` - Switch to a different session file
 - `createBranchedSession(leafId)` - Extract branch to new session file
 
@@ -406,7 +425,7 @@ Key methods for working with sessions programmatically.
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendContextWindowChange(contextWindow)` - Record context-window selection in tokens
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendContextCompaction(deletedTargets, protectedEntryIds, stats, backupPath?)` - Add logical deletion compaction
+- `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)

package/docs/sessions.md

@@ -34,7 +34,7 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 | `/tree` | Navigate the current session tree |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact` | Apply Verbatim Compaction with transcript-bound, validated logical deletions; see [Compaction](/compaction) |
+| `/compact` | Compact older transcript lines verbatim while preserving recent logical turns; see [Compaction](/compaction) |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
@@ -42,6 +42,8 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 
 `/resume` opens an interactive session picker for the current project. `atomic -r` opens the same picker at startup.
 
+When Atomic reconstructs a resumed session, the latest active verbatim `compaction` entry supplies a durable compacted transcript string followed by the original kept tail. Resume does not rerun a planner or re-derive omissions. Legacy logical-deletion `context_compaction` entries are inert archival records, so previously hidden content can re-enter context in sessions created by older versions.
+
 In the picker you can:
 
 - search by typing
@@ -146,12 +148,12 @@ When prompted, choose one of:
 2. summarize with the default prompt
 3. summarize with custom focus instructions
 
-Branch summaries are separate from `/compact`: branch navigation can generate summary prose (optionally with focus instructions), while Verbatim Compaction records validated deletion targets and does not accept summary instructions.
+Branch summaries are separate from `/compact`: branch navigation can generate summary prose (optionally with focus instructions), while Verbatim Compaction lets a model select numbered line ranges and reconstructs retained text mechanically.
 
 See [Compaction](/compaction) for Verbatim Compaction, branch summarization internals, and extension hooks.
 
 ## Session Format
 
-Session files are JSONL and contain message entries, model changes, thinking-level changes, context-window changes, labels, context compactions, branch summaries, extension entries, and retired legacy `type:"compaction"` records from older sessions.
+Session files are JSONL and contain message entries, model changes, thinking-level changes, context-window changes, labels, active verbatim `compaction` boundaries, branch summaries, and extension entries. Retired `context_compaction` and non-verbatim `compaction` records remain parseable but inert.
 
 For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](/session-format).

package/docs/settings.md

@@ -134,18 +134,26 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `compaction.enabled` | boolean | `true` | Enable automatic Verbatim Compaction |
-| `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
+| `compaction.enabled` | boolean | `true` | Enable automatic verbatim line compaction |
+| `compaction.reserveTokens` | number | `16384` | Tokens reserved for the next model response; automatic threshold compaction begins before this reserve is consumed |
+| `compaction.compression_ratio` | number | `0.5` | Fraction of compactable transcript **lines to keep** (`0 < value < 1`) |
+| `compaction.preserve_recent` | number | `2` | Recent context-visible messages kept outside the compactable region; Atomic widens the cut to a user-turn start and always retains the final logical turn |
+| `compaction.query` | string | last user message | Optional relevance focus for selecting older lines to retain |
 
 ```json
 {
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384
+    "reserveTokens": 16384,
+    "compression_ratio": 0.5,
+    "preserve_recent": 2,
+    "query": "optional focus"
   }
 }
 ```
 
+The model emits numbered line ranges only; Atomic reconstructs retained text mechanically. `preserve_recent` is enforced client-side and is not a provider parameter.
+
 ### Branch Summary
 
 | Setting | Type | Default | Description |
@@ -350,7 +358,9 @@ See [Atomic packages](/packages) for package management details.
   "theme": "dark",
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384
+    "reserveTokens": 16384,
+    "compression_ratio": 0.5,
+    "preserve_recent": 2
   },
   "retry": {
     "enabled": true,

package/docs/usage.md

@@ -93,7 +93,7 @@ Useful session commands:
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
-- `/compact` uses Verbatim Compaction: a fixed no-argument deletion-only planner searches/reads transcript slices, records exact deletion targets, and applies only locally validated logical deletions. Retained transcript content stays verbatim. Atomic's approach is informed by Morph's Context Compaction article: [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
+- `/compact` uses verbatim line compaction: the model selects one-based numbered ranges to delete, Atomic validates them, and retained text is reconstructed mechanically with `(filtered N lines)` markers. Recent logical turns remain ordinary messages.
 
 See [Sessions](/sessions) and [Compaction](/compaction) for details.