dsh-remote-vs 0.0.0-stage → 0.8.3

package/lib/types/changes/recorder.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Per-session change ledger for remote workspaces.
+ *
+ * DSH already records "what did this turn change" — but only for local
+ * sessions: `@deepseek-ai/dsh-workspace-changes` parses git's POSIX output with
+ * host path semantics and stages its scratch index through `node:fs`, so on a
+ * routed session the first baseline snapshot fails and the recorder returns
+ * before appending anything (measured: 58 remote-bound sessions, 390 fs
+ * writes, zero `workspace/changes` events).
+ *
+ * This ledger re-expresses the idea for a remote host, and one measurement
+ * decided its shape. A first version snapshotted the worktree with `git add
+ * --all` into a private index; on a monorepo (AOSP, ~1M files) that never
+ * finished — it was still hashing two minutes in, and the panel sat at
+ * "computing…" forever. Everything here is therefore **read-only and
+ * proportional to the files that changed**, never to the size of the
+ * repository:
+ *
+ * 1. `git status --porcelain -uno` names the tracked files that differ (1.7s
+ *    measured), `git ls-files --others` names the new ones (11.3s measured,
+ *    run as its own best-effort exec).
+ * 2. Only those paths are read (their current text, and `HEAD:<path>` for the
+ *    ones the session started clean).
+ * 3. The diff itself is computed here, line by line, with no git call at all.
+ *
+ * Nothing in this file writes to the repository: no `git add`, no index, no
+ * object store, no temp files under the repo. "What changed" is answered by
+ * git's own stat cache; "what changed *since the session started*" is answered
+ * by keeping the pre-existing dirty files' contents at session start and
+ * treating an unchanged one as untouched.
+ */
+import type { RemoteChangesDiff, RemoteChangesSummary, RemoteTimeouts } from '../protocol.ts';
+import type { RemotePool } from '../pool.ts';
+import type { RemoteWorlds } from '../p2/worlds.ts';
+/** The two facts a turn boundary needs from a Session, kept cordis-free. */
+export interface LedgerTarget {
+    sessionId: string;
+    /** Session working directory as the host sees it (an alias path for remote sessions). */
+    cwd: string;
+}
+/** Collaborators the ledger needs; all injectable so it can be unit-tested. */
+export interface SessionChangesDeps {
+    pool: RemotePool;
+    worlds: RemoteWorlds;
+    /** Effective git budget, read per call (a `volatile()` edit applies live). */
+    timeouts: () => RemoteTimeouts;
+    log?: (level: 'info' | 'warn', message: string) => void;
+    /** Cap on listed files; the header totals stay whole. */
+    maxFiles?: number;
+    /** Cap on one file's text, in bytes. */
+    maxFileBytes?: number;
+    /** Cap on one refresh's total text, in bytes. */
+    maxTotalBytes?: number;
+    /** Budget for the untracked scan, which is an order of magnitude slower. */
+    untrackedBudgetMs?: number;
+    /** How often the untracked scan may run again (default five seconds). */
+    untrackedRefreshMs?: number;
+    /**
+     * Override the per-exec budget outright.
+     *
+     * The timeouts setting is clamped to a sane range, which is right for a Host
+     * but useless for a check that must not wait five seconds to see a watchdog
+     * fire.
+     */
+    execBudgetMs?: number;
+}
+export declare class SessionChanges {
+    private readonly ledgers;
+    private readonly deps;
+    private disposed;
+    constructor(deps: SessionChangesDeps);
+    /** Open (or reuse) the ledger for one session at the start of a turn. */
+    beginTurn(target: LedgerTarget): void;
+    /** Refresh the ledger at the end of a turn. */
+    endTurn(target: LedgerTarget, turn: number): void;
+    /** The current summary for one session, or null when it has no ledger. */
+    summary(sessionId: string): RemoteChangesSummary | null;
+    /**
+     * Compare one listed file across the whole session.
+     *
+     * The `before` side comes from the session baseline, which never moves. The
+     * `after` side is read from the host on every call rather than replayed from
+     * the last scan: a revert, a save from the editor or a shell command all
+     * change the file between scans, and replaying a cached copy against a fresh
+     * buffer is exactly how the painted lines end up at the wrong places.
+     *
+     * @param sessionId - live session owning the ledger.
+     * @param path - the file's remote absolute path (as listed in the summary).
+     * @returns hunks for decorations, or null when the session/file is unknown.
+     */
+    diff(sessionId: string, path: string): Promise<RemoteChangesDiff | null>;
+    /** Resolve once every queued refresh has settled, including coalesced work. */
+    settled(): Promise<void>;
+    /** Drop one session's ledger. */
+    forget(sessionId: string): void;
+    /** Release every ledger (plugin unmount). */
+    dispose(): void;
+    /**
+     * Force a fresh pass, ignoring the untracked cadence.
+     *
+     * The panel's refresh button calls this: the cadence exists so a slow scan
+     * does not run on every turn, but "I clicked refresh" means the user wants
+     * the truth now — including files that appeared seconds ago.
+     */
+    rescan(sessionId: string): void;
+    /**
+     * Self-heal a ledger whose data has gone stale.
+     *
+     * The panel polls `list`, and a poll is the one moment we know a human is
+     * looking at the answer. If the data is older than `maxAgeMs`, re-scan — so a
+     * turn boundary this Host never delivered costs a few seconds of staleness
+     * instead of a manual refresh.
+     *
+     * @returns whether a refresh was queued.
+     */
+    touch(sessionId: string, maxAgeMs?: number): boolean;
+    /**
+     * Point one ledger at a subdirectory of the session root.
+     *
+     * This is the Source Control panel's "repository directory": an explicit
+     * choice by the user, and therefore the authority whenever it is set. The
+     * automatic one-level probe is only a fallback for a container workspace that
+     * holds exactly one repository.
+     *
+     * @param subdir - workspace-relative directory, or undefined for the session
+     *   root itself. Absolute paths and `..` are refused: they would move the
+     *   ledger outside the workspace it was created for.
+     */
+    useRepoSubdir(sessionId: string, subdir: string | undefined): void;
+    /** Resolve the routing target once per session, caching the ledger. */
+    private ensure;
+    /** Queue a refresh, coalescing bursts (a turn can end while one is running). */
+    private schedule;
+    /**
+     * One refresh: the cheap scan first, then the slow one in the background.
+     *
+     * The split is not cosmetic. On the reference monorepo `git status -uno`
+     * answers in ~3s while `git ls-files --others` needs over a minute, so a
+     * single sequential refresh would leave the panel empty for that whole
+     * minute even though the tracked changes were known after three seconds.
+     * Phase one publishes, phase two adds the new files when (and if) it lands.
+     */
+    private refresh;
+    /** Recompute the panel's list from the scans currently known. */
+    private publish;
+    /**
+     * The cheap scan: tracked files whose working-tree bytes differ from the
+     * index (1.4s measured on the reference monorepo).
+     *
+     * A session working directory is often a CONTAINER for repositories rather
+     * than one itself (the reference host has `/home/xiray/dsh_workbase` holding
+     * `emv-toolbox-web`), and `git status` there answers exit 128 — "not a git
+     * repository (or any parent up to mount point /)". When that happens the
+     * ledger looks one level down once and adopts the repository it finds, which
+     * is the same idea the SCM panel's `repoSubdir` expresses by hand.
+     *
+     * @returns entries relative to the ledger's root, or undefined when no
+     *   repository could be found (the ledger then reports why).
+     */
+    private scanTracked;
+    /**
+     * Look for a repository in the session root's immediate subdirectories.
+     *
+     * **Only an unambiguous answer is adopted.** A workspace that holds several
+     * repositories has no single right one, and silently picking the first would
+     * report changes from a project the session never touched — worse than saying
+     * "I don't know". The explicit repository directory the Source Control panel
+     * stores is the real answer, and this fallback exists only to spare the user
+     * from setting it when there is exactly one candidate.
+     *
+     * @returns the adopted root, or undefined when nothing (or too much) was found.
+     */
+    private adoptRepositoryBelow;
+    /**
+     * The slow scan: new files, in the background.
+     *
+     * The same command costs ~11s on a warm tree and over a minute on a cold one,
+     * and on the reference AOSP monorepo it has been measured past 60s with no
+     * answer at all. It therefore never runs inline with the tracked scan, never
+     * runs twice at once, and only runs again after {@link untrackedCadence}. A
+     * repository that cannot answer inside {@link untrackedBudget} is written off
+     * for the session (`untrackedGivenUp`) rather than retried every turn.
+     */
+    private kickUntracked;
+    /**
+     * How long before the untracked scan may run again.
+     *
+     * Self-tuning on purpose: the same command costs ~0.2s in a small repository
+     * and over a minute in a monorepo, so a fixed cadence is either wasteful or
+     * useless. Backing off to four times the last duration keeps small projects
+     * near-real-time while a big one settles into a scan every couple of minutes
+     * instead of one per turn.
+     */
+    private untrackedCadence;
+    /**
+     * Fold files that already existed when the session began into the baseline.
+     *
+     * The untracked walk is slow enough (a minute on a monorepo) that the baseline
+     * refresh publishes before it lands, so its first result arrives without a
+     * "before" side. Without this, every file the checkout already had — the
+     * user's own scratch files, a build's leftovers — would be announced as this
+     * session's work, complete with a full-file addition count.
+     *
+     * mtime decides: strictly older than the ledger's own start means the session
+     * cannot have created it, and its present content is therefore its baseline.
+     */
+    private absorbPreExisting;
+    /**
+     * Race one host call against its own budget.
+     *
+     * A budget handed to `exec` is a request, not a guarantee: the transport may
+     * keep the promise open long after the command should have been killed (the
+     * remote process can even be gone while the channel stays). Awaiting such a
+     * promise blocks the ledger's whole queue, so the panel shows "computing…"
+     * for as long as the user is willing to stare at it. This bounds that wait.
+     */
+    private withWatchdog;
+    /** Read a batch of files, capped per file and in total. */
+    private readPaths;
+    /** Run one command on the host, normalizing failure into a reason string. */
+    private run;
+    /** Turn a failed scan into something a user can act on. */
+    private reasonOf;
+    /** One exec's budget: the git setting, clamped so a hung host cannot pile up work. */
+    private execBudget;
+    /** The untracked scan gets its own, more generous budget. */
+    /**
+     * The untracked scan gets its own, much more generous budget.
+     *
+     * Three minutes is a deliberate choice for a monorepo: the walk is proportional
+     * to the whole checkout, not to the session, and the reference AOSP tree has
+     * been measured past a minute cold. Waiting is acceptable here because the
+     * scan runs in the background and the tracked changes are already on screen;
+     * giving up early is not, because the files a session creates with a shell
+     * command are visible ONLY through this scan.
+     */
+    private untrackedBudget;
+    private budget;
+    private warn;
+}

package/lib/types/changes/status.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Remote command builders and reply parsers for the session change ledger.
+ *
+ * Why this module exists: `@deepseek-ai/dsh-workspace-changes` (and the first
+ * cut of this plugin) answer "what did this session change?" by staging the
+ * whole worktree (`git add --all`) and diffing two trees. On a monorepo the
+ * staging step alone ran past 40s without finishing, so the panel never left
+ * "正在统计". Measured on a real AOSP checkout with a warm cache, same repo:
+ *
+ * | command                                      | time   |
+ * | -------------------------------------------- | ------ |
+ * | `git diff-files --name-status -z`            | 1.40s  |
+ * | `git status --porcelain -z -uno`             | 1.67s  |
+ * | `git ls-files --others --exclude-standard -z`| 11.25s |
+ * | `git add --all` (the old baseline)           | >40s   |
+ *
+ * So the cheap path is: ask git *which* paths changed (status), read only those
+ * paths' bytes, and diff locally. Cost becomes proportional to what the session
+ * touched instead of to the size of the repository.
+ *
+ * Everything here is pure string in / string out — no pool, no fs, no DSH
+ * import — so the recorder owns all the IO and this half stays testable.
+ *
+ * ## Paths, quoting, exit codes
+ *
+ * Every path is a POSIX absolute path on the host and every shell word is
+ * single-quoted ({@link shq}); a path that reaches a shell unquoted is a bug.
+ * A command exits `0` when it produced a reply, `90` when its root directory
+ * does not exist (a stale alias), `92` when the host has no `base64`, and
+ * otherwise with git's own exit status. The per-file problems of the read
+ * commands (missing, unreadable, too big) are *not* failures: they are flags
+ * inside a successful reply.
+ *
+ * ## Read reply wire format
+ *
+ * One block per requested path, in request order:
+ *
+ * ```
+ * @@RVS-FILE <base64(path)> ok@@
+ * <base64(content)>
+ * @@RVS-FILE <base64(path)> big@@
+ * @@RVS-FILE <base64(path)> absent@@
+ * ```
+ *
+ * - Paths travel base64-encoded in the marker so spaces, quotes, CJK and even
+ *   newlines cannot break the framing; content travels base64-encoded on the
+ *   single line after the marker so NUL bytes and `\r\n` survive a text-only
+ *   transport (one line, no wrapping — the shell strips base64's newlines).
+ * - `ok` is followed by exactly one content line. An empty file is an empty
+ *   content line (a bare `\n` after the marker line).
+ * - `big` means "not transferred": the file alone is over `capBytes`, or the
+ *   running total would pass `totalCapBytes`.
+ * - `absent` means the path is not there *or* could not be read (permissions,
+ *   a directory, a dangling blob); the recorder treats both as "no content".
+ *
+ * Binary detection is deliberately done in {@link parseReads} (any NUL byte in
+ * the decoded content) rather than in the shell: one definition of "binary" for
+ * every caller, and no dependence on `grep`/`od` behaviour across hosts.
+ */
+/** What happened to one path in this session. */
+export type ChangeStatus = 'A' | 'M' | 'D' | 'R' | 'C' | 'T' | 'U' | '?';
+/** One changed path, relative to the session root. */
+export interface StatusEntry {
+    path: string;
+    status: ChangeStatus;
+}
+/** What one read asked for and what came back. */
+export interface ReadResult {
+    /** Decoded text, or null when nothing usable was transferred. */
+    text: string | null;
+    /** Withheld because of a size cap (single file or the running total). */
+    truncated: boolean;
+    /** The content contains a NUL byte, so it is not text. */
+    binary: boolean;
+    /** Not there, or unreadable. */
+    absent: boolean;
+    /**
+     * Modification time in whole seconds (worktree reads only).
+     *
+     * A large file whose bytes were withheld can still be compared by mtime: two
+     * equal mtimes mean the session did not touch it, which is the difference
+     * between a clean list and one padded with every big file the checkout
+     * happens to carry. Zero when the host could not answer.
+     */
+    mtime?: number;
+    /** Size in bytes, when known (`0` for a missing path). */
+    size?: number;
+}
+/** Exit statuses of the read commands (git's own statuses pass through as-is). */
+export declare const READ_EXIT: {
+    /** The reported root does not exist on the host (stale alias). */
+    readonly noRoot: 90;
+    /**
+     * No `base64` on the host. Probed up front because without it every read
+     * would come back empty and look like "this file has no content", which is a
+     * far worse failure than a clear refusal.
+     */
+    readonly noBase64: 92;
+};
+/**
+ * Tracked paths that changed, HEAD/index vs worktree, staged changes included.
+ *
+ * `-uno` is what keeps this cheap: untracked detection is the expensive half
+ * (11s above) and it is answered by {@link untrackedCommand} instead. `-- .`
+ * scopes the walk to the session root, so a session sitting in one package of
+ * a monorepo does not pay for the rest.
+ *
+ * @param root - remote absolute POSIX directory (the session cwd).
+ * @returns a `sh` script printing NUL-separated porcelain v1 records.
+ */
+export declare function trackedStatusCommand(root: string): string;
+/**
+ * New files git is not tracking yet (the ones a session usually creates).
+ *
+ * @param root - remote absolute POSIX directory (the session cwd).
+ * @returns a `sh` script printing NUL-separated paths.
+ */
+export declare function untrackedCommand(root: string): string;
+/**
+ * Parse `git status --porcelain -z -uno` output.
+ *
+ * Porcelain v1 with `-z` writes `XY <path>\0`, and for a rename or copy the
+ * source path follows as its own record: `R  <new>\0<old>\0` (verified against
+ * git 2.x: the NEW path comes first). The source record is consumed, not parsed
+ * as its own entry, and the reported path is the NEW one — the only path the
+ * editor can open.
+ *
+ * The two status columns mean "index vs HEAD" (X) and "worktree vs index" (Y);
+ * one letter is reported, chosen for how the file reads in a session review:
+ * conflict > deleted > renamed > copied > added > typechange > modified.
+ *
+ * @param stdout - raw reply of {@link trackedStatusCommand}.
+ */
+export declare function parseStatusZ(stdout: string): StatusEntry[];
+/**
+ * Parse `git ls-files --others --exclude-standard -z` output into untracked
+ * entries. Git already filtered ignored files out, and its paths are never
+ * quoted in `-z` mode.
+ */
+export declare function parseUntrackedZ(stdout: string): StatusEntry[];
+/**
+ * Read several worktree files in one remote run.
+ *
+ * One `sh` script walks the paths in order and emits a {@link ReadResult} block
+ * per path. Sizes come from `wc -c` before anything is transferred, so a 4GB
+ * build artifact costs one `stat` instead of 5GB of base64; the running total
+ * stops the reply from growing past `totalCapBytes`, after which the remaining
+ * paths are reported `big` without being read.
+ *
+ * A symlink reports its target as content, because that is what git stores for
+ * mode 120000 — catting the link's target file would diff the wrong bytes.
+ *
+ * @param root - remote absolute POSIX directory (the session cwd).
+ * @param paths - paths relative to `root`.
+ * @param capBytes - per-file cap; larger files are reported `big`.
+ * @param totalCapBytes - cap on the sum of transferred content bytes.
+ */
+export declare function readWorktreeCommand(root: string, paths: readonly string[], capBytes: number, totalCapBytes: number): string;
+/**
+ * Read several `HEAD:<path>` blobs in one remote run — the "before" side of a
+ * file that was already committed and clean when the session started.
+ *
+ * `git cat-file -s` answers existence *and* size before any bytes move, so the
+ * caps are exact, and a path that is not in `HEAD` (a new file, a repository
+ * with no commit yet, a submodule gitlink) is reported `absent` rather than
+ * failing the whole read. `cat-file blob` is used instead of `show` on purpose:
+ * no textconv, no filters, no pager — the bytes git will diff.
+ *
+ * @param root - remote absolute POSIX directory (the session cwd).
+ * @param paths - paths relative to `root`.
+ * @param capBytes - per-file cap; larger blobs are reported `big`.
+ * @param totalCapBytes - cap on the sum of transferred content bytes.
+ */
+export declare function readHeadCommand(root: string, paths: readonly string[], capBytes: number, totalCapBytes: number): string;
+/**
+ * Name every immediate subdirectory that is a git repository.
+ *
+ * A session working directory is often a CONTAINER for repositories (the
+ * reference host has `/home/xiray/dsh_workbase` holding `emv-toolbox-web`), and
+ * `git status` at the container answers 128. This is a one-level `ls`-style
+ * probe — bounded work, no `find` — so it can never become the expensive part
+ * of a scan.
+ *
+ * It prints ALL matches on purpose: a workspace with several repositories has no
+ * single right answer, and the caller must refuse to guess rather than pick the
+ * first one. The SCM panel's explicit repository directory is the real answer.
+ *
+ * @param root - remote absolute POSIX directory (the session cwd).
+ */
+export declare function reposBelowCommand(root: string): string;
+/**
+ * Parse a {@link readWorktreeCommand} / {@link readHeadCommand} reply.
+ *
+ * Keys are the decoded paths, exactly as requested. A marker without its
+ * content line can only mean the reply was cut short (a timeout killing the
+ * pipe); such a path is reported truncated rather than as an empty file, so an
+ * aborted read never masquerades as "the file is empty".
+ *
+ * @param stdout - raw reply of either read command.
+ */
+export declare function parseReads(stdout: string): Map<string, ReadResult>;

package/lib/types/changes/text-diff.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Line-level diff for the session change ledger.
+ *
+ * The recorder gets *content* (see `status.ts`) and needs the same thing git
+ * would have printed with `-U3`: hunks a reviewer can read, counts for the file
+ * list, and a patch that can undo the change. Doing it here, on the host side,
+ * means a file's before/after text is compared without another round trip to
+ * the remote — and without teaching git about the session baseline.
+ *
+ * No dependency, no IO, on purpose. The algorithm is Myers' greedy edit script
+ * (the one git's own xdiff implements): common prefix and suffix are stripped
+ * first, then the middle is diffed, so the cost follows the size of the edit
+ * rather than the size of the file.
+ *
+ * Line conventions, chosen to match `git diff` byte for byte:
+ *
+ * - a final `\n` does not produce an extra empty line;
+ * - `\r` stays inside the line, so a CRLF file keeps its `\r` and a CRLF/LF
+ *   mismatch shows up as changed lines instead of a phantom whole-file edit;
+ * - a file that does not end in `\n` keeps its last line, and the hunk is
+ *   flagged `oldNoEol` / `newNoEol` so {@link hunkPatch} can emit git's
+ *   `` marker — without it `git apply -R` refuses to
+ *   touch such a file.
+ */
+/** One unified-diff hunk. Line numbers are 1-based, like git's. */
+export interface TextHunk {
+    /** First old-side line in the hunk; 0 when the hunk only adds lines. */
+    oldStart: number;
+    /** Number of old-side lines the hunk covers (context + removed). */
+    oldLines: number;
+    /** First new-side line in the hunk; 0 when the hunk only removes lines. */
+    newStart: number;
+    /** Number of new-side lines the hunk covers (context + added). */
+    newLines: number;
+    /**
+     * Lines with their leading `' '`, `'-'` or `'+'`, and without the trailing
+     * `\n` — the shape the client's diff view already consumes.
+     */
+    lines: string[];
+    /** The hunk reaches the end of `before`, which does not end in a newline. */
+    oldNoEol?: true;
+    /** The hunk reaches the end of `after`, which does not end in a newline. */
+    newNoEol?: true;
+}
+/** A whole text comparison: hunks plus the counts the file list shows. */
+export interface TextDiff {
+    hunks: TextHunk[];
+    /** `'+'` lines, counted from {@link hunks} so the two can never disagree. */
+    added: number;
+    /** `'-'` lines, counted from {@link hunks}. */
+    deleted: number;
+}
+/** Compare two texts into git-shaped hunks (default 3 lines of context). */
+export declare function diffText(before: string, after: string, context?: number): TextDiff;
+/**
+ * Serialize one hunk as a patch `git apply` accepts (and `git apply -R` undoes).
+ *
+ * The `@@ -a,b +c,d @@` counts are always written out — git accepts the elided
+ * `,1` and `,-0` spellings, but a reviewer reading a log is better served by the
+ * explicit form, and one spelling means one code path to test.
+ *
+ * @param displayPath - repo-relative path, as the panel shows it.
+ * @param hunk - one hunk of {@link diffText}.
+ */
+export declare function hunkPatch(displayPath: string, hunk: TextHunk): string;

package/lib/types/client/CodeEditor.d.ts

@@ -0,0 +1,125 @@
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * The bits of an editor's view state that must survive an unmount.
+ *
+ * Switching file tabs remounts `CodeEditor` (its `key` is the tab id, so an
+ * identity change gets a fresh buffer rather than inheriting the previous
+ * file's undo history). Without carrying this across, every tab switch threw
+ * the reader back to line 1 with the caret at the start.
+ */
+export interface CodeEditorViewState {
+    /** Scroll offset of the code scroller, in pixels. */
+    scrollTop: number;
+    /** Scroll offset of the code scroller, in pixels. */
+    scrollLeft: number;
+    /** Caret position as a document offset. */
+    cursor: number;
+    /** All selection ranges (multi-cursor survives a tab switch too). */
+    ranges: {
+        anchor: number;
+        head: number;
+    }[];
+}
+export interface CodeEditorHandle {
+    getContent: () => string;
+    isDirty: () => boolean;
+    markSaved: () => void;
+    /** Snapshot scroll + selection, for restoring after a remount. */
+    getViewState: () => CodeEditorViewState | undefined;
+    /** Scroll back and put the caret where it was. */
+    applyViewState: (state: CodeEditorViewState) => void;
+    /** 选中一个行区间（1-based 行号）并滚到视野中央。 */
+    revealRange: (from: number, to: number) => void;
+    /**
+     * 改动标记是否已被编辑作废（true = 屏幕上不再画任何改动点）。
+     *
+     * 暴露成独立的一个布尔查询、而不是把 `EditorView` 交出去：外部唯一需要知道的
+     * 就是"这份数据还准不准"，拿到了整个 view 则能改文档、改配置，是另一回事。
+     */
+    getChangeStale: () => boolean;
+}
+import { type ChangeMark, type ChangeSet } from './vsc/change-marks.ts';
+/**
+ * The editor surface is OPAQUE and scrolls in the editor's own palette
+ * (`vsc/editor-theme.ts`): a code editor is not a translucent DSH panel, and
+ * the VS Code theme is what gives the tokens their readable colors.
+ */
+export declare const CodeEditor: import("react").ForwardRefExoticComponent<{
+    initial: string;
+    path: string;
+    readOnly?: boolean;
+    /** Parent sub-tab visibility (views stay mounted; remeasure on show). */
+    visible?: boolean;
+    /** Chat-insert target: absent/disabled hides the selection popup. */
+    ctx?: Context;
+    sessionId?: string | undefined;
+    remoteRoot?: string | undefined;
+    chatEnabled?: boolean;
+    addLabel?: string;
+    /** 1-based line to reveal after mount (a content-search hit). */
+    revealLine?: number;
+    /** Bumped per reveal request, so the same line can be jumped to twice. */
+    revealNonce?: number;
+    /**
+     * 本会话在这个文件里的改动（行号 1-based）。`undefined` = 不开启改动标记：
+     * 不装扩展、不出现 gutter —— 没传这个 prop 的调用方（diff 面板等）行为与
+     * 加入本功能之前完全一致。
+     */
+    changeSet?: ChangeSet | null;
+    /**
+     * 用户在某一处改动上按下「撤销这处改动」时回调。
+     *
+     * 收到的是 `changeSet.marks` 里的那个对象（`hunk` 是 `changeSet.patches` 的下标）。
+     * 不传就不装悬浮撤销那一整套（`undoAffordance`），编辑器行为与没有这个功能时
+     * 完全一致 —— 也就不会点出一个没人接的动作。
+     */
+    onUndoChange?: (mark: ChangeMark) => void;
+    /** 悬浮按钮的文案（由调用方按 `kind` 给出它的 i18n 说法）。 */
+    undoLabel?: (mark: ChangeMark) => string;
+    /** 改动点跳转的目标行（1-based），配合 `revealHunkNonce` 重跳同一行。 */
+    revealHunkLine?: number;
+    /** 改动点跳转的 nonce（同 `revealNonce` 的道理）。 */
+    revealHunkNonce?: number;
+    /**
+     * 用户按下「上一个/下一个改动点」快捷键时回调。
+     *
+     * 列表算在 store 那边（`gotoChange`），编辑器只转发方向：组件内自己维护一份
+     * hunk 列表会与 tab 上的 `activeHunk` 漂成两份。
+     */
+    onStepHunk?: (dir: 1 | -1) => void;
+    /**
+     * 文档被编辑、改动标记已作废时回调一次（false→true 的跳变）。
+     *
+     * 用回调而不是让上层轮询 handle：这件事发生在一次按键里，轮询会漏。
+     */
+    onChangeStale?: () => void;
+    /** Reports how many token spans the grammar produced (diagnostics). */
+    onTokens?: (count: number) => void;
+    /**
+     * Reports this editor's scroll + caret as they change, and once more when it
+     * unmounts. The FIRST argument is this editor's own tab id, so the consumer
+     * never has to guess which tab a reading belongs to.
+     *
+     * The editor reports it, rather than the parent asking through the ref,
+     * because the parent's ref is already `null` by the time its layout-effect
+     * cleanup runs — React clears a child's ref before running the parent's
+     * cleanup. Only this component still holds the `EditorView` at that moment.
+     */
+    onViewState?: (tabId: string, state: CodeEditorViewState) => void;
+    /**
+     * This editor's tab id, echoed back with every report (see `onViewState`).
+     * Optional because the diff panes mount `CodeEditor` too and have no tab of
+     * their own; they pass no `onViewState`, so nothing is reported for them.
+     */
+    tabId?: string;
+    /**
+     * Scroll + caret to restore after this instance mounts.
+     *
+     * Read ONCE on mount (through a ref, so a later change to the prop cannot
+     * re-scroll a live editor out from under the reader). Used to come back to
+     * where a file was when its tab is re-selected.
+     */
+    viewState?: CodeEditorViewState;
+    onSave: () => void;
+    onDirty: (dirty: boolean) => void;
+} & import("react").RefAttributes<CodeEditorHandle>>;

package/lib/types/client/Dialog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Small inline input dialog (new file / folder / rename). Rendered as a
+ * fixed overlay card; Enter confirms, Escape cancels.
+ */
+import { type ReactNode } from 'react';
+export declare function InputDialog(props: {
+    title: string;
+    label: string;
+    initial?: string;
+    placeholder?: string;
+    okText?: string;
+    onOk: (value: string) => void;
+    onCancel: () => void;
+}): ReactNode;

package/lib/types/client/DirectoryFlow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Phase 4 native directory-flow occupant: a Local/Remote tabbed dialog that
+ * shadows the stock picker (registered at priority -1 into both
+ * directory-flow holes).
+ *
+ * - Local leg: dual-mode. When the Host serves the browse capability, a
+ *   compact in-app browser drives uiWorkspace.listDirectory/createDirectory.
+ *   When it serves native (this Windows machine), one button opens the OS
+ *   chooser via uiWorkspace.pickDirectory. The mode is probed once per open:
+ *   a working list() means browse, `directory-picker/unavailable` means
+ *   native, anything else is an inline error with retry.
+ * - Remote leg: the shared WorkspaceWizard; on save the materialized alias
+ *   path goes to onPicked and the owner adopts it as a real workspace
+ *   (its title was already set to `<server> > <base>` by syncWorkspaces).
+ *
+ * The occupant never drives the owner's onError arm: every failure stays
+ * inside the dialog (stock BrowseDirectoryFlow does the same), and Cancel is
+ * always available. If this entry ever crashes, slot shadowing retires it and
+ * the stock picker renders (graceful fallback, no dead surface).
+ */
+import { type ReactNode } from 'react';
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client';
+import type { DirectoryListing } from '@deepseek-ai/dsh-host-directory-picker/types';
+/** Injected face: uiWorkspace directory primitives (bound in apply's closure). */
+export interface DirectoryFlowInjected {
+    listDirectory: (path?: string, signal?: AbortSignal) => Promise<DirectoryListing>;
+    createDirectory: (path: string, name: string) => Promise<string>;
+    pickDirectory: () => Promise<string | null>;
+}
+export declare function RemoteDirectoryFlow(props: DirectoryFlowOwnerProps & DirectoryFlowInjected): ReactNode;