@dreb/coding-agent 2.66.0 → 2.66.2

package/docs/compaction.md

@@ -36,7 +36,7 @@ By default, `reserveTokens` is 16384 tokens (configurable in `~/.dreb/agent/sett
 
 The threshold is checked after a run ends, before a new prompt, and inside a running agent loop before each LLM request. Mid-turn checks run only when context is settled on a user or tool-result message, after all tool calls from the preceding assistant message have matching results. If the threshold is crossed, dreb compacts and replaces the running loop's context before that loop makes its next request; it does not start a second agent run.
 
-If response-length retries are exhausted, dreb distinguishes a genuine output-budget failure from a full-context truncation using recorded usage. Usage at or beyond `contextWindow` enters overflow compact-and-retry recovery; usage below it remains a loud output-budget error.
+When a response reaches its configured output limit, length retries discard the partial response and retry at that same configured limit; they never increase `maxTokens`. After those retries are exhausted, dreb distinguishes a genuine output-budget failure from possible context pressure. It enters one reactive compact-and-retry recovery only when the provider reports context exhaustion, recorded usage reaches `contextWindow`, or the measured request input plus configured output maximum could not fit in the window. Otherwise the turn fails loudly without discarding conversation history. This reactive recovery does not change the proactive threshold above: a large theoretical output maximum alone never triggers early compaction.
 
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
 

package/docs/dashboard.md

@@ -132,8 +132,8 @@ networking window above.
 
 | Screen | What it does |
 |---|---|
-| **Fleet** | Home. Live-first: one grid of every live session at the top — status chip (● running / ◆ needs-attention / ○ idle / ✕ error), project path, activity line, live subagent lines, tasks progress, ctx%, model, terminal provider-error reason, last activity. Live cards keep a deterministic order by project path, then session start time; needs-attention cards badge the browser tab without jumping around. Below the grid: past sessions grouped by project, three compact rows per group with an "all N on disk" expander, resume and delete. |
-| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, a bounded scrollable subagent panel that lists every retained agent newest-first with full running/done counts, a shared dismissible banner region for model fallback, extension notices, retry/compaction/paused/provider status, and local action results, a controls-only dock line with elapsed time plus ■ stop and explicitly labelled retry/compaction aborts, a persistent session-header live indicator, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, a TUI-parity latest-100 median TPS indicator (`~31 tok/s [100] · 10% ↑ median [10000]`), and a stats popover. A fleet sidebar lists every other live session beside the transcript with the fleet cards' project, status/reasons, activity/latest-assistant preview, running/done subagent summaries, task progress, model, context, cost, message count, and last activity, deterministically ordered by project path then session start time (the fleet page's comparator), so needs-attention/error entries are emphasized — a filled attention chip or outlined error chip plus an entry border — without moving position; clicking an entry navigates to that session, desktop collapse and pointer/keyboard-resizable width persist browser-locally (default expanded, 260px), the hidden toggle border reflects the highest-priority other-session status, and neither sidebar nor toggle renders when no other live sessions exist. The subagent drill-in shows the same sidebar with its parent session excluded. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. Registered built-in slash commands are discovered generically, deduplicated ahead of colliding resource commands, and intercepted before prompting: dashboard actions cover settings, model, scoped-models, export/import, name/session stats, fork/tree, new/compact/dream, resume/reload, and quit. `/scoped-models` deep-links to the Settings editor with the session's current cwd as project context; login/logout show an explicit not-yet-implemented notice, while copy/hotkeys/buddy give terminal-only guidance. Future built-ins are intercepted automatically. The RPC prompt boundary rejects any built-in that reaches it during command-loading races or failures, so slash text cannot leak to the model. Attachments are retained and the command is visibly rejected rather than silently discarded. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; a rich `ask`/`ask_user` request renders inline as a single wizard that presents all its questions together — each with Markdown-formatted question text, choices, optional free text — plus an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown, and is answered as one batch submit. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications for the viewed session render in its banner region; other sessions' and app-global notices use the fixed top-center toast stack. |
+| **Fleet** | Home. Live-first: one grid of every live session at the top — status chip (● running / ◆ needs-attention / ○ idle / ✕ error), project path, activity line, live subagent lines, tasks progress, ctx%, model, terminal provider-error reason, last activity. Live cards keep a deterministic order by project path, then session start time; needs-attention cards badge the browser tab without jumping around. Below the grid: past sessions grouped by their historical project, three compact rows per group with an "all N on disk" expander, resume and delete. Sessions remain visible when that historical directory is missing; resume opens an explicit runtime-directory chooser instead of mutating or hiding the session. |
+| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, a bounded scrollable subagent panel that lists every retained agent newest-first with full running/done counts, a shared dismissible banner region for model fallback, extension notices, retry/compaction/paused/provider status, and local action results, a controls-only dock line with elapsed time plus ■ stop and explicitly labelled retry/compaction aborts, a persistent session-header live indicator, and an info bar with cwd, original-session provenance when a historical session is resumed in a different runtime directory, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, a TUI-parity latest-100 median TPS indicator (`~31 tok/s [100] · 10% ↑ median [10000]`), and a stats popover. A fleet sidebar lists every other live session beside the transcript with the fleet cards' project, status/reasons, activity/latest-assistant preview, running/done subagent summaries, task progress, model, context, cost, message count, last activity, and any original-session provenance, deterministically ordered by project path then session start time (the fleet page's comparator), so needs-attention/error entries are emphasized — a filled attention chip or outlined error chip plus an entry border — without moving position; clicking an entry navigates to that session, desktop collapse and pointer/keyboard-resizable width persist browser-locally (default expanded, 260px), the hidden toggle border reflects the highest-priority other-session status, and neither sidebar nor toggle renders when no other live sessions exist. The subagent drill-in shows the same sidebar with its parent session excluded. Closed-session banners offer direct resume when the captured runtime directory still exists and an explicit directory chooser when the historical directory is missing or should be replaced. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. Registered built-in slash commands are discovered generically, deduplicated ahead of colliding resource commands, and intercepted before prompting: dashboard actions cover settings, model, scoped-models, export/import, name/session stats, fork/tree, new/compact/dream, resume/reload, and quit. `/scoped-models` deep-links to the Settings editor with the session's current cwd as project context; login/logout show an explicit not-yet-implemented notice, while copy/hotkeys/buddy give terminal-only guidance. Future built-ins are intercepted automatically. The RPC prompt boundary rejects any built-in that reaches it during command-loading races or failures, so slash text cannot leak to the model. Attachments are retained and the command is visibly rejected rather than silently discarded. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; a rich `ask`/`ask_user` request renders inline as a single wizard that presents all its questions together — each with Markdown-formatted question text, choices, optional free text — plus an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown, and is answered as one batch submit. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications for the viewed session render in its banner region; other sessions' and app-global notices use the fixed top-center toast stack. |
 | **Subagent view** | Transcript of a background agent: live events via the RPC relay, hydrated from the agent's on-disk session log (`/subagents/:agentId/messages`) so the transcript survives browser reloads. Shows the task, streaming output, tool activity, and any safe Dispatch Arbiter changed/unchanged/failure records with the final agent/model/thinking. No raw arbiter output is displayed or transported. While the child is running, a composer sends the user's text unchanged to that specific child as steering input, displays its pending steering queue, and reports its effective `one-at-a-time` or `all` delivery mode. Completed, failed, rehydrated, and unavailable children remain read-only. |
 | **Files** | Host-wide browser with places shortcuts (home, /tmp, project roots), breadcrumbs to `/`, new-folder, download, drop-zone/picker upload with explicit collision prompts, and "new session here" on any directory. It also shows the **effective global nested-context trust** for the displayed canonical directory: untrusted, trusted by that root, inherited from a granting root, or global expert trust-all. You can trust the displayed folder and descendants, or untrust the actual granting root; untrusting an inherited folder removes that root's trust for all descendants. |
 | **Memories** | Dreb-only memory management for `~/.dreb/memory` and `.dreb/memory` under active/disk project roots. It lists existing `MEMORY.md` indexes and direct child `.md` entries only (no Claude paths, create, or rename), shows entry frontmatter or metadata errors so malformed files can be repaired, renders sanitized Markdown preview beside a raw editor, and uses exact SHA-256 revisions so stale saves/deletes return conflicts while preserving drafts. The index view is complete, not truncated, and warns when it exceeds the 200-line memory-index convention. Entry deletion requires both entry and index revisions, removes only matching safe Markdown-link index lines (`file.md` / `./file.md`), writes the cleaned index atomically before unlinking the entry, and rolls back loudly if the unlink fails. |
@@ -205,7 +205,32 @@ captured) and **Return to fleet** actions. It is not a live runtime: composers,
 steering, model/thinking controls, stop controls, polling, and other runtime
 actions are disabled. Leaving that session's main/subagent route family releases
 the retained snapshot; Fleet shows no live card, and the authoritative on-disk
-session remains in its project group for normal resume.
+session remains in its project group for normal resume. Closed views also offer
+**Choose directory…** if their captured runtime path has disappeared.
+
+### Historical and runtime working directories
+
+A persisted session's `cwd` is historical metadata: it records where the session
+started and remains unchanged when the JSONL file is copied to another host or
+its project moves. Dashboard inventory reports that session even when the path no
+longer exists. Missing paths are labelled unavailable and are excluded from
+memory scopes, recent-project choices, and new-session shortcuts.
+
+A live runtime has a separate effective CWD. Valid historical paths are
+canonicalized and continue to resume directly. If the historical path is
+unavailable, Dashboard requires the user to choose an existing absolute
+directory; missing, unreadable, and non-directory paths are rejected before the
+RPC child is created. Tools, initial project context, settings, extensions, skills, git state,
+and project agent discovery use the effective runtime directory. Fleet cards and
+session chrome show that effective directory and retain the historical path as a
+separate note whenever they differ. Switching to another transcript inside an
+existing runtime does not change the process CWD.
+
+Choosing a fallback never rewrites the original session header. Normal resumed
+work can still append conversation entries. Starting `/new` from that runtime
+records the effective runtime directory in the new session's header, while the
+source transcript retains its historical path. Existing session-format migration
+behavior is unchanged.
 
 ### Dispatch Arbiter observability
 
@@ -311,9 +336,12 @@ nor a disk inventory scan.
 
 Live runtime state and on-disk session inventory have separate refresh paths.
 Before fleet, inventory, or resync serialization, the server explicitly projects
-each on-disk session to the declared browser DTO and bounds its first-message
-preview to 256 Unicode characters. Internal parent paths and complete searchable
-transcript text never cross this browser boundary. After creating, resuming,
+each on-disk session to the declared browser DTO, includes server-validated
+historical-CWD availability and its canonical candidate, and bounds its
+first-message preview to 256 Unicode characters. Unavailable historical paths
+remain visible but do not enter operational project-root inventories. Internal
+parent paths and complete searchable transcript text never cross this browser
+boundary. After creating, resuming,
 stopping, or deleting a session, the client narrowly refreshes the disk list
 through `GET /api/sessions` rather than reloading the whole fleet. While the
 Fleet screen or a session/subagent fleet sidebar is visible, it polls live-runtime

package/docs/extensions.md

@@ -524,13 +524,11 @@ dreb.on("stream_retry", async (event, ctx) => {
 
 #### length_retry
 
-Fired when a turn ends with `stopReason: "length"` (the model exhausted its output token budget mid-response) and dreb discards the truncated partial before retrying with a larger `maxTokens` budget. If all retries are exhausted (or the budget already sits at the model's ceiling), the turn fails loudly instead with an error message ("Response truncated at token limit after N attempts") rather than returning a silently truncated response.
+Fired when a turn ends with `stopReason: "length"` (the model exhausted its configured output limit mid-response) and dreb discards the truncated partial before retrying at that same configured limit. If all retries are exhausted, the agent loop fails loudly with an error message ("Response truncated at the configured output token limit after N attempts") rather than returning a silently truncated response. The session layer may then perform one compact-and-retry recovery when provider evidence or input-plus-output arithmetic indicates that remaining context, rather than the output limit alone, caused the truncation.
 
 ```typescript
 dreb.on("length_retry", async (event, ctx) => {
-  // event.attempt, event.maxAttempts
-  // event.previousMaxTokens - the budget used for the truncated attempt
-  // event.nextMaxTokens - the escalated budget the retry will request
+  // event.attempt, event.maxAttempts, event.maxTokens
   // event.discardedPartial - partial assistant message discarded before retry (debug/instrumentation only)
 });
 ```

package/docs/models.md

@@ -200,12 +200,14 @@ Leave `authHeader` unset or `false` for endpoints that expect `x-api-key`.
 | `reasoning` | No | `false` | Supports extended thinking |
 | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
 | `contextWindow` | No | `128000` | Context window size in tokens |
-| `maxTokens` | No | `16384` | Maximum output tokens |
+| `maxTokens` | No | `16384` | Ordinary request maximum output tokens, including per-model overrides; explicit bounded internal calls may use less |
 | `cost` | No | all zeros | `{"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}` (per million tokens) |
 | `compat` | No | provider `compat` | OpenAI compatibility overrides. Merged with provider-level `compat` when both are set. |
 | `systemPrompt` | No | — | Replace dreb's built-in prompt whenever this exact custom model is active. Mutually exclusive with `appendSystemPrompt`. |
 | `appendSystemPrompt` | No | — | Preserve the selected base prompt and append model-specific instructions. Mutually exclusive with `systemPrompt`. |
 
+`maxTokens` is sent as the ordinary request's output maximum; dreb does not reserve or pre-consume that allowance, and providers charge only for tokens actually generated. Purpose-specific internal calls may pass a smaller explicit limit. The ChatGPT-backed `openai-codex` protocol rejects `max_output_tokens`, so its built-in ceiling remains server-controlled and dreb rejects `maxTokens` overrides for that provider rather than silently ignoring them.
+
 Current behavior:
 - `/model` and `--list-models` list entries by model `id`.
 - The configured `name` is used for model matching and detail/status text.
@@ -287,7 +289,7 @@ Use `modelOverrides` to customize specific built-in models without replacing the
 }
 ```
 
-`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`, `systemPrompt`, `appendSystemPrompt`.
+`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`, `systemPrompt`, `appendSystemPrompt`. The ChatGPT-backed `openai-codex` protocol rejects `max_output_tokens`, so dreb rejects `maxTokens` overrides for that provider rather than silently ignoring them; its built-in model ceiling remains server-controlled.
 
 Prompt fields follow the same rules as custom model entries: choose replacement or append,
 not both; use a non-empty string; and do not also configure prompt behavior for the canonical

package/docs/rpc.md

@@ -18,6 +18,19 @@ await client.start();
 
 This enables per-user filesystem isolation by plain Unix DAC: give each authenticated user a dedicated UID and a working directory owned by that UID at mode `0700`. If the parent lacks the required capability (or the platform doesn't support `uid`/`gid`, e.g. Windows), the spawn fails and `start()` rejects rather than silently running as the parent user.
 
+### Runtime CWD and historical session CWD
+
+`RpcClientOptions.cwd` is the effective runtime directory supplied to the child
+process. Tools, resource and project-agent discovery, git/tab-title metadata,
+and relative runtime commands use it. Opening or switching to a persisted JSONL
+session does not replace that process directory.
+
+A session listing's `cwd` is different: it is historical metadata copied from
+the session header. It can name a moved or missing directory and is not rewritten
+merely because a host launches the transcript in another runtime directory.
+Embedders should display both values when they differ rather than treating the
+historical field as a safe process-spawn path.
+
 ### Process exit and pipe errors
 
 `RpcClient.onExit(listener)` receives an `RpcExitInfo` when the child dies: `{ code, signal }` from a process `exit`, or `{ error }` from a spawn/runtime `error`. Process exits also carry `stderrTail` — the last **2000 characters** of the child's captured stderr — so a host that only watches for exit codes can still surface the child's own diagnostic (for example the stdout backpressure guard's abort message) instead of an opaque exit code. In-flight requests are rejected with the exit reason.
@@ -203,7 +216,7 @@ Response:
 {"type": "response", "command": "dream", "success": true, "data": {"message": "Dream backup path: /home/user/.dreb/memory-archive"}}
 ```
 
-A consolidation run performs and verifies the backup before prompting the agent. Backup, lock, path-validation, settings-write, or consolidation failures are explicit RPC errors.
+A relative backup path is resolved from the effective runtime CWD, not the historical CWD in a resumed session header. A consolidation run performs and verifies the backup before prompting the agent. Backup, lock, path-validation, settings-write, or consolidation failures are explicit RPC errors.
 
 ### State
 
@@ -302,7 +315,7 @@ Response:
 
 #### get_git_branch
 
-Get the current git branch for the session cwd. Returns `null` outside a git repository and `"detached"` for detached HEAD.
+Get the current git branch for the effective runtime CWD. Returns `null` outside a git repository and `"detached"` for detached HEAD.
 
 ```json
 {"type": "get_git_branch"}
@@ -1054,7 +1067,7 @@ The extension SDK's `dreb.getCommands()` contract is unchanged: it continues to
 
 #### list_sessions
 
-List sessions for the current working directory. Returns sessions sorted by most recently modified first.
+List sessions associated with the current persisted session store and its historical working-directory provenance. Returns sessions sorted by most recently modified first. This is a transcript listing operation; switching one of these sessions does not change the RPC process's effective runtime CWD.
 
 ```json
 {"type": "list_sessions"}
@@ -1178,7 +1191,7 @@ The response data is `{ "steeringMode": "one-at-a-time" | "all", "pending": RpcP
 
 #### list_agent_types
 
-List discoverable subagent types for the current session working directory. This includes package-bundled agents, user-level agents, and project-level agents in `.dreb/agents/*.md`. Results are sorted by `name`.
+List discoverable subagent types for the effective runtime working directory. This includes package-bundled agents, user-level agents, and project-level agents in `.dreb/agents/*.md`. Results are sorted by `name`.
 
 ```json
 {"type": "list_agent_types"}
@@ -1770,7 +1783,7 @@ Response:
 | `tool_execution_update` | Tool execution progress (streaming output) |
 | `tool_execution_end` | Tool completes |
 | `stream_retry` | Stream dropped mid-turn; retrying (partial output discarded) |
-| `length_retry` | Response hit the token limit; retrying with a larger budget |
+| `length_retry` | Response hit the token limit; retrying at the configured output limit |
 | `auto_compaction_start` | Auto-compaction begins |
 | `auto_compaction_end` | Auto-compaction completes |
 | `context_window_upgrade` | Wire model tier auto-upgraded (e.g. Kimi K3 256k → 1M); includes `provider`, `modelId`, `fromContextWindow`, `toContextWindow` |

package/docs/session.md

@@ -386,7 +386,7 @@ Key methods for working with sessions programmatically.
 - `SessionManager.listAll(onProgress?)` - List all sessions across all projects
 
 ### Instance Methods - Session Management
-- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `newSession(options?)` - Start a new session (options: `{ parentSession?: string, cwd?: string }`)
 - `setSessionFile(path)` - Switch to a different session file
 - `createBranchedSession(leafId)` - Extract a branch to a new session file while preserving the current session name metadata
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.66.0",
+	"version": "2.66.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {