fix(workspace-context): reconcile resumed baselines

2026-08-15 21:04:50 +00:00 · 2026-08-04 23:11:15 +08:00
parent 01fa4ceb6e
commit 119c55e35e
16 changed files with 463 additions and 51 deletions
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md
-2026-06-24-workspace-context.md: a9d11f88ab9525a40f9bc58f817a088edc43105a
-2026-06-24-workspace-context.zh.md: 1273bd9b460055a4b0e193267c5e9ad37bbeb0a2
+2026-06-24-workspace-context.md: 6fb739bf9a3bd508859c7ba4df499c847eba0570
+2026-06-24-workspace-context.zh.md: 51e43a4f2fcfa61973a9cc025a2c37818eb56bd1
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
@@ -32,7 +32,7 @@ At the first `agent/step` of a fresh session, the plugin injects one sourced use

 The injection becomes a durable `user/message` with a typed `workspace-instructions` source. Its `baseline: true` marker distinguishes a complete baseline from later deltas, and its change list persists the included scopes and content digests. In the product spine workspace instructions are registered before the skills catalog, so their `agent/step` listener injects first. The loop drains both messages before deriving the first request.

-A resumed agent creates a new loop instance over persisted history. If a typed baseline remains in the visible surface, the loop retains that event and reconciles baseline plus dynamic scopes against current files before its first request. Unchanged files append nothing; files added, edited, or removed while the agent was offline append `set`, `replace`, or `remove` transitions without mutating or duplicating the original baseline. A hot plugin remount follows the same visibility rule. If no typed baseline remains visible, as after compaction shadows it, the loop composes and injects one complete current baseline.
+A resumed agent creates a new loop instance over persisted history. If a typed baseline remains in the visible surface and its persisted discovery, precedence, and budget identity matches current configuration, the loop retains that event and reconciles dynamic scopes plus the baseline files retained by the current complete rendering before its first request. Unchanged files and budget-omitted files append nothing; files added, edited, removed, or dropped from the retained set while the agent was offline append `set`, `replace`, or `remove` transitions without mutating or duplicating the original baseline. An incompatible visible baseline is superseded by one recomposed complete baseline in current precedence order, with explicit model-facing replacement language; an empty current candidate set emits an explicit clear baseline. A hot plugin remount follows the same compatibility rule. If no typed baseline remains visible, as after compaction shadows it, the loop composes and injects one complete current baseline.

 Compaction can shadow the baseline after this plugin's guarded `agent/step` listener has already run for the session. The `system-prompt/assemble` waterfall therefore delegates first, but restores only for an assembly explicitly marked for the loop's next model request; diagnostic assemblies remain read-only. When a prior typed baseline exists but none remains visible, the listener recomposes the current chain, rechecks cancellation and the current surface generation after every asynchronous probe, and injects before the loop drains its outbox and snapshots derived request history. A per-session settled marker prevents repeated preparation when the current generation produced no baseline; a separate queued marker plus the synchronous commit-time recheck lets concurrent preparations scan without queuing duplicate baselines.

@@ -84,7 +84,7 @@ Workspace guidance is isolated per session and shared by the demo front doors, W

 Repository text remains untrusted input. Lower-authority user-role framing, explicit precedence language, and delimiter escaping reduce risk but do not eliminate prompt injection. Following a candidate symlink to its target widens that surface to off-tree content, so the permission and sandbox layers that confine `ctx.fs` to trusted roots are the boundary that treats workspace files as data rather than authority (the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns the residual risk).

-The system is event-driven rather than watch-driven. Edits are not visible at the exact filesystem mutation instant unless that mutation goes through a structured tool; externally changed baseline files are also noticed when a surface replacement or resume triggers recomposition. This keeps the design deterministic and provider-neutral.
+The system is event-driven rather than watch-driven. Edits are not visible at the exact filesystem mutation instant unless that mutation goes through a structured tool; externally changed baseline files are also noticed when a surface replacement recomposes the baseline or resume reconciles its current retained set. This keeps the design deterministic and provider-neutral.

 ## Deferred

--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -32,7 +32,7 @@ Status: implemented

 该注入成为一条持久 `user/message`，并携带带类型的 `workspace-instructions` 来源。其 `baseline: true` 标记将完整基线与后续增量区分开来，变更列表则持久保存已纳入的作用域和内容 digest。在产品主干中，工作区指令的注册先于 skill 目录，所以其 `agent/step` 监听器先注入。循环会在派生第一次请求前 drain 这两条消息。

-恢复 agent 会基于持久化历史创建新的 loop 实例。如果带类型的基线仍位于可见表层，loop 会保留该事件，并在第一个请求前根据当前文件对账基线与动态 scope。未变文件不追加任何内容；agent 离线期间新增、编辑或移除的文件会追加 `set`、`replace` 或 `remove` 转换，既不改写也不重复追加原始基线。插件热重挂遵循相同的可见性规则。如果已无带类型的基线可见（例如压缩（compaction）将其遮蔽后），loop 会组合并注入一条完整的当前基线。
+恢复 agent 会基于持久化历史创建新的 loop 实例。如果带类型的基线仍位于可见表层，且其持久化的发现、优先顺序和预算标识与当前配置匹配，loop 会保留该事件，并在第一个请求前对账动态 scope 与当前完整渲染所保留的基线文件。未变文件和预算省略的文件都不追加任何内容；agent 离线期间新增、编辑、移除或从保留集中退出的文件会追加 `set`、`replace` 或 `remove` 转换，既不改写也不重复追加原始基线。不兼容的可见基线会被一条按当前优先顺序重新组合的完整基线取代，并以面向模型的明确措辞说明替换关系；当前候选集为空时，则会发出一条显式清除基线。插件热重挂遵循相同的兼容性规则。如果已无带类型的基线可见（例如压缩（compaction）将其遮蔽后），loop 会组合并注入一条完整的当前基线。

 在本插件带防护的 `agent/step` 监听器已经为该会话运行后，压缩仍可能遮蔽基线。因此，`system-prompt/assemble` waterfall（瀑布式事件）会先委托，但只有当组装被明确标记为供 loop 的下一个模型请求使用时才恢复；诊断组装保持只读。如果此前存在带类型的基线、但已无基线可见，该监听器会重新组合当前文件链，在每次异步探测后重新检查取消状态和当前表层代次，并在 loop 排空 outbox 和对派生请求历史创建快照之前注入。逐会话的已结算标记会在当前代次没有产生基线时避免重复准备；单独的排队标记加上提交时同步复查，使并发准备可以扫描而不会排入重复基线。

@@ -84,7 +84,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，

 仓库文本仍是不受信任的输入。低权威 user 角色框架、显式优先级说明和分隔符转义可以降低风险，但无法消除提示词注入。跟随候选符号链接到目标，会把该接口扩大至树外内容；因此，把 `ctx.fs` 限制在可信根目录内的权限与沙箱层才是真正的边界，它们让系统把工作区文件当作数据而不是权威（[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明残余风险）。

-系统由事件驱动，而不是文件监视器驱动。除非文件系统变更通过结构化工具完成，否则编辑不会在确切的文件系统变更时刻可见；表层替换或恢复触发重新组合时，也会发现外部变更的基线文件。这使设计保持确定性并且与提供方无关。
+系统由事件驱动，而不是文件监视器驱动。除非文件系统变更通过结构化工具完成，否则编辑不会在确切的文件系统变更时刻可见；表层替换重新组合基线，或恢复过程对账当前保留集时，也会发现外部变更的基线文件。这使设计保持确定性并且与提供方无关。

 ## 延后事项

--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2256,7 +2256,7 @@ export interface Config {
 }
 ```

-Source: [`packages/context/workspace-context/src/config.ts:17`](../packages/context/workspace-context/src/config.ts)
+Source: [`packages/context/workspace-context/src/config.ts:18`](../packages/context/workspace-context/src/config.ts)

 ## Loadable plugins with no config

--- a/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/session.expected.jsonl
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/session.expected.jsonl
@@ -1,7 +1,7 @@
 {"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
 {"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
 {"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Remember the workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
-{"type":"user/message","seq":2,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nOld workspace instruction.\n</system-reminder>"}],"source":{"kind":"workspace-instructions","baseline":true,"changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"ba65bdb41810f4d0129129dcbd6cadcd643c069d"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":2,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nOld workspace instruction.\n</system-reminder>"}],"source":{"kind":"workspace-instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"ba65bdb41810f4d0129129dcbd6cadcd643c069d"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"turn/end","seq":3,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
 {"type":"session/end-seed","seq":4,"time":0,"data":{}}
 {"type":"turn/start","seq":5,"time":0,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}}
--- a/examples/headless-agent/tests/workspace-context-resume-snapshots/precedence-change/session.expected.jsonl
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/precedence-change/session.expected.jsonl
@@ -0,0 +1,20 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Remember the workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":2,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: CLAUDE.md\n\nOld CLAUDE rule.\n\nInstructions from: AGENTS.md\n\nOld AGENTS rule.\n</system-reminder>"}],"source":{"kind":"workspace-instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"CLAUDE.md\",\"AGENTS.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000CLAUDE.md","path":"CLAUDE.md","digest":"b525eb8a6d3660b732dad4b0aff1b7c63ab32890"},{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"3113bd093ae91976207dcef7390bdc0b2bfcfa10"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"turn/end","seq":3,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session/end-seed","seq":4,"time":0,"data":{}}
+{"type":"turn/start","seq":5,"time":0,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":6,"time":0,"data":{"content":[{"type":"text","text":"Acknowledge the current workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":7,"time":0,"data":{"title":"Remember the workspace instruction.","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThis complete workspace instruction baseline replaces all earlier workspace instruction baselines. The following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nCurrent AGENTS rule.\n\n\nInstructions from: CLAUDE.md\n\nCurrent CLAUDE rule.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"7f53d2327837129750aef117f9754a001c46cf68"},{"action":"set","scope":".\u0000CLAUDE.md","path":"CLAUDE.md","digest":"5b1e9e3fd759eee6b43ceff899e47fb10c64701a"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"step/start","seq":9,"time":0,"data":{"turn":2,"step":1}}
+{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}"},"reason":"initial"}}
+{"type":"request/context","seq":11,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RESUME_DONE"}}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RESUME_DONE"}}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":16,"time":0,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RESUME_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"}},"sourceEventSeqs":[12,13,14,15],"surfaceOp":"append"}
+{"type":"step/end","seq":17,"time":0,"data":{"turn":2,"step":1}}
+{"type":"turn/end","seq":18,"time":0,"data":{"turn":2,"reason":{"kind":"completed"}}}
--- a/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
+++ b/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
@@ -19,12 +19,14 @@ import SessionStore, {
 } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { renderWorkspaceContext } from '@deepseek-ai/dsh-workspace-context'
+import { resolveConfig, workspaceBaselineIdentity } from '@deepseek-ai/dsh-workspace-context/src/config.ts'
 import { describe, expect, it } from 'vitest'

 const fixtureDir = join(dirname(fileURLToPath(import.meta.url)), 'workspace-context-resume-snapshots/offline-edit')
 const replayFixture = join(fixtureDir, 'replay.jsonl')
 const replayOverride = join(fixtureDir, 'replay.override.json')
 const sessionExpected = join(fixtureDir, 'session.expected.jsonl')
+const precedenceExpected = join(dirname(fixtureDir), 'precedence-change/session.expected.jsonl')
 const configPath = fileURLToPath(new URL('../workspace-context-resume.cordis.snapshot.yml', import.meta.url))
 const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
@@ -33,7 +35,16 @@ const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 const oldInstruction = 'Old workspace instruction.'
 const newInstruction = 'New workspace instruction after offline edit.'

-async function seedVisibleBaseline(root: string, cwd: string): Promise<string> {
+interface SeedBaselineOptions {
+  files?: Array<{ name: string; content: string }>
+  instructionFileCandidates?: string[]
+}
+
+async function seedVisibleBaseline(
+  root: string,
+  cwd: string,
+  options: SeedBaselineOptions = {},
+): Promise<string> {
  const ctx = new Context()
  await ctx.plugin(SessionStore)
  await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
@@ -44,11 +55,19 @@ async function seedVisibleBaseline(root: string, cwd: string): Promise<string> {
    cwd,
    delegationDepth: 0,
  }
-  const baseline = renderWorkspaceContext([{
-    absolutePath: join(cwd, 'AGENTS.md'),
-    displayPath: 'AGENTS.md',
-    content: oldInstruction,
-  }], { maxBytes: 65536 })
+  const files = options.files ?? [{ name: 'AGENTS.md', content: oldInstruction }]
+  const baseline = renderWorkspaceContext(files.map(file => ({
+    absolutePath: join(cwd, file.name),
+    displayPath: file.name,
+    content: file.content,
+  })), { maxBytes: 65536 })
+  const config = resolveConfig({
+    dshHome: join(cwd, '.dsh'),
+    maxBytes: 65536,
+    ...options.instructionFileCandidates === undefined
+      ? {}
+      : { instructionFileCandidates: options.instructionFileCandidates },
+  })
  const events: SessionEvent[] = [
    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
    {
@@ -67,12 +86,13 @@ async function seedVisibleBaseline(root: string, cwd: string): Promise<string> {
        source: {
          kind: 'workspace-instructions',
          baseline: true,
-          changes: [{
+          baselineIdentity: workspaceBaselineIdentity(config, cwd, cwd),
+          changes: files.map(file => ({
            action: 'set',
-            scope: '.\0AGENTS.md',
-            path: 'AGENTS.md',
-            digest: createHash('sha1').update(oldInstruction).digest('hex'),
-          }],
+            scope: `.\0${file.name}`,
+            path: file.name,
+            digest: createHash('sha1').update(file.content).digest('hex'),
+          })),
        },
      }),
      surfaceOp: 'append',
@@ -148,4 +168,69 @@ describe('workspace-context resume snapshot', () => {
      reason: { kind: 'completed' },
    })
  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('recomposes a compatible current-order baseline when precedence changed offline', async () => {
+    let cwd = ''
+    let sessionPath = ''
+    const result = await runLoaderSmoke({
+      label: 'workspace-context precedence-change resume snapshot',
+      tempDirPrefix: 'dsh-workspace-context-precedence-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'Acknowledge the current workspace instruction.'],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT_FILE: replayFixture,
+        DSH_SNAPSHOT_OVERRIDE: replayOverride,
+      },
+      prepare: async (runCwd) => {
+        cwd = runCwd
+        await mkdir(join(runCwd, '.git'), { recursive: true })
+        await writeFile(join(runCwd, 'AGENTS.md'), 'Current AGENTS rule.\n')
+        await writeFile(join(runCwd, 'CLAUDE.md'), 'Current CLAUDE rule.\n')
+        sessionPath = await seedVisibleBaseline(join(runCwd, '.sessions'), runCwd, {
+          files: [
+            { name: 'CLAUDE.md', content: 'Old CLAUDE rule.' },
+            { name: 'AGENTS.md', content: 'Old AGENTS rule.' },
+          ],
+          instructionFileCandidates: ['CLAUDE.md', 'AGENTS.md'],
+        })
+      },
+      inspect: async () => {
+        const normalization: NormalizeContext = { sessionIds: [sessionId], cwd }
+        const session = scrubRequestHeaders(normalizeSessionLog(await readFile(sessionPath, 'utf8'), normalization))
+        if (refreshing) {
+          await mkdir(dirname(precedenceExpected), { recursive: true })
+          await writeFile(precedenceExpected, session)
+        }
+        expect(session).toBe(await readFile(precedenceExpected, 'utf8'))
+
+        const records = session.trimEnd().split('\n').map(line => JSON.parse(line) as {
+          type?: string
+          data?: {
+            source?: { kind?: string; baseline?: boolean }
+            content?: Array<{ type?: string; text?: string }>
+          }
+        })
+        const baselines = records.filter(record => record.type === 'user/message'
+          && record.data?.source?.kind === 'workspace-instructions'
+          && record.data.source.baseline === true)
+        expect(baselines).toHaveLength(2)
+        const replacement = JSON.stringify(baselines.at(-1)?.data?.content)
+        expect(replacement).toContain('replaces all earlier workspace instruction baselines')
+        expect(replacement.indexOf('Instructions from: AGENTS.md'))
+          .toBeLessThan(replacement.indexOf('Instructions from: CLAUDE.md'))
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    expect(result.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>).at(-1))
+      .toMatchObject({
+        type: 'result',
+        success: true,
+        sessionId,
+        result: 'RESUME_DONE',
+        reason: { kind: 'completed' },
+      })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/workspace-context/README.md
-README.md: 79f913a1cbabbcf474c5befccf01fb6eae76e843
-README.zh.md: 02f88c4e339b6a816b49db1eb9f91a440df787df
+README.md: 16a1dd324b4ef8d87253d0cd0de1b61b850ae8be
+README.zh.md: 63ed50162174469c1a2d3c254cbfff216bf73c14
--- a/packages/context/workspace-context/README.md
+++ b/packages/context/workspace-context/README.md
@@ -6,7 +6,7 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The

 ## Lifecycle

-A complete baseline is injected at the first `agent/step` of a fresh session. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. The durable sourced `user/message` enters the same request as the claimed prompt. A resumed loop retains that baseline while it remains visible and appends only current-file transitions. If a later surface replacement such as compaction shadows the baseline, a model-request `system-prompt/assemble` recomposes and injects the current chain before the loop snapshots that request; inspection-only assemblies do not mutate the session.
+A complete baseline is injected at the first `agent/step` of a fresh session. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. The durable sourced `user/message` enters the same request as the claimed prompt. A resumed loop retains that baseline while it remains visible and its discovery, precedence, and budget identity matches the current configuration, then appends only transitions selected by the current baseline budget. An incompatible visible baseline is superseded by one recomposed complete baseline whose model-facing introduction states that replacement; if the current candidate set is empty, that baseline explicitly clears the earlier instructions. If a later surface replacement such as compaction shadows the baseline, a model-request `system-prompt/assemble` recomposes and injects the current chain before the loop snapshots that request; inspection-only assemblies do not mutate the session.

 The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.

@@ -48,11 +48,11 @@ The plugin owns the complete `<system-reminder>` framing, and every injected `us

 ## State And Refresh

-Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true`. 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 present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `user/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true` and a `baselineIdentity` derived from normalized discovery, precedence, and budget configuration. 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 present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `user/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.

 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter the source, pending state, and version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates only the provider cache.

-The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface. A resumed loop or hot plugin remount retains that one visible baseline and reconciles its baseline and dynamic scopes against current files before the first request: unchanged files append nothing, while offline additions, edits, and removals append typed `set`, `replace`, and `remove` transitions. If no typed baseline remains visible, as after a surface replacement, model-request prompt assembly recomposes the complete current baseline and rechecks cancellation, visibility, and the current replacement generation immediately before injecting it. Concurrent preparations can read in parallel, but only the first commit queues a baseline; inspection-only assemblies never restore one. The in-memory scope marker and provider-version cache only select and accelerate probes. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, when a model request restores a shadowed baseline, or when a resumed loop prepares its baseline.
+The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface. A resumed loop or hot plugin remount retains one compatible visible baseline and reconciles its dynamic scopes plus the baseline scopes retained by the current complete rendering before the first request: unchanged files append nothing, while offline additions, edits, and removals append typed `set`, `replace`, and `remove` transitions. A file omitted by the current baseline budget is not promoted into history by resume reconciliation; a previously visible file that leaves the retained set receives a removal transition. If the visible baseline identity is incompatible, one complete current baseline explicitly supersedes earlier baselines. If no typed baseline remains visible, as after a surface replacement, model-request prompt assembly recomposes the complete current baseline and rechecks cancellation, visibility, and the current replacement generation immediately before injecting it. Concurrent preparations can read in parallel, but only the first commit queues a baseline; inspection-only assemblies never restore one. The in-memory scope marker and provider-version cache only select and accelerate probes. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, when a model request restores a shadowed baseline, or when a resumed loop prepares its baseline.

 ## Configuration

@@ -83,7 +83,7 @@ Instruction content is read through `streamText()` under `maxSourceBytes`, even

 #### What the model sees

-A fresh session's first request contains one durable user-role message with the bounded user-global and project instruction chain in broad-to-specific order. A resumed request retains that message while it remains visible and adds only detected transitions; the first request after a surface replacement shadows it receives one recomposed complete baseline.
+A fresh session's first request contains one durable user-role message with the bounded user-global and project instruction chain in broad-to-specific order. A resumed request retains that message while it remains visible and compatible, then adds only budget-selected transitions. An incompatible visible baseline is followed by a complete replacement baseline in current precedence order; the first request after a surface replacement shadows a baseline receives one recomposed complete baseline.

 ##### Baseline instruction template

--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -6,7 +6,7 @@

 ## 生命周期

-完整基线会在全新会话的第一个 `agent/step` 注入。它先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。这条持久的带来源 `user/message` 与被认领的提示词进入同一个请求。恢复的 loop 会在该基线仍可见时保留它，只追加根据当前文件检测到的转换。如果后续表层替换（例如压缩（compaction））遮蔽了该基线，面向模型请求的 `system-prompt/assemble` 会在 loop 对该请求创建快照之前，重新组合并注入当前指令链；仅检查组装不会改变会话。
+完整基线会在全新会话的第一个 `agent/step` 注入。它先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。这条持久的带来源 `user/message` 与被认领的提示词进入同一个请求。恢复的 loop 会在该基线仍可见，且其发现、优先顺序和预算标识与当前配置匹配时保留它，然后只追加由当前基线预算选中的转换。不兼容的可见基线会被一条重新组合的完整基线取代，其面向模型的引言会明确说明替换关系；如果当前候选集为空，这条基线会显式清除先前的指令。如果后续表层替换（例如压缩（compaction））遮蔽了该基线，面向模型请求的 `system-prompt/assemble` 会在 loop 对该请求创建快照之前，重新组合并注入当前指令链；仅检查组装不会改变会话。

 该插件还会监听 `tools/post-execute` 中成功的第一方 `read`、`write` 和 `edit` 调用。每次 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件通过结果的 `additionalContexts` 附加；已改变文件追加替换；文件消失或成为同一目录中较早候选文件的重复项时，追加移除通知。原生调用与 Code Mode 子分派共享该路径：`run_code` 将每个嵌套上下文延迟到外层结果，因此 loop 仍会在工具调用／结果相邻关系完成后追加更新。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。

@@ -48,11 +48,11 @@ These instructions apply to work under `packages/app`. Use them as guidance when

 ## 状态与刷新

-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。匹配的持久 `user/message` 会确认 pending 转换。如果所属 `step/end` 在匹配上下文进入日志之前到达，插件会清除 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及根据规范化的发现、优先顺序和预算配置派生的 `baselineIdentity`。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。匹配的持久 `user/message` 会确认 pending 转换。如果所属 `step/end` 在匹配上下文进入日志之前到达，插件会清除 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。

 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。

-初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态。恢复的 loop 或插件热重挂会保留这一条可见基线，并在第一个请求前根据当前文件对账其基线和动态 scope：未变文件不追加任何内容，而 agent 离线期间新增、编辑或移除的文件会追加带类型的 `set`、`replace` 或 `remove` 转换。如果已无带类型的基线可见（例如表层替换后），面向模型请求的提示词组装会重新组合完整的当前基线，并在注入前立即重新检查取消状态、可见性和当前替换代次。并发准备可以并行读取，但只有第一次提交会将一条基线排入队列；仅检查组装绝不会恢复基线。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在模型请求恢复被遮蔽的基线时或恢复 loop 准备基线时可见。
+初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态。恢复的 loop 或插件热重挂会保留一条兼容的可见基线，并在第一个请求前对账其动态 scope 以及当前完整渲染所保留的基线 scope：未变文件不追加任何内容，而 agent 离线期间新增、编辑或移除的文件会追加带类型的 `set`、`replace` 或 `remove` 转换。当前基线预算省略的文件不会因恢复对账而进入历史；先前可见但已不在保留集内的文件会收到移除转换。如果可见基线标识不兼容，一条完整的当前基线会明确取代此前的基线。如果已无带类型的基线可见（例如表层替换后），面向模型请求的提示词组装会重新组合完整的当前基线，并在注入前立即重新检查取消状态、可见性和当前替换代次。并发准备可以并行读取，但只有第一次提交会将一条基线排入队列；仅检查组装绝不会恢复基线。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在模型请求恢复被遮蔽的基线时或恢复 loop 准备基线时可见。

 ## 配置

@@ -83,7 +83,7 @@ export interface Config {

 #### 模型看到的内容

-全新会话的第一个请求包含一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界用户全局指令与项目指令链。恢复后的请求会在该消息仍可见时保留它，并只追加检测到的转换；表层替换将其遮蔽后的第一个请求会收到一条重新组合的完整基线。
+全新会话的第一个请求包含一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界用户全局指令与项目指令链。恢复后的请求会在该消息仍可见且兼容时保留它，然后只追加预算选中的转换。不兼容的可见基线之后会跟随一条按当前优先顺序排列的完整替换基线；表层替换将基线遮蔽后的第一个请求会收到一条重新组合的完整基线。

 ##### 基线指令模板

--- a/packages/context/workspace-context/src/config.ts
+++ b/packages/context/workspace-context/src/config.ts
@@ -4,6 +4,7 @@
 * @module @deepseek-ai/dsh-workspace-context/config
 */

+import { relative } from 'node:path'
 import z from 'schemastery'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'

@@ -58,6 +59,28 @@ export interface ResolvedConfig extends ResolvedDiscoveryConfig {
  maxSourceBytes: number
 }

+/**
+ * Identify the discovery, precedence, and budget semantics of one baseline.
+ * @param config - normalized plugin configuration.
+ * @param cwd - absolute session working directory.
+ * @param projectRoot - project root selected for the current baseline.
+ * @returns stable serialized identity for compatibility checks on resume.
+ */
+export function workspaceBaselineIdentity(
+  config: ResolvedConfig,
+  cwd: string,
+  projectRoot: string,
+): string {
+  return JSON.stringify({
+    projectRoot: relative(cwd, projectRoot),
+    projectRootMarkers: config.projectRootMarkers,
+    maxBytes: config.maxBytes,
+    maxSourceBytes: config.maxSourceBytes,
+    instructionFileCandidates: config.instructionFileCandidates,
+    localInstructionFileCandidates: config.localInstructionFileCandidates,
+  })
+}
+
 /**
 * Resolve defaults, the harness home, and valid same-directory candidates.
 * @param config - user-facing plugin configuration.
--- a/packages/context/workspace-context/src/files.ts
+++ b/packages/context/workspace-context/src/files.ts
@@ -46,12 +46,14 @@ interface DiscoverOptions {
  projectRootMarkers?: string[]
  instructionFileCandidates?: string[]
  localInstructionFileCandidates?: string[]
+  projectRoot?: string
  signal?: AbortSignal
 }

 interface LoadOptions extends DiscoverOptions {
  maxBytes: number
  maxSourceBytes?: number
+  replacePreviousBaseline?: boolean
 }

 /** Rendered baseline plus the files that survived byte budgeting. */
@@ -286,7 +288,8 @@ async function discoverInstructionFiles(
  }

  const cwd = resolve(options.cwd)
-  const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
+  const projectRoot = options.projectRoot
+    ?? await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
  for (const dir of ancestorChain(projectRoot, cwd)) {
    for (const candidates of [config.instructionFileCandidates, config.localInstructionFileCandidates]) {
      for (const file of await allExistingInstructionFiles(dir, projectRoot, candidates, fileSystem, options.signal)) {
@@ -389,7 +392,7 @@ export async function loadBaselineInstructions(
 * Load a baseline together with the files retained after rendering.
 * @param options - discovery, source-size, byte-budget, and cancellation configuration.
 * @param fileSystem - optional provider used instead of host filesystem reads.
- * @returns rendered context and retained files, or undefined when empty or disabled.
+ * @returns rendered context and retained files, an explicit empty replacement set, or undefined when empty or disabled.
 */
 export async function loadBaselineInstructionSet(
  options: LoadOptions,
@@ -412,8 +415,22 @@ export async function loadBaselineInstructionSet(
    }
  }
  const deduped = dedupInstructionFilesByDirectory(loaded)
-  if (deduped.length === 0) return undefined
-  const rendered = renderWorkspaceContext(deduped, { maxBytes: config.maxBytes })
+  if (deduped.length === 0) {
+    if (options.replacePreviousBaseline !== true) return undefined
+    return {
+      rendered: renderWorkspaceContext([], {
+        maxBytes: config.maxBytes,
+        replacePreviousBaseline: true,
+      }),
+      included: [],
+    }
+  }
+  const rendered = renderWorkspaceContext(deduped, {
+    maxBytes: config.maxBytes,
+    ...options.replacePreviousBaseline === undefined
+      ? {}
+      : { replacePreviousBaseline: options.replacePreviousBaseline },
+  })
  const omitted = new Set(rendered.omitted.map(file => file.absolutePath))
  return { rendered, included: deduped.filter(file => !omitted.has(file.absolutePath)) }
 }
--- a/packages/context/workspace-context/src/index.ts
+++ b/packages/context/workspace-context/src/index.ts
@@ -15,8 +15,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type { PostToolDecision, ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
-import { Config, resolveConfig, type ResolvedConfig } from './config.ts'
-import { loadBaselineInstructionSet } from './files.ts'
+import { Config, resolveConfig, workspaceBaselineIdentity, type ResolvedConfig } from './config.ts'
+import { findProjectRoot, loadBaselineInstructionSet } from './files.ts'
 import {
  applyInstructionVersionUpdates,
  baselineInstructionState,
@@ -31,6 +31,7 @@ import {
  type InstructionVersionCache,
  type InstructionVersionUpdate,
  type PendingInstructionChange,
+  type WorkspaceInstructionSource,
 } from './state.ts'
 import type { WorkspaceInstructionChange } from './render.ts'

@@ -46,13 +47,18 @@ export type {
 export { renderWorkspaceContext } from './render.ts'
 export type { RenderedWorkspaceContext, TruncatedInstruction } from './render.ts'

-function hasVisibleBaseline(session: Agent['session']): boolean {
-  return session.surface.nodes.some((seq) => {
+function visibleBaselineSource(session: Agent['session']): WorkspaceInstructionSource | undefined {
+  for (const seq of session.surface.nodes.toReversed()) {
    const event = session.events[seq]
-    return event?.type === 'user/message'
+    if (event?.type === 'user/message'
      && event.data.source.kind === 'workspace-instructions'
-      && event.data.source.baseline === true
-  })
+      && event.data.source.baseline === true) return event.data.source
+  }
+  return undefined
+}
+
+function hasVisibleBaseline(session: Agent['session']): boolean {
+  return visibleBaselineSource(session) !== undefined
 }

 function hasBaselineHistory(session: Agent['session']): boolean {
@@ -88,7 +94,7 @@ export function apply(ctx: Context, config: Config): void {
  const prepareBaseline = async (
    agent: Agent,
    signal: AbortSignal | undefined,
-    keepVisibleBaseline: boolean,
+    retainCompatibleBaseline: boolean,
    deduplicateRestore = false,
  ): Promise<void> => {
    if (resolved.maxBytes <= 0 || !Number.isFinite(resolved.maxBytes)) {
@@ -106,6 +112,21 @@ export function apply(ctx: Context, config: Config): void {
    }
    /* v8 ignore next -- normal agents carry an absolute session cwd. */
    const cwd = agent.session.header.cwd ?? process.cwd()
+    const projectRoot = await findProjectRoot(
+      cwd,
+      resolved.projectRootMarkers,
+      fileSystem,
+      signal,
+    )
+    const identity = workspaceBaselineIdentity(resolved, cwd, projectRoot)
+    const visibleBaseline = visibleBaselineSource(agent.session)
+    const keepVisibleBaseline = retainCompatibleBaseline
+      && visibleBaseline !== undefined
+      && typeof visibleBaseline.baselineIdentity === 'string'
+      && visibleBaseline.baselineIdentity === identity
+    const replacePreviousBaseline = retainCompatibleBaseline
+      && visibleBaseline !== undefined
+      && !keepVisibleBaseline
    const instructions = await loadBaselineInstructionSet({
      cwd,
      dshHome: resolved.dshHome,
@@ -114,6 +135,8 @@ export function apply(ctx: Context, config: Config): void {
      maxSourceBytes: resolved.maxSourceBytes,
      instructionFileCandidates: resolved.instructionFileCandidates,
      localInstructionFileCandidates: resolved.localInstructionFileCandidates,
+      projectRoot,
+      replacePreviousBaseline,
      ...signal === undefined ? {} : { signal },
    }, fileSystem)
    const baseline = baselineInstructionState(instructions?.included ?? [])
@@ -126,7 +149,12 @@ export function apply(ctx: Context, config: Config): void {
      pendingNestedChanges,
      instructionVersions,
      fileSystem,
-      { includeBaselineScopes: keepVisibleBaseline, ...signal === undefined ? {} : { signal } },
+      {
+        includeBaselineScopes: keepVisibleBaseline,
+        ...keepVisibleBaseline ? { retainedBaselineScopes: new Set(baseline.changes.keys()) } : {},
+        projectRoot,
+        ...signal === undefined ? {} : { signal },
+      },
    )
    signal?.throwIfAborted()
    const generation = agent.session.surface.replaceGeneration
@@ -141,6 +169,15 @@ export function apply(ctx: Context, config: Config): void {
    }
    if (!keepVisibleBaseline && instructions !== undefined && instructions.rendered.text.length > 0) {
      const baselineMessage = workspaceContextMessage(instructions.rendered.text)
+      const replacementScopes = new Set(baseline.changes.keys())
+      const visibleBaselineChanges = visibleBaseline?.changes ?? []
+      const replacementRemovals = replacePreviousBaseline
+        ? visibleBaselineChanges.flatMap(change => (
+          change.action === 'remove' || replacementScopes.has(change.scope)
+            ? []
+            : [{ action: 'remove' as const, scope: change.scope, path: change.path }]
+        ))
+        : []
      baselineSettledGeneration.delete(agent.session)
      baselineQueuedGeneration.set(agent.session, generation)
      try {
@@ -149,7 +186,8 @@ export function apply(ctx: Context, config: Config): void {
          source: {
            kind: 'workspace-instructions',
            baseline: true,
-            changes: [...baseline.changes.values()],
+            baselineIdentity: identity,
+            changes: [...replacementRemovals, ...baseline.changes.values()],
          },
        }))
      } catch (error: unknown) {
@@ -165,8 +203,7 @@ export function apply(ctx: Context, config: Config): void {

  ctx.on('agent/step', async (agent: Agent, _turn, _step, signal): Promise<void> => {
    if (baselineLoaded.has(agent.session)) return
-    const keepVisibleBaseline = hasVisibleBaseline(agent.session)
-    await prepareBaseline(agent, signal, keepVisibleBaseline)
+    await prepareBaseline(agent, signal, true)
  })

  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
--- a/packages/context/workspace-context/src/render.ts
+++ b/packages/context/workspace-context/src/render.ts
@@ -12,6 +12,10 @@ const SYSTEM_REMINDER_CLOSE = '</system-reminder>'
 const WORKSPACE_CONTEXT_INTRO = 'The following workspace instructions may be relevant to your work. '
  + 'Use them as guidance when applicable. More specific instructions take precedence over broader ones. '
  + 'They do not override system, developer, or direct user instructions.'
+const REPLACEMENT_WORKSPACE_CONTEXT_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. '
+  + WORKSPACE_CONTEXT_INTRO
+const EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. '
+  + 'No workspace instructions are currently active.'
 const COMPACT_WORKSPACE_CONTEXT_INTRO = 'Workspace instructions were omitted or truncated to fit the configured byte budget.'

 /** Byte-accounting record for one truncated instruction file. */
@@ -294,12 +298,20 @@ function renderInstructionContext(
 /**
 * Render the baseline instruction chain with deterministic precedence budgeting.
 * @param files - loaded files ordered from broadest to most specific.
- * @param options - required rendering byte budget.
+ * @param options - rendering byte budget and whether this baseline supersedes a visible predecessor.
 * @returns bounded baseline prompt text and budget diagnostics.
 */
 export function renderWorkspaceContext(
  files: LoadedInstructionFile[],
-  options: { maxBytes: number },
+  options: { maxBytes: number; replacePreviousBaseline?: boolean },
 ): RenderedWorkspaceContext {
-  return renderInstructionContext(files, options.maxBytes, BASELINE_RENDER_STYLE)
+  const style = options.replacePreviousBaseline === true
+    ? {
+      ...BASELINE_RENDER_STYLE,
+      intro: files.length === 0
+        ? EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO
+        : REPLACEMENT_WORKSPACE_CONTEXT_INTRO,
+    }
+    : BASELINE_RENDER_STYLE
+  return renderInstructionContext(files, options.maxBytes, style)
 }
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -41,6 +41,8 @@ export interface WorkspaceInstructionSource {
  kind: 'workspace-instructions'
  /** Marks a complete baseline rather than a later delta. */
  baseline?: true
+  /** Discovery, precedence, and budget identity for safe baseline reuse. */
+  baselineIdentity?: string
  changes: WorkspaceInstructionChange[]
 }

@@ -386,7 +388,7 @@ function relativeScope(projectRoot: string, dir: string): string {
 * @param pendingBySession - short pending window before returned context is logged.
 * @param versionCache - per-session scope metadata used to skip unchanged reads.
 * @param fileSystem - provider used for current file probes.
- * @param options - touched path and whether baseline scopes should participate.
+ * @param options - touched path and baseline-scope selection.
 * @returns rendered context plus deferred cache updates, or undefined when unchanged/unavailable.
 */
 export async function reconcileInstructionContext(
@@ -395,7 +397,13 @@ export async function reconcileInstructionContext(
  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
  versionCache: InstructionVersionCache,
  fileSystem: FileSystem,
-  options: { touchedPath?: string; includeBaselineScopes: boolean; signal?: AbortSignal },
+  options: {
+    touchedPath?: string
+    includeBaselineScopes: boolean
+    retainedBaselineScopes?: ReadonlySet<string>
+    projectRoot?: string
+    signal?: AbortSignal
+  },
 ): Promise<ReconciledInstructionContext | undefined> {
  const session = agent.session
  const pending = pendingChangesFor(session, pendingBySession)
@@ -404,7 +412,8 @@ export async function reconcileInstructionContext(
  const cwd = session.header.cwd ?? process.cwd()
  // TODO(frozen-project-root): retain the baseline root for the loop instance;
  // recomputing it after marker edits reinterprets the existing relative scope keys.
-  const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
+  const projectRoot = options.projectRoot
+    ?? await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
  const scopes = new Set<string>()
  const baselineScopes = new Set<string>()
  const addDirScopes = (target: Set<string>, directory: string): void => {
@@ -455,6 +464,13 @@ export async function reconcileInstructionContext(
  for (const scope of scopes) {
    const { directory } = decodeScopeKey(scope)
    const previous = effective.get(scope)
+    if (options.retainedBaselineScopes !== undefined
+      && baselineScopes.has(scope)
+      && !options.retainedBaselineScopes.has(scope)) {
+      if (previous === undefined || previous.action === 'remove') versions.delete(scope)
+      else pushRemoval(scope, previous.path)
+      continue
+    }
    const probe = await probeScopeInstruction(scope, projectRoot, resolved, fileSystem, options.signal)
    if (probe.kind === 'unavailable') {
      // Last-good-state: the candidate stays effective, so its cached trimmed
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -1063,6 +1063,208 @@ describe('workspace context request injection', () => {
    }
  })

+  it('does not promote an unchanged budget-omitted baseline file during resume', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      const cwd = join(root, 'pkg')
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'root '.repeat(200))
+      await write(join(cwd, 'AGENTS.md'), 'package rule')
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 700 })
+      const original = stubAgent(cwd)
+      await composeBaselinePrefix(ctx, original)
+
+      const firstResume = stubAgent(cwd, [...original.session.events])
+      await composeBaselinePrefix(ctx, firstResume)
+      const secondResume = stubAgent(cwd, [...firstResume.session.events])
+      await composeBaselinePrefix(ctx, secondResume)
+
+      expect(baselineEvents(secondResume)).toHaveLength(1)
+      expect(secondResume.session.events.filter(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions')).toHaveLength(1)
+      expect(blocksText(secondResume.session.deriveMessages()[0]?.content)).toContain('omitted AGENTS.md')
+      expect(blocksText(secondResume.session.deriveMessages()[0]?.content)).not.toContain('root root')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('removes a previously visible baseline file that leaves the retained budget set', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      const cwd = join(root, 'pkg')
+      await mkdir(join(root, '.git'), { recursive: true })
+      await mkdir(cwd, { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'root '.repeat(200))
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 700 })
+      const original = stubAgent(cwd)
+      await composeBaselinePrefix(ctx, original)
+
+      await write(join(cwd, 'AGENTS.md'), 'package rule')
+      const resumed = stubAgent(cwd, [...original.session.events])
+      await composeBaselinePrefix(ctx, resumed)
+
+      expect(baselineEvents(resumed)).toHaveLength(1)
+      const update = resumed.session.events.findLast(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions'
+        && event.data.source.baseline !== true)
+      expect(update?.type === 'user/message' && update.data.source.changes).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+        { action: 'set', scope: sk('pkg', 'AGENTS.md'), path: join('pkg', 'AGENTS.md') },
+      ])
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('recomposes the baseline when candidate precedence changes between resumes', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const originalCtx = new Context()
+    const resumedCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await write(join(root, 'CLAUDE.md'), 'claude rule')
+      await mountWorkspaceContext(originalCtx, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(originalCtx, original)
+
+      await mountWorkspaceContext(resumedCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['CLAUDE.md', 'AGENTS.md'],
+      })
+      const resumed = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(resumedCtx, resumed)
+
+      const baselines = baselineEvents(resumed)
+      expect(baselines).toHaveLength(2)
+      const replacement = baselines.at(-1)
+      const replacementText = replacement?.type === 'user/message'
+        ? blocksText(replacement.data.content)
+        : ''
+      expect(replacementText).toContain('replaces all earlier workspace instruction baselines')
+      expect(replacementText.indexOf('Instructions from: CLAUDE.md'))
+        .toBeLessThan(replacementText.indexOf('Instructions from: AGENTS.md'))
+      const baselineIdentities: string[] = []
+      for (const event of baselines) {
+        if (event.type !== 'user/message' || event.data.source.kind !== 'workspace-instructions') continue
+        if (typeof event.data.source.baselineIdentity === 'string') {
+          baselineIdentities.push(event.data.source.baselineIdentity)
+        }
+      }
+      expect(new Set(baselineIdentities).size).toBe(2)
+
+      const repeated = stubAgent(root, [...resumed.session.events])
+      await composeBaselinePrefix(resumedCtx, repeated)
+      expect(baselineEvents(repeated)).toHaveLength(2)
+    } finally {
+      await originalCtx.fiber.dispose()
+      await resumedCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('tombstones candidates removed across successive baseline configurations', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const agentsCtx = new Context()
+    const claudeCtx = new Context()
+    const restoredCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await write(join(root, 'CLAUDE.md'), 'claude rule')
+      await mountWorkspaceContext(agentsCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+      })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(agentsCtx, original)
+
+      await mountWorkspaceContext(claudeCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['CLAUDE.md'],
+      })
+      const claudeResume = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(claudeCtx, claudeResume)
+      const claudeBaseline = baselineEvents(claudeResume).at(-1)
+      expect(claudeBaseline?.type === 'user/message' && claudeBaseline.data.source.changes).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+        { action: 'set', scope: sk('.', 'CLAUDE.md'), path: 'CLAUDE.md' },
+      ])
+
+      await mountWorkspaceContext(restoredCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+      })
+      const restored = stubAgent(root, [...claudeResume.session.events])
+      await composeBaselinePrefix(restoredCtx, restored)
+      const restoredBaseline = baselineEvents(restored).at(-1)
+      expect(restoredBaseline?.type === 'user/message' && restoredBaseline.data.source.changes).toMatchObject([
+        { action: 'remove', scope: sk('.', 'CLAUDE.md'), path: 'CLAUDE.md' },
+        { action: 'set', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+      ])
+    } finally {
+      await agentsCtx.fiber.dispose()
+      await claudeCtx.fiber.dispose()
+      await restoredCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('supersedes an incompatible visible baseline when no current candidate exists', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const originalCtx = new Context()
+    const resumedCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await mountWorkspaceContext(originalCtx, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(originalCtx, original)
+
+      await mountWorkspaceContext(resumedCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['POLICY.md'],
+      })
+      const resumed = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(resumedCtx, resumed)
+
+      const baselines = baselineEvents(resumed)
+      expect(baselines).toHaveLength(2)
+      const replacement = baselines.at(-1)
+      expect(replacement?.type === 'user/message' && blocksText(replacement.data.content))
+        .toContain('No workspace instructions are currently active.')
+      expect(replacement?.type === 'user/message' && replacement.data.source.changes).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+      ])
+
+      const repeated = stubAgent(root, [...resumed.session.events])
+      await composeBaselinePrefix(resumedCtx, repeated)
+      expect(baselineEvents(repeated)).toHaveLength(2)
+    } finally {
+      await originalCtx.fiber.dispose()
+      await resumedCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
  it('ignores a restored baseline during a file tool call before resume reconciliation', async () => {
    const root = await tempRepo()
    const home = await tempRepo()