fix(workspace-context): require explicit byte budgets

2026-07-12 12:09:35 +08:00
parent 855abe9d60
commit e9a54f0e71
32 changed files with 263 additions and 162 deletions
--- a/packages/prompt/workspace-context/README.md
+++ b/packages/prompt/workspace-context/README.md
@@ -48,7 +48,7 @@ The core `context/message` envelope is disabled for these messages because the p

 Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context returned by `tools/post-execute` but not yet appended by the loop.

-An unchanged path and SHA-256 content digest is not injected again. Resume works because visible metadata is persisted in the session log. Compaction re-arms a scope after its context event leaves the visible surface. A removal is a tombstone, so a later candidate reappearance is loaded again. Only changes actually rendered within the byte budget enter metadata and pending state; an omitted change remains eligible for a later touch.
+An unchanged path and SHA-1 content digest is not injected again. Resume works because visible metadata is persisted in the session log. Compaction re-arms a scope after its context event leaves the visible surface. A removal is a tombstone, so a later candidate reappearance is loaded again. Only changes actually rendered within the byte budget enter metadata and pending state; an omitted change remains eligible for a later touch.

 The frozen baseline itself is not rewritten mid-instance. Its initial path/digest map is retained as comparison state; the next successful filesystem touch appends any baseline replacement or removal. A resumed loop recomposes the current baseline and also reconciles still-visible dynamic scopes during prefix composition. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop composes its prefix.

@@ -58,12 +58,12 @@ The frozen baseline itself is not rewritten mid-instance. Its initial path/diges
 export interface Config {
  dshHome?: string
  projectRootMarkers?: string[]
-  maxBytes?: number
+  maxBytes: number
  instructionFileCandidates?: string[]
 }
 ```

-`projectRootMarkers` defaults to `['.git']`, `maxBytes` to `65536`, and `instructionFileCandidates` to `['AGENTS.md', 'CLAUDE.md']`. In each project directory, the first existing candidate wins; with defaults, `AGENTS.md` is native and `CLAUDE.md` is the compatibility fallback. Candidate entries must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored.
+`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory, the first existing candidate wins; with defaults, `AGENTS.md` is native and `CLAUDE.md` is the compatibility fallback. Candidate entries must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored.

 The user-global file is always `$DSH_HOME/AGENTS.md`; the candidate list only controls project scopes. `$DSH_HOME` defaults to `~/.dsh`, and configured `~`, `~/...`, and Windows-style `~\...` prefixes are expanded against the operating-system home directory. A non-positive or non-finite byte budget disables both baseline and dynamic loading.

@@ -71,7 +71,7 @@ The user-global file is always `$DSH_HOME/AGENTS.md`; the candidate list only co

 Rendering preserves the most specific instruction files first. It drops whole broader files before truncating the most-specific file and emits a visible `Workspace instruction budget ...` notice naming omitted and truncated paths. The rendered bytes never exceed `maxBytes`.

-File text is cached by normalized absolute path plus the provider's opaque version and optional size. A signature change causes a re-read. Discovery carries the signature into reading so a cache hit does not stat the same file twice in one pass. Cache identity is separate from loaded-state identity: persisted structured metadata, not cached prose, controls duplicate suppression.
+Each discovered candidate is read and identified by normalized absolute path, the provider's opaque version, and a SHA-1 content digest. Comparing the digest after reading prevents a same-version, same-size rewrite from returning stale cached text. Discovery carries the provider version into reading so one pass does not stat the same file twice. Cache identity is separate from loaded-state identity: persisted structured metadata, not cached prose, controls duplicate suppression.

 ## Non-goals

--- a/packages/prompt/workspace-context/src/config.ts
+++ b/packages/prompt/workspace-context/src/config.ts
@@ -1,7 +1,12 @@
+/**
+ * Configuration normalization for workspace instruction discovery and rendering.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/config
+ */
+
 import z from 'schemastery'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'

-const DEFAULT_MAX_BYTES = 64 * 1024
 const DEFAULT_PROJECT_ROOT_MARKERS = ['.git'] as const
 const DEFAULT_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.md', 'CLAUDE.md'] as const
 const RESERVED_PATH_SEGMENTS = new Set(['', '.', '..'])
@@ -12,8 +17,8 @@ export interface Config {
  dshHome?: string
  /** Directory entries that identify the project root while walking upward from the session cwd. */
  projectRootMarkers?: string[]
-  /** Maximum UTF-8 bytes in one rendered baseline or dynamic instruction batch; non-positive disables loading. */
-  maxBytes?: number
+  /** UTF-8 byte cap for one rendered baseline or dynamic batch; non-positive or non-finite disables loading. */
+  maxBytes: number
  /** Ordered same-directory project candidates; the first existing regular file wins in each scope. */
  instructionFileCandidates?: string[]
 }
@@ -21,28 +26,45 @@ export interface Config {
 export const Config: z<Config> = z.object({
  dshHome: z.string(),
  projectRootMarkers: z.array(z.string()).default([...DEFAULT_PROJECT_ROOT_MARKERS]),
-  maxBytes: z.number().default(DEFAULT_MAX_BYTES),
+  maxBytes: z.number().required(),
  instructionFileCandidates: z.array(z.string()).default([...DEFAULT_INSTRUCTION_FILE_CANDIDATES]),
 })

-/** Fully defaulted configuration used by discovery and reconciliation. */
-export interface ResolvedConfig {
+/** Normalized instruction discovery configuration. */
+export interface ResolvedDiscoveryConfig {
  dshHome: string
  projectRootMarkers: string[]
-  maxBytes: number
  instructionFileCandidates: string[]
 }

+/** Normalized configuration used by discovery and reconciliation. */
+export interface ResolvedConfig extends ResolvedDiscoveryConfig {
+  maxBytes: number
+}
+
 /**
 * Resolve defaults, the harness home, and valid same-directory candidates.
 * @param config - user-facing plugin configuration.
 * @returns normalized runtime configuration.
 */
 export function resolveConfig(config: Config): ResolvedConfig {
+  return {
+    ...resolveDiscoveryConfig(config),
+    maxBytes: config.maxBytes,
+  }
+}
+
+/**
+ * Resolve the subset of configuration used before instruction content is rendered.
+ * @param config - optional discovery controls.
+ * @returns normalized home, root markers, and instruction candidates.
+ */
+export function resolveDiscoveryConfig(
+  config: Pick<Config, 'dshHome' | 'projectRootMarkers' | 'instructionFileCandidates'>,
+): ResolvedDiscoveryConfig {
  return {
    dshHome: resolveDshHome(config.dshHome),
    projectRootMarkers: config.projectRootMarkers ?? [...DEFAULT_PROJECT_ROOT_MARKERS],
-    maxBytes: config.maxBytes ?? DEFAULT_MAX_BYTES,
    instructionFileCandidates: resolveInstructionFileCandidates(config.instructionFileCandidates),
  }
 }
--- a/packages/prompt/workspace-context/src/digest.ts
+++ b/packages/prompt/workspace-context/src/digest.ts
@@ -0,0 +1,16 @@
+/**
+ * Content identity for workspace instruction caching and duplicate suppression.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/digest
+ */
+
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute the content identity used across instruction loading and session state.
+ * @param content - exact UTF-8 instruction text.
+ * @returns lowercase SHA-1 digest in hexadecimal form.
+ */
+export function instructionContentSha1(content: string): string {
+  return createHash('sha1').update(content).digest('hex')
+}
--- a/packages/prompt/workspace-context/src/files.ts
+++ b/packages/prompt/workspace-context/src/files.ts
@@ -1,8 +1,15 @@
+/**
+ * Instruction-file discovery, provider reads, and content-aware caching.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/files
+ */
+
 import { lstat, readFile, stat } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import type { FileSystem, FsInfo, FsPathInfo, FsTarget } from '@deepseek-ai/dsh-fs'
 import { DEFAULT_DSH_HOME_DISPLAY, defaultDshHome } from '@deepseek-ai/dsh-paths'
-import { resolveConfig, type ResolvedConfig } from './config.ts'
+import { resolveConfig, resolveDiscoveryConfig, type ResolvedConfig } from './config.ts'
+import { instructionContentSha1 } from './digest.ts'
 import { renderWorkspaceContext, type RenderedWorkspaceContext } from './render.ts'

 /** An instruction candidate identified by absolute and model-facing paths. */
@@ -18,10 +25,10 @@ export interface LoadedInstructionFile extends InstructionFile {

 interface FileSignature {
  version: string
-  size: number | undefined
 }

 interface CachedContent extends FileSignature {
+  sha1: string
  content: string
 }

@@ -30,7 +37,7 @@ interface DiscoveredInstructionFile extends InstructionFile {
  target?: FsTarget
 }

-/** Provider-signature-keyed content cache shared across plugin hooks. */
+/** Provider-version and SHA-1 keyed content cache shared across plugin hooks. */
 export type InstructionContentCache = Map<string, CachedContent>

 interface DiscoverOptions {
@@ -41,7 +48,7 @@ interface DiscoverOptions {
 }

 interface LoadOptions extends DiscoverOptions {
-  maxBytes?: number
+  maxBytes: number
  cache?: InstructionContentCache
 }

@@ -61,7 +68,7 @@ async function nodeStatFile(path: string): Promise<FileSignature | undefined> {
  try {
    const info = await lstat(path)
    if (!info.isFile()) return undefined
-    return { version: `${info.mtimeMs}:${info.size}`, size: info.size }
+    return { version: String(info.mtimeMs) }
  } catch {
    // Candidates can disappear while discovery is in progress.
    return undefined
@@ -78,7 +85,7 @@ async function fsStatFile(
    const target = await fileSystem.resolve(path)
    const info = await fileSystem.stat(target)
    if (info?.type !== 'file') return undefined
-    return { version: info.version, size: info.size, target }
+    return { version: info.version, target }
  } catch {
    // Provider absence and discovery races are both non-fatal.
    return undefined
@@ -204,7 +211,7 @@ async function discoverInstructionFiles(
  options: DiscoverOptions,
  fileSystem?: FileSystem,
 ): Promise<DiscoveredInstructionFile[]> {
-  const config = resolveConfig(options)
+  const config = resolveDiscoveryConfig(options)
  const files: DiscoveredInstructionFile[] = []
  const seen = new Set<string>()
  const addFile = (file: DiscoveredInstructionFile): void => {
@@ -250,15 +257,14 @@ async function readCached(
 ): Promise<string | undefined> {
  const path = file.absolutePath
  const { signature } = file
-  const cached = cache.get(path)
-  if (cached !== undefined && cached.version === signature.version && cached.size === signature.size) {
-    return cached.content
-  }
  try {
    const content = fileSystem === undefined || file.target === undefined
      ? await readFile(path, 'utf8')
      : await fileSystem.readText(file.target)
-    cache.set(path, { ...signature, content })
+    const sha1 = instructionContentSha1(content)
+    const cached = cache.get(path)
+    if (cached !== undefined && cached.version === signature.version && cached.sha1 === sha1) return cached.content
+    cache.set(path, { ...signature, sha1, content })
    return content
  } catch {
    // A file may disappear or become unreadable after its metadata probe.
@@ -345,7 +351,7 @@ export async function loadScopeInstruction(
    const discovered: DiscoveredInstructionFile = {
      absolutePath,
      displayPath: scope === 'user-global' ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath),
-      signature: { version: info.version, size: info.size },
+      signature: { version: info.version },
      target,
    }
    const content = await readCached(discovered, cache, fileSystem)
--- a/packages/prompt/workspace-context/src/render.ts
+++ b/packages/prompt/workspace-context/src/render.ts
@@ -1,3 +1,9 @@
+/**
+ * Model-facing workspace instruction rendering within an explicit byte budget.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/render
+ */
+
 import { dirname } from 'node:path'
 import type { InstructionFile, LoadedInstructionFile } from './files.ts'

@@ -15,7 +21,7 @@ export interface TruncatedInstruction {
  includedBytes: number
 }

-/** Bounded model-facing text plus omitted and truncated source records. */
+/** Model-facing text plus omitted and truncated source records. */
 export interface RenderedWorkspaceContext {
  text: string
  omitted: InstructionFile[]
@@ -232,7 +238,7 @@ function renderInstructionContext(
 /**
 * Render the baseline instruction chain with deterministic precedence budgeting.
 * @param files - loaded files ordered from broadest to most specific.
- * @param options - rendering byte budget.
+ * @param options - required rendering byte budget.
 * @returns bounded baseline prompt text and budget diagnostics.
 */
 export function renderWorkspaceContext(
--- a/packages/prompt/workspace-context/src/state.ts
+++ b/packages/prompt/workspace-context/src/state.ts
@@ -1,10 +1,16 @@
-import { createHash } from 'node:crypto'
+/**
+ * Session-visible workspace instruction state and dynamic reconciliation.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/state
+ */
+
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
 import type { Message } from '@deepseek-ai/dsh-llm'
 import { renderContextContent, type JsonValue } from '@deepseek-ai/dsh-session'
 import type { FileSystem } from '@deepseek-ai/dsh-fs'
 import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import type { ResolvedConfig } from './config.ts'
+import { instructionContentSha1 } from './digest.ts'
 import {
  ancestorChain,
  descendantDirsBetween,
@@ -38,10 +44,6 @@ export interface WorkspaceHookContext extends HookContext {
  meta: JsonValue
 }

-function digest(content: string): string {
-  return createHash('sha256').update(content).digest('hex')
-}
-
 function workspaceContextHook(text: string, changes: WorkspaceInstructionChange[]): WorkspaceHookContext {
  const serializedChanges: JsonValue[] = changes.map(change => ({
    action: change.action,
@@ -154,7 +156,7 @@ export function baselineInstructionChanges(files: LoadedInstructionFile[]): Map<
      action: 'set',
      scope: scopeForDisplayPath(file.displayPath),
      path: file.displayPath,
-      digest: digest(file.content),
+      digest: instructionContentSha1(file.content),
    }
    return [change.scope, change]
  }))
@@ -181,7 +183,7 @@ function relativeScope(projectRoot: string, dir: string): string {
 * Compare visible/pending state with provider-visible files and render transitions.
 * @param agent - session owner whose visible surface supplies durable state.
 * @param resolved - normalized plugin configuration.
- * @param cache - shared provider-signature content cache.
+ * @param cache - shared provider-version and content-digest cache.
 * @param pendingBySession - short pending window before returned context is logged.
 * @param baselineBySession - frozen baseline comparison state per session.
 * @param fileSystem - provider used for current file probes.
@@ -245,7 +247,7 @@ export async function reconcileInstructionContext(
      }
      continue
    }
-    const currentDigest = digest(file.content)
+    const currentDigest = instructionContentSha1(file.content)
    if (previous !== undefined && previous.action !== 'remove' && previous.path === file.displayPath && previous.digest === currentDigest) continue
    const action = previous === undefined || previous.action === 'remove' ? 'set' : 'replace'
    const previousPath = action === 'replace' && previous !== undefined && previous.path !== file.displayPath
@@ -275,7 +277,7 @@ export async function reconcileInstructionContext(
 * @param exec - completed tool execution descriptor.
 * @param result - original tool result before post-execute decisions.
 * @param resolved - normalized plugin configuration.
- * @param cache - shared provider-signature content cache.
+ * @param cache - shared provider-version and content-digest cache.
 * @param pendingNestedChanges - per-session pending transition maps.
 * @param baselineInstructionStates - retained baseline comparison state.
 * @param fileSystem - provider used for current file probes.
--- a/packages/prompt/workspace-context/tests/workspace-context.e2e.ts
+++ b/packages/prompt/workspace-context/tests/workspace-context.e2e.ts
@@ -42,7 +42,7 @@ async function harness(): Promise<{ ctx: Context; agent: Agent }> {
  await ctx.plugin(AgentRegistry)
  await ctx.plugin(LocalFileSystem, { cwd: '/' })
  await ctx.plugin(ToolFs)
-  await ctx.plugin(WorkspaceContext)
+  await ctx.plugin(WorkspaceContext, { maxBytes: 65536 })
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
  const handle = ctx.agents.create({
--- a/packages/prompt/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/prompt/workspace-context/tests/workspace-context.spec.ts
@@ -1,4 +1,4 @@
-import { chmod, mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
@@ -219,7 +219,7 @@ describe('workspace context instruction discovery', () => {
    }
  })

-  it('re-walks the baseline path and re-reads content when file signatures change', async () => {
+  it('refreshes cached content after a same-version, same-size rewrite', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
    try {
@@ -228,19 +228,20 @@ describe('workspace context instruction discovery', () => {
      await mkdir(cwd, { recursive: true })

      const cache: InstructionContentCache = new Map()
-      expect(await loadBaselineInstructions({ cwd, dshHome: home, cache })).toBeUndefined()
+      expect(await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536, cache })).toBeUndefined()

      const leaf = join(cwd, 'AGENTS.md')
      await write(leaf, 'first')
-      const first = await loadBaselineInstructions({ cwd, dshHome: home, cache })
+      const first = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536, cache })
      expect(first?.text).toContain('first')
-      const cached = await loadBaselineInstructions({ cwd, dshHome: home, cache })
+      const cached = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536, cache })
      expect(cached?.text).toContain('first')

-      await new Promise(resolve => setTimeout(resolve, 5))
-      await writeFile(leaf, 'second and longer')
-      const second = await loadBaselineInstructions({ cwd, dshHome: home, cache })
-      expect(second?.text).toContain('second and longer')
+      const before = await stat(leaf)
+      await writeFile(leaf, 'other')
+      await utimes(leaf, before.atime, before.mtime)
+      const second = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536, cache })
+      expect(second?.text).toContain('other')
      expect(second?.text).not.toContain('first')
    } finally {
      await rm(root, { recursive: true, force: true })
@@ -259,7 +260,7 @@ describe('workspace context instruction discovery', () => {
      await write(leaf, 'secret-ish rule')
      await chmod(leaf, 0)

-      const loaded = await loadBaselineInstructions({ cwd, dshHome: home })
+      const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 })

      expect(loaded).toBeUndefined()
      await chmod(leaf, 0o600)
@@ -279,7 +280,7 @@ describe('workspace context instruction discovery', () => {
      await symlink(join(outside, 'secret.txt'), join(root, 'AGENTS.md'))

      const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home })
-      const loaded = await loadBaselineInstructions({ cwd: root, dshHome: home })
+      const loaded = await loadBaselineInstructions({ cwd: root, dshHome: home, maxBytes: 65536 })

      expect(files).toEqual([])
      expect(loaded).toBeUndefined()
@@ -299,7 +300,7 @@ describe('workspace context instruction discovery', () => {
      await write(join(outside, 'secret.txt'), 'outside secret')
      await symlink(join(outside, 'secret.txt'), join(root, 'AGENTS.md'))
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -655,11 +656,17 @@ describe('workspace context rendering', () => {
 })

 describe('workspace context request injection', () => {
+  it('requires an explicit maxBytes configuration', async () => {
+    const ctx = new Context()
+
+    await expect(ctx.plugin(workspaceContext, {} as workspaceContext.Config)).rejects.toThrow(/maxBytes/)
+  })
+
  it('mounts without requiring a filesystem provider', async () => {
    const ctx = new Context()
    try {
      const outcome = await Promise.race([
-        ctx.plugin(workspaceContext, {}).then(() => {
+        ctx.plugin(workspaceContext, { maxBytes: 65536 }).then(() => {
          return 'settled' as const
        }),
        new Promise<'pending'>((resolve) => {
@@ -682,7 +689,7 @@ describe('workspace context request injection', () => {
  it('does not inject baseline context when no filesystem provider is present', async () => {
    const ctx = new Context()
    try {
-      await ctx.plugin(workspaceContext, {})
+      await ctx.plugin(workspaceContext, { maxBytes: 65536 })
      const agent = stubAgent('/virtual/repo')

      await composeBaselinePrefix(ctx, agent)
@@ -696,7 +703,7 @@ describe('workspace context request injection', () => {
  it('leaves post-execute decisions unchanged when no filesystem provider is present', async () => {
    const ctx = new Context()
    try {
-      await ctx.plugin(workspaceContext, {})
+      await ctx.plugin(workspaceContext, { maxBytes: 65536 })

      const decision = await ctx.waterfall('tools/post-execute', {
        callId: CallId('no-fs-post-execute'),
@@ -725,7 +732,7 @@ describe('workspace context request injection', () => {
      await mkdir(join(root, '.git'), { recursive: true })
      await write(join(root, 'AGENTS.md'), 'repo rule')
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -750,7 +757,7 @@ describe('workspace context request injection', () => {
      await mkdir(join(root, '.git'), { recursive: true })
      await write(join(root, 'AGENTS.md'), 'repo rule')
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await composeBaselinePrefix(ctx, agent)
@@ -794,7 +801,7 @@ describe('workspace context request injection', () => {
      await mkdir(join(root, '.git'), { recursive: true })
      await write(join(root, 'AGENTS.md'), 'repo rule')
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => {
        const rest = await next()
        return [{ role: 'user', content: [{ type: 'text', text: '<system-reminder>Available skills</system-reminder>' }] }, ...rest]
@@ -819,7 +826,7 @@ describe('workspace context request injection', () => {
      await write(join(root, 'AGENTS.md'), 'old root rule')
      await write(join(root, 'file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -847,7 +854,7 @@ describe('workspace context request injection', () => {
      await write(join(root, 'AGENTS.md'), 'root rule')
      await write(join(root, 'file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -873,7 +880,7 @@ describe('workspace context request injection', () => {
      await write(join(root, 'AGENTS.md'), 'shared root and global rule')
      await write(join(root, 'file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: root })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: root, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -919,14 +926,14 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'ctx.fs rule' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)

      expect(derivedText(agent)).toContain('ctx.fs rule')
      expect(derivedText(agent)).not.toContain('node fs rule')
-      expect(fs.readTargets).toEqual([join(root, 'AGENTS.md')])
+      expect(fs.readTargets).toEqual([join(root, 'AGENTS.md'), join(root, 'AGENTS.md')])
    } finally {
      await rm(root, { recursive: true, force: true })
      await rm(home, { recursive: true, force: true })
@@ -942,13 +949,13 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'provider-only rule' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)

      expect(derivedText(agent)).toContain('provider-only rule')
-      expect(fs.readTargets).toEqual([join(root, 'AGENTS.md')])
+      expect(fs.readTargets).toEqual([join(root, 'AGENTS.md'), join(root, 'AGENTS.md')])
    } finally {
      await ctx.fiber.dispose()
      await rm(dirname(root), { recursive: true, force: true })
@@ -969,7 +976,7 @@ describe('workspace context request injection', () => {
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(home, 'AGENTS.md'), { type: 'file', content: 'ctx global rule' })
      fs.entries.set(join(root, 'CLAUDE.md'), { type: 'file', content: 'ctx claude rule' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -995,7 +1002,7 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'directory' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1019,7 +1026,7 @@ describe('workspace context request injection', () => {
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'directory' })
      fs.lstatTypes.set(join(root, 'AGENTS.md'), 'file')
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1042,7 +1049,7 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1065,7 +1072,7 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.throwOnStat.add(join(root, 'AGENTS.md'))
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1088,7 +1095,7 @@ describe('workspace context request injection', () => {
      const fs = ctx.fs as RecordingFileSystem
      fs.throwOnStat.add(join(root, '.git'))
      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'repo rule' })
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1110,7 +1117,7 @@ describe('workspace context request injection', () => {
      await write(join(repoA, 'AGENTS.md'), 'repo A only')
      await write(join(repoB, 'AGENTS.md'), 'repo B only')
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agentA = stubAgent(repoA)
      const agentB = stubAgent(repoB)

@@ -1138,7 +1145,7 @@ describe('workspace context request injection', () => {
      await write(join(cwd, 'AGENTS.md'), 'child schema default rule')
      const ctx = new Context()
      await ctx.plugin(LocalFileSystem, { cwd: '/' })
-      await ctx.plugin(workspaceContext, {})
+      await ctx.plugin(workspaceContext, { maxBytes: 65536 })
      const agent = stubAgent(cwd)

      await composeBaselinePrefix(ctx, agent)
@@ -1158,7 +1165,7 @@ describe('workspace context request injection', () => {
      await mkdir(join(root, '.git'), { recursive: true })
      await write(join(root, 'AGENTS.md'), 'repo rule')
      const ctx = new Context()
-      const fiber = await mountWorkspaceContext(ctx, { dshHome: home })
+      const fiber = await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      await fiber.dispose()
      const agent = stubAgent(root)

@@ -1215,7 +1222,7 @@ describe('workspace context request injection', () => {
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      const ctx = new Context()
-      await mountWorkspaceContext(ctx, { dshHome: home })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      await composeBaselinePrefix(ctx, agent)
@@ -1241,7 +1248,7 @@ describe('workspace context request injection', () => {
    }
  })

-  it('reuses the discovery lstat signature when reading cached content', async () => {
+  it('does not repeat a candidate metadata probe during one discovery and read pass', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
    try {
@@ -1263,9 +1270,9 @@ describe('workspace context request injection', () => {
      const isolated = await import('@deepseek-ai/dsh-workspace-context')
      const cache: InstructionContentCache = new Map()

-      await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, cache })
+      await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, maxBytes: 65536, cache })
      observedStats.clear()
-      await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, cache })
+      await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, maxBytes: 65536, cache })

      expect(observedStats.get(join(root, 'AGENTS.md'))).toBe(1)
    } finally {
@@ -1287,7 +1294,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const result = await ctx.tools.execute({
@@ -1316,7 +1323,7 @@ describe('dynamic nested workspace context injection', () => {
      const changeDigest = typeof firstChange === 'object' && firstChange !== null && !Array.isArray(firstChange)
        ? firstChange.digest
        : undefined
-      expect(changeDigest).toMatch(/^[a-f0-9]{64}$/)
+      expect(changeDigest).toMatch(/^[a-f0-9]{40}$/)
      const text = blocksText(result.additionalContext?.content)
      expect(text).toBe([
        '<system-reminder>',
@@ -1346,6 +1353,7 @@ describe('dynamic nested workspace context injection', () => {
      const ctx = new Context()
      await mountFileToolsAndWorkspaceContext(ctx, {
        dshHome: home,
+        maxBytes: 65536,
        instructionFileCandidates: ['CLAUDE.local.md', 'AGENTS.md', 'CLAUDE.md'],
      })

@@ -1374,7 +1382,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1406,7 +1414,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'old package rule')
      await write(join(root, 'pkg/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1446,7 +1454,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/CLAUDE.md'), 'fallback package rule')
      await write(join(root, 'pkg/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1485,7 +1493,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'package rule')
      await write(join(root, 'pkg/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1523,7 +1531,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'first package rule')
      await write(join(root, 'pkg/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1565,7 +1573,7 @@ describe('dynamic nested workspace context injection', () => {
      fs.entries.set(join(root, 'pkg/AGENTS.md'), { type: 'file', content: 'provider package rule' })
      fs.entries.set(join(root, 'pkg/file.txt'), { type: 'file', content: 'hello' })
      await ctx.plugin(ToolFs)
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const first = await ctx.tools.execute({
@@ -1594,7 +1602,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      const first = await ctx.tools.execute({
        callId: CallId('read-before-resume'),
@@ -1631,7 +1639,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'old nested rule')
      await write(join(root, 'pkg/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const original = stubAgent(root)
      const first = await ctx.tools.execute({
        callId: CallId('read-before-offline-change'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent: original,
@@ -1661,7 +1669,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      const first = await ctx.tools.execute({
        callId: CallId('read-before-compact'),
@@ -1709,7 +1717,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/sub/AGENTS.md'), 'subtree rule')
      await write(join(root, 'pkg/sub/file.txt'), 'subtree file')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      const first = await ctx.tools.execute({
        callId: CallId('read-package'),
@@ -1780,7 +1788,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      agent.session.append('context/message', {
        content: [
@@ -1838,7 +1846,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)

      const rootResult = await ctx.tools.execute({
@@ -1872,7 +1880,7 @@ describe('dynamic nested workspace context injection', () => {
      fs.entries.set(join(root, '.git'), { type: 'directory' })
      fs.lstatTypes.set(join(root, 'pkg/AGENTS.md'), 'file')
      fs.throwOnStat.add(join(root, 'pkg/AGENTS.md'))
-      await ctx.plugin(workspaceContext, { dshHome: home })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      const result = {
        callId: CallId('provider-probe-result'),
@@ -1908,7 +1916,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      await chmod(nested, 0)
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })

      const result = await ctx.tools.execute({
        callId: CallId('read-with-unreadable-nested-instruction'),
@@ -1934,7 +1942,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      ctx.on('tools/post-execute', async () => ({
        kind: 'accept' as const,
        content: [{ type: 'text' as const, text: 'downstream replacement' }],
@@ -1977,7 +1985,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      ctx.on('tools/post-execute', async () => ({
        kind: 'block' as const,
        feedback: [{ type: 'text' as const, text: 'blocked downstream' }],
@@ -2010,7 +2018,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      const agent = stubAgent(root)
      const result = {
        callId: CallId('manual'),
@@ -2073,7 +2081,7 @@ describe('dynamic nested workspace context injection', () => {
      await mkdir(join(root, '.git'), { recursive: true })
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })

      const result = await ctx.tools.execute({
        callId: CallId('read-missing'),
@@ -2098,7 +2106,7 @@ describe('dynamic nested workspace context injection', () => {
      await write(join(root, 'pkg/AGENTS.md'), 'nested package rule')
      await write(join(root, 'pkg/deep/file.txt'), 'hello')
      const ctx = new Context()
-      const fiber = await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home })
+      const fiber = await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
      await fiber.dispose()

      const result = await ctx.tools.execute({