@orion-agents/orion-code 0.3.20 → 0.3.21

package/CHANGELOG.md

@@ -22,12 +22,30 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.20]
+## [0.3.21] — 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. 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)
 >

package/README.md

@@ -2,10 +2,10 @@
 
 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.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) ·
@@ -170,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.20
+npm install -g @orion-agents/orion-code@0.3.21
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,9 +2,9 @@
 
 面向终端与浏览器、本地优先的目标驱动 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.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) ·
@@ -101,7 +101,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.21
 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/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[];

package/dist/web/workbench-controller.js

@@ -34,6 +34,8 @@ const workspace_mutation_arbiter_1 = require("./workspace-mutation-arbiter");
 const protocol_1 = require("./protocol");
 const native_directory_picker_1 = require("./native-directory-picker");
 const workspace_open_telemetry_1 = require("./workspace-open-telemetry");
+const workspace_discovery_1 = require("./workspace-discovery");
+const workspace_roots_registry_1 = require("../services/workspace-roots-registry");
 const review_service_1 = require("./review-service");
 const session_runtime_registry_1 = require("./session-runtime-registry");
 const terminal_manager_1 = require("./terminal-manager");
@@ -58,6 +60,11 @@ class WebWorkbenchController {
         this.pickerInFlight = false;
         /** v0.3.17 — bounded, path-free open-path traces exposed through diagnostics(). */
         this.openTelemetry = new workspace_open_telemetry_1.WorkspaceOpenTelemetryV1();
+        /**
+         * 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.
+         */
+        this.discoveryInflight = new Map();
         this.mutationResults = new Map();
         this.sessionViews = new Map();
         this.sessionViewBytes = 0;
@@ -93,6 +100,11 @@ class WebWorkbenchController {
             onStateChanged: state => this.emitWorkspaceMutationState(state),
         });
         this.workspaceRegistry = options.workspaceRegistry ?? new workspace_registry_1.WorkspaceRegistryV1();
+        this.workspaceRootsRegistry = options.workspaceRootsRegistry ?? new workspace_roots_registry_1.WorkspaceRootsRegistryV1();
+        this.discoveryTelemetry = options.discoveryTelemetry ?? new workspace_discovery_1.WorkspaceDiscoveryTelemetryV1();
+        this.discoveryService = new workspace_discovery_1.WorkspaceDiscoveryServiceV1({
+            telemetry: this.discoveryTelemetry,
+        });
         this.directoryPicker = options.nativeDirectoryPicker ?? (0, native_directory_picker_1.createNativeDirectoryPicker)();
         this.terminalManager = new terminal_manager_1.TerminalManagerV1({
             resolveWorkspace: workspaceId => this.workspaceRegistry.find(workspaceId)?.canonicalPath,
@@ -317,6 +329,98 @@ class WebWorkbenchController {
         }
         return candidate;
     }
+    // ---------------------------------------------------------------------
+    // v0.3.21 — user-authorized project roots and bounded discovery.
+    //
+    // Roots are scan boundaries, not workspaces: nothing here registers a
+    // workspace, activates a Context, installs a Runtime, or reads file
+    // contents. A discovered candidate is a hint; the client must still run the
+    // existing POST /workspaces/inspect → confirm → activate flow.
+    // ---------------------------------------------------------------------
+    listWorkspaceRoots() {
+        return this.workspaceRootsRegistry.list().map(entry => {
+            const cached = this.discoveryService.cached(entry.id);
+            return Object.freeze({
+                ...entry,
+                discovery: cached
+                    ? Object.freeze({
+                        status: cached.status,
+                        candidateCount: cached.candidates.length,
+                        durationMs: cached.durationMs,
+                        ...(cached.errorCode ? { errorCode: cached.errorCode } : {}),
+                        cached: true,
+                    })
+                    : null,
+            });
+        });
+    }
+    async addWorkspaceRoot(path, requestId) {
+        if (this.closed) {
+            throw new errors_1.WebWorkbenchError(503, 'The local Web Host is shutting down.', 'host_closed');
+        }
+        const entry = this.workspaceRootsRegistry.add(path);
+        void requestId;
+        const view = this.listWorkspaceRoots().find(root => root.id === entry.id);
+        if (!view)
+            throw new errors_1.WebWorkbenchError(500, 'Workspace root vanished after add.', 'scan_failed');
+        return view;
+    }
+    removeWorkspaceRoot(rootId) {
+        // Cancelling first: a removed root must never receive a late scan result.
+        const inflight = this.discoveryInflight.get(rootId);
+        if (inflight) {
+            inflight.controller.abort();
+            this.discoveryInflight.delete(rootId);
+        }
+        this.discoveryService.invalidate(rootId);
+        return this.workspaceRootsRegistry.remove(rootId);
+    }
+    async discoverWorkspaceRoot(rootId, requestId, options = {}) {
+        if (this.closed) {
+            throw new errors_1.WebWorkbenchError(503, 'The local Web Host is shutting down.', 'host_closed');
+        }
+        const entry = this.workspaceRootsRegistry.find(rootId);
+        if (!entry) {
+            throw new errors_1.WebWorkbenchError(404, 'Workspace root is not registered.', 'root_missing');
+        }
+        // Global single-flight: the newest discover request wins; the previous
+        // scan is aborted and reports scan_cancelled.
+        for (const [id, inflight] of this.discoveryInflight) {
+            inflight.controller.abort();
+            this.discoveryInflight.delete(id);
+        }
+        if (!options.refresh) {
+            const cached = this.discoveryService.cached(rootId);
+            if (cached)
+                return this.toDiscoverOutcome(cached, entry.lastScannedAt, requestId);
+        }
+        const controller = new AbortController();
+        const promise = this.discoveryService.discover({ root: entry, signal: controller.signal });
+        this.discoveryInflight.set(rootId, { controller, promise });
+        let outcome;
+        try {
+            outcome = await promise;
+        }
+        finally {
+            const current = this.discoveryInflight.get(rootId);
+            if (current && current.promise === promise)
+                this.discoveryInflight.delete(rootId);
+        }
+        const scanned = this.workspaceRootsRegistry.markScanned(rootId);
+        return this.toDiscoverOutcome(outcome, scanned?.lastScannedAt, requestId);
+    }
+    toDiscoverOutcome(outcome, lastScannedAt, requestId) {
+        return Object.freeze({
+            ...(requestId ? { requestId } : {}),
+            rootId: outcome.rootId,
+            status: outcome.status,
+            candidates: outcome.candidates,
+            ...(outcome.errorCode ? { errorCode: outcome.errorCode } : {}),
+            durationMs: outcome.durationMs,
+            scannedEntries: outcome.scannedEntries,
+            ...(lastScannedAt ? { lastScannedAt } : {}),
+        });
+    }
     listWorkspaceSessions(workspaceId, context) {
         if (context)
             this.assertContextGuard(context);
@@ -1766,6 +1870,9 @@ class WebWorkbenchController {
             workspaceKernel: this.runtimeValue.workspaceRuntimeKernel?.diagnostics() ?? null,
             // v0.3.17 — bounded, path-free open-path traces (picker / inspect / activate).
             workspaceOpen: this.openTelemetry.snapshot(),
+            // v0.3.21 — bounded, path-free discovery traces (scan duration, counts,
+            // error codes). Never a root path, a label, a marker name, or content.
+            workspaceDiscovery: this.discoveryTelemetry.snapshot(),
             session: {
                 ...this.sessionActivity,
                 actors: this.sessionRegistry.stats(),