@orion-agents/orion-code 0.3.19 → 0.3.21

package/CHANGELOG.md

@@ -22,6 +22,67 @@ which is **not** a pass.
 
 ## [Unreleased]
 
+## [0.3.21] — UNRELEASED
+
+> **Status: candidate.** Open. Adds user-authorized local project-root discovery to
+> `LOCAL WORKSPACE` (bounded scan, explicit inspect → confirm → activate reuse, no
+> Home/network-volume scanning, no silent registration) and corrects the v0.3.20
+> release-facts documentation (`docs/plan/evidence/v0.3.20-e2e/release-receipt-v0.3.20.md`).
+> Not merged, tagged or published.
+
+### Added (planned)
+
+- Saved project roots registry (`WorkspaceRootsRegistryV1`) and a bounded, cancellable
+  discovery service with depth/candidate/time budgets and partial-result semantics.
+
+### Fixed (planned)
+
+- README / README.zh-CN / CHANGELOG release-state drift for v0.3.20, plus a release-check
+  guard that fails when a README describes a tagged version as unpublished.
+
+## [0.3.20] — 2026-10-07
+
+> **Status: published.** Released as `@orion-agents/orion-code@0.3.20` from
+> `refs/tags/v0.3.20`, and merged to `main` as `e658932` (#261). Repairs the Web E2E
+> suite that has been red since v0.3.11 (the dock's tabs became rail buttons)
+> independently of the Git panel work, and fixes the product defects the repair exposed.
+>
+> ### Fixed (product)
+>
+> - The work-panel rail no longer sets `aria-orientation` on `role=navigation`
+>   (axe `aria-allowed-attr`, critical), and the navigation aside keeps one stable
+>   id so `aria-controls` always resolves.
+> - The first archived-sessions load no longer storms the host (2476 requests
+>   measured in ~80s): the loading state claims workspace ownership like the
+>   failure path already did.
+> - The narrow-width navigation toggle and the drawer close button are restored
+>   (v0.3.15 removed them with the conversation header, leaving sub-~800px
+>   viewports without a pointer entry while their CSS and focus wiring survived).
+> - A bare Escape no longer moves focus to a stale drawer trigger, and the
+>   shortcut-help dialog restores focus to its trigger explicitly; its scrollable
+>   body is keyboard focusable (axe `scrollable-region-focusable`, serious).
+>
+> ### Test infrastructure
+>
+> - Every stale E2E locator and copy assertion traced to its contract change and
+>   rewritten; all previously failing specs pass locally (full suite 100/103 —
+>   the remainder are sandbox-only: a bulk-delete shim, two perf bounds).
+> - `allowExpectedConsoleErrors(testInfo, text, maximum)` bounds the console
+>   noise that deliberate failure journeys (CAS conflicts, phantom catalog
+>   sessions) produce; the evidence capture caps can be raised via env for
+>   diagnosis.
+> - The receipt upload only fires when the evidence gate actually ran.
+>
+> ### Security
+>
+> - The production dependency tree is patched to zero known high advisories:
+>   `js-yaml` 4.3.2 (the advisory the audit job originally failed on) plus the
+>   `axios` 1.20.0, `undici` 6.29.0, `brace-expansion`, `braces` and `figlet`
+>   patch updates. The audit job now audits `--omit=dev`: the remaining high
+>   advisories sit in dev-only tooling (jest 29 → 30, typescript-eslint 7 → 8,
+>   nodemon) whose fixes are major tooling upgrades; they are follow-up work,
+>   not shipped code.
+
 ## [0.3.19] — 2026-09-19
 
 > **Status: published.** Released as `@orion-agents/orion-code@0.3.19` from
@@ -39,7 +100,7 @@ which is **not** a pass.
   affordances never activated on any load whose status was not already cached. The observer is
   now attached with a callback ref, so it follows the node in and out of the tree.
 - **A discarded diff read left the pane blank with a file still selected.** Only a newer
-  *selection* supersedes a read now. The document states the revision it was rendered against,
+  _selection_ supersedes a read now. The document states the revision it was rendered against,
   so accepting it and letting `stale` tell the truth is both safer and correct — dropping it
   because the 2s visible poll had bumped the revision abandoned the read with nothing to
   re-issue it.
@@ -50,7 +111,7 @@ which is **not** a pass.
 ### Added
 
 - **A bare repository is no longer reported as "not a repository".** `rev-parse
-  --show-toplevel` fails for a bare repository too, and that single failure was read as "no
+--show-toplevel` fails for a bare repository too, and that single failure was read as "no
   repository here". Status now carries `repositoryKind: 'worktree' | 'bare' | 'absent'` and
   `hasWorktree`; every worktree-backed surface gates on `hasWorktree`, which is the only flag
   that cannot be wrong. A bare repository's branch is reported instead of hidden, its change
@@ -109,6 +170,7 @@ which is **not** a pass.
   and the agent-led file-change scenario are still open.
 
 ---
+
 ## [0.3.17]
 
 > **Status: candidate.** Opening a local project is made fast and honest
@@ -255,7 +317,7 @@ which is **not** a pass.
   same timestamp granularity and with an unchanged size was not re-hashed, so
   `git add` succeeded while changing nothing. The copy now preserves the
   original timestamps, and staging verifies each path with `hash-object
-  --path` against the index entry.
+--path` against the index entry.
 - **`localhost` was rejected site-wide:** the Host and Origin checks compared
   header strings exactly, so `http://localhost:<port>` returned 421 (and, with
   only the Host check fixed, every mutation would have returned 403). Both now

package/README.md

@@ -2,12 +2,10 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.19 — closes the v0.3.17 Git work panel's assertion backlog
-> (`docs/plan/evidence/v0.3.17-git/g317-status.md`) and fixes what those
-> assertions found: responsive tiers that never activated, a diff read discarded
-> on a background refresh that left the pane blank, a narrow back control that
-> dropped the reading position, and a bare repository reported as "not a
-> repository". Published to npm as 0.3.19 and tagged `v0.3.19`.
+> v0.3.21 candidate — open. Adds user-authorized local project-root discovery to
+> `LOCAL WORKSPACE` (bounded scan, explicit inspect → confirm → activate reuse). The previous
+> release 0.3.20 is on npm (registry `latest`) and tagged `v0.3.20` (`e658932`, #261) —
+> release facts: `docs/plan/evidence/v0.3.20-e2e/release-receipt-v0.3.20.md`.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.7 plan](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -172,7 +170,7 @@ current development environments. Node 20 is upstream EOL and is no longer a v0.
 After the immutable `0.3.5` npm receipt exists:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.19
+npm install -g @orion-agents/orion-code@0.3.21
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,10 +2,9 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.19：补齐 v0.3.17 Git 工作栏的断言欠账
-> （`docs/plan/evidence/v0.3.17-git/g317-status.md`），并修掉这些断言找出来的问题——
-> 响应式三档从未生效、被后台刷新丢弃的 Diff 读取导致内容区空白、窄屏返回丢失阅读位置、
-> 裸仓库被当成「不是仓库」。已发布 npm 0.3.19 并打 tag `v0.3.19`。
+> v0.3.21 候选版本：进行中。为 `LOCAL WORKSPACE` 增加用户显式授权的项目根目录发现（有界
+> 扫描、复用 inspect → confirm → activate）。上一版 0.3.20 已发布 npm（registry `latest`）
+> 并打 tag `v0.3.20`（`e658932`，#261）——发布事实：`docs/plan/evidence/v0.3.20-e2e/release-receipt-v0.3.20.md`。
 
 [English](README.md) ·
 [v0.3.7 方案](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -102,7 +101,7 @@ Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 当 npm 已存在不可变的 `0.3.4` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.19
+npm install -g @orion-agents/orion-code@0.3.21
 orion --version
 orion doctor
 ```

package/dist/runtime/release-receipts.d.ts

@@ -8,12 +8,28 @@ export declare const WEB_E2E_WEB31_SCENARIOS_V1: readonly ["WEB31-P0-01", "WEB31
 export declare const WEB_E2E_WEB32_SCENARIOS_V1: readonly ["WEB32-P0-01", "WEB32-P0-02", "WEB32-P0-03", "WEB32-P0-04", "WEB32-P0-05", "WEB32-P0-06", "WEB32-P0-07", "WEB32-P0-08", "WEB32-P0-09", "WEB32-P0-10", "WEB32-P0-11", "WEB32-P0-12"];
 export declare const WEB_E2E_WEB33_THEME_SCENARIOS_V1: readonly ["WEB33-P0-01", "WEB33-P0-02", "WEB33-P0-03", "WEB33-P0-04", "WEB33-P0-05", "WEB33-P0-06", "WEB33-P0-07", "WEB33-P0-08", "WEB33-P0-09", "WEB33-P0-10", "WEB33-P0-11", "WEB33-P0-12"];
 export declare const WEB_E2E_WEB33_SESSION_SCENARIOS_V1: readonly ["WEB33-P0-16", "WEB33-P0-17", "WEB33-P0-18", "WEB33-P0-19", "WEB33-P0-20", "WEB33-P0-21", "WEB33-P0-22", "WEB33-P0-23", "WEB33-P0-24"];
-export declare const WEB_E2E_WEB33_SCENARIOS_V1: readonly ("WEB33-P0-01" | "WEB33-P0-02" | "WEB33-P0-03" | "WEB33-P0-04" | "WEB33-P0-05" | "WEB33-P0-06" | "WEB33-P0-07" | "WEB33-P0-08" | "WEB33-P0-09" | "WEB33-P0-10" | "WEB33-P0-11" | "WEB33-P0-12" | "WEB33-P0-16" | "WEB33-P0-17" | "WEB33-P0-18" | "WEB33-P0-19" | "WEB33-P0-20" | "WEB33-P0-21" | "WEB33-P0-22" | "WEB33-P0-23" | "WEB33-P0-24")[];
+/**
+ * v0.3.20 — the WEB33 scenarios whose specs shipped between v0.3.13 and
+ * v0.3.15 (rail, transcript navigator, brand, files editor, resource layout)
+ * and used these ids before they were registered. The receipts' exact
+ * coverage check requires every running id to be registered exactly once:
+ * WEB33-P0-16/17/18 belong to the session-concurrency journeys, so the
+ * v0.3.13 resource-layout specs were renumbered to P0-41/42/43.
+ */
+export declare const WEB_E2E_WEB33_RESOURCE_SCENARIOS_V1: readonly ["WEB33-P0-13", "WEB33-P0-14", "WEB33-P0-15", "WEB33-P0-25", "WEB33-P0-26", "WEB33-P0-27", "WEB33-P0-28", "WEB33-P0-29", "WEB33-P0-30", "WEB33-P0-31", "WEB33-P0-32", "WEB33-P0-34", "WEB33-P0-41", "WEB33-P0-42", "WEB33-P0-43"];
+/**
+ * v0.3.15 — keyboard and shell surface journeys.
+ */
+export declare const WEB_E2E_WEB36_SCENARIOS_V1: readonly ["WEB36-P0-01", "WEB36-P1-01", "WEB36-P1-02", "WEB36-P1-03"];
+/**
+ * v0.3.16 — transcript / workspace surface journeys.
+ */
+export declare const WEB_E2E_WEB37_SCENARIOS_V1: readonly ["WEB37-P0-01", "WEB37-P0-02", "WEB37-P0-03"];
 /**
  * v0.3.17 — LOCAL WORKSPACE open path. The picker is driven by a script file
  * (`ORION_CODE_WEB_PICKER_FIXTURE`) so CI never opens a real Finder dialog.
  */
-export declare const WEB_E2E_WEB38_SCENARIOS_V1: readonly ["WEB38-P0-01", "WEB38-P0-02", "WEB38-P0-03", "WEB38-P0-04", "WEB38-P0-05"];
+export declare const WEB_E2E_WEB38_SCENARIOS_V1: readonly ["WEB38-P0-01", "WEB38-P0-02", "WEB38-P0-03", "WEB38-P0-04", "WEB38-P0-05", "WEB38-P0-06"];
 /**
  * v0.3.17 — Git right-hand work panel (`docs/plan/v0.3.17-plan.md`).
  *
@@ -21,6 +37,7 @@ export declare const WEB_E2E_WEB38_SCENARIOS_V1: readonly ["WEB38-P0-01", "WEB38
  * actually verify; the per-stage unit suites are registered separately.
  */
 export declare const WEB_E2E_WEB317_SCENARIOS_V1: readonly string[];
+export declare const WEB_E2E_WEB33_SCENARIOS_V1: readonly ("WEB33-P0-01" | "WEB33-P0-02" | "WEB33-P0-03" | "WEB33-P0-04" | "WEB33-P0-05" | "WEB33-P0-06" | "WEB33-P0-07" | "WEB33-P0-08" | "WEB33-P0-09" | "WEB33-P0-10" | "WEB33-P0-11" | "WEB33-P0-12" | "WEB33-P0-16" | "WEB33-P0-17" | "WEB33-P0-18" | "WEB33-P0-19" | "WEB33-P0-20" | "WEB33-P0-21" | "WEB33-P0-22" | "WEB33-P0-23" | "WEB33-P0-24" | "WEB33-P0-13" | "WEB33-P0-14" | "WEB33-P0-15" | "WEB33-P0-25" | "WEB33-P0-26" | "WEB33-P0-27" | "WEB33-P0-28" | "WEB33-P0-29" | "WEB33-P0-30" | "WEB33-P0-31" | "WEB33-P0-32" | "WEB33-P0-34" | "WEB33-P0-41" | "WEB33-P0-42" | "WEB33-P0-43")[];
 /**
  * v0.3.19 — closing the v0.3.17 G317 assertion backlog.
  *

package/dist/runtime/release-receipts.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WEB_E2E_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB33_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB32_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB31_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_SETTINGS_SCENARIOS_V1 = exports.WEB_E2E_FULL_SCENARIOS_V1 = exports.WEB_E2E_WEB34_SCENARIOS_V1 = exports.WEB_E2E_WEB317_SCENARIOS_V1 = exports.WEB_E2E_WEB38_SCENARIOS_V1 = exports.WEB_E2E_WEB33_SCENARIOS_V1 = exports.WEB_E2E_WEB33_SESSION_SCENARIOS_V1 = exports.WEB_E2E_WEB33_THEME_SCENARIOS_V1 = exports.WEB_E2E_WEB32_SCENARIOS_V1 = exports.WEB_E2E_WEB31_SCENARIOS_V1 = exports.WEB_E2E_LEGACY_SCENARIOS_V1 = exports.SUPPORTED_RELEASE_VERSION_LINE_V1 = exports.SUPPORTED_RELEASE_NODE_FLOORS_V1 = exports.SUPPORTED_RELEASE_NODE_MAJORS_V1 = exports.RELEASE_RECEIPT_VERSION_V1 = void 0;
+exports.WEB_E2E_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB33_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB32_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_WEB31_CRITICAL_SCENARIOS_V1 = exports.WEB_E2E_SETTINGS_SCENARIOS_V1 = exports.WEB_E2E_FULL_SCENARIOS_V1 = exports.WEB_E2E_WEB34_SCENARIOS_V1 = exports.WEB_E2E_WEB33_SCENARIOS_V1 = exports.WEB_E2E_WEB317_SCENARIOS_V1 = exports.WEB_E2E_WEB38_SCENARIOS_V1 = exports.WEB_E2E_WEB37_SCENARIOS_V1 = exports.WEB_E2E_WEB36_SCENARIOS_V1 = exports.WEB_E2E_WEB33_RESOURCE_SCENARIOS_V1 = exports.WEB_E2E_WEB33_SESSION_SCENARIOS_V1 = exports.WEB_E2E_WEB33_THEME_SCENARIOS_V1 = exports.WEB_E2E_WEB32_SCENARIOS_V1 = exports.WEB_E2E_WEB31_SCENARIOS_V1 = exports.WEB_E2E_LEGACY_SCENARIOS_V1 = exports.SUPPORTED_RELEASE_VERSION_LINE_V1 = exports.SUPPORTED_RELEASE_NODE_FLOORS_V1 = exports.SUPPORTED_RELEASE_NODE_MAJORS_V1 = exports.RELEASE_RECEIPT_VERSION_V1 = void 0;
 exports.createTarballArtifactReceiptV1 = createTarballArtifactReceiptV1;
 exports.verifyTarballArtifactReceiptV1 = verifyTarballArtifactReceiptV1;
 exports.createRuntimeMatrixReceiptV1 = createRuntimeMatrixReceiptV1;
@@ -97,9 +97,47 @@ exports.WEB_E2E_WEB33_SESSION_SCENARIOS_V1 = Object.freeze([
     'WEB33-P0-23',
     'WEB33-P0-24',
 ]);
-exports.WEB_E2E_WEB33_SCENARIOS_V1 = Object.freeze([
-    ...exports.WEB_E2E_WEB33_THEME_SCENARIOS_V1,
-    ...exports.WEB_E2E_WEB33_SESSION_SCENARIOS_V1,
+/**
+ * v0.3.20 — the WEB33 scenarios whose specs shipped between v0.3.13 and
+ * v0.3.15 (rail, transcript navigator, brand, files editor, resource layout)
+ * and used these ids before they were registered. The receipts' exact
+ * coverage check requires every running id to be registered exactly once:
+ * WEB33-P0-16/17/18 belong to the session-concurrency journeys, so the
+ * v0.3.13 resource-layout specs were renumbered to P0-41/42/43.
+ */
+exports.WEB_E2E_WEB33_RESOURCE_SCENARIOS_V1 = Object.freeze([
+    'WEB33-P0-13',
+    'WEB33-P0-14',
+    'WEB33-P0-15',
+    'WEB33-P0-25',
+    'WEB33-P0-26',
+    'WEB33-P0-27',
+    'WEB33-P0-28',
+    'WEB33-P0-29',
+    'WEB33-P0-30',
+    'WEB33-P0-31',
+    'WEB33-P0-32',
+    'WEB33-P0-34',
+    'WEB33-P0-41',
+    'WEB33-P0-42',
+    'WEB33-P0-43',
+]);
+/**
+ * v0.3.15 — keyboard and shell surface journeys.
+ */
+exports.WEB_E2E_WEB36_SCENARIOS_V1 = Object.freeze([
+    'WEB36-P0-01',
+    'WEB36-P1-01',
+    'WEB36-P1-02',
+    'WEB36-P1-03',
+]);
+/**
+ * v0.3.16 — transcript / workspace surface journeys.
+ */
+exports.WEB_E2E_WEB37_SCENARIOS_V1 = Object.freeze([
+    'WEB37-P0-01',
+    'WEB37-P0-02',
+    'WEB37-P0-03',
 ]);
 /**
  * v0.3.17 — LOCAL WORKSPACE open path. The picker is driven by a script file
@@ -111,6 +149,7 @@ exports.WEB_E2E_WEB38_SCENARIOS_V1 = Object.freeze([
     'WEB38-P0-03',
     'WEB38-P0-04',
     'WEB38-P0-05',
+    'WEB38-P0-06',
 ]);
 /**
  * v0.3.17 — Git right-hand work panel (`docs/plan/v0.3.17-plan.md`).
@@ -125,6 +164,11 @@ exports.WEB_E2E_WEB317_SCENARIOS_V1 = Object.freeze([
     'WEB39-P0-04',
     'WEB39-P0-05',
 ]);
+exports.WEB_E2E_WEB33_SCENARIOS_V1 = Object.freeze([
+    ...exports.WEB_E2E_WEB33_THEME_SCENARIOS_V1,
+    ...exports.WEB_E2E_WEB33_SESSION_SCENARIOS_V1,
+    ...exports.WEB_E2E_WEB33_RESOURCE_SCENARIOS_V1,
+]);
 /**
  * v0.3.19 — closing the v0.3.17 G317 assertion backlog.
  *
@@ -145,6 +189,8 @@ exports.WEB_E2E_FULL_SCENARIOS_V1 = Object.freeze([
     ...exports.WEB_E2E_WEB31_SCENARIOS_V1,
     ...exports.WEB_E2E_WEB32_SCENARIOS_V1,
     ...exports.WEB_E2E_WEB33_SCENARIOS_V1,
+    ...exports.WEB_E2E_WEB36_SCENARIOS_V1,
+    ...exports.WEB_E2E_WEB37_SCENARIOS_V1,
     ...exports.WEB_E2E_WEB38_SCENARIOS_V1,
     ...exports.WEB_E2E_WEB317_SCENARIOS_V1,
     ...exports.WEB_E2E_WEB34_SCENARIOS_V1,
@@ -358,10 +404,16 @@ function createWebE2EReleaseReceiptV1(input) {
         status: input.liveCanary === 'FAIL' ? 'fail' : 'pass',
         detail: `observed=${input.liveCanary}`,
     });
+    // v0.3.20 — the run scenario ids are sorted by the evidence assembler; the
+    // registries concatenate their per-epoch groups in delivery order, so both
+    // sides are compared as sorted sets (order-sensitive comparison against the
+    // declared order rejected runs that covered exactly the registered ids).
+    const sortedFull = [...exports.WEB_E2E_FULL_SCENARIOS_V1].sort();
+    const sortedCritical = [...exports.WEB_E2E_CRITICAL_SCENARIOS_V1].sort();
     const primaryCoverage = primaryRuns.length === 3 &&
-        primaryRuns.every(run => run.role === 'primary' && sameOrderedValues(run.scenarioIds, exports.WEB_E2E_FULL_SCENARIOS_V1));
+        primaryRuns.every(run => run.role === 'primary' && sameOrderedValues(run.scenarioIds, sortedFull));
     const runtimeCoverage = runtimeRuns.length === exports.SUPPORTED_RELEASE_NODE_MAJORS_V1.length &&
-        runtimeRuns.every(run => run.role === 'runtime' && sameOrderedValues(run.scenarioIds, exports.WEB_E2E_CRITICAL_SCENARIOS_V1));
+        runtimeRuns.every(run => run.role === 'runtime' && sameOrderedValues(run.scenarioIds, sortedCritical));
     checks.push({
         id: 'scenario_coverage',
         status: primaryCoverage && runtimeCoverage ? 'pass' : 'fail',

package/dist/services/workspace-roots-registry.d.ts

@@ -0,0 +1,46 @@
+/** Saved roots are user-authorized scan boundaries, not a project catalog. */
+export declare const MAX_WORKSPACE_ROOTS = 12;
+export interface WorkspaceRootEntryV1 {
+    readonly id: string;
+    readonly canonicalPath: string;
+    readonly label: string;
+    readonly addedAt: string;
+    readonly lastScannedAt?: string;
+}
+export interface WorkspaceRootsRegistryOptions {
+    readonly storagePath?: string;
+    readonly now?: () => Date;
+    readonly createId?: () => string;
+}
+export declare class WorkspaceRootsRegistryError extends Error {
+    readonly code: 'workspace_roots_invalid' | 'workspace_roots_capacity' | 'workspace_root_unavailable';
+    constructor(message: string, code: 'workspace_roots_invalid' | 'workspace_roots_capacity' | 'workspace_root_unavailable');
+}
+/**
+ * v0.3.21 — durable registry of user-authorized project-root directories.
+ *
+ * A root is a scan boundary the user explicitly granted through the native
+ * picker (or an explicit migration path); it is a different entity from a
+ * workspace and lives in its own versioned file so discovery can never be
+ * confused with `WorkspaceRegistryV1` (opened workspaces). Adding a root never
+ * registers a workspace, activates a Context, or touches the session catalog.
+ */
+export declare class WorkspaceRootsRegistryV1 {
+    private readonly storagePath;
+    private readonly now;
+    private readonly createId;
+    constructor(options?: WorkspaceRootsRegistryOptions);
+    list(): readonly WorkspaceRootEntryV1[];
+    find(id: string): WorkspaceRootEntryV1 | undefined;
+    /** Canonicalize, dedupe by path, cap the count, and persist atomically. */
+    add(path: string): WorkspaceRootEntryV1;
+    remove(id: string): boolean;
+    /** Record that a discovery scan completed for this root (success or partial). */
+    markScanned(id: string, scannedAt?: string): WorkspaceRootEntryV1 | undefined;
+    private readDocument;
+    private writeDocument;
+    private ensureStorageDirectory;
+}
+/** Re-exported for tests: a root must be an existing, readable directory. */
+export declare function canonicalWorkspaceRoot(path: string): string;
+//# sourceMappingURL=workspace-roots-registry.d.ts.map

package/dist/services/workspace-roots-registry.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceRootsRegistryV1 = exports.WorkspaceRootsRegistryError = exports.MAX_WORKSPACE_ROOTS = void 0;
+exports.canonicalWorkspaceRoot = canonicalWorkspaceRoot;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const paths_1 = require("../product/paths");
+const atomic_write_1 = require("./atomic-write");
+const file_lock_1 = require("./file-lock");
+const workspace_registry_1 = require("./workspace-registry");
+/** Translate the shared directory error into this registry's own code. */
+function canonicalRootPath(path) {
+    try {
+        return (0, workspace_registry_1.canonicalWorkspaceDirectory)(path);
+    }
+    catch (error) {
+        if (error instanceof workspace_registry_1.WorkspaceRegistryError) {
+            throw new WorkspaceRootsRegistryError('Workspace root directory is unavailable.', 'workspace_root_unavailable');
+        }
+        throw error;
+    }
+}
+const WORKSPACE_ROOTS_SCHEMA_VERSION = 1;
+const DEFAULT_ROOTS_FILENAME = 'workspace-roots.v1.json';
+/** Saved roots are user-authorized scan boundaries, not a project catalog. */
+exports.MAX_WORKSPACE_ROOTS = 12;
+class WorkspaceRootsRegistryError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceRootsRegistryError';
+    }
+}
+exports.WorkspaceRootsRegistryError = WorkspaceRootsRegistryError;
+/**
+ * v0.3.21 — durable registry of user-authorized project-root directories.
+ *
+ * A root is a scan boundary the user explicitly granted through the native
+ * picker (or an explicit migration path); it is a different entity from a
+ * workspace and lives in its own versioned file so discovery can never be
+ * confused with `WorkspaceRegistryV1` (opened workspaces). Adding a root never
+ * registers a workspace, activates a Context, or touches the session catalog.
+ */
+class WorkspaceRootsRegistryV1 {
+    constructor(options = {}) {
+        this.storagePath = options.storagePath ?? (0, path_1.join)((0, paths_1.getConfigHome)(), DEFAULT_ROOTS_FILENAME);
+        this.now = options.now ?? (() => new Date());
+        this.createId = options.createId ?? crypto_1.randomUUID;
+    }
+    list() {
+        return freezeEntries(this.readDocument().entries);
+    }
+    find(id) {
+        return this.readDocument().entries.find(entry => entry.id === id);
+    }
+    /** Canonicalize, dedupe by path, cap the count, and persist atomically. */
+    add(path) {
+        const canonicalPath = canonicalRootPath(path);
+        this.ensureStorageDirectory();
+        return (0, file_lock_1.withFileLockSync)(this.storagePath, () => {
+            const document = this.readDocument();
+            const existing = document.entries.find(entry => entry.canonicalPath === canonicalPath);
+            if (existing)
+                return existing;
+            if (document.entries.length >= exports.MAX_WORKSPACE_ROOTS) {
+                throw new WorkspaceRootsRegistryError(`Workspace roots registry cannot contain more than ${exports.MAX_WORKSPACE_ROOTS} entries.`, 'workspace_roots_capacity');
+            }
+            const now = this.now().toISOString();
+            const entry = Object.freeze({
+                id: this.createId(),
+                canonicalPath,
+                label: workspaceRootLabel(canonicalPath),
+                addedAt: now,
+            });
+            this.writeDocument([...document.entries, entry]);
+            return entry;
+        });
+    }
+    remove(id) {
+        this.ensureStorageDirectory();
+        return (0, file_lock_1.withFileLockSync)(this.storagePath, () => {
+            const document = this.readDocument();
+            const entries = document.entries.filter(entry => entry.id !== id);
+            if (entries.length === document.entries.length)
+                return false;
+            this.writeDocument(entries);
+            return true;
+        });
+    }
+    /** Record that a discovery scan completed for this root (success or partial). */
+    markScanned(id, scannedAt) {
+        this.ensureStorageDirectory();
+        const at = (scannedAt ?? this.now().toISOString()).trim();
+        return (0, file_lock_1.withFileLockSync)(this.storagePath, () => {
+            const document = this.readDocument();
+            const target = document.entries.find(entry => entry.id === id);
+            if (!target)
+                return undefined;
+            const updated = Object.freeze({
+                ...target,
+                lastScannedAt: Number.isFinite(Date.parse(at)) ? new Date(at).toISOString() : at,
+            });
+            this.writeDocument(document.entries.map(entry => (entry.id === id ? updated : entry)));
+            return updated;
+        });
+    }
+    readDocument() {
+        if (!(0, fs_1.existsSync)(this.storagePath)) {
+            return Object.freeze({ schemaVersion: WORKSPACE_ROOTS_SCHEMA_VERSION, entries: [] });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse((0, fs_1.readFileSync)(this.storagePath, 'utf8'));
+        }
+        catch {
+            throw new WorkspaceRootsRegistryError('Workspace roots registry is not valid JSON.', 'workspace_roots_invalid');
+        }
+        return parseDocument(parsed);
+    }
+    writeDocument(entries) {
+        this.ensureStorageDirectory();
+        const normalized = [...entries]
+            .sort((left, right) => Date.parse(right.addedAt) - Date.parse(left.addedAt) ||
+            left.label.localeCompare(right.label) ||
+            left.id.localeCompare(right.id))
+            .map(entry => ({ ...entry }));
+        (0, atomic_write_1.atomicWriteFileSync)(this.storagePath, `${JSON.stringify({ schemaVersion: WORKSPACE_ROOTS_SCHEMA_VERSION, entries: normalized }, null, 2)}\n`, { mode: 0o600, fsync: true });
+    }
+    ensureStorageDirectory() {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(this.storagePath), { recursive: true, mode: 0o700 });
+    }
+}
+exports.WorkspaceRootsRegistryV1 = WorkspaceRootsRegistryV1;
+function parseDocument(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalidDocument();
+    const row = value;
+    if (row.schemaVersion !== WORKSPACE_ROOTS_SCHEMA_VERSION || !Array.isArray(row.entries)) {
+        return invalidDocument();
+    }
+    if (row.entries.length > exports.MAX_WORKSPACE_ROOTS)
+        return invalidDocument();
+    const entries = row.entries.map(parseEntry);
+    if (new Set(entries.map(entry => entry.id)).size !== entries.length ||
+        new Set(entries.map(entry => entry.canonicalPath)).size !== entries.length) {
+        return invalidDocument();
+    }
+    return Object.freeze({
+        schemaVersion: WORKSPACE_ROOTS_SCHEMA_VERSION,
+        entries: freezeEntries(entries),
+    });
+}
+function parseEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalidDocument();
+    const row = value;
+    if (typeof row.id !== 'string' ||
+        !row.id.trim() ||
+        row.id.length > 128 ||
+        typeof row.canonicalPath !== 'string' ||
+        !row.canonicalPath.trim() ||
+        typeof row.label !== 'string' ||
+        !row.label.trim() ||
+        typeof row.addedAt !== 'string' ||
+        !Number.isFinite(Date.parse(row.addedAt)) ||
+        (row.lastScannedAt !== undefined &&
+            (typeof row.lastScannedAt !== 'string' || !Number.isFinite(Date.parse(row.lastScannedAt))))) {
+        return invalidDocument();
+    }
+    return Object.freeze({
+        id: row.id,
+        canonicalPath: row.canonicalPath,
+        label: row.label,
+        addedAt: row.addedAt,
+        ...(row.lastScannedAt !== undefined ? { lastScannedAt: row.lastScannedAt } : {}),
+    });
+}
+function invalidDocument() {
+    throw new WorkspaceRootsRegistryError('Workspace roots registry document is invalid.', 'workspace_roots_invalid');
+}
+function freezeEntries(entries) {
+    return Object.freeze([...entries]
+        .sort((left, right) => Date.parse(right.addedAt) - Date.parse(left.addedAt) ||
+        left.label.localeCompare(right.label) ||
+        left.id.localeCompare(right.id))
+        .map(entry => Object.freeze({ ...entry })));
+}
+function workspaceRootLabel(path) {
+    const normalized = path.replace(/[\\/]+$/u, '');
+    return normalized.split(/[\\/]/u).filter(Boolean).at(-1) ?? normalized;
+}
+/** Re-exported for tests: a root must be an existing, readable directory. */
+function canonicalWorkspaceRoot(path) {
+    const canonical = (0, workspace_registry_1.canonicalWorkspaceDirectory)(path);
+    (0, fs_1.statSync)(canonical);
+    return canonical;
+}
+//# sourceMappingURL=workspace-roots-registry.js.map

package/dist/web/protocol.d.ts

@@ -419,6 +419,42 @@ export interface WebWorkspaceInspectRequestV1 {
     readonly path: string;
     readonly source?: WebWorkspaceCandidateSourceV1;
 }
+export type WebWorkspaceRootDiscoveryHintV1 = 'git' | 'manifest';
+export interface WebWorkspaceRootEntryV1 {
+    readonly id: string;
+    readonly canonicalPath: string;
+    readonly label: string;
+    readonly addedAt: string;
+    readonly lastScannedAt?: string;
+}
+export interface WebWorkspaceRootDiscoveryStatusV1 {
+    readonly status: 'ready' | 'partial';
+    readonly candidateCount: number;
+    readonly durationMs: number;
+    readonly errorCode?: string;
+    readonly cached: boolean;
+}
+export interface WebWorkspaceRootViewV1 extends WebWorkspaceRootEntryV1 {
+    /** The cached outcome of the most recent scan, when one is still fresh. */
+    readonly discovery: WebWorkspaceRootDiscoveryStatusV1 | null;
+}
+export interface WebWorkspaceRootCandidateV1 {
+    readonly rootId: string;
+    readonly relativePath: string;
+    readonly label: string;
+    readonly hint: WebWorkspaceRootDiscoveryHintV1;
+    readonly status: 'ready' | 'partial';
+}
+export interface WebWorkspaceRootDiscoverOutcomeV1 {
+    readonly requestId?: string;
+    readonly rootId: string;
+    readonly status: 'ready' | 'partial';
+    readonly candidates: readonly WebWorkspaceRootCandidateV1[];
+    readonly errorCode?: string;
+    readonly durationMs: number;
+    readonly scannedEntries: number;
+    readonly lastScannedAt?: string;
+}
 export type WebWorkspaceInvalidationReasonV1 = 'context-change' | 'filesystem-change' | 'terminal-command' | 'tool-finished';
 export type WebToolDetailSummaryV1 = ToolDetailSummary;
 export type WebToolDetailPageV1 = ToolDetailPage;

package/dist/web/server.js

@@ -300,6 +300,51 @@ async function handleRequest(context) {
         sendJson(response, 200, { requestId, candidate });
         return;
     }
+    // v0.3.21 — saved project roots: read-only list. Roots are scan boundaries,
+    // not workspaces; listing them changes nothing.
+    if (method === 'GET' && path === '/workspaces/roots') {
+        sendJson(response, 200, { roots: context.workbench.listWorkspaceRoots() });
+        return;
+    }
+    // v0.3.21 — add a root through the native picker's confirmed path. A local
+    // configuration mutation: transport-guarded, naturally idempotent (roots
+    // dedupe by canonical path), and never a Context mutation.
+    if (method === 'POST' && path === '/workspaces/roots/add') {
+        assertMutation(request, context.nonce, context.origin);
+        const body = requireRecord(await readJson(request), 'Workspace root request');
+        assertOnlyKeys(body, ['requestId', 'path']);
+        const requestId = requireUuid(body.requestId, 'requestId');
+        const rootPath = requireText(body.path, 'path', 4096);
+        const root = await context.workbench.addWorkspaceRoot(rootPath, requestId);
+        sendJson(response, 200, { requestId, root });
+        return;
+    }
+    // v0.3.21 — remove a root. Cancels any in-flight scan for it first; the
+    // workspaces registry is untouched.
+    if (method === 'POST' && path === '/workspaces/roots/remove') {
+        assertMutation(request, context.nonce, context.origin);
+        const body = requireRecord(await readJson(request), 'Workspace root request');
+        assertOnlyKeys(body, ['requestId', 'rootId']);
+        const requestId = requireUuid(body.requestId, 'requestId');
+        const rootId = requireText(body.rootId, 'rootId', 128);
+        const removed = context.workbench.removeWorkspaceRoot(rootId);
+        sendJson(response, 200, { requestId, removed });
+        return;
+    }
+    // v0.3.21 — bounded discovery inside one saved root. Read-only, abortable,
+    // host-wide single-flight; the newest request aborts the previous scan. A
+    // candidate is a hint: the client still runs inspect → confirm → activate.
+    if (method === 'POST' && path === '/workspaces/roots/discover') {
+        assertMutation(request, context.nonce, context.origin);
+        const body = requireRecord(await readJson(request), 'Workspace discovery request');
+        assertOnlyKeys(body, ['requestId', 'rootId', 'refresh']);
+        const requestId = requireUuid(body.requestId, 'requestId');
+        const rootId = requireText(body.rootId, 'rootId', 128);
+        const refresh = body.refresh === undefined ? true : body.refresh === true;
+        const outcome = await context.workbench.discoverWorkspaceRoot(rootId, requestId, { refresh });
+        sendJson(response, 200, outcome);
+        return;
+    }
     if (method === 'GET' && path === '/sessions') {
         const contextGuard = requireContextGuardQuery(url);
         sendJson(response, 200, collectionPage(url, 'sessions', context.workbench.listSessions(contextGuard), session => session.id));