@orion-agents/orion-code 0.3.15 → 0.3.18

package/dist/web/git-version-service.d.ts

@@ -0,0 +1,71 @@
+export type GitVersionLabelV1 = 'base' | 'ours' | 'theirs' | 'worktree' | 'revision';
+export interface GitFileVersionV1 {
+    readonly label: GitVersionLabelV1;
+    /** The blob OID, or null when this version does not exist for this conflict shape. */
+    readonly oid: string | null;
+    readonly exists: boolean;
+    readonly binary: boolean;
+    readonly byteSize: number;
+    readonly truncated: boolean;
+    /** Text content, or null when absent, binary or over the limit. */
+    readonly content: string | null;
+    /**
+     * Set when the content is an LFS pointer: the pointer is shown as state, and the object is
+     * never fetched.
+     */
+    readonly lfs: {
+        readonly oid: string;
+        readonly size: number | null;
+    } | null;
+    /**
+     * v0.3.17 S6 — a renderable data URL when this version is a bounded, known image.
+     * Built from bytes already read locally; the plan forbids fetching anything.
+     */
+    readonly dataUrl?: string | null;
+}
+export type GitConflictShapeV1 = 'both-modified' | 'both-added' | 'added-by-us' | 'added-by-them' | 'deleted-by-us' | 'deleted-by-them' | 'both-deleted' | 'other';
+export interface GitConflictVersionsV1 {
+    readonly path: string;
+    readonly shape: GitConflictShapeV1;
+    readonly base: GitFileVersionV1;
+    readonly ours: GitFileVersionV1;
+    readonly theirs: GitFileVersionV1;
+    readonly worktree: GitFileVersionV1;
+}
+export interface GitBlobResultV1 {
+    readonly path: string;
+    readonly rev: string;
+    readonly oid: string;
+    readonly binary: boolean;
+    readonly byteSize: number;
+    readonly truncated: boolean;
+    readonly content: readonly string[];
+    readonly lfs: {
+        readonly oid: string;
+        readonly size: number | null;
+    } | null;
+    /** Present only when the blob is a bounded, known image. */
+    readonly dataUrl: string | null;
+}
+export interface GitSubmoduleEntryV1 {
+    readonly path: string;
+    readonly gitlinkOid: string;
+    /** Never inspected: plan G6 forbids traversing submodules to compute this. */
+    readonly dirtySummary: null;
+    readonly dirtyNote: string;
+}
+export interface GitVersionReader {
+    conflict(path: string): Promise<GitConflictVersionsV1>;
+    blob(input: {
+        readonly path: string;
+        readonly rev: string;
+    }): Promise<GitBlobResultV1>;
+    submodules(): Promise<readonly GitSubmoduleEntryV1[]>;
+}
+export interface GitVersionReaderOptions {
+    readonly runGit: (args: readonly string[]) => Promise<string>;
+    /** Runs git and returns raw bytes, for content that may not be valid UTF-8. */
+    readonly runGitBytes: (args: readonly string[]) => Promise<Buffer>;
+}
+export declare function createGitVersionReader(options: GitVersionReaderOptions): GitVersionReader;
+//# sourceMappingURL=git-version-service.d.ts.map

package/dist/web/git-version-service.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGitVersionReader = createGitVersionReader;
+/**
+ * v0.3.17 S5 — historical file versions: conflict stages, arbitrary-revision blobs, LFS
+ * pointer state and gitlink (submodule) entries.
+ *
+ * Plan G5/G6 constraints this module is responsible for:
+ *   - a conflicted file must NOT be rendered as an ordinary staged diff: base / ours / theirs
+ *     come from index stages 1/2/3, and a version that legitimately does not exist (add/add,
+ *     modify/delete) is reported as absent rather than silently omitted;
+ *   - a file that no longer exists in the working tree can still be read at a revision
+ *     ("view that version");
+ *   - LFS only reads local objects or reports pointer state — nothing is fetched;
+ *   - submodules are never traversed or switched: only the recorded gitlink SHAs are read, and
+ *     the dirty summary is explicitly reported as not inspected.
+ */
+const redaction_1 = require("../services/redaction");
+const errors_1 = require("./errors");
+/** Upper bound on the bytes returned for one file version. */
+const MAX_VERSION_BYTES = 256 * 1024;
+/** Bytes inspected when deciding whether a file is an LFS pointer. */
+const LFS_PROBE_BYTES = 512;
+function assertRelativePath(value, name = 'path') {
+    if (typeof value !== 'string' || !value || value.length > 1024) {
+        throw new errors_1.WebWorkbenchError(400, `A ${name} is required.`, 'git_path_invalid');
+    }
+    if (value.startsWith('/') || value.startsWith(':') || value.includes('\0')) {
+        throw new errors_1.WebWorkbenchError(400, 'Unsafe Git path.', 'git_path_unsafe');
+    }
+    if (value.split('/').some(segment => segment === '..' || segment === '.' || segment === '')) {
+        throw new errors_1.WebWorkbenchError(400, 'Unsafe Git path.', 'git_path_unsafe');
+    }
+    return value;
+}
+function assertRev(value) {
+    // A revision expression here would be an injection surface; a plain ref or hash is enough.
+    if (typeof value !== 'string' || !/^[0-9A-Za-z][0-9A-Za-z._/-]{0,250}$/u.test(value)) {
+        throw new errors_1.WebWorkbenchError(400, 'rev must be a ref name or commit hash.', 'git_ref_invalid');
+    }
+    if (value.includes('..')) {
+        throw new errors_1.WebWorkbenchError(400, 'rev must be a ref name or commit hash.', 'git_ref_invalid');
+    }
+    return value;
+}
+/**
+ * Recognises the image formats the browser can render from a data URL, by magic bytes —
+ * never by extension, which is user-controlled and proves nothing.
+ */
+const IMAGE_SIGNATURES = Object.freeze([
+    { offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], mime: 'image/png' },
+    { offset: 0, bytes: [0xff, 0xd8, 0xff], mime: 'image/jpeg' },
+    { offset: 0, bytes: [0x47, 0x49, 0x46, 0x38], mime: 'image/gif' },
+    { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46], mime: 'image/webp' },
+]);
+/** Largest image that may be inlined as a data URL (bounded, and nothing is fetched). */
+const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+/**
+ * Returns a renderable data URL when the bytes are a known image, so the UI can show the
+ * two versions of a picture side by side. The bytes were already read locally — the plan
+ * forbids fetching anything.
+ */
+function imageDataUrl(bytes) {
+    for (const signature of IMAGE_SIGNATURES) {
+        if (bytes.length < signature.offset + signature.bytes.length)
+            continue;
+        const matches = signature.bytes.every((byte, index) => bytes[signature.offset + index] === byte);
+        if (matches) {
+            return `data:${signature.mime};base64,${bytes.toString('base64')}`;
+        }
+    }
+    return null;
+}
+/** Detects an LFS pointer and extracts its state. Never fetches anything. */
+function parseLfsPointer(head) {
+    if (!head.startsWith('version https://git-lfs.github.com/spec/'))
+        return null;
+    const oidMatch = /^oid sha256:([0-9a-f]{64})$/mu.exec(head);
+    if (!oidMatch)
+        return null;
+    const sizeMatch = /^size (\d+)$/mu.exec(head);
+    return Object.freeze({
+        oid: oidMatch[1],
+        size: sizeMatch ? Number(sizeMatch[1]) : null,
+    });
+}
+function createGitVersionReader(options) {
+    const { runGit, runGitBytes } = options;
+    /**
+     * Reads one blob by OID, bounded, with binary and LFS detection.
+     *
+     * The size is read first so an enormous historical file is reported by its size instead of
+     * being pulled into memory just to be truncated.
+     */
+    const readVersion = async (label, oid) => {
+        if (oid === null) {
+            return Object.freeze({
+                label,
+                oid: null,
+                exists: false,
+                binary: false,
+                byteSize: 0,
+                truncated: false,
+                content: null,
+                lfs: null,
+            });
+        }
+        const sizeRaw = (await runGit(['cat-file', '-s', oid])).trim();
+        const byteSize = Number(sizeRaw) || 0;
+        if (byteSize > MAX_VERSION_BYTES) {
+            return Object.freeze({
+                label,
+                oid,
+                exists: true,
+                binary: false,
+                byteSize,
+                truncated: true,
+                content: null,
+                lfs: null,
+            });
+        }
+        const bytes = await runGitBytes(['cat-file', 'blob', oid]);
+        const probe = bytes.subarray(0, LFS_PROBE_BYTES).toString('utf8');
+        const lfs = parseLfsPointer(probe);
+        if (lfs) {
+            return Object.freeze({
+                label,
+                oid,
+                exists: true,
+                binary: false,
+                byteSize,
+                truncated: false,
+                content: probe.trimEnd(),
+                lfs,
+            });
+        }
+        const binary = bytes.includes(0);
+        // Only a bounded known image becomes a data URL; anything else stays an opaque count.
+        const dataUrl = binary && byteSize <= MAX_IMAGE_BYTES ? imageDataUrl(bytes) : null;
+        return Object.freeze({
+            label,
+            oid,
+            exists: true,
+            binary,
+            byteSize,
+            truncated: false,
+            content: binary ? null : bytes.toString('utf8'),
+            lfs: null,
+            dataUrl,
+        });
+    };
+    return {
+        async conflict(pathInput) {
+            const path = assertRelativePath(pathInput);
+            if ((0, redaction_1.isSensitiveFilePath)(path)) {
+                throw new errors_1.WebWorkbenchError(403, 'Sensitive file content is not available in the Web Workbench.', 'sensitive_file_blocked');
+            }
+            // `ls-files -u` lists one entry per unmerged stage, which is the authoritative record
+            // of what the conflict actually contains. Stages absent here do not exist.
+            const raw = await runGit(['ls-files', '-u', '-z', '--', path]);
+            const stageOids = new Map();
+            for (const record of raw.split('\0')) {
+                if (!record)
+                    continue;
+                const [meta] = record.split('\t');
+                const [mode, oid, stage] = meta.split(' ');
+                if (!mode || !oid || !stage)
+                    continue;
+                stageOids.set(Number(stage), oid);
+            }
+            const worktreeOid = (await runGit(['hash-object', '--path=' + path, '--', path]).catch(() => ''))
+                .toString()
+                .trim();
+            const worktreeExists = /^[0-9a-f]{7,64}$/iu.test(worktreeOid);
+            const [base, ours, theirs, worktree] = await Promise.all([
+                readVersion('base', stageOids.get(1) ?? null),
+                readVersion('ours', stageOids.get(2) ?? null),
+                readVersion('theirs', stageOids.get(3) ?? null),
+                worktreeExists ? readVersion('worktree', worktreeOid) : readVersion('worktree', null),
+            ]);
+            const hasBase = stageOids.has(1);
+            const hasOurs = stageOids.has(2);
+            const hasTheirs = stageOids.has(3);
+            let shape = 'other';
+            if (hasBase && hasOurs && hasTheirs)
+                shape = 'both-modified';
+            else if (!hasBase && hasOurs && hasTheirs)
+                shape = 'both-added';
+            // The delete shapes must be tested BEFORE the add shapes: a modify/delete conflict also
+            // has exactly one side present, so a loose `hasOurs && !hasTheirs` would swallow it and
+            // mislabel a deletion as an addition. A missing side only means 'added' when there is no
+            // base to delete from.
+            else if (hasBase && !hasOurs && hasTheirs)
+                shape = 'deleted-by-us';
+            else if (hasBase && hasOurs && !hasTheirs)
+                shape = 'deleted-by-them';
+            else if (hasOurs && !hasTheirs)
+                shape = 'added-by-us';
+            else if (!hasOurs && hasTheirs)
+                shape = 'added-by-them';
+            else if (hasBase && !hasOurs && !hasTheirs)
+                shape = 'both-deleted';
+            return Object.freeze({ path, shape, base, ours, theirs, worktree });
+        },
+        async blob(input) {
+            const path = assertRelativePath(input.path);
+            const rev = assertRev(input.rev);
+            if ((0, redaction_1.isSensitiveFilePath)(path)) {
+                throw new errors_1.WebWorkbenchError(403, 'Sensitive file content is not available in the Web Workbench.', 'sensitive_file_blocked');
+            }
+            // `rev:path` is a tree lookup, not a working-tree read: a file deleted since that
+            // revision is still readable, which is the whole point of "view that version".
+            const oid = (await runGit(['rev-parse', '--verify', '--quiet', `${rev}:${path}`]).catch(() => ''))
+                .toString()
+                .trim();
+            if (!/^[0-9a-f]{7,64}$/iu.test(oid)) {
+                throw new errors_1.WebWorkbenchError(404, 'That file does not exist at the requested revision.', 'git_blob_not_found');
+            }
+            const version = await readVersion('revision', oid);
+            return Object.freeze({
+                path,
+                rev,
+                oid,
+                binary: version.binary,
+                byteSize: version.byteSize,
+                truncated: version.truncated,
+                content: Object.freeze((version.content ?? '').split('\n')),
+                lfs: version.lfs,
+                dataUrl: version.dataUrl ?? null,
+            });
+        },
+        async submodules() {
+            // Only the recorded gitlink SHAs. `git submodule status` is deliberately NOT run: it
+            // traverses every submodule, which plan G6 forbids.
+            const raw = await runGit(['ls-files', '--stage', '-z']);
+            const entries = [];
+            for (const record of raw.split('\0')) {
+                if (!record)
+                    continue;
+                const [meta, filePath] = record.split('\t');
+                const [mode, oid] = (meta ?? '').split(' ');
+                if (mode !== '160000' || !oid || !filePath)
+                    continue;
+                entries.push(Object.freeze({
+                    path: filePath,
+                    gitlinkOid: oid,
+                    dirtySummary: null,
+                    dirtyNote: '未检测：不遍历子模块（计划 G6）。',
+                }));
+            }
+            return Object.freeze(entries);
+        },
+    };
+}
+//# sourceMappingURL=git-version-service.js.map

package/dist/web/native-directory-picker.d.ts

@@ -0,0 +1,63 @@
+export type NativeDirectoryPickResult = {
+    readonly kind: 'selected';
+    readonly path: string;
+} | {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export interface NativeDirectoryPickerInput {
+    readonly title?: string;
+    readonly initialPath?: string;
+}
+export interface NativeDirectoryPicker {
+    pickDirectory(input: NativeDirectoryPickerInput): Promise<NativeDirectoryPickResult>;
+}
+export interface DirectoryPickerCommand {
+    readonly file: string;
+    readonly args: readonly string[];
+}
+/** Injectable process runner so the picker can be unit-tested without a GUI. */
+export type DirectoryPickerRunner = (command: DirectoryPickerCommand) => Promise<{
+    readonly stdout: string;
+}>;
+export interface NativeDirectoryPickerOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly runner?: DirectoryPickerRunner;
+    /** Reject absurd paths from a misbehaving picker. */
+    readonly maxPathLength?: number;
+    readonly timeoutMs?: number;
+}
+/** Why a picker invocation could not produce a directory. */
+export type DirectoryPickerFailureReason = 'picker_unavailable' | 'picker_timeout';
+export declare function parseNativePickerStdout(stdout: string, maxPathLength: number): NativeDirectoryPickResult;
+export declare function createNativeDirectoryPicker(options?: NativeDirectoryPickerOptions): NativeDirectoryPicker;
+/**
+ * v0.3.17 — scripted picker for end-to-end tests.
+ *
+ * CI must never pop a real Finder dialog, so E2E points the Host at a JSON
+ * script file instead. The script is re-read on every invocation, which lets a
+ * test change the next answer between clicks:
+ *
+ * ```json
+ * { "path": "/abs/dir" }                        // selected
+ * { "paths": ["/a", "/b"] }                     // sequential, last one repeats
+ * { "outcome": "cancelled" }                    // user cancelled
+ * { "outcome": "unavailable", "reason": "..." } // no picker on this platform
+ * ```
+ *
+ * This is a browse-only seam: the returned path still has to be confirmed on
+ * the card and passes through the same guarded activation flow, so it can never
+ * cause an unattended workspace switch.
+ */
+export interface FixturePickerScript {
+    readonly path?: string;
+    readonly paths?: readonly string[];
+    readonly outcome?: 'cancelled' | 'unavailable';
+    readonly reason?: string;
+}
+export declare function createFixtureDirectoryPicker(readScript: () => FixturePickerScript): NativeDirectoryPicker;
+/** Reads the script from `ORION_CODE_WEB_PICKER_FIXTURE`; absent means real. */
+export declare function fixturePickerFromEnvironment(env?: NodeJS.ProcessEnv): NativeDirectoryPicker | undefined;
+//# sourceMappingURL=native-directory-picker.d.ts.map

package/dist/web/native-directory-picker.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNativePickerStdout = parseNativePickerStdout;
+exports.createNativeDirectoryPicker = createNativeDirectoryPicker;
+exports.createFixtureDirectoryPicker = createFixtureDirectoryPicker;
+exports.fixturePickerFromEnvironment = fixturePickerFromEnvironment;
+/**
+ * v0.3.16 — Host-side native directory picker.
+ *
+ * The browser cannot hand the local Node Host a real filesystem path (no such
+ * API exists, by design), so opening a *new* local project has to start from
+ * the Host. This adapter shells out to the OS picker and returns the chosen
+ * directory — nothing else. It never writes to the workspace registry, never
+ * activates a Context and never reads file contents.
+ *
+ * Safety contract:
+ * - The AppleScript is a fixed constant. The prompt and the optional default
+ *   location travel as `argv`, so a path can never be interpolated into a
+ *   script (or a shell) string.
+ * - We use `execFile`, not `exec`/`spawn(shell: true)`, so no shell parses the
+ *   arguments.
+ * - Cancellation is a normal outcome, not an error. Unexpected output is
+ *   reported as `unavailable` with a fixed reason code — never echoed back,
+ *   because picker output may contain a path the user has not confirmed.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+/** Fixed markers so we can tell outcomes apart without pattern-matching paths. */
+const MARKER_SELECTED = '__ORION_PICK_SELECTED__';
+const MARKER_CANCELLED = '__ORION_PICK_CANCELLED__';
+const MARKER_ERROR = '__ORION_PICK_ERROR__';
+const DEFAULT_TITLE = '选择要打开的本地项目文件夹';
+const DEFAULT_MAX_PATH_LENGTH = 4096;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * `choose folder` blocks until the user acts. Cancelling raises AppleScript
+ * error -128, which we translate into the CANCELLED marker so the process
+ * exits 0 and the caller can treat it as a normal outcome.
+ */
+const MACOS_PICK_SCRIPT = [
+    'on run argv',
+    '  set promptText to item 1 of argv',
+    '  set defaultPath to item 2 of argv',
+    '  try',
+    '    if defaultPath is "" then',
+    '      set chosen to choose folder with prompt promptText',
+    '    else',
+    '      set chosen to choose folder with prompt promptText default location (POSIX file defaultPath)',
+    '    end if',
+    '  on error errMsg number errNum',
+    '    if errNum is -128 then',
+    `      return "${MARKER_CANCELLED}"`,
+    '    end if',
+    `    return "${MARKER_ERROR}"`,
+    '  end try',
+    `  return "${MARKER_SELECTED}" & (POSIX path of chosen)`,
+    'end run',
+].join('\n');
+/**
+ * The default runner kills the child process when `timeoutMs` elapses, which is
+ * a distinct outcome from "this platform has no picker". It is surfaced as a
+ * fixed reason code so callers never have to parse an error message.
+ */
+const createDefaultRunner = (timeoutMs) => command => new Promise((resolve, reject) => {
+    (0, node_child_process_1.execFile)(command.file, [...command.args], { timeout: timeoutMs, maxBuffer: 64 * 1024, windowsHide: true }, (error, stdout) => {
+        if (error) {
+            const failure = new Error('native directory picker failed');
+            failure.reason = error.killed
+                ? 'picker_timeout'
+                : 'picker_unavailable';
+            reject(failure);
+            return;
+        }
+        resolve({ stdout: typeof stdout === 'string' ? stdout : String(stdout ?? '') });
+    });
+});
+/**
+ * `POSIX path of` always appends a trailing slash; the registry compares
+ * canonical paths exactly, so normalize here rather than downstream.
+ */
+function stripTrailingSeparator(path) {
+    if (path.length <= 1)
+        return path;
+    return path.replace(/\/+$/u, '') || '/';
+}
+function parseNativePickerStdout(stdout, maxPathLength) {
+    const text = stdout.trim();
+    if (text === MARKER_CANCELLED)
+        return { kind: 'cancelled' };
+    if (text.startsWith(MARKER_SELECTED)) {
+        const path = stripTrailingSeparator(text.slice(MARKER_SELECTED.length).trim());
+        if (!path || path.length > maxPathLength) {
+            return { kind: 'unavailable', reason: 'picker_returned_invalid_path' };
+        }
+        return { kind: 'selected', path };
+    }
+    if (text.startsWith(MARKER_ERROR)) {
+        return { kind: 'unavailable', reason: 'picker_failed' };
+    }
+    return { kind: 'unavailable', reason: 'picker_unexpected_output' };
+}
+function createNativeDirectoryPicker(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const runner = options.runner ?? createDefaultRunner(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const maxPathLength = options.maxPathLength ?? DEFAULT_MAX_PATH_LENGTH;
+    return {
+        async pickDirectory(input) {
+            // Only macOS has an implemented adapter. Other platforms answer
+            // explicitly instead of pretending a directory was chosen, so the UI can
+            // fall back to the advanced manual path entry.
+            if (platform !== 'darwin') {
+                return { kind: 'unavailable', reason: 'picker_unavailable' };
+            }
+            const title = input.title?.trim() || DEFAULT_TITLE;
+            const initialPath = input.initialPath?.trim() ?? '';
+            let stdout;
+            try {
+                ({ stdout } = await runner({
+                    file: 'osascript',
+                    args: ['-e', MACOS_PICK_SCRIPT, title, initialPath],
+                }));
+            }
+            catch (error) {
+                const reason = error?.reason;
+                return {
+                    kind: 'unavailable',
+                    reason: reason === 'picker_timeout' ? 'picker_timeout' : 'picker_unavailable',
+                };
+            }
+            return parseNativePickerStdout(stdout, maxPathLength);
+        },
+    };
+}
+function createFixtureDirectoryPicker(readScript) {
+    let cursor = 0;
+    return {
+        async pickDirectory() {
+            const script = readScript();
+            const paths = script.paths ?? (script.path ? [script.path] : []);
+            if (paths.length > 0) {
+                const next = paths[Math.min(cursor, paths.length - 1)];
+                cursor += 1;
+                return next ? { kind: 'selected', path: next } : { kind: 'cancelled' };
+            }
+            if (script.outcome === 'unavailable') {
+                return { kind: 'unavailable', reason: script.reason ?? 'picker_unavailable' };
+            }
+            return { kind: 'cancelled' };
+        },
+    };
+}
+/** Reads the script from `ORION_CODE_WEB_PICKER_FIXTURE`; absent means real. */
+function fixturePickerFromEnvironment(env = process.env) {
+    const scriptPath = env.ORION_CODE_WEB_PICKER_FIXTURE?.trim();
+    if (!scriptPath)
+        return undefined;
+    return createFixtureDirectoryPicker(() => {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(scriptPath, 'utf8'));
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            // A missing or malformed script behaves like a cancelled dialog rather
+            // than failing the request.
+            return {};
+        }
+    });
+}
+//# sourceMappingURL=native-directory-picker.js.map

package/dist/web/protocol.d.ts

@@ -8,7 +8,8 @@ import type { ToolDetailPage, ToolDetailSummary } from '../runtime/tool-detail-r
 import type { SessionMeta } from '../services/session-storage';
 import type { ToolConfirmationPolicy } from '../services/global-config';
 import type { WebFileContentPageV1, WebFileNodeV1, WebFileTreePageV1 } from './file-read-service';
-import type { WebGitCommitV1, WebGitDiffPageV1, WebGitFileV1, WebGitLogPageV1, WebGitStatusV1 } from './git-read-model-service';
+import type { GitCommitIdentityV1, GitCommitOutcomeV1, GitCommitPreviewV1, GitIndexEntryV1, GitMutationResultV1, GitWorktreeSourceV1, WebGitCommitV1, WebGitDiffPageV1, WebGitFileSourceV1, WebGitFileV1, WebGitLogPageV1, WebGitStatusCountsV1, WebGitStatusV1 } from './git-read-model-service';
+import type { GitDiffCapabilitiesV2, GitDiffDocumentV2, GitDiffDocumentKindV2, GitDiffLineKindV2, GitDiffLineV2, GitHunkV2 } from './git-diff-document';
 import type { WebReviewSnapshotV1 } from './review-service';
 import type { WebSessionRuntimeSummaryV1 } from './session-runtime-registry';
 import type { WebTerminalCreateResultV1, WebTerminalExitV1, WebTerminalGapV1, WebTerminalMetadataV1, WebTerminalOutputFrameV1, WebTerminalStateV1 } from './terminal-manager';
@@ -373,10 +374,58 @@ export interface WebWorkspaceProjectSummaryV1 {
     readonly conflictCount: number;
 }
 export type WebWorkspaceResourceV1 = 'files' | 'git' | 'review';
+/** v0.3.16 — LOCAL WORKSPACE picker contracts (read-only until confirm). */
+export type WebDirectoryPickOutcomeV1 = 'selected' | 'cancelled' | 'unavailable';
+export interface WebDirectoryPickResultV1 {
+    readonly outcome: WebDirectoryPickOutcomeV1;
+    /** Present only when `outcome === 'selected'`. */
+    readonly path?: string;
+    /** Operator-readable reason code; present only when `outcome === 'unavailable'`. */
+    readonly reason?: string;
+}
+export interface WebDirectoryPickRequestV1 {
+    readonly requestId: string;
+    readonly title?: string;
+    readonly initialPath?: string;
+}
+export type WebWorkspaceAvailabilityV1 = 'available' | 'missing' | 'not_directory' | 'unreadable';
+export type WebWorkspaceKindV1 = 'git' | 'folder';
+export type WebWorkspaceCandidateSourceV1 = 'picker' | 'recent' | 'pinned' | 'discovered' | 'manual';
+/**
+ * v0.3.17 — `deferred` means the picker deliberately did not wait for the
+ * session catalog to rebuild; the count may arrive later or not at all. It must
+ * never be rendered as a spinner that blocks the confirmation card.
+ */
+export type WebWorkspaceSessionCountStatusV1 = 'ready' | 'deferred';
+/**
+ * A read-only description of a directory the user *may* open. Inspecting a
+ * path never registers it, never activates a Context and never reads file
+ * contents — only `stat` plus the existence of a few project markers.
+ */
+export interface WebWorkspaceCandidateV1 {
+    readonly canonicalPath: string;
+    readonly label: string;
+    readonly availability: WebWorkspaceAvailabilityV1;
+    readonly kind: WebWorkspaceKindV1;
+    readonly source: WebWorkspaceCandidateSourceV1;
+    readonly existingWorkspaceId?: string;
+    readonly sessionCount?: number;
+    readonly sessionCountStatus?: WebWorkspaceSessionCountStatusV1;
+    readonly pinnedOrder?: number;
+    readonly isActive?: boolean;
+}
+export interface WebWorkspaceInspectRequestV1 {
+    readonly requestId: string;
+    readonly path: string;
+    readonly source?: WebWorkspaceCandidateSourceV1;
+}
 export type WebWorkspaceInvalidationReasonV1 = 'context-change' | 'filesystem-change' | 'terminal-command' | 'tool-finished';
 export type WebToolDetailSummaryV1 = ToolDetailSummary;
 export type WebToolDetailPageV1 = ToolDetailPage;
-export type { WebFileContentPageV1, WebFileNodeV1, WebFileTreePageV1, WebGitCommitV1, WebGitDiffPageV1, WebGitFileV1, WebGitLogPageV1, WebGitStatusV1, WebReviewSnapshotV1, WebTerminalCreateResultV1, WebTerminalExitV1, WebTerminalGapV1, WebTerminalMetadataV1, WebTerminalOutputFrameV1, WebTerminalStateV1, };
+export type { GitBlameLineV1, GitGraphPageV1, GitGraphRowV1, GitBlameResultV1, GitRefKindV1, GitRefV1, GitRefsV1, GitCommitSummaryV1, GitCommitDetailV1, GitCommitFileV1, GitCommitFilesV1, GitHistoryQueryV1, GitHistoryPageV1, GitFileHistoryPageV1, } from './git-history-service';
+export type { GitCompareFileV1, GitCompareModeV1, GitCompareResultV1, } from './git-compare-service';
+export type { GitBlobResultV1, GitConflictShapeV1, GitConflictVersionsV1, GitFileVersionV1, GitSubmoduleEntryV1, GitVersionLabelV1, } from './git-version-service';
+export type { WebFileContentPageV1, WebFileNodeV1, WebFileTreePageV1, GitCommitIdentityV1, GitCommitOutcomeV1, GitCommitPreviewV1, GitIndexEntryV1, GitMutationResultV1, GitWorktreeSourceV1, GitDiffCapabilitiesV2, GitDiffDocumentV2, GitDiffDocumentKindV2, GitDiffLineKindV2, GitDiffLineV2, GitHunkV2, WebGitCommitV1, WebGitDiffPageV1, WebGitFileSourceV1, WebGitFileV1, WebGitLogPageV1, WebGitStatusCountsV1, WebGitStatusV1, WebReviewSnapshotV1, WebTerminalCreateResultV1, WebTerminalExitV1, WebTerminalGapV1, WebTerminalMetadataV1, WebTerminalOutputFrameV1, WebTerminalStateV1, };
 export interface WebBootstrapV1 {
     readonly apiVersion: 1;
     readonly productVersion: string;