Merge remote-tracking branch 'origin/master' into worktree/session-reference

# Conflicts:
#	.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	packages/compact/compact-basic/src/region.ts
#	packages/compact/compact/README.md
#	packages/compact/compact/tests/compact.spec.ts
#	packages/examples/acp-demo/package.json
#	packages/ui/tui/README.md
#	packages/ui/tui/package.json
#	packages/ui/tui/src/index.ts
#	packages/ui/tui/tests/harness.ts
#	packages/ui/tui/tests/tui.spec.ts

packages/core/agent/README.md

@@ -2,13 +2,15 @@
 
 Agent interface, registry, process-local initiator scope, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
 
+The optional `@deepseek-ai/dsh-agent/invariant` companion registers this package's agent-status transition checks with `ctx.invariants`. The root agent service does not load diagnostics implicitly.
+
 ## Service: `AgentRegistry` (ctx key: `agents`)
 
 Tracks live agents and carries the initiating Agent through asynchronous driver work without importing the concrete loop package.
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installAgentLlmTarget(agentCtx, target)` snapshots a mutable provider/model selection during prompt assembly and applies that pair to both prompt variables and request routing for one step. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
 - Advanced ordered lifecycle: `enter(agent, owner): () => void` enforces `agent.id === agent.session.id`, performs the authoritative ID collision check, and inserts without announcing; `owner` explicitly records the live creator-agent relation (or `undefined` for a root), independently of durable session lineage. `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.

packages/core/agent/package.json

@@ -11,11 +11,16 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -23,6 +28,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-scope": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -31,6 +37,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/core/agent/src/index.ts

@@ -15,6 +15,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
+export * from './llm-target.ts'
 export { agentEvents, assembleContextFor } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 

packages/core/agent/src/invariant.ts

@@ -0,0 +1,35 @@
+/** Package-owned agent lifecycle invariants. @module @deepseek-ai/dsh-agent/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Install the agent contribution into its child registration fiber. */
+const install: InvariantInstaller = (ctx, fail) => {
+  const lastStatus = new WeakMap<Agent, AgentStatus>()
+  ctx.on('agent/status', (agent, status) => {
+    const previous = lastStatus.get(agent)
+    if (previous === status) {
+      fail(`agent/status repeated ${status} (no-op transition)`)
+    }
+    if (previous === 'disposed') {
+      fail(`agent/status left terminal state disposed → ${status}`)
+    }
+    lastStatus.set(agent, status)
+  }, { global: true })
+}
+
+/**
+ * Register the agent invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/core/agent/src/llm-target.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent-scoped provider/model target snapshot shared by interactive front doors.
+ * @module @deepseek-ai/dsh-agent/llm-target
+ */
+
+import type { Context } from 'cordis'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+/** Complete provider/model route selected for one live agent. */
+export interface AgentLlmTarget {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+
+/** Mutable selection plus the target captured for the current step. */
+export interface AgentLlmTargetRef {
+  /** Target selected for the next step that enters prompt assembly. */
+  current: AgentLlmTarget | undefined
+  /** Target captured when the current step entered prompt assembly. */
+  assembled: AgentLlmTarget | undefined
+}
+
+/**
+ * Couple one mutable target to agent-scoped prompt assembly and request routing.
+ * Prompt assembly snapshots the selected pair before delegating, then applies
+ * both prompt variables and request config to that snapshot so a concurrent
+ * switch takes effect on a later step instead of splitting the two surfaces.
+ *
+ * @param agentCtx - The target agent's scoped context.
+ * @param target - Mutable selection owned by the calling front door.
+ * @returns Disposer for both scoped waterfall listeners.
+ */
+export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetRef): () => void {
+  const disposeAssembly = agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+    const selected = target.current
+    const assembled = await next()
+    target.assembled = selected
+    if (selected === undefined) return assembled
+    return {
+      ...assembled,
+      variables: {
+        ...assembled.variables,
+        provider: selected.provider,
+        model: selected.model,
+      },
+    }
+  })
+  const disposeRequest = agentCtx.on(
+    'agent/request',
+    async (_agent, _turn, _step, _config, next): Promise<LlmCallConfig> => {
+      const resolved = await next()
+      const selected = target.assembled
+      return selected === undefined ? resolved : {
+        ...resolved,
+        provider: selected.provider,
+        model: selected.model,
+      }
+    },
+  )
+  return () => {
+    disposeAssembly()
+    disposeRequest()
+  }
+}

packages/core/agent/tests/invariant.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentInvariant)
+  return ctx
+}
+
+function mockAgent(id: string): Agent {
+  return { id } as unknown as Agent
+}
+
+describe('agent status invariants', () => {
+  it('accepts lifecycle transitions through idle, running, and disposed', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a1')
+    expect(() => {
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+    }).not.toThrow()
+
+    const running = mockAgent('a2')
+    ctx.emit(scopeTarget(running, running), 'agent/status', running, 'running')
+    expect(() => { ctx.emit(scopeTarget(running, running), 'agent/status', running, 'disposed') }).not.toThrow()
+  })
+
+  it('rejects a no-op transition', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a3')
+    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running') })
+      .toThrow(/no-op transition/)
+  })
+
+  it('rejects leaving the terminal disposed state', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a4')
+    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle') })
+      .toThrow(/left terminal state disposed/)
+  })
+
+  it('tracks agents independently', async () => {
+    const ctx = await setup()
+    const a = mockAgent('a5')
+    const b = mockAgent('b5')
+    ctx.emit(scopeTarget(a, a), 'agent/status', a, 'running')
+    expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow()
+  })
+})

packages/core/agent/tests/llm-target.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import {
+  agentEvents,
+  installAgentLlmTarget,
+  type Agent,
+  type AgentLlmTargetRef,
+} from '../src/index.ts'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+describe('installAgentLlmTarget()', () => {
+  it('snapshots prompt variables and request routing together, then disposes both listeners', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const target: AgentLlmTargetRef = { current: undefined, assembled: undefined }
+    const dispose = installAgentLlmTarget(ctx, target)
+    const agent = {} as Agent
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+
+    target.current = { provider: 'alpha', model: 'a1' }
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'alpha', model: 'a1' })
+    target.current = { provider: 'beta', model: 'b1' }
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'alpha', model: 'a1', temperature: 0.2 })
+
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'beta', model: 'b1' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'beta', model: 'b1', temperature: 0.2 })
+
+    dispose()
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 2, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+    await ctx.fiber.dispose()
+  })
+})

packages/core/agent/tsconfig.json

@@ -28,6 +28,9 @@
     },
     {
       "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }

packages/core/agent/tsdown.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])