Merge remote-tracking branch 'origin/master' into worktree/pr468-retarget-latest-master

# Conflicts:
#	docs/architecture.i18n.yaml
#	docs/config-catalog.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	packages/examples/acp-demo/README.md
#	packages/examples/acp-demo/src/index.ts
#	packages/examples/acp-demo/tests/built-bin.e2e.ts
#	packages/examples/tui-demo/package.json
#	packages/examples/tui-demo/src/index.ts
#	packages/examples/tui-demo/tests/tui-agent.spec.ts

packages/examples/tui-demo/README.md

@@ -12,6 +12,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-commands` | Human-only discovery and dispatch consumed by the TUI and command plugins |
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
+| `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | Exact current-surface reads and bounded `@session` snapshots consumed by the TUI |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
@@ -38,6 +39,7 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `workspaceContext` | required | Workspace-instruction config, or `false` |
 | `persistenceRoot` | `./.sessions` | JSONL persistence root |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
+| `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
 | `welcome` | `ready.` | TUI subtitle |
 | `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height |
 | `resumeSessionId` | — | Exact persisted session to resume |

packages/examples/tui-demo/package.json

@@ -46,6 +46,7 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
     "@deepseek-ai/dsh-session-query": "^0.0.1",
     "@deepseek-ai/dsh-session-reference": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
@@ -69,6 +70,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-query": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",

packages/examples/tui-demo/src/index.ts

@@ -21,6 +21,7 @@ import SessionPersistenceJsonl, {
   JsonlCompressionSchema,
   type JsonlCompression,
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
@@ -124,6 +125,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
     root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
     ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
   })
+  ctx.plugin(sessionCheckpointPolicy)
   ctx.plugin(SessionQueryService)
   ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
   ctx.plugin(UserInteractionService)

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -50,6 +50,7 @@ describe('dsh-tui-demo app', () => {
       'CommandService',
       'command-goal',
       'SessionPersistenceJsonl',
+      'session-checkpoint-policy',
       'SessionQueryService',
       'SessionReferenceService',
       'UserInteractionService',
@@ -59,12 +60,12 @@ describe('dsh-tui-demo app', () => {
     ])
     expect(calls[0]?.config).toBeUndefined()
     expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[4]?.config).toEqual({
+    expect(calls[5]?.config).toEqual({
       maxReferences: 2,
       candidateLimit: 7,
       maxReferenceBytes: 1234,
     })
-    const tuiConfig = calls[6]?.config as { sessionId: string }
+    const tuiConfig = calls[7]?.config as { sessionId: string }
     expect(tuiConfig).toMatchObject({
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
@@ -72,7 +73,7 @@ describe('dsh-tui-demo app', () => {
       maxToolOutputLines: 3,
     })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[7]?.config as {
+    const spineConfig = calls[8]?.config as {
       readonly agents: Array<Record<string, unknown>>
       readonly goals: Record<string, never>
       readonly maxParallelToolCalls: number
@@ -106,10 +107,10 @@ describe('dsh-tui-demo app', () => {
     })
 
     expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[4]?.config).toEqual({})
+    expect(calls[5]?.config).toEqual({})
     // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[6]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
+    expect(calls[7]?.config).toEqual({ sessionId: 'persisted-session' })
+    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',
       resumeSessionId: 'persisted-session',
     })
@@ -125,12 +126,12 @@ describe('dsh-tui-demo app', () => {
       workspaceContext: false,
     })
 
-    const tuiConfig = calls[5]?.config as { sessionId: string }
+    const tuiConfig = calls[6]?.config as { sessionId: string }
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[6]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
+    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
       .toMatchObject({ sessionId: tuiConfig.sessionId })
     expect(calls.map(call => call.name)).not.toContain('command-goal')
-    expect(calls[6]?.config).toMatchObject({ goals: false })
+    expect(calls[7]?.config).toMatchObject({ goals: false })
   })
 
   it('has the namespace-plugin export shape so the Loader keeps its schema', () => {

packages/examples/tui-demo/tsconfig.json

@@ -53,6 +53,9 @@
     {
       "path": "../../ui/tool-ask-user"
     },
+    {
+      "path": "../../session-persistence/session-checkpoint-policy"
+    },
     {
       "path": "../../session-persistence/session-persistence-jsonl"
     },