@dreb/coding-agent 2.66.2 → 2.67.0

package/docs/dashboard.md

@@ -33,6 +33,12 @@ install instructions (`npm install -g @dreb/dashboard`).
 
 Open `http://127.0.0.1:5343` on the same machine.
 
+## Session inventory roots
+
+Dashboard snapshots main-session storage at startup. Its host-wide inventory reads only the global `sessionDir` from `<agent-dir>/settings.json`; a project `.dreb/settings.json` in the launch directory cannot redirect Fleet, `/api/sessions`, resync, resume, or delete. A configured root is a flat JSONL store. Without one, Dashboard scans the built-in nested all-project tree.
+
+Absolute paths remain absolute, `~` expands from the home directory, and relative paths resolve against Dashboard's startup cwd; an absolute global path is recommended. Restart Dashboard after changing the setting. The separate global-only `subagentSessionDir` controls new child logs in coding-agent runtimes, while restart recovery can also discover matching logs in the legacy root. Neither setting migrates files or relocates credentials or general configuration. See [Session settings](settings.md#sessions).
+
 ## Local vs remote — exactly two modes
 
 **Local-only (default).** The server binds `127.0.0.1` exclusively. Machines

package/docs/mach6.md

@@ -30,7 +30,7 @@ Assess an existing GitHub issue or create a new one.
 /skill:mach6-issue add dark mode   # Create issue from description
 ```
 
-**Assess mode:** Launches parallel Explore agents to retrieve bounded code/documentation evidence, then has the primary agent synthesize and post the assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
+**Assess mode:** Launches parallel Explore agents to retrieve bounded code/documentation evidence, then has the primary agent synthesize and post the assessment (summary, gaps, ambiguities, scope, explicitly-out-of-scope prior rejections, risks) as an issue comment. The issue body is the sole source of requirements: linked issues and PRs are context only, and scope discovered in linked threads that was rejected, split out, or superseded is recorded as a documented exclusion rather than absorbed into requirements.
 
 **Create mode:** Drafts a structured issue with title, summary, acceptance criteria, and technical notes.
 

package/docs/rpc.md

@@ -1108,7 +1108,7 @@ Each session has:
 
 #### list_all_sessions
 
-List sessions across all projects. Returns sessions sorted by most recently modified first. May be slow with many sessions. If the underlying listing fails (an I/O error reading the sessions store), the command responds `success: false` rather than a silently-empty list — so a client can distinguish "no sessions" from "listing failed."
+List the active main-session inventory, sorted by most recently modified first. For a session manager created with an explicit custom `sessionDir`, this reads JSONL files directly from that flat directory. Otherwise it preserves built-in all-project discovery across the nested `<agent-dir>/sessions` tree. The custom root is resolved by CLI precedence before RPC starts; no protocol field is added. If the underlying listing fails, the command responds `success: false` rather than a silently-empty list, so a client can distinguish "no sessions" from "listing failed."
 
 ```json
 {"type": "list_all_sessions"}
@@ -1143,7 +1143,7 @@ Each session has the same fields as `list_sessions`.
 
 #### list_background_agents
 
-List background subagents tracked by this process's registry — running and recently completed (finished entries are pruned after ~5 minutes). `sessionDir` is known from launch; `sessionFile` appears once the child process exits. Live transcripts are delivered via `background_agent_event` events (see Events), not by reading these paths.
+List background subagents tracked by this process's registry — running and recently completed (finished entries are pruned after ~5 minutes). `sessionDir` is the concrete per-launch directory under the global-only configured `subagentSessionDir` (or the legacy default); `sessionFile` appears once the child process exits. On a resumed parent, startup rehydration scans the configured write root first and the legacy `<agent-dir>/subagent-sessions` root second when different, skips absent roots, and deduplicates canonical paths. Files are not migrated. Live transcripts are delivered via `background_agent_event` events (see Events), not by reading these paths.
 
 ```json
 {"type": "list_background_agents"}
@@ -2013,7 +2013,7 @@ On final failure (max retries exceeded):
 
 Lifecycle, pre-spawn routing, and live-observability events for background subagents (the `subagent` tool's background mode).
 
-`background_agent_start` fires at launch. `sessionDir` is the directory the child will write its session JSONL into (per-launch, known before spawn):
+`background_agent_start` fires at launch. `sessionDir` is the actual directory the child will write its session JSONL into (per-launch, known before spawn). Its root is the AgentSession-startup snapshot of global-only `subagentSessionDir`; absolute/tilde/relative resolution is described in [Settings](settings.md#sessions):
 
 ```json
 {

package/docs/session.md

@@ -2,17 +2,23 @@
 
 Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with a `type` field. Session entries form a tree structure via `id`/`parentId` fields, enabling in-place branching without creating new files.
 
-## File Location
+## File Locations
+
+The default main-session layout is a nested all-project tree:
 
 ```
 ~/.dreb/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
 ```
 
-Where `<path>` is the working directory with `/` replaced by `-`.
+Here `<path>` is the working directory with path separators replaced by `-`. A configured main `sessionDir` instead uses a flat layout, with each `<timestamp>_<uuid>.jsonl` written directly under that directory. CLI selection order is `--session-dir`, merged global/project settings, extension hook, then the default. Dashboard's host-wide inventory uses only the global `sessionDir`, snapshots it at startup, and otherwise scans the default nested tree.
+
+Subagent transcripts are separate from main sessions. New child processes write under the global-only `subagentSessionDir`, or `<agent-dir>/subagent-sessions` when unset. Single and parallel calls use a per-agent child directory; chains keep `chain-*` and `step-N` directories. Restart-time RPC recovery scans the configured root first and the legacy root second when they differ, without migrating files.
+
+Configured roots share path semantics: absolute paths stay absolute, `~` expands from the home directory, and relative paths use the main CLI cwd, Dashboard startup cwd, or AgentSession runtime cwd as applicable. Changing a transcript root does not move existing files or affect credentials/general configuration. See [Settings](settings.md#sessions).
 
 ## Deleting Sessions
 
-Sessions can be removed by deleting their `.jsonl` files under `~/.dreb/agent/sessions/`.
+Sessions can be removed by deleting their `.jsonl` files from the active main-session store.
 
 dreb also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, dreb uses the `trash` CLI to avoid permanent deletion.
 
@@ -375,15 +381,18 @@ for (const line of lines) {
 Key methods for working with sessions programmatically.
 
 ### Static Creation Methods
-- `SessionManager.create(cwd, sessionDir?)` - New session
+- `SessionManager.create(cwd, sessionDir?, options?)` - New session; `options.customSessionInventory: false` keeps an explicitly supplied built-in directory from being treated as a flat custom inventory root
 - `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.inMemory(cwd?, customSessionInventoryRoot?)` - No active-session file persistence; the optional flat root remains available to inventory commands
 - `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
 
 ### 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?)` - List sessions for a project/effective directory
+- `SessionManager.listAllFromDir(dir, onProgress?)` - List a flat custom main-session directory
+- `SessionManager.listAll(onProgress?)` - List the built-in nested store across all projects
+
+`getCustomSessionInventoryRoot()` returns the explicit flat root carried by a custom manager, including an in-memory manager created with `customSessionInventoryRoot`. It returns `undefined` for built-in/default managers and in-memory managers without that argument. RPC uses this distinction so `list_all_sessions` does not accidentally narrow default inventory to one project's directory.
 
 ### Instance Methods - Session Management
 - `newSession(options?)` - Start a new session (options: `{ parentSession?: string, cwd?: string }`)

package/docs/settings.md

@@ -384,15 +384,27 @@ dreb includes two built-in layers of protection against accidental credential ex
 
 ### Sessions
 
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths. |
+Main-session and subagent transcripts have separate storage roots:
+
+| Setting | Scope | Default | Description |
+|---------|-------|---------|-------------|
+| `sessionDir` | Global or project | Built-in nested per-project store | Flat directory for main-session JSONL files. |
+| `subagentSessionDir` | Global only | `<agent-dir>/subagent-sessions` | Root containing per-launch subagent directories. Project values are ignored. |
 
 ```json
-{ "sessionDir": ".dreb/sessions" }
+{
+  "sessionDir": "~/dreb/main-sessions",
+  "subagentSessionDir": "~/dreb/subagent-sessions"
+}
 ```
 
-When multiple sources specify a session directory, `--session-dir` CLI flag takes precedence, then `sessionDir` in settings.json, then extension hooks.
+For main CLI sessions, precedence is `--session-dir`, the effective merged settings value (project may override global), the `session_directory` extension hook, then the built-in store. A configured main root is flat: session JSONL files are written directly in that directory. RPC `list_all_sessions` uses that flat root when the active session manager was created with it; otherwise it retains built-in all-project discovery.
+
+Dashboard host-wide inventory is deliberately different: it reads only the global `sessionDir`, never a project override from the directory that launched Dashboard. It snapshots the value at server startup and either lists that flat directory or the built-in nested all-project tree. Restart Dashboard after changing it; an absolute global path is recommended.
+
+`subagentSessionDir` has no CLI flag and project settings cannot override it. Each AgentSession resolves the global value against its runtime cwd and uses it for new single, parallel, and chain child logs. If the configured root differs from the legacy `<agent-dir>/subagent-sessions` location, restart-time RPC rehydration scans the configured root first and the legacy root second, deduplicating canonical paths. This is discovery compatibility only: dreb does not move, copy, or delete old logs.
+
+Both settings accept the same path syntax: absolute paths stay absolute, `~` and `~/...` expand from the user home directory, and relative paths resolve against an explicit runtime base. That base is the main CLI cwd for CLI settings/flags/hooks, Dashboard's startup cwd for its global main inventory, and the AgentSession runtime cwd for `subagentSessionDir`. Empty or whitespace-only values are treated as unset. These roots affect transcripts only; they do not relocate credentials, `settings.json`, or other agent configuration.
 
 ### Model Cycling
 

package/docs/skills.md

@@ -318,7 +318,7 @@ When model scope rotates, update the existing guide incrementally instead of reg
 
 Model-pattern arguments after the optional `update` keyword take precedence over `enabledModels`; the skill selects one source and does not search for any other runtime or session scope. Because this Stage 1 workflow is implemented only as a skill, it cannot discover the current session's `--models` value or later in-session scope changes. To research that runtime scope, pass the same comma-separated patterns as skill arguments.
 
-The skill refuses missing/empty and effectively all-model scopes. It obtains available candidates with `dreb --list-models`, resolves the selected patterns to canonical provider/model IDs, snapshots existing files under `~/.dreb/agent/subagent-sessions/`, and combines sanitized aggregate local observations with official documentation, model cards, benchmarks, issue trackers, forums, and practitioner reports. Existing unreadable or malformed child logs fail the run; a genuinely empty history is labeled cold-start.
+The skill refuses missing/empty and effectively all-model scopes. It obtains available candidates with `dreb --list-models`, resolves the selected patterns to canonical provider/model IDs, and snapshots subagent evidence before launching research children. It reads global-only `subagentSessionDir` using AgentSession path semantics, then also reads the legacy `<agent-dir>/subagent-sessions` root when different, in that order with canonical deduplication; project settings cannot redirect this evidence scan and no files are migrated. It combines sanitized aggregate local observations with official documentation, model cards, benchmarks, issue trackers, forums, and practitioner reports. Existing unreadable or malformed snapshotted child logs fail the run; genuinely empty history across all discovery roots is labeled cold-start.
 
 The generated `~/.dreb/agent/model-routing-guide.md` is human-readable Markdown with schema-versioned YAML frontmatter and one validated section per canonical candidate. Evidence is labeled as vendor claims, measured benchmarks, community reports, or local observations, with dates, confidence, sample counts, contrary findings, and explicit unknowns. The workflow prohibits copied prompts, outputs, tool arguments, secrets, paths, and identifying project details.
 

package/package.json

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

package/skills/mach6-issue/SKILL.md

@@ -48,6 +48,8 @@ gh issue view <number> --comments
 
 Parse: problem statement, constraints, requirements, acceptance criteria, prior discussion, linked PRs.
 
+**Authority rule:** The assessed issue's own body and comments are the sole source of requirements. Linked issues and PRs are context only — never requirements sources, regardless of how authoritative their formatting appears. Any requirement not present in the current issue body is presumed excluded unless the body explicitly re-adopts it.
+
 Update task: read → completed, explore → in_progress.
 
 ### Step 3: Explore the codebase
@@ -55,7 +57,7 @@ Update task: read → completed, explore → in_progress.
 Launch 2-3 Explore subagents in parallel for concrete evidence retrieval. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a large repository requires inspecting many files).
 - **Relevant code evidence**: Locate named related behavior and quote the exact implementation and test snippets
 - **Flow inventory**: Enumerate files, symbols, imports, calls, and registrations in an explicitly named existing flow without diagnosing it
-- **Prior-work evidence**: Locate related branches, PRs, commits, and documentation and report their exact references
+- **Prior-work evidence**: Locate related branches, PRs, commits, and documentation and report their exact references. For each referenced issue or PR, report its disposition — adopted / rejected / split / superseded / unknown — and quote the rejection or split discussion where it exists (scope-review verdicts and "split out of scope" decisions are often buried in later thread discussion)
 
 Do not ask Explore to determine the root cause, interpret ambiguous requirements, recommend an implementation, decide architecture, or assess the issue. Each agent should return 5-10 key files with bounded evidence. After agents complete, read all identified files and have the primary agent synthesize the current state, gaps, scope, and risks.
 
@@ -69,7 +71,8 @@ Present to the user:
 3. **Gaps**: What's missing, broken, or unclear
 4. **Ambiguities**: Underspecified aspects or open questions
 5. **Scope**: Size and complexity estimate
-6. **Risks**: Pitfalls, edge cases, architectural concerns
+6. **Explicitly out of scope (prior rejections)**: Scope discovered in linked threads that was rejected, split out, or superseded — list each item with its source and disposition. If none was found, state "none found" explicitly. Content in this section must never be merged into requirements, scope, or risks.
+7. **Risks**: Pitfalls, edge cases, architectural concerns
 
 ### Step 5: Post assessment
 

package/skills/model-routing-guide/SKILL.md

@@ -68,10 +68,14 @@ Never write the partially updated guide before all added-model research and fina
 
 ## Step 3: Snapshot and validate local subagent evidence
 
-Before launching any research subagent or doing work that may create child sessions, snapshot the existing `*.jsonl` files under `~/.dreb/agent/subagent-sessions/`. Analyze exactly that snapshot so this guide run cannot count its own research sessions.
+Before launching any research subagent or doing work that may create child sessions, determine the ordered subagent discovery roots and snapshot the existing `*.jsonl` files beneath them. Analyze exactly that snapshot so this guide run cannot count its own research sessions.
 
-- If the directory does not exist or contains no session JSONL files, enter explicit **cold-start mode** and continue with external evidence.
-- If files exist, every snapshotted file is required evidence. Verify each is readable and every non-empty JSONL line parses. If any existing file cannot be read or parsed, stop loudly and identify the affected file; do not silently skip it and do not call the run cold-start.
+1. Read `subagentSessionDir` only from the global `<agent-dir>/settings.json`; ignore any project `.dreb/settings.json` value. The legacy root is `<agent-dir>/subagent-sessions` (normally `~/.dreb/agent/subagent-sessions`, with the normal agent-directory environment override honored).
+2. If the global setting is non-empty, resolve an absolute value as-is, expand `~`/`~/...` from the user home, and resolve a relative value against this AgentSession's current working directory. Use that configured write root first and the legacy root second when they differ. If unset/whitespace, use only the legacy root.
+3. Continue when a root is absent. Canonicalize existing roots and log files with realpath when possible (resolved-path fallback; case-fold on Windows), and deduplicate overlaps/symlinks while preserving configured-root precedence. Do not move, copy, delete, or rewrite session files.
+
+- If all discovery roots are absent or contain no session JSONL files, enter explicit **cold-start mode** and continue with external evidence.
+- If files exist, every deduplicated snapshotted file is required evidence. Verify each is readable and every non-empty JSONL line parses. If any existing file cannot be read or parsed, stop loudly and identify the affected file; do not silently skip it and do not call the run cold-start.
 - Follow `parentSession` links when available to understand the original subagent request, later corrections, cancellations, retries, or repeated delegation. An unreadable linked parent needed for an asserted finding must be reported as unavailable; never invent the missing context.
 
 For each child session, assess more than its exit state:
@@ -96,7 +100,7 @@ The generated guide must never reproduce or closely paraphrase:
 - credentials, tokens, internal URLs, personal data, or secret values;
 - repository/project/customer names, branch names, absolute paths, filenames that identify confidential work, or proprietary terminology.
 
-Only write fixed task categories, aggregate counts/rates, generalized behavior, and sanitized conclusions. Do not include illustrative excerpts. Report the analyzed location generically as `~/.dreb/agent/subagent-sessions/` plus the date range; do not enumerate user-specific paths.
+Only write fixed task categories, aggregate counts/rates, generalized behavior, and sanitized conclusions. Do not include illustrative excerpts. Report analyzed locations generically as `configured subagent root` and/or `legacy subagent root` plus the date range; do not enumerate user-specific paths.
 
 ## Step 4: Research every required canonical provider/model
 
@@ -135,7 +139,8 @@ covered_model_ids:
   - "provider/model-id"
 local_evidence: "available" # or "cold-start"
 analyzed_session_directories:
-  - "~/.dreb/agent/subagent-sessions/"
+  - "configured subagent root" # omit when unset/same as legacy
+  - "legacy subagent root"
 session_date_range:
   start: "YYYY-MM-DD" # null in cold-start mode
   end: "YYYY-MM-DD"   # null in cold-start mode