feat(tool-fs): result-time applied-hunk diffs for write/edit

fs write/edit now emit a result-time contextual-diff tool_call_update
(the applied hunk with ±3 context lines, one hunk per replace_all site),
matching what claude-agent-acp sends and what makes an editor render the
change in place. The call-time snippet diff stays; the result hunk
supersedes it (ACP content-replace).

Mechanism:
- A persisted tool-private `meta` channel: execute may return
  `{ content, meta }`; `meta` (JsonValue) rides on the tool/result event
  and is handed back to presentResult, so the diff reproduces on replay
  (event-sourced). JsonValue is now exported from dsh-session.
- The backend returns raw before/after text (storage facts) on
  FsWriteOutcome/FsEditOutcome; the tool computes the hunk via the npm
  `diff` package's structuredPatch. A create has no before → no result
  diff; a failed/aborted mutation carries no meta.
- ToolResultView gains a DiffResultView; the bridge's result-side switch
  renders it as {type:'diff'} content blocks.

RFC: docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
(justifies the npm `diff` runtime dep over vendoring and the meta channel);
the render-intent-union RFC's Non-goal is updated to record this shipped.
All fs snapshot goldens re-recorded; edit/overwrite gain the contextual
result diff, create/read/policy-reject unchanged in structure.

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

@@ -382,6 +382,25 @@ export async function readForEdit(
   return { content: normalizeLineEndings(raw), lineEndings: detectLineEndings(raw) }
 }
 
+/**
+ * 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 diff
+ * (the caller treats `null` the same as an absent file: call-time card only).
+ */
+export async function readTextForDiff(absolutePath: string, signal?: AbortSignal): Promise<string | null> {
+  const buffer = await readFileAbortable(absolutePath, 'read', signal)
+  if (buffer.includes(0)) return null
+  try {
+    return normalizeLineEndings(new TextDecoder('utf-8', { fatal: true }).decode(buffer))
+  } catch (error: unknown) {
+    /* v8 ignore next 2 -- TextDecoder({fatal}) only throws TypeError on invalid bytes; any other throw is an unreachable runtime fault. */
+    if (!(error instanceof TypeError)) throw error
+    return null
+  }
+}
+
 /**
  * Apply a literal replacement to LF-normalized content. Throws
  * `FS_EDIT_NOT_FOUND` on empty `oldString` or zero matches and

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

@@ -28,6 +28,7 @@ import {
   applyLiteralEdit,
   probe,
   readForEdit,
+  readTextForDiff,
   readWholeText,
   resolveLocalTarget,
   restoreLineEndings,
@@ -41,6 +42,7 @@ export {
   applyLiteralEdit,
   probe,
   readForEdit,
+  readTextForDiff,
   readWholeText,
   resolveLocalTarget,
   restoreLineEndings,
@@ -143,11 +145,18 @@ export class LocalFileSystem extends FileSystem {
       // provider) — no version guard, no read-first requirement. Still atomic
       // (the per-target lock is unconditional), so the write is never torn.
 
+      // 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 consumer renders no result-time diff for
+      // either, only the call-time whole-file card.
+      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)
       return {
         operation: existing ? 'update' : 'create',
         version: this.versionAfterWrite(after, target),
+        before,
+        after: content,
       }
     })
   }
@@ -183,6 +192,10 @@ export class LocalFileSystem extends FileSystem {
         replacements: edited.replacements,
         replaceAll: edit.replaceAll,
         version: this.versionAfterWrite(after, target),
+        // The LF-normalized before/after text (the applied-hunk diff basis);
+        // line-ending restoration is a storage detail the diff ignores.
+        before: original.content,
+        after: edited.content,
       }
     })
   }

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

@@ -188,6 +188,49 @@ describe('writeText', () => {
     await expect(fs.writeText(target, 'x')).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
   })
 
+  it('a create reports before:null and after = the written content (no prior file)', async () => {
+    const target = await fs.resolve('new.txt')
+    const outcome = await fs.writeText(target, 'fresh')
+    expect(outcome.before).toBeNull()
+    expect(outcome.after).toBe('fresh')
+  })
+
+  it('an overwrite reports before = the OLD content and after = the new content', async () => {
+    await writeFile(join(dir, 'a.txt'), 'old body')
+    const target = await fs.resolve('a.txt')
+    const outcome = await fs.writeText(target, 'new body')
+    expect(outcome.before).toBe('old body')
+    expect(outcome.after).toBe('new body')
+  })
+
+  it('an overwrite of a CRLF file returns LF-normalized before content', async () => {
+    await writeFile(join(dir, 'a.txt'), 'a\r\nb\r\n')
+    const target = await fs.resolve('a.txt')
+    const outcome = await fs.writeText(target, 'a\nB\n')
+    expect(outcome.before).toBe('a\nb\n')
+  })
+
+  it('an overwrite of a BINARY prior file reports before:null (undiffable), still succeeds', async () => {
+    await writeFile(join(dir, 'a.bin'), Buffer.from([0x00, 0x01, 0x02]))
+    const target = await fs.resolve('a.bin')
+    const outcome = await fs.writeText(target, 'now text')
+    expect(outcome.operation).toBe('update')
+    expect(outcome.before).toBeNull()
+    expect(outcome.after).toBe('now text')
+  })
+
+  it('an overwrite of an INVALID-UTF-8 (non-NUL) prior file reports before:null, still succeeds', async () => {
+    // 0xff is never valid UTF-8 but is not a NUL, so it exercises the decoder's
+    // fatal-throw path (not the NUL-scan short-circuit): an undiffable prior file
+    // still yields a successful write with no before-content basis.
+    await writeFile(join(dir, 'a.bin'), Buffer.from([0x68, 0xff, 0x69]))
+    const target = await fs.resolve('a.bin')
+    const outcome = await fs.writeText(target, 'now valid')
+    expect(outcome.operation).toBe('update')
+    expect(outcome.before).toBeNull()
+    expect(outcome.after).toBe('now valid')
+  })
+
   it('releases per-target mutation locks after success and failure', async () => {
     const target = await fs.resolve('a.txt')
     await fs.writeText(target, 'created', { kind: 'createIfAbsent' })
@@ -242,6 +285,17 @@ describe('editText', () => {
     expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello there')
   })
 
+  it('reports before/after content (the applied-hunk basis), LF-normalized', async () => {
+    await writeFile(join(dir, 'a.txt'), 'a\r\nOLD\r\nb\r\n')
+    const target = await fs.resolve('a.txt')
+    const outcome = await fs.editText(target, { oldString: 'OLD', newString: 'NEW', replaceAll: false })
+    expect(outcome.before).toBe('a\nOLD\nb\n')
+    expect(outcome.after).toBe('a\nNEW\nb\n')
+    // The written file keeps the original CRLF endings (before/after are the
+    // LF-normalized diff basis, not the on-disk bytes).
+    expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('a\r\nNEW\r\nb\r\n')
+  })
+
   it('checks the stale version BEFORE literal matching', async () => {
     await writeFile(join(dir, 'a.txt'), 'hello world')
     const target = await fs.resolve('a.txt')