Merge latest master into manual compaction

# Conflicts: # apps/cli/README.i18n.yaml # docs/architecture.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/compact/compact-basic/README.i18n.yaml # packages/pty/pty-local/tests/index.spec.ts
2026-07-31 17:57:11 +08:00
parent b2cd3d26da aba776b179
commit 6e26f9fd83
419 changed files with 78109 additions and 4095 deletions
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/ui/app-boot/README.md
-README.md: 54f754842d9a6673ed6791b94656139f0f1be6a3
-README.zh.md: dd56084812e8241f0db24601ce2baeba51252d42
+README.md: 51bc5082512632dd493956b96c605aff47dc872e
+README.zh.md: 644d3a3613a9516cb02881fac8ba7531bffa81eb
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -14,6 +14,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
 | `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |

--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -14,6 +14,7 @@
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文 |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）自身源代码 checkout 的磁盘路径；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |

--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -12,7 +12,7 @@ import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import Include, { type PatchOptions } from '@cordisjs/plugin-include'
+import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -60,16 +60,12 @@ export function loadEnv(
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'

-// The include's YAML dialect: `!!js` scalars become expression nodes the
-// Loader interpolates against each entry's context at mount time. Personal
-// patches are parsed with the same schema so they may reference `process.env`.
-// Load-only: this schema never dumps, so no `predicate`/`represent`.
-const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
-  kind: 'scalar',
-  resolve: data => typeof data === 'string',
-  construct: data => ({ __jsExpr: String(data) }),
-})
-const personalPatchesSchema = yaml.JSON_SCHEMA.extend(jsExprType)
+// The include's YAML dialect (`!!js` scalars become expression nodes the
+// Loader interpolates against each entry's context at mount time), imported
+// from the include itself so patch parsing and config dumping can never drift
+// from what the include mounts. Personal patches share it so they may
+// reference `process.env`.
+const personalPatchesSchema = entryListSchema

 /**
 * Load the optional personal overlay patches (`config.yaml` under the Harness
@@ -149,6 +145,141 @@ function parsePatchList(
  return parsed as PatchOptions[]
 }

+/** One overlay patch list with the label provenance comments print for it. */
+export interface ConfigDumpLayer {
+  /** Source name shown in provenance comments (a file basename or path). */
+  label: string
+  /** The layer's patches, from {@link loadOverlayPatches} / {@link loadPersonalPatches}. */
+  patches: PatchOptions[]
+}
+
+/**
+ * Compose the effective entry list exactly as `boot()` would mount it: parse
+ * the base config file with the include's entry-list dialect, apply every
+ * layer's patches as ONE flattened list through the include's own patch
+ * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
+ * even patch-visibility corner cases (a later layer targeting a group child a
+ * plain config replacement introduced, which the single-pass id index never
+ * sees) compose identically — then render the result as YAML in the same
+ * dialect (`!!js` expressions print verbatim, unevaluated).
+ *
+ * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * naming the file that contributed the rows and any layers that patched them,
+ * so the output stays a loadable YAML document while showing which section
+ * comes from which file. Provenance is derived from single-call prefix
+ * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
+ * only rewrites rows in place or appends, so a top-level index identifies one
+ * row across snapshots, and a layer whose addition changes the row (config
+ * replacement, disable, group insert) is listed as having patched it.
+ *
+ * A patch that matches no row is reported through `warn` with its layer
+ * label, mirroring the Loader's boot-time warning. Earlier layers' patches
+ * see an identical preceding state in every snapshot that includes them, so
+ * each snapshot's warning list extends the previous one and the new tail
+ * belongs to the added layer.
+ * @param binName - the diagnostic prefix on read/parse errors.
+ * @param absoluteConfigPath - the base config file `boot()` would include.
+ * @param layers - overlay layers in application order (later wins).
+ * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
+ * @returns the composed entry list rendered as a YAML document with
+ * provenance comment separators.
+ */
+export function renderConfigDump(
+  binName: string,
+  absoluteConfigPath: string,
+  layers: ConfigDumpLayer[],
+  warn: (line: string) => void = line => void process.stderr.write(`${line}\n`),
+): string {
+  let content: string
+  try {
+    content = readFileSync(absoluteConfigPath, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: entryListSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: config ${absoluteConfigPath} must be a top-level YAML array of entries`)
+  }
+  const baseLabel = basename(absoluteConfigPath)
+  // The YAML boundary yields untyped rows; the include validates entry shape
+  // at mount, and the dump prints whatever the file holds, so `EntryOptions`
+  // here is structural trust in the same file `boot()` would include.
+  const base = parsed as Parameters<typeof applyEntryPatches>[0]
+  // snapshot_k = ONE application of layers 1..k flattened — boot's exact call
+  // shape for that prefix. snapshot_N is therefore the mounted composition.
+  // The patches are cloned per call: applyEntryPatches detaches the entry
+  // list but pushes `insert` rows by reference from the patch list, so
+  // sharing patch objects across snapshot calls would leak a later
+  // snapshot's mutations into an earlier one's result.
+  const snapshot = (count: number, warnings: string[]): ReturnType<typeof applyEntryPatches> => {
+    const flattened = structuredClone(layers.slice(0, count).flatMap(layer => layer.patches))
+    return applyEntryPatches(base, flattened, (message: string, ...args: unknown[]) => {
+      // The include logs through cordis's printf-style logger (`%C` = code); a
+      // dump has no logger, so substitute inline for a plain line.
+      let index = 0
+      warnings.push(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+    })
+  }
+  let previous = base
+  let previousWarnings: string[] = []
+  const provenance: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] }))
+  let composed = base
+  for (let count = 1; count <= layers.length; count += 1) {
+    const layer = layers[count - 1]
+    /* v8 ignore next -- count iterates 1..length, so the slot exists */
+    if (layer === undefined) continue
+    const warnings: string[] = []
+    composed = snapshot(count, warnings)
+    for (const line of warnings.slice(previousWarnings.length)) {
+      warn(`${binName}: [${layer.label}] ${line}`)
+    }
+    const before = previous.map(entry => JSON.stringify(entry))
+    for (let index = 0; index < composed.length; index += 1) {
+      if (index >= before.length) provenance.push({ origin: layer.label, patchedBy: [] })
+      else if (JSON.stringify(composed[index]) !== before[index]) provenance[index]?.patchedBy.push(layer.label)
+    }
+    previous = composed
+    previousWarnings = warnings
+  }
+  return groupedDump(composed, provenance)
+}
+
+/** Render the composed rows grouped under one provenance comment per contiguous run. */
+function groupedDump(
+  composed: readonly unknown[],
+  provenance: readonly { origin: string; patchedBy: string[] }[],
+): string {
+  const lines: string[] = []
+  let currentLabel: string | undefined
+  let group: unknown[] = []
+  const flush = (): void => {
+    if (currentLabel === undefined || group.length === 0) return
+    lines.push(`# == ${currentLabel}`)
+    lines.push(yaml.dump(group, { schema: entryListSchema, noRefs: true }).trimEnd())
+    group = []
+  }
+  for (let index = 0; index < composed.length; index += 1) {
+    const record = provenance[index]
+    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    if (record === undefined) continue
+    const label = record.patchedBy.length === 0
+      ? record.origin
+      : `${record.origin}, patched by ${record.patchedBy.join(', ')}`
+    if (label !== currentLabel) {
+      flush()
+      currentLabel = label
+    }
+    group.push(composed[index])
+  }
+  flush()
+  return lines.join('\n') + '\n'
+}
+
 /**
 * The slice of `process` {@link installFailLoud} needs — injectable so tests
 * exercise the handler without registering on (or exiting) the real process.
--- a/packages/ui/app-boot/tests/config-dump.spec.ts
+++ b/packages/ui/app-boot/tests/config-dump.spec.ts
@@ -0,0 +1,187 @@
+/**
+ * `renderConfigDump` behavior: the offline composition must equal what
+ * `boot()` mounts (same parser, same patch algorithm), print `!!js`
+ * expressions verbatim, separate provenance runs with comment lines while
+ * staying one loadable YAML document, and report skipped patches through
+ * `warn` instead of failing — mirroring the Loader's boot-time warning for a
+ * shared overlay whose row exists only on another surface.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import * as yaml from 'js-yaml'
+import { entryListSchema } from '@cordisjs/plugin-include'
+import { loadOverlayPatches, renderConfigDump } from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-config-dump-'))
+
+function writeBase(dir: string): string {
+  const base = join(dir, 'base.yml')
+  writeFileSync(base, [
+    '- id: shared',
+    '  name: ./noop.mjs',
+    '  config:',
+    '    value: base',
+    '    key: !!js process.env.DSH_DUMP_SPEC',
+    '- id: untouched',
+    '  name: ./noop.mjs',
+    '',
+  ].join('\n'))
+  return base
+}
+
+describe('renderConfigDump', () => {
+  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its provenance', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const surface = join(dir, 'surface.yml')
+    writeFileSync(surface, [
+      '- id: shared',
+      '  config:',
+      '    value: surface',
+      '    key: !!js process.env.DSH_DUMP_SPEC',
+      '- insert:',
+      '    - id: surface-extra',
+      '      name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const personal = join(dir, 'personal.yml')
+    writeFileSync(personal, [
+      '- id: surface-extra',
+      '  config:',
+      '    value: personal',
+      '',
+    ].join('\n'))
+
+    const dump = renderConfigDump(NAME, base, [
+      { label: 'surface.yml', patches: loadOverlayPatches(NAME, surface) },
+      { label: 'personal.yml', patches: loadOverlayPatches(NAME, personal) },
+    ], () => {})
+    // Comments do not break loadability: the dump parses as one document
+    // equal to what boot() would mount.
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      id: string
+      config?: Record<string, unknown>
+    }[]
+    expect(parsed).toEqual([
+      {
+        id: 'shared',
+        name: './noop.mjs',
+        config: { value: 'surface', key: { __jsExpr: 'process.env.DSH_DUMP_SPEC' } },
+      },
+      { id: 'untouched', name: './noop.mjs' },
+      { id: 'surface-extra', name: './noop.mjs', config: { value: 'personal' } },
+    ])
+    // Unevaluated: the expression text round-trips as a !!js scalar.
+    expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
+    // Provenance separators: origin file, plus every layer that changed the
+    // row; an inserted row carries the inserting layer as its origin.
+    expect(dump).toContain('# == base.yml, patched by surface.yml')
+    expect(dump).toContain('# == base.yml\n- id: untouched')
+    expect(dump).toContain('# == surface.yml, patched by personal.yml\n- id: surface-extra')
+    expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
+  })
+
+  it('groups contiguous same-provenance rows under one separator', () => {
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: a',
+      '  name: ./noop.mjs',
+      '- id: b',
+      '  name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const dump = renderConfigDump(NAME, base, [], () => {})
+    expect(dump.match(/# == base\.yml/g)).toHaveLength(1)
+    expect(dump).toContain('# == base.yml\n- id: a')
+  })
+
+  it('composes all layers as one flattened patch list, exactly like boot()', () => {
+    // boot() flattens every layer into ONE applyEntryPatches call, whose id
+    // index sees inserted rows but NOT children introduced by a plain group
+    // `config` replacement. A per-layer composition would rebuild the index
+    // between layers and let the second layer patch that child — a tree the
+    // real boot never mounts. Pin the single-call semantics: the child patch
+    // is skipped (with the layer-labeled warning), matching boot.
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: g',
+      '  name: ./group.mjs',
+      '  group: true',
+      '  config: []',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(NAME, base, [
+      {
+        label: 'a.yml',
+        patches: [{ id: 'g', config: [{ id: 'child', name: './noop.mjs', config: { v: 1 } }] }],
+      },
+      { label: 'b.yml', patches: [{ id: 'child', config: { v: 2 } }] },
+    ], line => void warnings.push(line))
+    expect(warnings).toEqual([`${NAME}: [b.yml] patch: entry "child" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      config?: { config?: { v?: number } }[]
+    }[]
+    expect(parsed[0]?.config?.[0]?.config?.v).toBe(1)
+    // The skipped layer did not change the row, so it is not in provenance.
+    expect(dump).toContain('# == base.yml, patched by a.yml\n- id: g')
+    expect(dump).not.toContain('b.yml\n- id: g')
+  })
+
+  it('reports a patch whose target row is absent through warn with its layer label and keeps composing', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const overlay = join(dir, 'overlay.yml')
+    writeFileSync(overlay, [
+      '- id: only-on-another-surface',
+      '  config:',
+      '    value: ignored',
+      '- id: shared',
+      '  config:',
+      '    value: patched',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(
+      NAME, base,
+      [{ label: 'overlay.yml', patches: loadOverlayPatches(NAME, overlay) }],
+      line => void warnings.push(line),
+    )
+    expect(warnings).toEqual([`${NAME}: [overlay.yml] patch: entry "only-on-another-surface" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as { config?: { value?: string } }[]
+    expect(parsed[0]?.config?.value).toBe('patched')
+  })
+
+  it('defaults its warn sink to one stderr line per skipped patch', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      renderConfigDump(NAME, base, [{ label: 'x.yml', patches: [{ id: 'absent', config: {} }] }])
+      expect(write).toHaveBeenCalledWith(`${NAME}: [x.yml] patch: entry "absent" not found\n`)
+    } finally {
+      write.mockRestore()
+    }
+  })
+
+  it('fails loud on a missing, unparsable, or non-array base config', () => {
+    const dir = tmp()
+    expect(() => renderConfigDump(NAME, join(dir, 'absent.yml'), [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to read config `))
+    const invalid = join(dir, 'invalid.yml')
+    writeFileSync(invalid, 'invalid: [unclosed\n')
+    expect(() => renderConfigDump(NAME, invalid, [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to parse config `))
+    const scalar = join(dir, 'scalar.yml')
+    writeFileSync(scalar, 'id: not-a-list\n')
+    expect(() => renderConfigDump(NAME, scalar, [], () => {}))
+      .toThrow('must be a top-level YAML array of entries')
+  })
+})
--- a/packages/ui/user-approval/README.i18n.yaml
+++ b/packages/ui/user-approval/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/ui/user-approval/README.md
-README.md: 38bcfbfe81c3ff5f16d1835259bd4c35a06dcb64
-README.zh.md: 7f2678d8572b191ec88a326374420dde7deed3dc
+README.md: 7b87a75d1c7c43874c484bc11f8deed45cb523ce
+README.zh.md: c15871073231b6e97f37fc0338f4824025ba86ca
--- a/packages/ui/user-approval/README.md
+++ b/packages/ui/user-approval/README.md
@@ -8,38 +8,37 @@ Each request must belong to an open agent turn. The service appends a paired `ap

 Answerers are `approval/request` waterfall listeners. Return an outcome to answer for an owned agent or call `next()` to delegate. Agent-scoped listeners receive only that agent's requests; compose one terminal answerer per deployment because sibling listener order is not a policy priority mechanism. The ACP automation bridge supplies one-shot machine decisions for sessions it owns.

-`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice, attributed to the user when the override follows the last `request/header` and to operator/config otherwise.
+`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch. Both policies contribute their complete current meaning to the cache-safe runtime-context snapshot.

 The tools pipeline routes `ask` decisions through this seam and fails closed when it is absent; the sandboxed bash tool also uses it for escalated retries. The ACP automation bridge answers calls for its own agents through the client's machine policy. Audit events remain log-only, so the model sees only the asking consumer's result. See the [approval-seam Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-approval-seam.md) and [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).

 ## Model Experience

-### System prompt and policy notice
+### Current approval policy context

 #### What the model sees

-Under `ask`, every agent request carries the ask-policy prompt section below. Under `never`, it carries the never-policy prompt section below. A policy switch injects exactly `The approval policy changed from "<old>" to "<new>" (changed by the user).` or `The approval policy changed from "<old>" to "<new>" (changed by the operator/config).` before the next step.
+The first request and each effective policy change append a full runtime-context snapshot after retained history. Under `ask`, the approval contribution states that configured answerers may be consulted and absence fails closed. Under `never`, it states the deterministic rejection and non-escalation consequence. Unchanged requests retain the earlier snapshot without adding another message.

-##### Ask-policy prompt section
+##### Ask-policy contribution

 ```markdown
-<!-- dsh-user-approval-policy:ask -->
+Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.
 ```

-##### Never-policy prompt section
+##### Never-policy contribution

 ```markdown
 Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
-<!-- dsh-user-approval-policy:never -->
 ```

 #### Token effect

-Small fixed per-request cost, larger under `never`; a change notice is conditional and retained in history.
+One concise context message on the first request and on an effective change; unchanged requests add no duplicate policy tokens.

 #### KV Cache effect

-Prefix-stable while the approval policy is unchanged. An `ask`/`never` switch changes the system-prompt section and invalidates reuse from its first changed token; the accompanying notice is append-only.
+Append-only after retained history. An `ask`/`never` switch preserves the stable system and conversation prefix instead of rewriting the first wire message.

 ### Tool outcome

--- a/packages/ui/user-approval/README.zh.md
+++ b/packages/ui/user-approval/README.zh.md
@@ -8,38 +8,37 @@

 应答者是 `approval/request` waterfall（瀑布式事件）监听器。要回答其负责的 agent 请求，请返回一个结果；否则调用 `next()` 委托。限定到 agent 的监听器只接收该 agent 的请求；每项部署应当组合一个最终应答者，因为同级监听器的顺序不是策略优先级机制。ACP（Agent Client Protocol）自动化桥接层为其负责的会话提供一次性机器决定。

-`ApprovalPolicy` 为 `'ask'` 或 `'never'`。实际值取最后一条 `approval/policy` 事件，并回退到配置；`setApprovalPolicy()` 是写入路径。`'never'` 会在交互式分发之前拒绝请求，也是提示词中唯一声明的策略。切换最多产生一条合并通知：如果覆盖发生在最后一个 `request/header` 之后，则归因于用户；否则归因于操作方／配置。
+`ApprovalPolicy` 为 `'ask'` 或 `'never'`。实际值取最后一条 `approval/policy` 事件，并回退到配置；`setApprovalPolicy()` 是写入路径。`'never'` 会在交互式分发之前拒绝请求。两种策略都会将各自完整的当前含义贡献给缓存安全的运行时上下文快照。

 工具流水线通过此 seam 路由 `ask` 决定，并在该 seam 缺失时以拒绝方式关闭；沙箱 bash 工具也会将它用于升权重试。ACP 自动化桥接层根据客户端的机器策略，回答其自有 agent 的调用。审计事件仍只写入日志，因此模型只会看到发起请求的消费方所返回的结果。详见[审批 seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-06-approval-seam.md)和[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。

 ## 模型体验

-### 系统提示词与策略通知
+### 当前审批策略上下文

 #### 模型看到的内容

-在 `ask` 下，每个 agent 请求都会携带下方的 ask 策略提示词段。在 `never` 下，请求会携带下方的 never 策略提示词段。策略切换会在下一步骤前精确注入 `The approval policy changed from "<old>" to "<new>" (changed by the user).` 或 `The approval policy changed from "<old>" to "<new>" (changed by the operator/config).`。
+首次请求和有效策略每次变化时，都会在保留的历史后追加一份完整运行时上下文快照。在 `ask` 下，批准贡献会说明可咨询已配置的应答者，缺少应答者时以拒绝方式关闭。在 `never` 下，它会说明确定性的拒绝与非升权后果。未变化的请求会保留先前快照，不增加另一条消息。

-##### Ask 策略提示词段
+##### Ask 策略贡献

 ```markdown
-<!-- dsh-user-approval-policy:ask -->
+Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.
 ```

-##### Never 策略提示词段
+##### Never 策略贡献

 ```markdown
 Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
-<!-- dsh-user-approval-policy:never -->
 ```

 #### Token 影响

-每个请求有少量固定成本，`never` 下的成本更高；变更通知按条件出现，并保留在历史中。
+首次请求和策略实际变化时增加一条简洁的上下文消息；未变化的请求不增加重复的策略 token。

 #### KV Cache 影响

-审批策略不变时，前缀保持稳定。`ask`／`never` 切换会改变系统提示词段，并从首个变化的 token 开始使复用失效；随附通知只会追加。
+在保留的历史之后仅追加。`ask`／`never` 切换会保留稳定的系统与对话前缀，而不会改写第一条 wire 消息。

 ### 工具结果

--- a/packages/ui/user-approval/src/index.ts
+++ b/packages/ui/user-approval/src/index.ts
@@ -8,7 +8,7 @@ import { randomUUID } from 'node:crypto'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { createUserMessage, type CallId } from '@deepseek-ai/dsh-llm'
+import type { CallId } from '@deepseek-ai/dsh-llm'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
@@ -59,7 +59,7 @@ declare module '@deepseek-ai/dsh-session' {
    /**
     * The session's approval policy was switched — log-only, durable,
     * replayable, never in the model transcript (the model learns the policy
-     * from the prompt section and the narrator's notices). The LAST such
+     * from the cache-safe runtime-context snapshot). The LAST such
     * event is the session's override ({@link effectiveApprovalPolicy}).
     * `source: 'delegation'` marks an override seeded into a child; an absent
     * source is a runtime switch.
@@ -90,41 +90,17 @@ const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cance
 *   (exactly today's behavior).
 * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
 *   deterministically. The strict headless stance (CI, unattended runs) and
- *   the only policy value stated in the system prompt — unlike `'ask'`, its
- *   outcome is knowable without asking, so stating it cannot overclaim.
+ *   the policy whose outcome is knowable without asking.
 */
 export type ApprovalPolicy = 'ask' | 'never'

 /** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
 export const APPROVAL_POLICIES: readonly ApprovalPolicy[] = ['ask', 'never']

-/**
- * The prompt sentence stating a `'never'` policy — visibility for the one
- * deterministic policy (see {@link ApprovalPolicy}). Narrator persistence
- * does NOT parse this prose: deployments can quote it in a persona or another
- * section, so the section also emits a source-owned marker.
- */
+/** Model-facing statement for the deterministic `'never'` policy. */
 const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'
-
-/** Source-owned prompt markers used to reconstruct the policy in a logged header. */
-const POLICY_MARKERS = {
-  ask: '<!-- dsh-user-approval-policy:ask -->',
-  never: '<!-- dsh-user-approval-policy:never -->',
-} as const satisfies Record<ApprovalPolicy, string>
-
-/**
- * Read the policy fact emitted by this service from a logged system prompt.
- * The section is ordered after deployment persona text, and the last marker
- * wins so a persona quoting an earlier marker cannot shadow the service's own
- * contribution. Ordinary policy prose is deliberately ignored.
- */
-function toldApprovalPolicy(system: string | undefined): ApprovalPolicy | undefined {
-  if (system === undefined) return undefined
-  const ask = system.lastIndexOf(POLICY_MARKERS.ask)
-  const never = system.lastIndexOf(POLICY_MARKERS.never)
-  if (ask < 0 && never < 0) return undefined
-  return never > ask ? 'never' : 'ask'
-}
+/** Model-facing statement for an interactive policy that may still fail closed. */
+const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.'

 /**
 * The session's approval-policy override: the last `approval/policy` event in
@@ -212,7 +188,7 @@ export interface Config {
 /**
 * Approval service that applies session policy before answerers and logs every
 * ask/outcome pair to the requesting session. It exposes deterministic policy
- * changes to the model through prompt and pre-step notices.
+ * changes to the model through the cache-safe runtime-context snapshot.
 */
 export class ApprovalService extends Service {
  static Config: z<Config> = z.object({
@@ -224,9 +200,10 @@ export class ApprovalService extends Service {

    const effective = (agent: Agent): ApprovalPolicy => this.effectivePolicy(agent.session)

-    // State only deterministic policy; a marker records the otherwise silent state.
+    // The complete current value travels after retained history, so switching
+    // policy does not rewrite the stable system-prompt cache prefix.
    ctx.inject(['systemPrompt'], (scope: Context) => {
-      scope.systemPrompt.section({
+      scope.systemPrompt.context({
        name: 'approval:policy',
        order: 115,
        text: (context) => {
@@ -234,54 +211,10 @@ export class ApprovalService extends Service {
          // A bare assemble() (tests, diagnostics) has no session to state.
          if (agent === undefined) return ''
          const policy = effective(agent)
-          return policy === 'never' ? `${NEVER_SENTENCE}\n${POLICY_MARKERS.never}` : POLICY_MARKERS.ask
+          return policy === 'never' ? NEVER_SENTENCE : ASK_SENTENCE
        },
      })
    })
-
-    // Visibility layer 2: the boundary narrator. agent/step runs before the
-    // request history is derived, so the notice is
-    // seen by THIS step's request: idle-time flip-flops coalesce at the
-    // turn's first step (net-zero → nothing), and a mid-turn switch is
-    // narrated no later than the next step. What each session was last told
-    // is in-memory with a log-derived fallback (the folded header's system
-    // text), so restarts lose nothing. Attribution is positional: an
-    // override event after the log's last `request/header` was a runtime
-    // switch by the user; otherwise the configured default moved under the
-    // session (operator/config).
-    const narrated = new WeakMap<Agent['session'], ApprovalPolicy>()
-    ctx.on('agent/step', (agent) => {
-      const session = agent.session
-      const events = session.events
-      let overrideIndex = -1
-      let overrideSource: 'delegation' | undefined
-      let headerIndex = -1
-      for (let index = events.length - 1; index >= 0 && (overrideIndex < 0 || headerIndex < 0); index -= 1) {
-        const event = events[index] as (typeof events)[number]
-        if (overrideIndex < 0 && event.type === 'approval/policy') {
-          overrideIndex = index
-          overrideSource = event.data.source
-        } else if (headerIndex < 0 && event.type === 'request/header') {
-          headerIndex = index
-        }
-      }
-      // Same fold effectivePolicy performs — override is scanned here anyway
-      // for POSITIONAL attribution; the default lives once, in the method.
-      const current = this.effectivePolicy(session)
-      const header = session.requestHeader()
-      const told = narrated.get(session) ?? toldApprovalPolicy(header?.system)
-      narrated.set(session, current)
-      // Cold start (nothing ever told) narrates nothing — the section about
-      // to go out states the truth, and there is no delta to explain.
-      if (told === undefined || told === current) return
-      const cause = overrideSource === 'delegation'
-        ? 'inherited from the delegating session'
-        : overrideIndex > headerIndex ? 'changed by the user' : 'changed by the operator/config'
-      agent.inject(createUserMessage({
-        content: [{ type: 'text', text: `The approval policy changed from "${told}" to "${current}" (${cause}).` }],
-        source: { kind: 'plugin', plugin: 'user-approval' },
-      }))
-    })
  }

  /**
--- a/packages/ui/user-approval/tests/approval.spec.ts
+++ b/packages/ui/user-approval/tests/approval.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { carrierKeyOf, createScope } from '@deepseek-ai/dsh-scope'
 import type { Scope } from '@deepseek-ai/dsh-scope'
@@ -351,33 +351,17 @@ describe('ApprovalService.request', () => {

 describe('approval policy (the approval/policy fold)', () => {
  const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'
-  const ASK_MARKER = '<!-- dsh-user-approval-policy:ask -->'
-  const NEVER_MARKER = '<!-- dsh-user-approval-policy:never -->'
+  const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.'

-  /**
-   * An agent stand-in over a REAL Session — gate, section, and narrator fold
-   * real events; the opened turn satisfies request()'s enclosure precondition.
-   */
-  function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } {
+  /** Agent stand-in over a real Session; the opened turn satisfies request()'s enclosure precondition. */
+  function sessionAgent(id: string): { agent: Agent; session: Session } {
    const session = new Session(SessionId(id))
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const injected: string[] = []
    const agent = {
      id,
      session,
-      inject: (input: { content: Array<{ type: string; text: string }> }) => {
-        injected.push(input.content[0]?.text ?? '')
-      },
    } as unknown as Agent
-    return { agent, session, injected }
-  }
-
-  const preStep = (ctx: Context, agent: Agent): Promise<void> =>
-    agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal)
-
-  /** Append a `request/header` snapshot whose system text is exactly `system`. */
-  function appendHeader(session: Session, system: string): void {
-    session.append('request/header', { header: { config: { provider: 'mock', model: 'mock' }, system }, reason: 'initial' })
+    return { agent, session }
  }

  it('folds to the last event, or undefined without one', () => {
@@ -464,131 +448,46 @@ describe('approval policy (the approval/policy fold)', () => {
    await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('rejected')
  })

-  it('states never (and only never) in prose while recording either policy with a source-owned marker', async () => {
+  it('contributes the complete current ask or never policy as cache-safe context', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ApprovalService)
    const askAgent = sessionAgent('sess-sect-ask').agent
    const { agent: neverAgent, session } = sessionAgent('sess-sect-never')
    setApprovalPolicy(session, 'never')
-    const sectionFor = async (context: object) =>
-      (await ctx.systemPrompt.assemble(context)).sections.find(s => s.name === 'approval:policy')?.text
-    expect(await sectionFor({ agent: askAgent })).toBe(ASK_MARKER)
-    expect(await sectionFor({ agent: neverAgent })).toBe(`${NEVER_SENTENCE}\n${NEVER_MARKER}`)
+    const contextFor = async (context: object) =>
+      (await ctx.systemPrompt.assemble(context)).contexts.find(entry => entry.name === 'approval:policy')?.text
+    expect(await contextFor({ agent: askAgent })).toBe(ASK_SENTENCE)
+    expect(await contextFor({ agent: neverAgent })).toBe(NEVER_SENTENCE)
    // A bare assemble (no agent) has no session to state.
-    expect(await sectionFor({})).toBe('')
+    expect(await contextFor({})).toBe('')
  })

-  it('narrates nothing cold, once per coalesced switch (user wording), and idempotently', async () => {
+  it('reflects the latest durable switch and stays byte-stable while unchanged', async () => {
    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ApprovalService)
-    const { agent, session, injected } = sessionAgent('sess-narr-1')
-    await preStep(ctx, agent)
-    expect(injected).toEqual([])
+    const { agent, session } = sessionAgent('sess-context-switch')
+    const contextFor = async () =>
+      (await ctx.systemPrompt.assemble({ agent })).contexts.find(entry => entry.name === 'approval:policy')?.text
+    expect(await contextFor()).toBe(ASK_SENTENCE)
+    expect(await contextFor()).toBe(ASK_SENTENCE)
    setApprovalPolicy(session, 'never')
    setApprovalPolicy(session, 'ask')
    setApprovalPolicy(session, 'never')
-    await preStep(ctx, agent)
-    expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).'])
-    await preStep(ctx, agent)
-    expect(injected).toHaveLength(1)
-    setApprovalPolicy(session, 'ask')
-    setApprovalPolicy(session, 'never')
-    await preStep(ctx, agent)
-    expect(injected).toHaveLength(1)
+    expect(await contextFor()).toBe(NEVER_SENTENCE)
+    expect(await contextFor()).toBe(NEVER_SENTENCE)
  })

-  it('reads what the model was told back from the folded header text after a restart', async () => {
-    // A session whose last request carried the never sentence resumes under
-    // an ask default: the narrator attributes the change to the operator.
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService)
-    const { agent, session, injected } = sessionAgent('sess-narr-2')
-    appendHeader(session, `persona\n\n${NEVER_SENTENCE}\n${NEVER_MARKER}`)
-    await preStep(ctx, agent)
-    expect(injected).toEqual(['The approval policy changed from "never" to "ask" (changed by the operator/config).'])
-  })
-
-  it('attributes a constructor-seeded policy event to delegation', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService)
-    const { agent, session, injected } = sessionAgent('sess-narr-inherited')
-    appendHeader(session, ASK_MARKER)
-    session.append('approval/policy', { policy: 'never', source: 'delegation' })
-
-    await preStep(ctx, agent)
-
-    expect(injected).toEqual(['The approval policy changed from "ask" to "never" (inherited from the delegating session).'])
-  })
-
-  it('narrates a config default drift from the logged ask marker', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService, { policy: 'never' })
-    const { agent, session, injected } = sessionAgent('sess-narr-3')
-    appendHeader(session, `persona only\n${ASK_MARKER}`)
-    await preStep(ctx, agent)
-    expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the operator/config).'])
-  })
-
-  it('a pinned override survives a default change silently', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService, { policy: 'never' })
-    const { agent, session, injected } = sessionAgent('sess-narr-4')
-    appendHeader(session, `persona only\n${ASK_MARKER}`)
-    setApprovalPolicy(session, 'ask')
-    appendHeader(session, `persona only\n${ASK_MARKER}`)
-    await preStep(ctx, agent)
-    expect(injected).toEqual([])
-  })
-
-  it('does not infer never from deployment prose that quotes the never sentence', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService)
-    const { agent, session, injected } = sessionAgent('sess-narr-spoof-prose')
-    appendHeader(session, `persona quotes this warning: ${NEVER_SENTENCE}\n${ASK_MARKER}`)
-    await preStep(ctx, agent)
-    expect(injected).toEqual([])
-  })
-
-  it('treats a legacy header with no source-owned marker as untold', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService, { policy: 'never' })
-    const { agent, session, injected } = sessionAgent('sess-narr-unmarked-header')
-    appendHeader(session, 'legacy persona-only header')
-    await preStep(ctx, agent)
-    expect(injected).toEqual([])
-  })
-
-  it('uses the service marker after an earlier persona marker', async () => {
-    const ctx = new Context()
-    await ctx.plugin(ApprovalService)
-    const { agent, session, injected } = sessionAgent('sess-narr-spoof-marker')
-    appendHeader(session, `persona quotes ${NEVER_MARKER}\n${ASK_MARKER}`)
-    await preStep(ctx, agent)
-    expect(injected).toEqual([])
-  })
-
-  it('disposes the service prompt section and pre-step narrator together (HMR safety)', async () => {
+  it('disposes the service context contribution with its fiber (HMR safety)', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    const fiber = await ctx.plugin(ApprovalService)
    const live = sessionAgent('sess-hmr-service-live')
-    const afterDispose = sessionAgent('sess-hmr-service-disposed')
-    const sectionFor = async () =>
-      (await ctx.systemPrompt.assemble({ agent: live.agent })).sections.find(section => section.name === 'approval:policy')
-    expect(await sectionFor()).toBeDefined()
-
-    appendHeader(live.session, `persona\n${ASK_MARKER}`)
-    setApprovalPolicy(live.session, 'never')
-    await preStep(ctx, live.agent)
-    expect(live.injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).'])
-
-    appendHeader(afterDispose.session, `persona\n${ASK_MARKER}`)
-    setApprovalPolicy(afterDispose.session, 'never')
+    const contextFor = async () =>
+      (await ctx.systemPrompt.assemble({ agent: live.agent })).contexts.find(context => context.name === 'approval:policy')
+    expect(await contextFor()).toBeDefined()
    await fiber.dispose()
-
-    expect(await sectionFor()).toBeUndefined()
-    await preStep(ctx, afterDispose.agent)
-    expect(afterDispose.injected).toEqual([])
+    expect(await contextFor()).toBeUndefined()
  })
 })