Merge master into codex/grep-glob-require-rg

packages/fs/fs-local/README.md

@@ -1,26 +1,35 @@
 # @deepseek-ai/dsh-fs-local
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the seven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eight `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 
 await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
-// ctx.fs is now the local backend; load @deepseek-ai/dsh-fs-policy for the
+// ctx.fs uses the local backend; load @deepseek-ai/dsh-fs-policy for the
 // freshness policy gate and @deepseek-ai/dsh-tool-fs to expose read/write/edit.
 ```
 
 ## Behavior
 
-- **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
-- **`stat`** — returns `FsInfo` (`version` = `mtimeMs:size`, `type` of `file`/`directory`/`other`, byte `size`) or `undefined` when the target is absent.
+- **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
-## `cwd` is not a sandbox
+The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
 
-`config.cwd` is a resolution default, not a containment boundary — absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall. See [the filesystem capability-seam RFC's Consequences section](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences).
+## Model Experience
 
-The raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
+Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders this provider's line-windowed UTF-8 content, mutation acknowledgements, and exact provider messages in capped retained results while versions, atomic-write mechanics, and directory metadata remain internal.
+
+## Known Limitations and Deferred Work
+
+- **`config.cwd` is not a sandbox** — it is a resolution default, not containment: absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall ([capability-seam RFC](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)).
+- **An overwrite reads the whole prior file into memory** — solely as the UI diff basis; bounding that pre-read above a size threshold is deferred (`TODO(overwrite-diff-bound)`).
+- **Version tokens are `mtimeMs:size`** — an external change that preserves both within the filesystem's timestamp granularity defeats the stale guard.
+- **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
+- **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
+- **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.

packages/fs/fs-local/package.json

@@ -23,7 +23,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-fs": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
     "schemastery": "^3.18.0"
@@ -31,6 +31,6 @@
   "devDependencies": {
     "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   }
 }

packages/fs/fs-local/src/fsio.ts

@@ -1,27 +1,14 @@
 /**
- * Cordis-free local-filesystem I/O for `@deepseek-ai/dsh-fs-local`. Kept
- * separate from the service class (mirroring `dsh-bash-local`'s `run.ts`) so
- * the raw stat/read/write/edit mechanics can be unit-tested without a Context.
- *
- * This is the PROVIDER layer: it hands back decoded whole-file text (validated
- * UTF-8, binary rejected) — never line windows or numbered lines, which are
- * model-facing read policy owned by `@deepseek-ai/dsh-fs-policy`. Large files
- * stream their text in chunks so a huge file never has to be held whole in
- * memory; the binary/NUL sample and cross-chunk UTF-8 decoding stay here.
- *
- * Writes are atomic: content goes to a temp file opened exclusively (`wx`,
- * `0o600`, so a pre-existing path can never be clobbered and write-in-progress
- * bytes stay owner-only) inside a randomly-named private staging directory
- * (`0o700`) next to the target, then `rename`d over the target. Edits are
- * read-modify-write over the same atomic primitive.
- *
+ * Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
+ * streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
+ * stage an exclusive owner-only file in a private sibling directory and atomically rename it.
  * @module @deepseek-ai/dsh-fs-local/fsio
  */
 
 import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
-import { chmod, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
-import type { Dirent, Stats } from 'node:fs'
+import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
+import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
 import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
@@ -76,9 +63,9 @@ async function readFileAbortable(absolutePath: string, verb: 'read' | 'edit', si
   }
 }
 
-/** Opaque version token from a stat: mtime (ns precision) + size. */
-function versionOf(info: Stats): FsVersion {
-  return FsVersion(`${info.mtimeMs}:${info.size}`)
+/** Opaque version token from high-resolution identity and freshness metadata. */
+function versionOf(info: BigIntStats): FsVersion {
+  return FsVersion(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`)
 }
 
 /**
@@ -111,6 +98,14 @@ export interface PathInfo {
   size: number
 }
 
+/** Result of probing a path without following the final symlink component. */
+export interface PathLinkInfo {
+  version: FsVersion
+  mode: number
+  type: 'file' | 'directory' | 'symlink' | 'other'
+  size: number
+}
+
 /** One local directory child with a resolved target and cheap metadata. */
 export interface LocalDirEntry {
   name: string
@@ -121,14 +116,9 @@ export interface LocalDirEntry {
 }
 
 /**
- * Resolve a path to its absolute display path and realpath identity. Relative
- * paths are based on `cwd`. When the file itself does not yet exist, the
- * `targetKey` realpaths the nearest EXISTING ancestor directory and re-appends
- * the still-missing suffix, so a not-yet-created file gets the same stable key
- * it will have after creation — even when an ancestor (e.g. `cwd`) is a symlink
- * and intermediate directories are created by the write. Two input paths
- * reaching the same file via symlinks share one key. Falls back to the absolute
- * path only when no ancestor (not even the filesystem root) can be resolved.
+ * Resolve a path to its absolute display path and realpath identity. For a missing target,
+ * realpath the nearest existing ancestor and append the missing suffix, preserving identity
+ * across symlinked ancestors before and after creation.
  * @param cwd - base directory a relative `path` resolves against.
  * @param path - absolute or relative path; empty/whitespace-only throws `FS_NOT_FOUND`.
  * @returns the absolute display path plus the realpath-derived stable target key.
@@ -168,22 +158,62 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
   }
 }
 
+function pathType(info: Stats | BigIntStats): PathInfo['type'] {
+  if (info.isFile()) return 'file'
+  if (info.isDirectory()) return 'directory'
+  return 'other'
+}
+
+function pathLinkType(info: Stats | BigIntStats): PathLinkInfo['type'] {
+  if (info.isSymbolicLink()) return 'symlink'
+  return pathType(info)
+}
+
+async function probeStats<T extends Stats | BigIntStats>(
+  absolutePath: string,
+  readStats: (path: string) => Promise<T>,
+): Promise<T | null> {
+  try {
+    return await readStats(absolutePath)
+  } catch (error: unknown) {
+    // ENOENT (no such file) and ENOTDIR (a parent segment is a file) both mean
+    // the target is absent; any other metadata failure is a real permission/IO
+    // fault.
+    /* v8 ignore next -- a non-ENOENT/ENOTDIR metadata failure needs a permission/IO fault; surface it. */
+    if (!isENOENT(error) && !isENOTDIR(error)) throw error
+    return null
+  }
+}
+
 /**
  * Probe a path for its version, mode, type, and size. Null if absent.
  * @param absolutePath - the path to stat (typically a target key; symlinks are followed).
  * @returns the metadata, or null when the path — or a parent segment — does not exist.
  */
 export async function probe(absolutePath: string): Promise<PathInfo | null> {
-  try {
-    const info = await stat(absolutePath)
-    const type = info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other'
-    return { version: versionOf(info), mode: info.mode & 0o777, type, size: info.size }
-  } catch (error: unknown) {
-    // ENOENT (no such file) and ENOTDIR (a parent segment is a file) both mean
-    // the target is absent; any other stat failure is a real permission/IO fault.
-    /* v8 ignore next -- a non-ENOENT/ENOTDIR stat failure needs a permission/IO fault; surface it. */
-    if (!isENOENT(error) && !isENOTDIR(error)) throw error
-    return null
+  const info = await probeStats(absolutePath, path => stat(path, { bigint: true }))
+  if (!info) return null
+  return {
+    version: versionOf(info),
+    mode: Number(info.mode & 0o777n),
+    type: pathType(info),
+    size: Number(info.size),
+  }
+}
+
+/**
+ * Probe a path without following the final symlink component.
+ * @param absolutePath - the path entry to inspect with `lstat` semantics.
+ * @returns path-entry metadata, or null when the entry is absent.
+ */
+export async function probeNoFollow(absolutePath: string): Promise<PathLinkInfo | null> {
+  const info = await probeStats(absolutePath, path => lstat(path, { bigint: true }))
+  if (!info) return null
+  return {
+    version: versionOf(info),
+    mode: Number(info.mode & 0o777n),
+    type: pathLinkType(info),
+    size: Number(info.size),
   }
 }
 
@@ -363,15 +393,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
 }
 
 /**
- * Atomically write `content` to `absolutePath`: create parent dirs, write to a
- * randomly-named temp file opened exclusively (`wx`, `0o600`) inside a private
- * (`0o700`) staging directory, fsync, optionally chmod to the final mode while
- * still private, then rename over the target. `mode` (when given) preserves an
- * existing file's permissions across the replace.
- * @param absolutePath - the final destination (typically a target key); missing parent dirs are created.
+ * Atomically replace a file through a private, synced staging file in the same directory.
+ * @param absolutePath - destination; missing parent directories are created.
  * @param content - the full UTF-8 text to write.
- * @param mode - final file mode applied before the rename (an existing file's, to preserve permissions); undefined leaves `0o600`.
- * @param signal - aborts the write (`FS_ABORTED`); checked before the rename, so the target is never left torn.
+ * @param mode - final mode, or `0o600` when omitted.
+ * @param signal - cancellation checked before the final rename.
  * @param internals - test seam for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
@@ -492,12 +518,8 @@ export async function readForEdit(
 }
 
 /**
- * Best-effort read of a file's current text for a before/after diff basis, used
- * by an overwrite. Returns the LF-normalized decoded content, or `null` when the
- * file is binary or not valid UTF-8 — a write must succeed regardless of the
- * prior bytes, so an undiffable prior file simply yields no contextual-hunk basis
- * (the caller treats `null` the same as an absent file: the result renders a
- * whole-file diff rather than an applied hunk).
+ * Best-effort overwrite diff basis. Binary or invalid UTF-8 returns `null` so the write still
+ * succeeds and presentation falls back to a whole-file diff.
  * @param absolutePath - the file to read (typically a target key); it must exist.
  * @param signal - aborts the read (`FS_ABORTED`).
  * @returns the LF-normalized text, or null for a binary or non-UTF-8 file.
@@ -515,12 +537,11 @@ export async function readTextForDiff(absolutePath: string, signal?: AbortSignal
 }
 
 /**
- * Apply a literal replacement to LF-normalized content. Throws
- * `FS_EDIT_NOT_FOUND` on empty `oldString` or zero matches and
- * `FS_AMBIGUOUS_EDIT` on multiple matches when `replaceAll` is false. Returns
- * the edited content (still LF-normalized) and the replacement count.
+ * Apply a literal replacement to LF-normalized content. Empty or missing search text throws
+ * `FS_EDIT_NOT_FOUND`; multiple matches throw `FS_AMBIGUOUS_EDIT` unless `replaceAll` is true.
  * @param content - the current file content, already LF-normalized.
- * @param oldString - literal text to find; CRLF inside it is normalized to LF before matching.
+ * @param oldString - literal text to find; CRLF inside it is normalized to LF before
+ *   matching.
  * @param newString - literal replacement text, normalized the same way.
  * @param replaceAll - replace every match instead of requiring exactly one.
  * @param displayPath - the caller-facing path used in error messages.

packages/fs/fs-local/src/index.ts

@@ -1,19 +1,11 @@
 /**
- * Local-filesystem implementation of the `ctx.fs` provider seam.
- * {@link LocalFileSystem} subclasses {@link FileSystem} and backs the seven
- * text-storage primitives with the host filesystem via
- * {@link module:@deepseek-ai/dsh-fs-local/fsio}. Path resolution uses
- * `realpath`, so the stable `targetKey` is the real file identity (two input
- * paths reaching the same file through symlinks share one key, and writes land
- * on the link target — preserving the link).
- *
- * Future sandboxed/remote/virtual backends are sibling packages implementing
- * the same interface; loading this one populates `ctx.fs`.
- *
+ * Host-filesystem implementation of `ctx.fs`. Realpath-derived target identity makes aliases
+ * share stale guards, and writes through a symlink update its target without replacing the link.
  * @module @deepseek-ai/dsh-fs-local
  */
 
 import { Context } from 'cordis'
+import { resolve } from 'node:path'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -21,6 +13,7 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
@@ -30,6 +23,7 @@ import {
   listDirectory,
   normalizeLineEndings,
   probe,
+  probeNoFollow,
   readForEdit,
   readTextForDiff,
   readWholeText,
@@ -40,20 +34,6 @@ import {
 } from './fsio.ts'
 import type { FsIoInternals } from './fsio.ts'
 
-export {
-  applyLiteralEdit,
-  listDirectory,
-  probe,
-  readForEdit,
-  readTextForDiff,
-  readWholeText,
-  resolveLocalTarget,
-  restoreLineEndings,
-  streamWholeText,
-  writeFileAtomic,
-} from './fsio.ts'
-export type { FsIoInternals, LineEndings, LocalDirEntry, LocalTarget, PathInfo } from './fsio.ts'
-
 /** Configuration for the local filesystem backend. */
 export interface Config {
   /** Base directory for relative paths. Defaults to `process.cwd()`. */
@@ -103,14 +83,26 @@ export class LocalFileSystem extends FileSystem {
     }
   }
 
-  override async resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget> {
+  override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
+    if (opts?.signal?.aborted) throw new FsError('resolve aborted', 'FS_ABORTED')
     const local = await resolveLocalTarget(opts?.cwd ?? this.config.cwd, path)
+    if (opts?.signal?.aborted) throw new FsError('resolve aborted', 'FS_ABORTED')
     return { targetKey: local.targetKey, displayPath: local.displayPath }
   }
 
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
     const info = await probe(target.targetKey)
+    if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
+    if (!info) return undefined
+    return { version: info.version, type: info.type, size: info.size }
+  }
+
+  override async lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined> {
+    if (signal?.aborted) throw new FsError('lstat aborted', 'FS_ABORTED')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const info = await probeNoFollow(resolve(opts?.cwd ?? this.config.cwd, path))
+    if (signal?.aborted) throw new FsError('lstat aborted', 'FS_ABORTED')
     if (!info) return undefined
     return { version: info.version, type: info.type, size: info.size }
   }
@@ -156,18 +148,10 @@ export class LocalFileSystem extends FileSystem {
         // createIfAbsent onto an existing file: a blind overwrite — require a read first.
         throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')
       }
-      // expected === undefined: unconditional create-or-overwrite (the bare
-      // provider) — no version guard, no read-first requirement. Still atomic
-      // (the per-target lock is unconditional), so the write is never torn.
+      // No expectation means an unconditional but still atomic write.
 
-      // Capture the prior text (the before/after diff basis) BEFORE the write.
-      // `null` for a create (no existing file) OR an existing-but-undiffable
-      // file (binary/invalid-UTF-8) — a null `before` gives no contextual-hunk
-      // basis, so a consumer falls back to a whole-file diff (the tool still
-      // renders a result-time diff card, not the raw result text).
-      // TODO(overwrite-diff-bound): this reads the whole prior file into memory
-      // for a UI-only diff; bound the pre-read and fall back to no contextual
-      // basis above a size threshold (see the applied-hunk-diffs RFC non-goals).
+      // Preserve prior text for contextual diffs; null falls back to a whole-file diff.
+      // TODO(overwrite-diff-bound): cap this UI-only pre-read for large files.
       const before = existing ? await readTextForDiff(target.targetKey, signal) : null
       await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals)
       const after = await probe(target.targetKey)
@@ -191,10 +175,9 @@ export class LocalFileSystem extends FileSystem {
   ): Promise<FsEditOutcome> {
     return this.withLock(target.targetKey, async () => {
       const existing = await probe(target.targetKey)
-      // Stale guard BEFORE literal matching: an edit based on an old read reports
+      // Stale guard before literal matching: an edit based on an old read reports
       // FS_STALE_VERSION, not FS_EDIT_NOT_FOUND/FS_AMBIGUOUS_EDIT against newer content.
-      // A missing target reports FS_STALE_VERSION on BOTH paths (guarded and
-      // unconditional) — one "cannot edit this target now" code.
+      // Missing targets use the same stale code on guarded and unconditional edit paths.
       if (!existing) throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
       if (existing.type !== 'file') throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
       // expected === undefined: unconditional edit of the current content — no

packages/fs/fs-local/tests/filesystem.spec.ts

@@ -6,8 +6,8 @@
  * `dsh-fs-policy`, so it is not exercised here.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, writeFile, unlink } from 'node:fs/promises'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, unlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
@@ -73,6 +73,18 @@ describe('resolve', () => {
     const target = await fs.resolve(join(dir, 'abs.txt'), { cwd: '/nonexistent-base' })
     expect(await fs.readText(target)).toBe('absolute')
   })
+
+  it('honors a pre-aborted signal', async () => {
+    await expect(fs.resolve('a.txt', { signal: AbortSignal.abort() })).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
+  it('honors a signal aborted while resolution is in flight', async () => {
+    const controller = new AbortController()
+    const pending = fs.resolve('a.txt', { signal: controller.signal })
+    controller.abort()
+
+    await expect(pending).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
 })
 
 describe('stat', () => {
@@ -87,11 +99,104 @@ describe('stat', () => {
     expect(await fs.stat(await fs.resolve('missing.txt'))).toBeUndefined()
   })
 
+  it('changes version after a same-size rewrite even when mtime is restored', async () => {
+    const path = join(dir, 'same-size.txt')
+    await writeFile(path, 'first')
+    const target = await fs.resolve(path)
+    const beforeInfo = await stat(path)
+    const beforeVersion = await versionOf(target)
+
+    await fs.writeText(target, 'other')
+    await utimes(path, beforeInfo.atime, beforeInfo.mtime)
+
+    expect((await stat(path)).size).toBe(beforeInfo.size)
+    expect(await versionOf(target)).not.toBe(beforeVersion)
+  })
+
   it('honors a pre-aborted signal', async () => {
     await expect(fs.stat(await fs.resolve('a.txt'), AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
   })
 })
 
+describe('lstat', () => {
+  it('reports path metadata without following the final symlink component', async () => {
+    await writeFile(join(dir, 'real.txt'), 'hello')
+    await symlink(join(dir, 'real.txt'), join(dir, 'link.txt'))
+
+    expect((await fs.lstat('real.txt'))?.type).toBe('file')
+    expect((await fs.lstat('link.txt'))?.type).toBe('symlink')
+    expect(await fs.lstat('missing.txt')).toBeUndefined()
+  })
+
+  it('resolves relative paths against opts.cwd and honors a pre-aborted signal', async () => {
+    const other = await mkdtemp(join(tmpdir(), 'dsh-fs-other-'))
+    try {
+      await writeFile(join(other, 'x.txt'), 'in other')
+      expect((await fs.lstat('x.txt', { cwd: other }))?.type).toBe('file')
+      await expect(fs.lstat('x.txt', { cwd: other }, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      await expect(fs.lstat('   ')).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+    } finally {
+      await rm(other, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('metadata cancellation', () => {
+  it('rejects stat and lstat when their signals abort while the metadata probes are in flight', async () => {
+    await writeFile(join(dir, 'slow.txt'), 'hello')
+    const statStarted = Promise.withResolvers<undefined>()
+    const statRelease = Promise.withResolvers<undefined>()
+    const lstatStarted = Promise.withResolvers<undefined>()
+    const lstatRelease = Promise.withResolvers<undefined>()
+    let isolatedCtx: Context | undefined
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return {
+        ...actual,
+        async stat(path: string) {
+          statStarted.resolve(undefined)
+          await statRelease.promise
+          return actual.stat(path, { bigint: true })
+        },
+        async lstat(path: string) {
+          lstatStarted.resolve(undefined)
+          await lstatRelease.promise
+          return actual.lstat(path, { bigint: true })
+        },
+      }
+    })
+
+    try {
+      const { LocalFileSystem: IsolatedLocalFileSystem } = await import('../src/index.ts')
+      isolatedCtx = new Context()
+      await isolatedCtx.plugin(IsolatedLocalFileSystem, { cwd: dir })
+      const isolatedFs = isolatedCtx.fs as InstanceType<typeof IsolatedLocalFileSystem>
+      const target = await isolatedFs.resolve('slow.txt')
+      const statController = new AbortController()
+      const lstatController = new AbortController()
+      const pendingStat = isolatedFs.stat(target, statController.signal)
+      const pendingLstat = isolatedFs.lstat('slow.txt', undefined, lstatController.signal)
+
+      await Promise.all([statStarted.promise, lstatStarted.promise])
+      statController.abort()
+      lstatController.abort()
+      const statRejected = expect(pendingStat).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      const lstatRejected = expect(pendingLstat).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      statRelease.resolve(undefined)
+      lstatRelease.resolve(undefined)
+
+      await Promise.all([statRejected, lstatRejected])
+    } finally {
+      statRelease.resolve(undefined)
+      lstatRelease.resolve(undefined)
+      await isolatedCtx?.fiber.dispose()
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+})
+
 describe('readText / streamText', () => {
   it('reads whole-file text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
@@ -292,9 +397,6 @@ describe('writeText', () => {
     await writeFile(join(dir, 'a.txt'), 'v1')
     const target = await fs.resolve('a.txt')
     const before = await versionOf(target)
-    // Change the byte length so the mtimeMs:size token provably differs (a
-    // same-size same-tick rewrite can collide — the documented version-token
-    // limitation; not what this test is about).
     const outcome = await fs.writeText(target, 'a much longer replacement body', { kind: 'replaceIfVersion', version: before })
     expect(outcome.version).not.toBe(before)
     expect(outcome.version).toBe(await versionOf(target))

packages/fs/fs-local/tests/fsio.spec.ts

@@ -14,14 +14,15 @@ import {
   applyLiteralEdit,
   listDirectory,
   probe,
+  probeNoFollow,
   readForEdit,
   readWholeText,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
   writeFileAtomic,
-} from '@deepseek-ai/dsh-fs-local'
-import type { LocalTarget } from '@deepseek-ai/dsh-fs-local'
+} from '../src/fsio.ts'
+import type { LocalTarget } from '../src/fsio.ts'
 import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs'
 
 let dir: string
@@ -146,6 +147,27 @@ describe('probe', () => {
   })
 })
 
+describe('probeNoFollow', () => {
+  it('reports symlinks without following them', async () => {
+    const real = join(dir, 'real.txt')
+    const link = join(dir, 'link.txt')
+    await writeFile(real, 'hi')
+    await symlink(real, link)
+
+    expect((await probeNoFollow(real))?.type).toBe('file')
+    const linkInfo = await probeNoFollow(link)
+    expect(linkInfo?.type).toBe('symlink')
+    expect(typeof linkInfo?.version).toBe('string')
+    expect(linkInfo?.size).toBeGreaterThan(0)
+  })
+
+  it('returns null for a missing path or a file-valued ancestor path segment', async () => {
+    expect(await probeNoFollow(join(dir, 'missing'))).toBeNull()
+    await writeFile(join(dir, 'afile'), 'i am a file')
+    expect(await probeNoFollow(join(dir, 'afile', 'child.txt'))).toBeNull()
+  })
+})
+
 describe('listDirectory', () => {
   it('lists direct children in stable order without reading content', async () => {
     const root = join(dir, 'skills')

packages/fs/fs-policy/README.md

@@ -37,7 +37,7 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a `WeakMap<owner, Map<targetKey, FsVersion>>`. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no `hasRead` flag and no `full`/`partial` view. This plugin does **no** filesystem I/O: "have you observed this file?" is a `WeakMap` lookup, and "is the version you read still current?" is decided inside `ctx.fs.editText`/`writeText` in the same atomic lock that performs the mutation — this plugin only supplies `vObserved` as the basis. A windowed read of lines 100-150 records the file's version, and a later edit of line 120 is authorized as long as the file is unchanged. State is held weakly and dropped on disposal (HMR safety); persistence across sessions is deferred.
+Observed state is a weak owner-to-target version map updated after every successful read or mutation; presence alone is the prior-observation record. The plugin performs no filesystem I/O: it supplies the observed version to the provider's atomic mutation guard. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
@@ -46,3 +46,18 @@ The `fs/write-intent`/`fs/edit-intent` slots hold exactly one decider — this p
 ## No method coupling
 
 Because the plugin influences the world only through events, removing it does not break `@deepseek-ai/dsh-tool-fs` at a service-injection boundary: the tool falls through to the bare `ctx.fs` provider (unconditional write/edit, no observed-state). Loading it back layers the policy on. That graceful add/remove is the whole point of the event gate over a mandatory method service.
+
+## Model Experience
+
+### Filesystem tool outcome
+
+**What the model sees**: This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper; observation state is never shown.
+
+**Token effect**: Zero tokens on allowed operations beyond the ordinary tool result. A denial adds the small retained error result and avoids any success payload.
+
+## Known Limitations and Deferred Work
+
+- **Observed state does not survive a session resume** — persistence of the `WeakMap` record is deferred, so a resumed session must re-read files before guarded writes/edits.
+- **Actors without an agent session can never satisfy the policy** — their edits throw `FS_NOT_OBSERVED` and their writes always resolve `createIfAbsent`, so a non-agent caller cannot overwrite an existing file through the gate.
+- **Direct `ctx.fs` reads emit no `fs/observed`** — a file read outside the `read` tool stays unobserved, and a later guarded edit rejects with `FS_NOT_OBSERVED` until the tool reads it.
+- **Authorization is version freshness, not view completeness** — any windowed read authorizes a full-file overwrite of an unchanged file, deliberately weaker than a full-view rule ([seam-split RFC](../../../docs/rfc/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)).

packages/fs/fs-policy/package.json

@@ -23,11 +23,11 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-fs": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   }
 }

packages/fs/fs-policy/src/index.ts

@@ -1,45 +1,8 @@
 /**
- * The fs-policy PLUGIN: observed-state, read-before-edit, and
- * "write/edit must be based on the version you read" — added on top of the
- * `ctx.fs` provider seam through the `fs/*` event gate, NOT through a method
- * service. This plugin registers NO `ctx.fsPolicy` service and exposes no
- * `read`/`write`/`edit`/`resolve` methods; it influences the world only by
- * deciding the `fs/write-intent`/`fs/edit-intent` waterfalls and
- * recording on `fs/observed`. That is what keeps `@deepseek-ai/dsh-tool-fs`
- * (the executor) free of any method coupling to the policy layer — removing
- * this plugin gracefully loses the policy and leaves the unconstrained bare
- * provider, rather than breaking the tool at a service-injection boundary.
- *
- * ## Observed state IS the prior-observation record
- *
- * State lives here as `WeakMap<owner, Map<targetKey, { version }>>`. An entry
- * exists iff the owner has read, written, OR edited that target (every success
- * emits `fs/observed`), so its presence means "this owner has observed this
- * target at this version". This is what lets a create-then-edit or
- * edit-then-edit sequence work without an intervening re-read: the mutation
- * refreshes the recorded version to its own result. The owner is derived
- * structurally from `{ agent?: { session? } }` and held weakly, so a collected
- * session frees its state; disposal drops everything (HMR safety).
- *
- * ## Freshness via provider CAS, not stat
- *
- * This plugin does NO filesystem I/O. "Have you observed this file?" is a
- * `WeakMap` lookup (no record ⇒ `FS_NOT_OBSERVED`). "Is the version you read
- * still current?" is decided INSIDE `ctx.fs.editText`/`writeText`, in the same
- * atomic lock that performs the mutation — this plugin only supplies the
- * observed version as the CAS basis. Stat-ing and comparing here would open a
- * TOCTOU gap the provider lock has to back up anyway, so it is deliberately
- * avoided.
- *
- * ## Single-slot, first-wins
- *
- * The `fs/write-intent`/`fs/edit-intent` listeners do NOT call
- * `next()`: each fully decides its single slot. The slot is first-wins by
- * registration order — this plugin owning it is the default-deployment
- * convention, not an event-enforced invariant (a decider registered before /
- * `prepend`ed would win instead). This is not a composable authorization chain;
- * layered permission/audit/sandbox interception belongs on `tools/execute`.
- *
+ * Event-only filesystem observation policy; it registers no service. A weak owner/target map
+ * records every successful read or mutation, single-slot intent listeners supply that version,
+ * and the provider performs the atomic freshness check. Without this plugin, tools retain the
+ * bare provider's unconditional mutation behavior. See the package README for composition rules.
  * @module @deepseek-ai/dsh-fs-policy
  */
 
@@ -145,15 +108,11 @@ export function apply(ctx: Context): void {
   // holds (a throw rejects, never escapes synchronously through the waterfall).
   ctx.on('fs/write-intent', (target, actor) => Promise.resolve().then(() => gate.writeIntent(target, actor)))
 
-  // fs/edit-intent: occupy the single decision slot — do NOT call next().
-  // Deferred the same way so an FS_NOT_OBSERVED throw becomes a rejected promise
-  // the edit tool's `await ctx.waterfall(...)` surfaces as its isError result.
+  // fs/edit-intent: occupy the single decision slot — do not call next().
   ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))
 
-  // fs/observed: synchronous, side-effect-only WeakMap write. The tool emits
-  // this with a plain (unguarded) ctx.emit, so this listener MUST NOT throw —
-  // a throw would surface as the tool's isError result for a mutation that
-  // already succeeded. A WeakMap.set honors that contract.
+  // fs/observed must remain synchronous and non-throwing: the mutation already succeeded, and
+  // emit does not await promises. WeakMap.set satisfies that contract.
   ctx.on('fs/observed', (target, version, actor) => {
     gate.observe(target, version, actor)
   })

packages/fs/fs-policy/tests/policy.spec.ts

@@ -1,14 +1,4 @@
-/**
- * Tests for the fs-policy PLUGIN: it registers no service, only the
- * three `fs/*` listeners. We dispatch those events directly (the unbound
- * waterfalls the tool would dispatch, and the `fs/observed` emit) and assert the
- * decisions: createIfAbsent vs replaceIfVersion, FS_NOT_OBSERVED for an unread
- * edit, observed-state-as-prior-observation (read/write/edit all record),
- * multi-owner isolation, single-slot first-wins, and disposal/HMR release.
- *
- * No `ctx.fs` provider is needed — the plugin does no filesystem I/O; it only
- * decides intents and records versions on its own WeakMap.
- */
+/** Event-level policy tests; no filesystem provider is needed because the plugin performs no I/O. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'

packages/fs/fs/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-fs
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, no-follow path metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam RFC](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam RFC](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam RFC](../../../docs/rfc/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate RFC](../../../docs/rfc/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
@@ -15,12 +15,13 @@ A future sandboxed, virtual, or remote backend implements this interface and the
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements seven primitives.
+A backend subclasses `FileSystem` and implements eight primitives.
 
 | Member | Semantics |
 |---|---|
-| `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default). Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
+| `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
@@ -41,4 +42,15 @@ This package declares three events (see the generated [events catalog](../../../
 
 ## Vocabulary
 
-`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids RFC](../../../docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy RFC](../../../docs/rfc/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids RFC](../../../docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy RFC](../../../docs/rfc/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
+
+## Known Limitations and Deferred Work
+
+- **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas RFC](../../../docs/rfc/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
+- **Eight primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing RFC](../../../docs/rfc/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
+- **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.

packages/fs/fs/package.json

@@ -24,11 +24,11 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   }
 }

packages/fs/fs/src/index.ts

@@ -1,59 +1,8 @@
 /**
- * The filesystem provider seam (`ctx.fs`): an abstract service defining the
- * text-storage primitives a backend provides — resolve a path into a stable
- * target, stat its metadata, read/stream its text, write it atomically with an
- * explicit intent, and apply a guarded literal edit — without saying HOW.
- * Implementations subclass {@link FileSystem} and register themselves as the
- * `fs` service; `@deepseek-ai/dsh-fs-local` (the host filesystem) is the first.
- * Future implementations swap in sandboxed, remote, virtual, or project-scoped
- * backends without touching the model-facing tool schemas
- * (`@deepseek-ai/dsh-tool-fs`).
- *
- * The split mirrors the bash seam (`BashExecutor`/`LocalBashExecutor`). See the
- * capability-seam RFC for why a swappable capability is three (here four)
- * packages.
- *
- * ## This is a provider seam, not the policy layer
- *
- * `ctx.fs` is deliberately close to fsspec-style storage primitives. It owns
- * UTF-8 decoding, binary/NUL rejection, atomic full-file writes, and the
- * literal-edit critical section — but NOT line windows, numbered lines,
- * rendered footers, or observed-state. Read windowing lives in the model-facing
- * tool (`@deepseek-ai/dsh-tool-fs`); observed-state and read-before-write/edit
- * are policy a plugin (`@deepseek-ai/dsh-fs-policy`) adds through the `fs/*`
- * event gate. So a sandboxed/remote backend inherits no model-facing observation
- * policy it has no business carrying.
- *
- * `editText` stays on this seam (not composed in the policy layer from a read
- * plus a write) because version guard + literal match + atomic rewrite must
- * stay inside one mutation critical section for correct error attribution and
- * one-wins/one-stale concurrency, and a remote backend may implement it as a
- * native compare-and-edit.
- *
- * ## The version guard is OPTIONAL — additive policy, not subtractive
- *
- * `ctx.fs` on its own is a complete, unconstrained text-storage seam: `read`
- * reads, `write` unconditionally creates-or-overwrites, `edit` unconditionally
- * replaces literal text in the current content. Both mutations take their
- * version guard as an OPTIONAL argument — omit it for the unconstrained
- * bare-provider behavior, supply it to guard against a concurrent change. The
- * mutation runs inside the backend's per-target lock either way, so an
- * unconditional write/edit is still atomic; "unconditional" drops the *version*
- * precondition, not the atomicity. Observed-state, read-before-edit, and
- * version-guarded write/edit are NOT provider behavior — they are policy a
- * plugin (`@deepseek-ai/dsh-fs-policy`) adds on top by supplying the guard.
- *
- * ## The fs policy events live here, not in the policy plugin
- *
- * This package owns the `fs/write-intent`, `fs/edit-intent`, and
- * `fs/observed` event vocabulary (see {@link Events}). The emitter is
- * `@deepseek-ai/dsh-tool-fs` and the default listener is
- * `@deepseek-ai/dsh-fs-policy`; the events live in the one package both
- * already depend on, so the emitter shares a vocabulary with the policy listener
- * without depending on the policy plugin. The events carry only `dsh-fs`
- * vocabulary plus an opaque `object` actor — no model-facing concepts (line
- * windows, numbered lines) and no agent/session owner structure leak down.
- *
+ * Filesystem text-storage provider seam. Backends own stable target identity,
+ * text decoding, binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText` remains
+ * here so version check, literal match, and rewrite share one critical section.
  * @module @deepseek-ai/dsh-fs
  */
 
@@ -63,6 +12,7 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsVersion,
   FsWriteIntent,
@@ -80,6 +30,7 @@ export type {
   FsDirEntry,
   FsErrorCode,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
@@ -92,44 +43,25 @@ declare module 'cordis' {
 
   interface Events {
     /**
-     * Single-slot decision: produce the write intent for the next
-     * {@link FileSystem.writeText}. The tool dispatches this as an unbound
-     * waterfall (no `this`) and supplies a default thunk returning `undefined`
-     * (unconditional create-or-overwrite — the bare provider). The
-     * `@deepseek-ai/dsh-fs-policy` policy listener returns `createIfAbsent`
-     * (unobserved actor) or `{ kind: 'replaceIfVersion', version: vObserved }`
-     * (observed) and does NOT call `next()` — one decision, not a composable
-     * chain. The slot is first-wins: the first non-`next()` decider (registration
-     * order, or `prepend`) occupies it; a second decider is a misconfiguration,
-     * not layering. `actor` is the opaque tool-execution context, never read here.
+     * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+     * `next()` yields the bare provider's unconditional write; the first listener
+     * that returns an intent owns the decision rather than composing with peers.
      * @param target - the resolved target about to be written.
      * @param actor - the opaque tool-execution context the decider keys off.
      * @mode waterfall
      */
     'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
     /**
-     * Single-slot decision: produce the optional version guard for the next
-     * {@link FileSystem.editText}. The tool dispatches this as an unbound
-     * waterfall and supplies a default thunk returning `undefined` (unconditional
-     * edit of the current content — the bare provider; no `stat`). The
-     * `@deepseek-ai/dsh-fs-policy` policy listener returns
-     * `{ version: vObserved }`, or throws `FS_NOT_OBSERVED` if the actor is unset
-     * or has not observed the target. Does NOT call `next()`: one decision,
-     * first-wins (see {@link Events.'fs/write-intent'}).
+     * Single-slot decision for the next {@link FileSystem.editText}. Calling
+     * `next()` yields an unconditional edit; the first returned guard wins.
      * @param target - the resolved target about to be edited.
      * @param actor - the opaque tool-execution context the decider keys off.
      * @mode waterfall
      */
     'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
     /**
-     * Record that an actor observed a target at a version, after a successful
-     * read/write/edit. Fire-and-forget (plain `emit`). A listener MUST be a
-     * synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s
-     * is a `WeakMap.set`): the tool does not guard the emit, so a listener that
-     * throws surfaces as the tool's `isError` result, and cordis `emit` does not
-     * await listener promises — async or fallible audit/telemetry does not
-     * belong here. No listener ⇒ nothing recorded. `actor` is the opaque
-     * tool-execution context.
+     * Record a successful observation. Listeners must be synchronous recorders:
+     * throws fail the tool call and returned promises are not awaited.
      * @param target - the target that was read/written/edited.
      * @param version - the version the actor now holds as its observation.
      * @param actor - the observing tool-execution context; undefined records nothing useful.
@@ -140,34 +72,10 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract filesystem provider service. Subclass, implement the seven storage
- * primitives, and load the subclass as a plugin — it registers as `ctx.fs` (one
- * implementation per context; loading a second throws, cordis' standard
- * duplicate-service behavior).
- *
- * Semantics every backend must honor:
- * - {@link resolve} returns a stable {@link FsTarget}; the same underlying file
- *   reached by different input paths must yield the same `targetKey` so stale
- *   guards and target lookup agree across paths (e.g. through symlinks).
- * - {@link stat} returns {@link FsInfo} metadata (never content) or `undefined`
- *   when the target is absent.
- * - {@link readText}/{@link streamText} read the whole regular text file (the
- *   stream for large files); both own regular-file checks, UTF-8 decoding,
- *   binary/NUL rejection, and `FS_NOT_TEXT`.
- * - {@link listDir} returns direct children of a directory in stable name order
- *   with resolved child targets and cheap metadata only. It never reads file
- *   contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw
- *   `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and
- *   other backend I/O failures throw `FS_IO_ERROR`.
- * - {@link writeText} is atomic temp-file + rename. `expected` is OPTIONAL:
- *   omit it for an unconditional create-or-overwrite (the bare-provider default),
- *   or supply a {@link FsWriteIntent} to guard the write.
- * - {@link editText} verifies `expected.version` BEFORE literal matching (so a
- *   stale edit reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND`/
- *   `FS_AMBIGUOUS_EDIT` against newer content), then applies literal replacement
- *   and writes atomically — all inside one mutation critical section. `expected`
- *   is OPTIONAL: omit it for an unconditional edit of the current content (a
- *   missing target still reports `FS_STALE_VERSION`).
+ * Abstract filesystem provider. Targets must preserve identity across aliases;
+ * reads expose regular UTF-8 text or typed errors, listings are stable and
+ * content-free, and mutations are atomic. Optional guards add stale protection
+ * without changing the unguarded provider contract.
  */
 export abstract class FileSystem extends Service {
   constructor(ctx: Context) {
@@ -175,23 +83,15 @@ export abstract class FileSystem extends Service {
   }
 
   /**
-   * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May
-   * perform I/O (a remote/sandboxed backend may need a round-trip to map a path
-   * to a stable identity), hence async even though the local backend only
-   * normalizes + realpaths.
+   * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+   * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+   * async even though the local backend only normalizes + realpaths.
    *
-   * `opts.cwd` is the base directory a RELATIVE `path` resolves against; an
-   * absolute `path` ignores it. Omitted ⇒ the backend's own default base (the
-   * local backend uses its configured `cwd`). The CALLER supplies this — the
-   * seam does not read a session or agent — so a tool can resolve against the
-   * caller's per-session workspace (`exec.agent.session.header.cwd`) without the
-   * provider depending on `dsh-agent`/`dsh-session`. Mirrors how `dsh-tool-bash`
-   * defaults a bash `workdir` to the session cwd.
    * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
-   * @param opts - `cwd` overrides the backend's default base for relative paths.
+   * @param opts - optional cwd override and cancellation signal.
    * @returns the stable target; the same file yields the same `targetKey`.
    */
-  abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
+  abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
   /**
    * Return target metadata, or `undefined` when the target does not exist.
@@ -201,6 +101,22 @@ export abstract class FileSystem extends Service {
    */
   abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
 
+  /**
+   * Return path metadata without following the final path component when it is a
+   * symbolic link. This is intentionally path-shaped, not target-shaped:
+   * {@link resolve} follows symlinks to produce the stable identity used by
+   * normal reads/writes, while `lstat` lets a consumer reject the path itself
+   * before that follow happens.
+   *
+   * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+   * absent.
+   * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+   * @param opts - `cwd` overrides the backend's default base for relative paths.
+   * @param signal - aborts the metadata round-trip.
+   * @returns metadata only, never content; undefined for an absent path.
+   */
+  abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
   /**
    * Read the whole regular text file as a single decoded string.
    * @param target - the resolved target to read.
@@ -230,10 +146,8 @@ export abstract class FileSystem extends Service {
   abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
 
   /**
-   * Create or fully replace a UTF-8 text file atomically. `expected` is the
-   * create-vs-replace decision and stale guard when supplied; OMITTING it is an
-   * unconditional create-or-overwrite (the bare provider — no version guard, no
-   * read-first requirement). Atomic either way.
+   * Atomically create or replace UTF-8 text. `expected` guards intent and
+   * staleness; omission allows unconditional overwrite.
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
@@ -243,11 +157,9 @@ export abstract class FileSystem extends Service {
   abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
 
   /**
-   * Apply a literal edit to an existing UTF-8 text file. When `expected` is
-   * supplied, verifies `expected.version` as the stale guard BEFORE literal
-   * matching; OMITTING it edits the current content unconditionally (no version
-   * guard). Either way applies the replacement and writes atomically — one
-   * mutation critical section — and a missing target reports `FS_STALE_VERSION`.
+   * Atomically edit literal text. When supplied, the version guard is checked
+   * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+   * the current content without a freshness precondition.
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.

packages/fs/fs/src/types.ts

@@ -1,21 +1,7 @@
 /**
- * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque
- * target/version identities, the metadata `stat` returns, the write-intent
- * and outcome shapes, the literal-edit request/outcome, and the typed error
- * taxonomy.
- *
- * These types are shared by every backend (`@deepseek-ai/dsh-fs-local` and
- * future sandboxed/remote backends) and by the policy layer
- * (`@deepseek-ai/dsh-fs-policy`). They are deliberately a *text-storage*
- * vocabulary half a level above byte-level fsspec: `readText`/`streamText` hand
- * back decoded text, never raw bytes. Host-path assumptions stay out — `targetKey`
- * and `version` are opaque branded tokens, and `displayPath` is the only field a
- * consumer may show.
- *
- * Model-facing concepts (line windows, numbered lines, observed-state) do NOT
- * live here; they belong to the consumer tool and the policy plugin
- * (`@deepseek-ai/dsh-tool-fs` / `@deepseek-ai/dsh-fs-policy`).
- *
+ * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque target/version
+ * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+ * literal-edit request/outcome, and the typed error taxonomy.
  * @module @deepseek-ai/dsh-fs/types
  */
 
@@ -41,16 +27,17 @@ export function FsTargetKey(key: string): FsTargetKey {
 
 /**
  * Opaque file-version token — the freshness token a write/edit guards against.
- * The local backend derives it from mtime+size; a remote backend might use a
- * revision id. The policy layer records it for stale checks; consumers may
- * display related metadata but MUST NOT interpret this token.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
  */
 export type FsVersion = Branded<'FsVersion'>
 
 /**
  * Brand a string as an {@link FsVersion}. For backend use only — a consumer
  * never manufactures a version, it receives one from `stat`/write/edit outcomes.
- * @param v - the backend's raw version string (the local backend derives it from mtime+size).
+ * @param v - the backend's raw version string.
  * @returns the same string, branded; no validation is performed.
  */
 export function FsVersion(v: string): FsVersion {
@@ -86,6 +73,21 @@ export interface FsInfo {
   size?: number
 }
 
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
+export interface FsPathInfo {
+  /** Opaque freshness token of the path entry right now. */
+  version: FsVersion
+  /** Whether the path entry is a regular file, directory, symlink, or other. */
+  type: 'file' | 'directory' | 'symlink' | 'other'
+  /** Byte size of the path entry, when the backend can report it. */
+  size?: number
+}
+
 /**
  * One direct child returned by {@link FileSystem.listDir}. Listing returns
  * metadata and resolved targets only; it must not read file contents.
@@ -104,17 +106,10 @@ export interface FsDirEntry {
 }
 
 /**
- * The explicit intent of a guarded {@link FileSystem.writeText} call.
- * `createIfAbsent` creates a missing target and rejects an existing one with
- * `FS_NOT_OBSERVED` (the path the policy plugin uses when the owner has no prior
- * read). `replaceIfVersion` replaces only when the target exists at the observed
- * version; a missing target or a version mismatch throws `FS_STALE_VERSION`.
- *
- * `writeText` takes this OPTIONALLY: omitting `expected` is the third,
- * unconstrained state — an unconditional create-or-overwrite (the bare
- * provider). The union itself carries only the two GUARDED intents; "no guard"
- * is expressed by omission, so the write and edit mutations share one symmetric
- * shape (`expected?`: omit = unconditional, present = guarded).
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
  */
 export type FsWriteIntent =
   | { kind: 'createIfAbsent' }

packages/fs/fs/tests/service.spec.ts

@@ -13,12 +13,13 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 
-/** A minimal in-memory fake implementing the seven provider primitives. */
+/** A minimal in-memory fake implementing the eight provider primitives. */
 class FakeFileSystem extends FileSystem {
   files = new Map<string, string>()
 
@@ -30,6 +31,11 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) return undefined
     return { version: FsVersion('v1'), type: 'file', size: content.length }
   }
+  override async lstat(path: string): Promise<FsPathInfo | undefined> {
+    const content = this.files.get(path)
+    if (content === undefined) return undefined
+    return { version: FsVersion('v1'), type: 'file', size: content.length }
+  }
   override async readText(target: FsTarget): Promise<string> {
     const content = this.files.get(target.targetKey)
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
@@ -120,6 +126,15 @@ describe('FileSystem provider seam', () => {
     const fs = ctx.fs as FakeFileSystem
     expect(await fs.stat(await fs.resolve('missing.txt'))).toBeUndefined()
   })
+
+  it('lstat returns path metadata before resolving a target', async () => {
+    const ctx = new Context()
+    await ctx.plugin(FakeFileSystem)
+    const fs = ctx.fs as FakeFileSystem
+    fs.files.set('a.txt', 'hi')
+    expect(await fs.lstat('a.txt')).toEqual({ version: 'v1', type: 'file', size: 2 })
+    expect(await fs.lstat('missing.txt')).toBeUndefined()
+  })
 })
 
 describe('branded id factories', () => {

packages/fs/tool-fs-search/README.md

@@ -44,3 +44,47 @@ Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMax
 ## Errors
 
 Search failures carry the package-owned `SearchError` (a `HarnessError` subclass), surfaced as `{ name, code }` on `isError` results: `SEARCH_INVALID_PATTERN` (ripgrep rejected the regex/glob), `SEARCH_FAILED` (runtime `rg` disappearance after registration, inaccessible target, signal kill, malformed `--json` output), `SEARCH_RAW_OUTPUT_OVERFLOW` (raw output over `rawOutputMaxBytes`, or still truncated after the requested stdout capture budget), and `SEARCH_ABORTED` (tool timeout, caller cancellation, or the bash executor's own timeout). ripgrep exit semantics are tool-owned: exit 0 is success with results, exit 1 is a successful empty search (`No files found` / `No matches found`), and only other exits are failures. Model argument mistakes (blank pattern, a list-valued `include`) stay ordinary tool argument errors.
+
+## Model Experience
+
+### System prompt
+
+**What the model sees**: After the load-time `rg` probe succeeds, every request in this plugin's registration scope contains the independently registered glob and grep guidance below. Agent-scoped tool restrictions can hide either schema without removing its prompt section.
+
+**Token effect**: Fixed guidance cost per request while the tools are registered.
+
+#### Glob guidance
+
+```markdown
+Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files.
+```
+
+#### Grep guidance
+
+```markdown
+Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context.
+```
+
+### Tool schemas
+
+**What the model sees**: The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) after the load-time `rg` probe succeeds and while this surface is visible.
+
+**Token effect**: Fixed schema cost on every request where the tools are visible.
+
+### Results and spill notices
+
+**What the model sees**: `glob` returns one path per line; `grep` groups `Line <line>: <preview>` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved.
+
+**Token effect**: Inline paths and matches are bounded by `globMaxResults`, `grepMaxMatches`, and `grepMaxLineBytes`; the call and retained result remain in history until compaction.
+
+### Tool errors
+
+**What the model sees**: Failures are normalized as `Error: <message>` with structured `SEARCH_INVALID_PATTERN`, `SEARCH_FAILED`, `SEARCH_RAW_OUTPUT_OVERFLOW`, or `SEARCH_ABORTED` metadata for callers.
+
+**Token effect**: Only a failing call adds these retained tokens.
+
+## Known Limitations and Deferred Work
+
+- **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation.
+- **Ripgrep is a deployment dependency** — a missing `rg` executable makes the package register no tools or guidance; an incompatible executable or one that disappears after registration fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located executor or another search consumer.
+- **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend.

packages/fs/tool-fs-search/tests/load-path.spec.ts

@@ -19,7 +19,7 @@ import Loader from '@cordisjs/plugin-loader'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
 
 const RG_PROBE_COMMAND = 'command -v rg >/dev/null 2>&1'
@@ -36,7 +36,6 @@ class ProbeSuccessBashExecutor extends BashExecutor {
       timeoutMs: request.timeoutMs ?? 60_000,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       signal: request.signal,
-      owner: request.owner,
       sandboxMode: request.sandboxMode,
     }
   }
@@ -56,28 +55,8 @@ class ProbeSuccessBashExecutor extends BashExecutor {
     })
   }
 
-  override start(): BashTask {
-    throw new Error('load-path guard must not start bash tasks')
-  }
-
-  override get(): BashTask | undefined {
-    return undefined
-  }
-
-  override ownerOf(): OwnerToken | undefined {
-    return undefined
-  }
-
-  override list(): BashTask[] {
-    return []
-  }
-
-  override readOutput(id: BashTaskId): BashTaskRead {
-    throw new Error(`unknown bash task ${id}`)
-  }
-
-  override kill(id: BashTaskId): boolean {
-    throw new Error(`unknown bash task ${id}`)
+  override start(): BashProcess {
+    throw new Error('load-path guard must not start background processes')
   }
 }
 

packages/fs/tool-fs-search/tests/tools.spec.ts

@@ -16,7 +16,7 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
 import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
 import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
@@ -72,7 +72,6 @@ class FakeBash extends BashExecutor {
       timeoutMs: request.timeoutMs ?? 60_000,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       signal: request.signal,
-      owner: request.owner,
       sandboxMode: request.sandboxMode,
     }
   }
@@ -85,25 +84,10 @@ class FakeBash extends BashExecutor {
     this.specs.push(spec)
     return this.handler(spec)
   }
-  override start(): BashTask {
+  override start(): BashProcess {
     this.startCalls++
     throw new Error('search tools must never start a background task')
   }
-  override get(): BashTask | undefined {
-    return undefined
-  }
-  override ownerOf(): OwnerToken | undefined {
-    return undefined
-  }
-  override list(): BashTask[] {
-    return []
-  }
-  override readOutput(id: BashTaskId): BashTaskRead {
-    throw new Error(`unknown bash task ${id}`)
-  }
-  override kill(id: BashTaskId): boolean {
-    throw new Error(`unknown bash task ${id}`)
-  }
 }
 
 /** A recording spill backend; arm `failWith` to script a storage failure. */

packages/fs/tool-fs/README.md

@@ -34,7 +34,7 @@ Field names are snake_case to match Claude Code and existing harness tool schema
 
 ## The tool is the executor; policy is an event gate
 
-The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash` (see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
+The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
 
 - **read** — one `ctx.fs.stat` (type + size routing + version), then `readText`/`streamText`, then builds the line window, then emits `fs/observed` with a plain `ctx.emit`. (1 stat.)
 - **write** — `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.writeText(target, content, intent)`, then `fs/observed`. (0 stat.)
@@ -46,4 +46,60 @@ The tool passes `exec` (the tool-execution context) as the opaque `actor` on eve
 
 `fs/observed` fires AFTER the read/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — async or fallible observation does not belong on this event.
 
-The read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them.
+The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them.
+
+## Model Experience
+
+### System prompt
+
+**What the model sees**: Every request in this plugin's registration scope receives the independently registered read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections.
+
+**Token effect**: Fixed guidance cost per request while the plugin is active, even when a restriction hides one or more tools.
+
+#### Read guidance
+
+```markdown
+Use the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.
+```
+
+#### Write guidance
+
+```markdown
+Use the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.
+```
+
+#### Edit guidance
+
+```markdown
+Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.
+```
+
+### Tool schemas
+
+**What the model sees**: The model sees the generated [`read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent.
+
+**Token effect**: Fixed schema cost on every request in that tool view.
+
+### Read result
+
+**What the model sees**: A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`.
+
+**Token effect**: Read output is capped by `readLimit`, `readMaxLineLength`, and `readMaxBytes`; the retained call and result are resent until compaction.
+
+### Write and edit results
+
+**What the model sees**: Write returns the exact five-line envelope `<path><displayPath></path>`, `<type>file</type>`, `<content>`, `Created file` or `Updated file`, then `</content>`. Edit returns exactly `The file <displayPath> has been updated successfully.` or, for `replace_all`, `The file <displayPath> has been updated. All occurrences were successfully replaced.` The full write or replacement text remains in the assistant tool-call arguments.
+
+**Token effect**: Success text is small, but large mutation arguments and any result are resent until compaction.
+
+### Tool errors
+
+**What the model sees**: Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs.
+
+**Token effect**: Only a failing call adds these retained tokens.
+
+## Known Limitations and Deferred Work
+
+- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
+- **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
+- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)).

packages/fs/tool-fs/package.json

@@ -31,11 +31,12 @@
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
@@ -44,6 +45,6 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
   }
 }

packages/fs/tool-fs/src/diff.ts

@@ -1,14 +1,6 @@
 /**
- * Result-time contextual-diff computation for the `write`/`edit` tools. Turns a
- * before/after pair of file texts into one {@link FileDiff} per applied hunk —
- * each hunk's `oldText`/`newText` reconstructed from the unified-diff lines with
- * ±{@link DIFF_CONTEXT} surrounding context lines, matching how claude-agent-acp
- * renders an editor inline diff.
- *
- * This is display-only presentation vocabulary (a UI concern), so it lives in
- * the model-facing tool, NOT the `dsh-fs` storage seam — the backend returns
- * only the raw before/after text (storage facts) and the tool computes the diff.
- *
+ * Result-time contextual diff presentation for write and edit. Storage returns before/after
+ * text; this model-facing layer derives one three-line-context card per applied hunk.
  * @module @deepseek-ai/dsh-tool-fs/src/diff
  */
 
@@ -29,18 +21,12 @@ export const DIFF_CONTEXT = 3
 export type FsDiffMeta = { diffs: FileDiff[] }
 
 /**
- * Compute one {@link FileDiff} per hunk between `before` and `after`, each
- * carrying the applied change plus {@link DIFF_CONTEXT} context lines. Returns an
- * empty array when the texts are identical (no hunks). For a scattered
- * `replace_all` edit the patch yields multiple hunks, so multiple `FileDiff`s
- * come back — matching the editor rendering one diff block per site.
+ * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
+ * applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
+ * patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
  *
- * Each hunk's `oldText` is its `-` (removed) and context lines joined by `\n`;
- * `newText` is its `+` (added) and context lines. A hunk with no old lines
- * (a pure insertion) reports `oldText: null` (nothing to diff against), mirroring
- * the call-time card's new-file convention. The unified-diff "\ No newline at end
- * of file" markers are dropped — they annotate the patch, not file content.
- * @param path - the path stamped on every produced diff (the model-facing `file_path`; the bridge relativizes it).
+ * @param path - the path stamped on every produced diff (the model-facing `file_path`; the
+ *   bridge relativizes it).
  * @param before - the file text before the change (the backend's LF-normalized diff basis).
  * @param after - the file text after the change, on the same basis.
  * @returns one diff per applied hunk, in file order; empty when the texts are identical.
@@ -81,14 +67,10 @@ function isFileDiff(value: unknown): value is FileDiff {
 }
 
 /**
- * Narrow an opaque `tool/result` `meta` back to this tool's {@link FileDiff}
- * hunks, or `undefined` when it is absent/malformed. `presentResult` runs on
- * arbitrary logged `meta` (possibly from an older shape or a hand-edited log), so
- * it validates defensively rather than trusting the payload — a bad `meta` yields
- * `undefined`, and the caller decides the fallback (edit → the generic result
- * rendering; write → an args-derived whole-file diff), never a thrown presenter.
- * @param meta - the opaque `tool/result` meta payload (live or replayed from the session log).
- * @returns the validated non-empty hunk list, or undefined for an absent/empty/malformed payload.
+ * Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
+ * returns `undefined` so presentation can fall back instead of throwing during replay.
+ * @param meta - result metadata.
+ * @returns validated hunks, or `undefined` for absent or malformed data.
  */
 export function diffsFromMeta(meta: unknown): FileDiff[] | undefined {
   if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined

packages/fs/tool-fs/src/edit.ts

@@ -1,14 +1,7 @@
 /**
- * The model-facing `edit` tool: update an existing UTF-8 text file by replacing
- * literal text, requiring a unique match by default. The tool is the executor:
- * it dispatches the `fs/edit-intent` waterfall to obtain the optional
- * version guard, calls `ctx.fs.editText` directly, and emits `fs/observed`. The
- * default thunk returns `undefined` (unconditional edit of the current content
- * — the bare provider); a policy plugin (`@deepseek-ai/dsh-fs-policy`)
- * occupies the single decision slot, returning `{ version: vObserved }` or
- * throwing `FS_NOT_OBSERVED` for an unread file. The tool stats ZERO times
- * either way; a missing target is reported by the provider as `FS_STALE_VERSION`.
- *
+ * Model-facing literal edit, unique-match by default. It obtains an optional guard from the
+ * single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
+ * version; no policy means an unconditional atomic edit.
  * @module @deepseek-ai/dsh-tool-fs/src/edit
  */
 
@@ -19,7 +12,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /** Validated `edit` arguments after defaulting. */
 interface EditInput {
@@ -82,8 +75,7 @@ export function applyEditTool(ctx: Context): void {
     },
     async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseEditArgs(args)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin returns { version: vObserved } or
       // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
       // No stat — the bare default never manufactures a version basis.
@@ -96,22 +88,16 @@ export function applyEditTool(ctx: Context): void {
       )
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // The result-time applied-hunk diff (before→after with context lines). An
-      // edit always changes content (parseEditArgs requires old_string to differ
-      // and editText matches at least once), so there is always at least one hunk.
-      // The bridge renders these as an inline diff that supersedes the call-time
-      // snippet; the display path is the model-facing `file_path` (the bridge
-      // relativizes it).
+      // An edit necessarily changes content, so result metadata carries at least one applied hunk.
       const diffs = computeHunkDiffs(input.filePath, outcome.before, outcome.after)
       return {
         content: [{ type: 'text', text: formatEditOutput(target.displayPath, input.replaceAll) }],
         meta: { diffs },
       }
     },
-    // Pure display: a diff card of the literal replacement (old_string →
-    // new_string), derived from the call args. `oldText: old_string || null`
-    // matches claude-agent-acp's Edit arm; new_string is a required arg here, so
-    // it maps straight to newText. A follow-along location points at the file.
+    // Pure display: a diff card of the literal replacement (old_string → new_string), derived
+    // from the call args. `oldText: old_string || null` matches claude-agent-acp's Edit arm;
+    // new_string is a required arg here, so it maps straight to newText.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -120,10 +106,8 @@ export function applyEditTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: the applied contextual-diff hunks carried on `meta`.
-    // On success with diffs, a `diff` result card supersedes the call-time
-    // snippet; on error (nothing applied) or malformed meta, fall through to the
-    // generic "updated successfully" rendering.
+    // Applied metadata replaces the call-time snippet; errors or malformed replay metadata use
+    // the generic result rendering.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

packages/fs/tool-fs/src/index.ts

@@ -1,24 +1,7 @@
 /**
- * The model-facing filesystem tool suite (`read`, `write`, `edit`) over the
- * `ctx.fs` provider seam. This single plugin registers all three tools.
- *
- * ## The tool is the executor; policy is an event gate
- *
- * The tool reads/writes/edits through `ctx.fs` DIRECTLY and owns model-facing
- * concerns only — tool names, JSON schemas, argument validation, prompt
- * sections, read windowing, result formatting. It does NOT inject a policy
- * service. Instead, on each write/edit it dispatches a single-slot waterfall
- * (`fs/write-intent`/`fs/edit-intent`) to obtain the OPTIONAL version guard, and
- * after every read/write/edit it emits `fs/observed` with a plain (unguarded)
- * `ctx.emit`. A policy plugin (`@deepseek-ai/dsh-fs-policy`) occupies the
- * decision slot and listens for `fs/observed` to add observed-state +
- * read-before-edit + version-guarded write/edit; a deployment that loads these
- * tools is expected to also load it. With no policy plugin the waterfalls fall
- * through to their `undefined` default (the unconstrained bare provider) and
- * `fs/observed` is unheard — the tool still functions. This package never
- * imports `node:fs`, `node:path`, or an `@deepseek-ai/dsh-fs-local`
- * implementation.
- *
+ * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+ * read windows, formatting, and observation events, never a concrete provider. An optional
+ * event policy supplies mutation guards; without one the tools use unconditional provider calls.
  * @module @deepseek-ai/dsh-tool-fs
  */
 
@@ -29,15 +12,6 @@ import { applyWriteTool } from './write.ts'
 import { applyEditTool } from './edit.ts'
 import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from './read-render.ts'
 
-export { READ_LIMIT, STREAM_MIN_SIZE, applyReadTool, parseReadArgs } from './read.ts'
-export type { ReadToolCaps } from './read.ts'
-export { applyWriteTool, formatWriteOutput, parseWriteArgs } from './write.ts'
-export { applyEditTool, formatEditOutput, parseEditArgs } from './edit.ts'
-export { READ_MAX_BYTES, READ_MAX_LINE_LENGTH, buildWindow, formatReadOutput } from './read-render.ts'
-export type { FileReadOutcome, FileTextLine, ReadWindow, WindowResult } from './read-render.ts'
-export { DIFF_CONTEXT, computeHunkDiffs, diffsFromMeta } from './diff.ts'
-export type { FsDiffMeta } from './diff.ts'
-
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'tool-fs'
 

packages/fs/tool-fs/src/read-render.ts

@@ -1,18 +1,7 @@
 /**
- * Cordis-free read rendering for `@deepseek-ai/dsh-tool-fs`: turn a file's
- * decoded text into a bounded, line-numbered window (offset/limit, byte cap,
- * per-line truncation) and format it as the model-facing text block. This is
- * the `read` tool's RENDERING detail — not a storage primitive, not freshness
- * policy — so it lives apart from the tool's I/O and event wiring as a pure,
- * independently-testable module (no cordis, no filesystem).
- *
- * The provider (`ctx.fs.readText`/`streamText`) hands back already-decoded text
- * (UTF-8 validated, binary rejected); {@link buildWindow} only scans that text
- * for newlines and builds the requested window. A capped line buffer means a
- * newline-free giant line can never balloon memory even when streamed.
- * {@link formatReadOutput} turns the resulting {@link FileReadOutcome} into the
- * `<path>/<content>` envelope the model sees.
- *
+ * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
+ * model-facing envelope. Chunk scanning caps the current line, so even one newline-free giant
+ * line cannot grow memory without bound.
  * @module @deepseek-ai/dsh-tool-fs/read-render
  */
 
@@ -113,12 +102,8 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
 }
 
 /**
- * Build a bounded, line-numbered window from a file's decoded text chunks.
- * Accepts an `AsyncIterable<string>` (a chunked `streamText`) or an
- * `Iterable<string>` (a whole-file `readText` wrapped as `[text]`), so one code
- * path serves both. Scans for newlines with a capped line buffer (a newline-free
- * giant line is truncated, never buffered past `request.maxLineLength`),
- * enforces the byte cap, and throws `FS_NOT_FOUND` for an offset past EOF.
+ * Build one window from streamed or whole-file chunks, enforcing line and byte caps and throwing
+ * `FS_NOT_FOUND` when the requested offset is past EOF.
  * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
  * @param request - the resolved window; the caller has already applied its defaults and caps.
  * @param displayPath - the caller-facing path used in the offset-out-of-range error.

packages/fs/tool-fs/src/read.ts

@@ -1,14 +1,6 @@
 /**
- * The model-facing `read` tool: inspect a UTF-8 text file and return
- * line-numbered content with pagination guidance. The tool is the executor — it
- * stats and reads through `ctx.fs` directly, builds the line window
- * ({@link module:@deepseek-ai/dsh-tool-fs/read-render}), and emits `fs/observed`
- * so a policy plugin (`@deepseek-ai/dsh-fs-policy`) can record the read. With
- * no policy plugin the emit is simply unheard. This module owns the
- * model-facing schema, argument validation, and the read I/O; the rendering
- * (windowing + formatting) lives in `read-render.ts` and the
- * freshness/observation policy is not its concern.
- *
+ * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+ * streams large or size-unknown files, renders a bounded window, then emits the observation.
  * @module @deepseek-ai/dsh-tool-fs/src/read
  */
 
@@ -21,7 +13,7 @@ import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { buildWindow, formatReadOutput } from './read-render.ts'
 import type { FileReadOutcome } from './read-render.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /** Default and maximum number of lines returned by one `read` call (the `readLimit` config). */
 export const READ_LIMIT = 2000
@@ -94,13 +86,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
     },
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseReadArgs(args, caps.limit)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
 
       // One stat: type check + size routing + the version recorded as observed.
-      // A writer racing between this stat and the read can at worst make a LATER
-      // guarded edit spuriously FS_STALE_VERSION (fail-closed: re-read; editText
-      // re-checks the version in its lock).
+      // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
       if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
@@ -128,12 +117,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       ctx.emit('fs/observed', target, info.version, exec)
       return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
     },
-    // Pure display: a generic card titled by the file with the read window
-    // appended (`Read foo.txt (5 - 8)`), `read` kind (icon), and a follow-along
-    // location whose line is the read's offset (defaulting to 1). The window is
-    // derived from the RAW args (offset/limit as the model passed them), NOT the
-    // tool's defaulted 1/configured limit, so an unbounded read shows a bare
-    // title (and the presenter stays a pure function of args, config-free).
+    // Pure display: a generic card titled by the file with the read window appended (`Read
+    // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
+    // read's offset (defaulting to 1). The window reflects raw args, so an omitted limit keeps
+    // the title bare instead of smuggling config into this pure presenter.
     presentCall(args): GenericCallView {
       const { offset, limit } = args
       const window = limit !== undefined && limit > 0

packages/fs/tool-fs/src/session-cwd.ts

@@ -1,18 +1,10 @@
 /**
- * Derive the working directory a filesystem tool resolves relative paths
- * against: the calling agent's per-session workspace
- * (`exec.agent.session.header.cwd`), so each ACP session's `read`/`write`/`edit`
- * act on ITS workspace, not the server's launch dir — mirroring how
+ * Derive the working directory a filesystem tool resolves relative paths against: the calling
+ * agent's per-session workspace (`exec.agent.session.header.cwd`), so each ACP session's
+ * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
  * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
- *
- * The `agent` is optional-chained — a non-agent caller yields `undefined`, and
- * the tool then calls `ctx.fs.resolve(path)` with no base so the backend applies
- * its own configured default (preserving the non-ACP / no-session behavior).
- * `session`/`header` are non-optional on a real `Agent`, so only `agent` needs
- * the guard (mirroring `dsh-tool-bash`'s `resolveWorkdir`). Returning `undefined`
- * rather than reading `process.cwd()` here keeps the default in ONE place (the
- * provider), per the "explicit > implicit at seams" convention.
- *
+ * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
+ * `process.cwd()` at the tool seam.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
  */
 
@@ -26,3 +18,16 @@ import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 export function sessionCwd(exec: ToolExecution): string | undefined {
   return exec.agent?.session.header.cwd
 }
+
+/**
+ * Resolution options shared by all model-facing filesystem tools.
+ * @param exec - the tool-execution context supplying session cwd and cancellation.
+ * @returns provider resolution options for the current tool call.
+ */
+export function sessionResolveOptions(exec: ToolExecution): { cwd?: string; signal?: AbortSignal } {
+  const cwd = sessionCwd(exec)
+  return {
+    ...cwd !== undefined ? { cwd } : {},
+    ...exec.signal !== undefined ? { signal: exec.signal } : {},
+  }
+}

packages/fs/tool-fs/src/write.ts

@@ -1,13 +1,7 @@
 /**
- * The model-facing `write` tool: create or fully replace a UTF-8 text file. The
- * tool is the executor: it dispatches the `fs/write-intent` waterfall to
- * obtain the optional version guard, calls `ctx.fs.writeText` directly, and
- * emits `fs/observed`. The default thunk returns `undefined` (unconditional
- * create-or-overwrite — the bare provider); a policy plugin
- * (`@deepseek-ai/dsh-fs-policy`) occupies the single decision slot and
- * returns `createIfAbsent`/`replaceIfVersion` instead. The tool stats ZERO
- * times either way.
- *
+ * Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+ * `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+ * unconditional atomic create-or-overwrite.
  * @module @deepseek-ai/dsh-tool-fs/src/write
  */
 
@@ -19,7 +13,7 @@ import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /**
  * Validate value constraints the schema DSL can't express: only a non-blank
@@ -67,28 +61,24 @@ export function applyWriteTool(ctx: Context): void {
     },
     async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseWriteArgs(args)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin produces createIfAbsent/
       // replaceIfVersion; the bare default is undefined (unconditional). No stat.
       const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)
       const outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal)
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // Attach a contextual hunk as `meta` ONLY for an overwrite (a before-version
-      // exists). A create has no "before" — `outcome.before` is null — so it
-      // carries no `meta`; `presentResult` then renders a whole-file diff from the
-      // args, so the completed card is still a diff (never the result text).
+      // Overwrites carry applied hunks. Creates have no prior text, so result presentation uses
+      // the args-derived whole-file diff instead.
       const diffs = outcome.before !== null ? computeHunkDiffs(input.filePath, outcome.before, outcome.after) : []
       return {
         content: [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }],
         ...diffs.length > 0 ? { meta: { diffs } } : {},
       }
     },
-    // Pure display: a diff card (an editor renders write as a new-file / full-
-    // replace diff). `oldText: null` — a call-time presenter has no access to the
-    // file's prior content, so even an overwrite renders new-file style, matching
-    // claude-agent-acp. A follow-along location points at the written file.
+    // Pure display: a diff card (an editor renders write as a new-file / full- replace diff).
+    // `oldText: null` — a call-time presenter has no access to the file's prior content, so
+    // even an overwrite renders new-file style, matching claude-agent-acp.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -97,14 +87,10 @@ export function applyWriteTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: a `diff` card so the completed `tool_call_update`
-    // re-installs the diff rather than the model-facing result text (an ACP
-    // `tool_call_update.content` REPLACES the call's content, so a text result
-    // would clobber the pending diff card). An OVERWRITE uses the applied
-    // contextual hunks on `meta`; a CREATE has no `meta` (no prior content), so
-    // its whole-file new-file diff is derived from `args.content` (replay-safe,
-    // matching the call-time card). An error falls through to generic rendering
-    // so its message shows.
+    // Result-time display: a `diff` card so the completed `tool_call_update` re-installs the
+    // diff rather than the model-facing result text (an ACP `tool_call_update.content` REPLACES
+    // the call's content, so a text result would clobber the pending diff card). Overwrites use
+    // applied metadata; creates and identical overwrites use the replay-safe args fallback.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

packages/fs/tool-fs/tests/diff.spec.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { computeHunkDiffs, diffsFromMeta, DIFF_CONTEXT } from '@deepseek-ai/dsh-tool-fs'
+import { computeHunkDiffs, diffsFromMeta, DIFF_CONTEXT } from '../src/diff.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 
 const lines = (n: number): string => Array.from({ length: n }, (_, i) => `line${i + 1}`).join('\n') + '\n'

packages/fs/tool-fs/tests/harness.ts

@@ -1,33 +1,20 @@
 import { Context } from 'cordis'
-import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 
 /**
- * Shared harness for the fs-tools with-key e2e: a minimal real agent stack (the
- * DeepSeek adapter + the real fs provider + the read-before-write/edit policy +
- * the model-facing read/write/edit tools). Lives outside the *.e2e.ts pattern so
- * importing it never re-registers another file's tests.
- *
- * `fsCwd` is the local backend's default base; a per-session cwd (set via a
- * session header) overrides it, but this harness creates agents without a
- * session cwd, so the provider default IS the workspace. `persona` is the
- * deployment persona (the system-prompt plugin's per-context config).
+ * Build the real fs-tool stack for with-key e2e tests. Agents have no session
+ * cwd, so `fsCwd` is their workspace; `persona` configures the deployment prompt.
+ * This helper lives outside the e2e glob so imports do not register tests.
  */
 export async function fsHarness(fsCwd: string, persona = ''): Promise<Context> {
   const ctx = new Context()
-  await ctx.plugin(LlmService)
-  await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt, { persona })
-  await ctx.plugin(ToolRegistry)
-  await ctx.plugin(AgentRegistry)
+  await mountAgentLoopTestDependencies(ctx, { systemPrompt: { persona } })
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
   await ctx.plugin(LocalFileSystem, { cwd: fsCwd })

packages/fs/tool-fs/tests/integration.spec.ts

@@ -1,16 +1,8 @@
 /**
- * Integration tests: the real local backend (`dsh-fs-local`) plus the model
- * tools (`dsh-tool-fs`) as the executor, exercised through `ctx.tools.execute()`
- * so nothing bypasses the tool registry. Two deployments:
- *
- *  - DEFAULT — with the real `dsh-fs-policy` policy gate plugin: read-before-
- *    write/edit, version-guarded mutation, FS_NOT_OBSERVED for unread edits.
- *  - BARE — WITHOUT the policy plugin: every `fs/*` waterfall falls through to
- *    its undefined default, so write/edit are unconditional. This proves the
- *    tool carries no dependency on the policy plugin.
- *
- * These verify the WORLD — files are read back from disk and asserted
- * byte-for-byte — not the tool's self-report.
+ * End-to-end tool-registry tests against the real local backend. The policy deployment verifies
+ * observed-state and guarded mutation; the bare deployment proves unconditional tools have no
+ * policy-service dependency. Assertions read files back byte-for-byte rather than trusting tool
+ * messages.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -28,9 +20,7 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 let dir: string
 let ctx: Context
 let fiber: Awaited<ReturnType<Context['plugin']>>
-// A stable session object stands in for an agent session (the file-state
-// owner). It carries a `header` (no `cwd`) so `sessionCwd(exec)` resolves to
-// `undefined` and the backend falls back to its configured cwd (= `dir`).
+// No header cwd: sessionCwd returns undefined and the provider's configured test dir applies.
 const session = { header: {} }
 
 let callCounter = 0
@@ -290,13 +280,9 @@ describe('bare provider (no dsh-fs-policy)', () => {
   })
 })
 
-// --------------------------------------------------------------------------
-// Per-session cwd: a relative file_path resolves against the CALLING session's
-// workspace (`exec.agent.session.header.cwd`), NOT the backend's config.cwd —
-// so an ACP editor's per-session dir wins, matching dsh-tool-bash. The regression
-// this guards: before the seam fix the tool passed no cwd, so a relative write
-// landed in config.cwd instead of the session dir.
-// --------------------------------------------------------------------------
+// Per-session cwd: a relative file_path resolves against the calling session's workspace
+// (`exec.agent.session.header.cwd`), not the backend's config.cwd — so an ACP editor's
+// per-session dir wins, matching dsh-tool-bash.
 describe('per-session cwd', () => {
   let sessionDir: string
   beforeEach(async () => {
@@ -399,9 +385,8 @@ describe('signal, concurrency, and the fs/observed contract', () => {
   })
 
   it('a throwing fs/observed listener surfaces as isError, but the mutation already hit disk', async () => {
-    // fs/observed is a plain ctx.emit AFTER the write succeeded; a throwing
-    // listener cannot roll the write back — it only turns the tool result into
-    // isError. The file must still carry the written bytes.
+    // fs/observed is a plain ctx.emit after the write succeeded; a throwing listener cannot
+    // roll the write back — it only turns the tool result into isError.
     ctx.on('fs/observed', () => { throw new Error('recording bug') })
     const result = await callOwned('write', { file_path: 'w.txt', content: 'durable' })
     expect(result.isError).toBe(true)

packages/fs/tool-fs/tests/read-render.spec.ts

@@ -6,8 +6,8 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { buildWindow, READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from '@deepseek-ai/dsh-tool-fs'
-import type { ReadWindow } from '@deepseek-ai/dsh-tool-fs'
+import { buildWindow, READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from '../src/read-render.ts'
+import type { ReadWindow } from '../src/read-render.ts'
 
 const DEFAULT_CAPS = { maxLineLength: READ_MAX_LINE_LENGTH, maxBytes: READ_MAX_BYTES }
 const READ_ALL: ReadWindow = { offset: 1, limit: 2000, ...DEFAULT_CAPS }

packages/fs/tool-fs/tests/tools.spec.ts

@@ -1,11 +1,6 @@
 /**
- * Consumer-surface tests for the filesystem tools as the EXECUTOR. They run the
- * REAL `@deepseek-ai/dsh-fs-policy` gate plugin (the genuine policy
- * collaborator, per the prefer-the-real-implementation rule) over a fake
- * `ctx.fs` provider, so they verify schemas, argument validation, result
- * formatting, FsError→isError propagation, and that each tool dispatches the
- * `fs/*` waterfalls + records observed-state through the gate (read authorizes a
- * later edit) — not just that it moved bytes.
+ * Consumer-surface tests over a fake provider and the real policy collaborator: schemas,
+ * validation, formatting, typed errors, intent dispatch, and observation-driven authorization.
  */
 
 import { describe, expect, it, vi } from 'vitest'
@@ -19,14 +14,16 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
-import { formatReadOutput, STREAM_MIN_SIZE } from '@deepseek-ai/dsh-tool-fs'
-import type { FileReadOutcome } from '@deepseek-ai/dsh-tool-fs'
+import { STREAM_MIN_SIZE } from '../src/read.ts'
+import { formatReadOutput } from '../src/read-render.ts'
+import type { FileReadOutcome } from '../src/read-render.ts'
 
 /** An in-memory fake provider; a test can arm a rejection on any primitive. */
 class FakeFs extends FileSystem {
@@ -48,6 +45,11 @@ class FakeFs extends FileSystem {
     if (content === undefined) return undefined
     return { version: FsVersion('v1'), type: 'file', size: content.length }
   }
+  override async lstat(path: string): Promise<FsPathInfo | undefined> {
+    const content = this.files.get(`key:${path}`)
+    if (content === undefined) return undefined
+    return { version: FsVersion('v1'), type: 'file', size: content.length }
+  }
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }
@@ -409,9 +411,8 @@ describe('tool-owned presentation (pure presentCall)', () => {
 })
 
 describe('result-time contextual diff (meta + presentResult)', () => {
-  // An edit records the applied contextual hunk on `tool/result` meta, and the
-  // tool's presentResult narrows it back into a `diff` result card the bridge
-  // renders. Drive execute end-to-end so the meta is the REAL computed hunk.
+  // An edit records the applied contextual hunk on `tool/result` meta, and the tool's
+  // presentResult narrows it back into a `diff` result card the bridge renders.
   const withContext = 'a\nb\nc\nOLD\nd\ne\nf\n'
 
   it('edit: execute attaches the applied hunk as meta { diffs }', async () => {
@@ -452,10 +453,9 @@ describe('result-time contextual diff (meta + presentResult)', () => {
   })
 
   it('write CREATE: no before-version → no meta, but presentResult still renders a whole-file diff card', async () => {
-    // A create has no prior content (no `meta`), yet the completed card must be a
-    // `diff` — an ACP tool_call_update.content REPLACES the call's content, so a
-    // non-diff result would clobber the pending new-file diff. The whole-file diff
-    // is derived from the args (oldText:null), replay-safe.
+    // A create has no prior content (no `meta`), yet the completed card must be a `diff` — an
+    // ACP tool_call_update.content REPLACES the call's content, so a non-diff result would
+    // clobber the pending new-file diff.
     const { ctx } = await setup()
     const session = { header: {} }
     const result = await call(ctx, 'write', { file_path: 'new.txt', content: 'fresh\n' }, { session })