@orion-agents/orion-code 0.3.20 → 0.3.22

package/CHANGELOG.md

@@ -22,12 +22,44 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.20]
+## [0.3.22] — UNRELEASED
 
-> **Status: candidate.** Open. 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. Not merged, tagged or
-> published.
+> **Status: candidate.** Open. Agent Reliability & Efficiency — hardens ToolGateway
+> in-flight request identity (T22-01), adds the durability fault-injection matrix (T22-02),
+> the four-state release verification gate (T22-03), and a real coding-task evaluation
+> harness (T22-04). Plan: `docs/plan/v0.3.22-plan.md`. Not merged, tagged or published.
+
+### Fixed (product)
+
+- ToolGateway in-flight dedupe now compares the full request digest: the same invocationId
+  with different arguments, tool, snapshot, or parent conflicts
+  (`ORION_TOOL_INVOCATION_CONFLICT`) instead of reusing the running execution's promise.
+
+## [0.3.21] — 2026-10-09
+
+> **Status: published.** Released as `@orion-agents/orion-code@0.3.21` from
+> `refs/tags/v0.3.21`, and merged to `main` as `0d22c9a` (#264). 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`).
+
+### 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)
 >

package/README.md

@@ -2,10 +2,9 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.20 candidate — open. The v0.3.19 round found that the Web E2E suite has been red
-> since v0.3.11 (the dock's tabs became rail buttons), independently of the Git panel work;
-> repairing those specs is this cycle's intended content.
-> 0.3.19 is published to npm and tagged `v0.3.19`; 0.3.20 is not.
+> v0.3.22 candidate — open. Hardens agent reliability (ToolGateway in-flight request
+> identity) and builds a real coding-task evaluation harness. The previous release 0.3.21
+> is on npm (registry `latest`) and tagged `v0.3.21` (`0d22c9a`, #264).
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.7 plan](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -170,7 +169,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.20
+npm install -g @orion-agents/orion-code@0.3.22
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,9 +2,8 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.20 候选版本：进行中。v0.3.19 那轮验证发现 Web E2E 套件自 v0.3.11（停靠栏 tab 改为
-> rail 按钮）起就与产品脱节，与 Git 工作栏的工作无关；修好这些 spec 是本周期的目标。
-> 0.3.19 已发布 npm 并打 tag `v0.3.19`，0.3.20 尚未发布。
+> v0.3.22 候选版本：进行中。强化 Agent 可靠性（ToolGateway 执行中请求身份）并建设真实编码
+> 任务评测体系。上一版 0.3.21 已发布 npm（registry `latest`）并打 tag `v0.3.21`（`0d22c9a`，#264）。
 
 [English](README.md) ·
 [v0.3.7 方案](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -101,7 +100,7 @@ Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 当 npm 已存在不可变的 `0.3.4` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.20
+npm install -g @orion-agents/orion-code@0.3.22
 orion --version
 orion doctor
 ```

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

@@ -29,7 +29,7 @@ export declare const WEB_E2E_WEB37_SCENARIOS_V1: readonly ["WEB37-P0-01", "WEB37
  * 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`).
  *

package/dist/runtime/release-receipts.js

@@ -149,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`).

package/dist/runtime/tool-gateway.d.ts

@@ -140,6 +140,12 @@ export declare class ToolGatewayError extends Error {
 /** Capability → Policy → Approval → Sandbox → Execute → durable terminal receipt. */
 export declare class ToolGateway {
     private readonly services;
+    /**
+     * v0.3.22 T22-01 — in-flight entries carry the full request digest so the
+     * same invocationId with different arguments, tool, snapshot, or parent
+     * conflicts instead of silently reusing the first execution's promise
+     * (matching the durable journal's guard strength).
+     */
     private readonly inflight;
     private readonly clock;
     constructor(services: ToolGatewayServicesV1);

package/dist/runtime/tool-gateway.js

@@ -19,16 +19,38 @@ exports.ToolGatewayError = ToolGatewayError;
 class ToolGateway {
     constructor(services) {
         this.services = services;
+        /**
+         * v0.3.22 T22-01 — in-flight entries carry the full request digest so the
+         * same invocationId with different arguments, tool, snapshot, or parent
+         * conflicts instead of silently reusing the first execution's promise
+         * (matching the durable journal's guard strength).
+         */
         this.inflight = new Map();
         this.clock = services.clock ?? Date.now;
     }
     invoke(invocation) {
+        const requestDigest = computeRequestDigest(invocation);
         const existing = this.inflight.get(invocation.invocationId);
-        if (existing)
-            return existing;
-        const run = this.invokeOnce(invocation).finally(() => this.inflight.delete(invocation.invocationId));
-        this.inflight.set(invocation.invocationId, run);
-        return run;
+        if (existing) {
+            if (existing.requestDigest !== requestDigest) {
+                // Reject (rather than throw synchronously) so callers awaiting the
+                // invocation observe the conflict through the same promise channel as
+                // the durable-journal conflict.
+                return Promise.reject(new ToolGatewayError('ORION_TOOL_INVOCATION_CONFLICT', 'Invocation ID is already executing with different arguments or snapshot', invocation.invocationId));
+            }
+            return existing.promise;
+        }
+        const promise = this.invokeOnce(invocation).finally(() => {
+            // Remove only our own entry: the guard keeps a defensive barrier against
+            // deleting an entry created by a later invocation after this run
+            // finished.
+            const current = this.inflight.get(invocation.invocationId);
+            if (current && current.requestDigest === requestDigest) {
+                this.inflight.delete(invocation.invocationId);
+            }
+        });
+        this.inflight.set(invocation.invocationId, { requestDigest, promise });
+        return promise;
     }
     async invokeOnce(invocation) {
         validateInvocation(invocation);
@@ -237,8 +259,13 @@ function createStaticApprovalDecisionV1(input) {
 function createSandboxPreparationV1(input) {
     return deepFreeze({ ...input, digest: (0, canonical_1.digestRuntimeValue)(input) });
 }
-function createIntent(invocation, startedAt) {
-    const requestDigest = (0, canonical_1.digestRuntimeValue)({
+/**
+ * v0.3.22 T22-01 — the authoritative request identity, shared by the durable
+ * intent and the in-flight dedupe map. Excludes startedAt so identity stays
+ * stable across retries within one execution.
+ */
+function computeRequestDigest(invocation) {
+    return (0, canonical_1.digestRuntimeValue)({
         invocationId: invocation.invocationId,
         parentInvocationId: invocation.parentInvocationId,
         threadId: invocation.snapshot.threadId,
@@ -248,6 +275,9 @@ function createIntent(invocation, startedAt) {
         snapshotDigest: invocation.snapshot.digest,
         argsDigest: (0, canonical_1.digestRuntimeValue)(invocation.args),
     });
+}
+function createIntent(invocation, startedAt) {
+    const requestDigest = computeRequestDigest(invocation);
     const content = {
         version: 1,
         invocationId: invocation.invocationId,

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));

package/dist/web/workbench-controller.d.ts

@@ -6,8 +6,10 @@ import { WorkspaceRegistryV1 } from '../services/workspace-registry';
 import { WebEventHub } from './event-hub';
 import { FileReadServiceV1 } from './file-read-service';
 import { GitReadModelServiceV1 } from './git-read-model-service';
-import { type WebComposerActionResultV1, type WebComposerActionV1, type WebComposerControlStateV1, type WebBootstrapV1, type WebCommandResultV1, type WebContextActivateRequestV1, type WebContextGuardV1, type WebMcpServerSummaryV1, type WebPageV1, type WebSessionSnapshotV1, type WebSessionSummaryV1, type WebSettingsMutationResultV1, type WebSettingsSnapshotV1, type WebSettingsUpdateRequestV1, type WebSkillSummaryV1, type WebToolDetailPageV1, type WebToolDetailSummaryV1, type WebWorkspaceSummaryV1, type WebWorkspaceProjectSummaryV1, type WebWorkspaceCandidateSourceV1, type WebWorkspaceCandidateV1 } from './protocol';
+import { type WebComposerActionResultV1, type WebComposerActionV1, type WebComposerControlStateV1, type WebBootstrapV1, type WebCommandResultV1, type WebContextActivateRequestV1, type WebContextGuardV1, type WebMcpServerSummaryV1, type WebPageV1, type WebSessionSnapshotV1, type WebSessionSummaryV1, type WebSettingsMutationResultV1, type WebSettingsSnapshotV1, type WebSettingsUpdateRequestV1, type WebSkillSummaryV1, type WebToolDetailPageV1, type WebToolDetailSummaryV1, type WebWorkspaceSummaryV1, type WebWorkspaceProjectSummaryV1, type WebWorkspaceCandidateSourceV1, type WebWorkspaceCandidateV1, type WebWorkspaceRootViewV1, type WebWorkspaceRootDiscoverOutcomeV1 } from './protocol';
 import { type NativeDirectoryPickResult, type NativeDirectoryPicker } from './native-directory-picker';
+import { WorkspaceDiscoveryTelemetryV1 } from './workspace-discovery';
+import { WorkspaceRootsRegistryV1 } from '../services/workspace-roots-registry';
 import { type WebSessionRuntimeSummaryV1 } from './session-runtime-registry';
 import { TerminalManagerV1 } from './terminal-manager';
 export { WebWorkbenchError } from './errors';
@@ -17,6 +19,10 @@ export interface WebWorkbenchControllerOptions {
     readonly createRuntime?: (cwd: string) => Promise<OrionCodeUiRuntime>;
     readonly createSessionRuntime?: (cwd: string) => Promise<OrionCodeUiRuntime>;
     readonly workspaceRegistry?: WorkspaceRegistryV1;
+    /** v0.3.21 — user-authorized scan boundaries; injectable for tests. */
+    readonly workspaceRootsRegistry?: WorkspaceRootsRegistryV1;
+    /** v0.3.21 — injectable discovery telemetry for tests. */
+    readonly discoveryTelemetry?: WorkspaceDiscoveryTelemetryV1;
     /** v0.3.16 — Host native directory picker; injectable for tests. */
     readonly nativeDirectoryPicker?: NativeDirectoryPicker;
 }
@@ -44,6 +50,14 @@ export declare class WebWorkbenchController {
     private pickerInFlight;
     /** v0.3.17 — bounded, path-free open-path traces exposed through diagnostics(). */
     private readonly openTelemetry;
+    private readonly workspaceRootsRegistry;
+    private readonly discoveryTelemetry;
+    private readonly discoveryService;
+    /**
+     * v0.3.21 — global discovery single-flight: at most one scan runs per Host;
+     * a new discover request aborts the previous one (scan_cancelled) and wins.
+     */
+    private readonly discoveryInflight;
     readonly terminalManager: TerminalManagerV1;
     private readonly mutationResults;
     private readonly sessionViews;
@@ -111,6 +125,13 @@ export declare class WebWorkbenchController {
      * file contents, or touches the session catalog beyond a warm-cache peek.
      */
     inspectWorkspaceFast(path: string, source?: WebWorkspaceCandidateSourceV1, requestId?: string): Promise<WebWorkspaceCandidateV1>;
+    listWorkspaceRoots(): readonly WebWorkspaceRootViewV1[];
+    addWorkspaceRoot(path: string, requestId?: string): Promise<WebWorkspaceRootViewV1>;
+    removeWorkspaceRoot(rootId: string): boolean;
+    discoverWorkspaceRoot(rootId: string, requestId?: string, options?: {
+        readonly refresh?: boolean;
+    }): Promise<WebWorkspaceRootDiscoverOutcomeV1>;
+    private toDiscoverOutcome;
     listWorkspaceSessions(workspaceId: string, context?: WebContextGuardV1): readonly WebSessionSummaryV1[];
     /** Archived sessions of a Workspace (v0.3.7), newest archive first. */
     listArchivedWorkspaceSessions(workspaceId: string, context?: WebContextGuardV1): readonly WebSessionSummaryV1[];