refactor(fs): split filesystem seam into provider ctx.fs + policy ctx.fileContext

Implements the split-the-filesystem-seam RFC. ctx.fs shrinks to a text-storage
provider seam (resolve/stat/readText/streamText/writeText/editText with branded
FsTargetKey/FsVersion and an explicit FsWriteExpectation); the new
dsh-file-context package owns the model-facing policy (read windowing,
observed-state, write/edit freshness) as the concrete ctx.fileContext service.

Authorization is now freshness-based rather than full/partial view: a windowed
read records the file version and authorizes a later edit when the file is
unchanged, removing the dead-end where reading lines 100-150 of a large file
could not edit line 120. editText stays a provider primitive so version guard +
literal match + atomic rewrite remain one critical section, and the stale check
runs before matching so a stale edit reports FS_STALE_VERSION. tool-fs injects
fileContext, never reaching around to ctx.fs (the no-bypass contract).

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

@@ -1,8 +1,8 @@
 /**
  * The model-facing `edit` tool: update an existing UTF-8 text file by replacing
  * literal text, requiring a unique match by default. Execution goes through
- * `ctx.fs`, which enforces prior observation and the stale-version guard and
- * owns the literal-match semantics.
+ * `ctx.fileContext`, which enforces prior observation (the freshness policy)
+ * and delegates the literal-match + stale-guard critical section to `ctx.fs`.
  *
  * @module @deepseek-ai/dsh-tool-fs/edit
  */
@@ -60,8 +60,8 @@ export function apply(ctx: Context): void {
     },
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseEditArgs(args)
-      const target = await ctx.fs.resolve(input.filePath)
-      const outcome = await ctx.fs.edit(
+      const target = await ctx.fileContext.resolve(input.filePath)
+      const outcome = await ctx.fileContext.edit(
         target,
         { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
         exec,
@@ -76,7 +76,7 @@ export function apply(ctx: Context): void {
 export const name = 'fs-edit'
 
 /** Services required by the `edit` tool plugin. */
-export const inject = ['tools', 'fs', 'systemPrompt']
+export const inject = ['tools', 'fileContext', 'systemPrompt']
 
 /** Named helper for direct registration in the root plugin and tests. */
 export const applyEditTool = apply

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

@@ -1,13 +1,16 @@
 /**
  * The model-facing filesystem tool suite (`read`, `write`, `edit`) over the
- * `ctx.fs` seam. This root plugin registers all three tools by composing the
- * per-tool registration helpers; each tool is also exposed as a subpath plugin
- * (`@deepseek-ai/dsh-tool-fs/read`, `/write`, `/edit`) for focused deployments.
+ * `ctx.fileContext` policy layer. This root plugin registers all three tools by
+ * composing the per-tool registration helpers; each tool is also exposed as a
+ * subpath plugin (`@deepseek-ai/dsh-tool-fs/read`, `/write`, `/edit`) for focused
+ * deployments.
  *
  * The package owns model-facing concerns only — tool names, JSON schemas,
  * argument validation, prompt sections, result formatting. All filesystem
- * execution goes through `ctx.fs`; this package never imports `node:fs`,
- * `node:path`, or an `@deepseek-ai/dsh-fs-local` implementation.
+ * execution goes through `ctx.fileContext` (never directly around it to
+ * `ctx.fs`), so every model read records observed-state before rendering; this
+ * package never imports `node:fs`, `node:path`, or an
+ * `@deepseek-ai/dsh-fs-local` implementation.
  *
  * @module @deepseek-ai/dsh-tool-fs
  */
@@ -25,7 +28,7 @@ export { applyEditTool, formatEditOutput, parseEditArgs } from './edit.ts'
 export const name = 'tool-fs'
 
 /** Services required by the filesystem tool suite. */
-export const inject = ['tools', 'fs', 'systemPrompt']
+export const inject = ['tools', 'fileContext', 'systemPrompt']
 
 /** Register the full `read`/`write`/`edit` filesystem tool suite. */
 export function apply(ctx: Context): void {

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

@@ -1,8 +1,9 @@
 /**
  * The model-facing `read` tool: inspect a UTF-8 text file and return
  * line-numbered content with pagination guidance. Execution goes through
- * `ctx.fs` — this module owns only the model-facing schema, argument
- * validation, and result formatting, never filesystem I/O.
+ * `ctx.fileContext` (which records observed state and owns read windowing) —
+ * this module owns only the model-facing schema, argument validation, and
+ * result formatting, never filesystem I/O.
  *
  * @module @deepseek-ai/dsh-tool-fs/read
  */
@@ -10,7 +11,7 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { FsReadOutcome } from '@deepseek-ai/dsh-fs'
+import type { FileReadOutcome } from '@deepseek-ai/dsh-file-context'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 
 /** Default and maximum number of lines returned by one `read` call. */
@@ -40,7 +41,7 @@ export function parseReadArgs(args: { file_path: string; offset?: number; limit?
 }
 
 /** Format a read outcome as one OpenCode-style line-numbered text block body. */
-export function formatReadOutput(displayPath: string, outcome: FsReadOutcome): string {
+export function formatReadOutput(displayPath: string, outcome: FileReadOutcome): string {
   const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1)
   let footer: string
   if (outcome.truncatedByBytes) {
@@ -78,8 +79,8 @@ export function apply(ctx: Context): void {
     },
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseReadArgs(args)
-      const target = await ctx.fs.resolve(input.filePath)
-      const outcome = await ctx.fs.read(target, { offset: input.offset, limit: input.limit }, exec, exec.signal)
+      const target = await ctx.fileContext.resolve(input.filePath)
+      const outcome = await ctx.fileContext.read(target, { offset: input.offset, limit: input.limit }, exec, exec.signal)
       return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
     },
   }))
@@ -89,7 +90,7 @@ export function apply(ctx: Context): void {
 export const name = 'fs-read'
 
 /** Services required by the `read` tool plugin. */
-export const inject = ['tools', 'fs', 'systemPrompt']
+export const inject = ['tools', 'fileContext', 'systemPrompt']
 
 /** Named helper for direct registration in the root plugin and tests. */
 export const applyReadTool = apply

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

@@ -1,8 +1,8 @@
 /**
  * The model-facing `write` tool: create or fully replace a UTF-8 text file.
- * Execution goes through `ctx.fs`, which enforces the read-before-overwrite
- * policy (updating an existing file requires a prior read in the same
- * execution context; creating a new file does not).
+ * Execution goes through `ctx.fileContext`, which enforces the freshness policy
+ * (creating a new file needs no prior read; replacing an existing file requires
+ * a prior read in the same execution context at the unchanged version).
  *
  * @module @deepseek-ai/dsh-tool-fs/write
  */
@@ -46,8 +46,8 @@ export function apply(ctx: Context): void {
     },
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseWriteArgs(args)
-      const target = await ctx.fs.resolve(input.filePath)
-      const outcome = await ctx.fs.write(target, input.content, exec, exec.signal)
+      const target = await ctx.fileContext.resolve(input.filePath)
+      const outcome = await ctx.fileContext.write(target, input.content, exec, exec.signal)
       return [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }]
     },
   }))
@@ -57,7 +57,7 @@ export function apply(ctx: Context): void {
 export const name = 'fs-write'
 
 /** Services required by the `write` tool plugin. */
-export const inject = ['tools', 'fs', 'systemPrompt']
+export const inject = ['tools', 'fileContext', 'systemPrompt']
 
 /** Named helper for direct registration in the root plugin and tests. */
 export const applyWriteTool = apply