feat(invariants): require package-owned companions

2026-07-19 22:13:50 +08:00
parent 2c7822ddee
commit 433670a754
316 changed files with 5348 additions and 646 deletions
--- a/packages/ui/acp/package.json
+++ b/packages/ui/acp/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"
@@ -29,6 +34,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-bash": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-permission": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
--- a/packages/ui/acp/src/invariant.ts
+++ b/packages/ui/acp/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-acp`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-acp/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-acp'
+
+/** Cordis companion plugin name. */
+export const name = 'acp-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/acp/tsconfig.json
+++ b/packages/ui/acp/tsconfig.json
@@ -46,6 +46,9 @@
    },
    {
      "path": "../../bash/bash"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/app-boot/package.json
+++ b/packages/ui/app-boot/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"
@@ -24,11 +29,13 @@
  "peerDependencies": {
    "@cordisjs/plugin-include": "^1.0.4",
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/ui/app-boot/src/invariant.ts
+++ b/packages/ui/app-boot/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-app-boot`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-app-boot/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-app-boot'
+
+/** Cordis companion plugin name. */
+export const name = 'app-boot-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/app-boot/tsconfig.json
+++ b/packages/ui/app-boot/tsconfig.json
@@ -16,6 +16,9 @@
    },
    {
      "path": "../../../vendor/include"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/jsonrpc/package.json
+++ b/packages/ui/jsonrpc/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"
@@ -26,6 +31,7 @@
  },
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-llm-deepseek": "^0.0.1",
    "@deepseek-ai/dsh-scope": "^0.0.1",
@@ -37,6 +43,7 @@
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
--- a/packages/ui/jsonrpc/src/invariant.ts
+++ b/packages/ui/jsonrpc/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-jsonrpc`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-jsonrpc/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-jsonrpc'
+
+/** Cordis companion plugin name. */
+export const name = 'jsonrpc-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/jsonrpc/tsconfig.json
+++ b/packages/ui/jsonrpc/tsconfig.json
@@ -28,6 +28,9 @@
    },
    {
      "path": "../../subagent/subagent"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/permission/package.json
+++ b/packages/ui/permission/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-bash": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-user-approval": "^0.0.1",
@@ -33,6 +39,7 @@
  },
  "devDependencies": {
    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-user-approval": "workspace:^",
--- a/packages/ui/permission/src/invariant.ts
+++ b/packages/ui/permission/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-permission`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-permission/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-permission'
+
+/** Cordis companion plugin name. */
+export const name = 'permission-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/permission/tsconfig.json
+++ b/packages/ui/permission/tsconfig.json
@@ -28,6 +28,9 @@
    },
    {
      "path": "../user-approval"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/stdio/package.json
+++ b/packages/ui/stdio/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"
@@ -24,6 +29,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -41,6 +47,7 @@
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-user-interaction": "workspace:^",
--- a/packages/ui/stdio/src/invariant.ts
+++ b/packages/ui/stdio/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-stdio`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-stdio/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-stdio'
+
+/** Cordis companion plugin name. */
+export const name = 'stdio-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/stdio/tests/stdio.spec.ts
+++ b/packages/ui/stdio/tests/stdio.spec.ts
@@ -1,9 +1,9 @@
 import { Readable, Writable } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, type Agent, type AgentStatus } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import { SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { createStdioChat, mountStdio, type Config, type StdioRuntime } from '../src/index.ts'
@@ -67,10 +67,26 @@ function makeAgent(id: string, status: AgentStatus = 'idle'): Agent & {
 /** Register a fake configured agent and cross the supported startup-work boundary. */
 function registerReady(ctx: Context, agent: Agent, source: 'startup' | 'resume' = 'startup'): () => void {
  const dispose = ctx.agents.register(agent)
-  ctx.emit('agent/session-start', agent, source)
+  agentEvents(ctx, agent).emit('agent/session-start', source)
  return dispose
 }

+function emitAgentSessionStart(ctx: Context, agent: Agent, source: 'startup' | 'resume'): void {
+  agentEvents(ctx, agent).emit('agent/session-start', source)
+}
+
+function emitAgentStatus(ctx: Context, agent: Agent, status: AgentStatus): void {
+  agentEvents(ctx, agent).emit('agent/status', status)
+}
+
+function emitAgentDisposed(ctx: Context, agent: Agent): void {
+  agentEvents(ctx, agent).emit('agent/disposed')
+}
+
+function emitSessionEvent(ctx: Context, session: Session, event: SessionEvent): void {
+  ctx.emit(scopeTarget(session, undefined), 'session/event', session, event)
+}
+
 /** A session stub whose `header.id` matches an agent's, for `session/event` emits. */
 function makeSession(id: string): Session {
  return { id, header: { id } } as Session
@@ -192,23 +208,23 @@ describe('createStdioChat rendering', () => {

  it('renders text-delta chunks verbatim', async () => {
    const { ctx, out } = await setup()
-    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
+    emitSessionEvent(ctx, makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
    expect(out.text()).toContain('hello')
  })

  it('wraps reasoning-delta in the dim SGR and resets on the following text-delta', async () => {
    const { ctx, out } = await setup()
    const session = makeSession('main')
-    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'think' }))
-    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'more' }))
-    ctx.emit('session/event', session, chunkEvent({ type: 'text-delta', index: 0, text: 'answer' }))
+    emitSessionEvent(ctx, session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'think' }))
+    emitSessionEvent(ctx, session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'more' }))
+    emitSessionEvent(ctx, session, chunkEvent({ type: 'text-delta', index: 0, text: 'answer' }))
    expect(out.text()).toContain('\x1B[2mthinkmore\x1B[0m\nanswer')
  })

  it('ignores stream-chunk types it does not render', async () => {
    const { ctx, out } = await setup()
    const before = out.text()
-    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'block-start', index: 0, blockType: 'text' }))
+    emitSessionEvent(ctx, makeSession('main'), chunkEvent({ type: 'block-start', index: 0, blockType: 'text' }))
    expect(out.text()).toBe(before)
  })

@@ -217,20 +233,20 @@ describe('createStdioChat rendering', () => {
    const agent = makeAgent('main')
    ctx.agents.register(agent)
    const session = agent.session
-    ctx.emit('session/event', session, {
+    emitSessionEvent(ctx, session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 3, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[main turn 3] ')
-    ctx.emit('session/event', session, {
+    emitSessionEvent(ctx, session, {
      type: 'turn/end', seq: 2, time: 0, data: { turn: 3, reason: { kind: 'completed' } },
-    } as SessionEvent)
+    })
    expect(out.text()).toContain('\n> ')
  })

  it('uses the session id as the label for a non-target session', async () => {
    const { ctx, out } = await setup()
    // No target exists, so the event's durable identity is the label.
-    ctx.emit('session/event', makeSession('orphan'), {
+    emitSessionEvent(ctx, makeSession('orphan'), {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[orphan turn 1] ')
@@ -253,7 +269,7 @@ describe('createStdioChat rendering', () => {
    await ctx.plugin(Object.assign((inner: Context) => {
      createStdioChat(inner, CONFIG, runtime)
    }, { inject: ['agents', 'userInteraction'] }))
-    ctx.emit('session/event', agent.session, {
+    emitSessionEvent(ctx, agent.session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[main turn 5] ')
@@ -266,14 +282,14 @@ describe('createStdioChat rendering', () => {

    const unrelated = makeAgent('unrelated')
    ctx.agents.register(unrelated)
-    ctx.emit('agent/session-start', unrelated, 'startup')
+    emitAgentSessionStart(ctx, unrelated, 'startup')
    const resumed = makeAgent('resumed')
    ;(resumed.session.header as { parentSession?: string }).parentSession = 'persisted-parent'
    ctx.agents.register(resumed)
    await new Promise(resolve => setImmediate(resolve))
    expect(resumed.sent).toEqual([])

-    ctx.emit('agent/session-start', resumed, 'resume')
+    emitAgentSessionStart(ctx, resumed, 'resume')
    await new Promise(resolve => setImmediate(resolve))

    expect(unrelated.sent).toEqual([])
@@ -283,10 +299,10 @@ describe('createStdioChat rendering', () => {
  it('resets dim styling at turn/end if a turn ends mid-reasoning', async () => {
    const { ctx, out } = await setup()
    const session = makeSession('main')
-    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'mid' }))
-    ctx.emit('session/event', session, {
+    emitSessionEvent(ctx, session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'mid' }))
+    emitSessionEvent(ctx, session, {
      type: 'turn/end', seq: 1, time: 0, data: { turn: 1, reason: { kind: 'completed' } },
-    } as SessionEvent)
+    })
    expect(out.text()).toContain('\x1B[2mmid\x1B[0m')
  })

@@ -297,7 +313,7 @@ describe('createStdioChat rendering', () => {
    dispose()
    // After disposal the event belongs to a non-target session, so its durable
    // identity is rendered directly.
-    ctx.emit('session/event', agent.session, {
+    emitSessionEvent(ctx, agent.session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[main turn 1] ')
@@ -307,8 +323,8 @@ describe('createStdioChat rendering', () => {
    const { ctx, out } = await setup()
    const target = makeAgent('main')
    ctx.agents.register(target)
-    ctx.emit('agent/disposed', makeAgent('other'))
-    ctx.emit('session/event', target.session, {
+    emitAgentDisposed(ctx, makeAgent('other'))
+    emitSessionEvent(ctx, target.session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[main turn 1] ')
@@ -326,7 +342,7 @@ describe('createStdioChat rendering', () => {
    input.feed('after hmr')
    await new Promise(resolve => setImmediate(resolve))
    expect(replacement.sent).toEqual([])
-    ctx.emit('agent/session-start', replacement, 'resume')
+    emitAgentSessionStart(ctx, replacement, 'resume')
    await new Promise(resolve => setImmediate(resolve))

    expect(prefixCollision.sent).toEqual([])
@@ -356,28 +372,28 @@ describe('createStdioChat rendering', () => {
      type: 'tool/call', seq: 1, time: 0,
      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{"command":"ls"}' },
    } as SessionEvent
-    ctx.emit('session/event', session, callEvent)
+    emitSessionEvent(ctx, session, callEvent)
    expect(out.text()).toContain('[tool call] bash({"command":"ls"})')

    const resultEvent = {
      type: 'tool/result', seq: 2, time: 0,
      data: { turn: 1, step: 0, callId: 'c1', content: [{ type: 'text', text: 'file.txt' }], isError: false },
    } as SessionEvent
-    ctx.emit('session/event', session, resultEvent)
+    emitSessionEvent(ctx, session, resultEvent)
    expect(out.text()).toContain('[tool result] file.txt')
  })

  it('renders a todo/write session event as a glyphed checklist', async () => {
    const { ctx, out } = await setup()
    const session = {} as Session
-    ctx.emit('session/event', session, {
+    emitSessionEvent(ctx, session, {
      type: 'todo/write', seq: 1, time: 0,
      data: { todos: [
        { content: 'read the code', status: 'completed' },
        { content: 'write the fix', status: 'in_progress' },
        { content: 'run the tests', status: 'pending' },
      ] },
-    } as SessionEvent)
+    })
    const text = out.text()
    expect(text).toContain('[todos]')
    expect(text).toContain('[x] read the code')
@@ -387,19 +403,19 @@ describe('createStdioChat rendering', () => {

  it('resets dim styling when a todo/write interrupts reasoning', async () => {
    const { ctx, out } = await setup()
-    ctx.emit('session/event', {} as Session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
-    ctx.emit('session/event', {} as Session, {
+    emitSessionEvent(ctx, {} as Session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    emitSessionEvent(ctx, {} as Session, {
      type: 'todo/write', seq: 1, time: 0,
      data: { todos: [{ content: 'a task', status: 'pending' }] },
-    } as SessionEvent)
+    })
    expect(out.text()).toContain('\x1B[2mr\x1B[0m')
  })

  it('resets dim styling when a tool/call interrupts reasoning', async () => {
    const { ctx, out } = await setup()
    const session = {} as Session
-    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
-    ctx.emit('session/event', session, {
+    emitSessionEvent(ctx, session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    emitSessionEvent(ctx, session, {
      type: 'tool/call', seq: 1, time: 0,
      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{}' },
    } as SessionEvent)
@@ -409,10 +425,10 @@ describe('createStdioChat rendering', () => {
  it('ignores session events it does not render', async () => {
    const { ctx, out } = await setup()
    const before = out.text()
-    ctx.emit('session/event', {} as Session, {
+    emitSessionEvent(ctx, {} as Session, {
      type: 'user/message', seq: 1, time: 0,
      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
-    } as SessionEvent)
+    })
    expect(out.text()).toBe(before)
  })
 })
@@ -799,7 +815,7 @@ describe('createStdioChat input', () => {
    ctx.agents.register(agent)
    await new Promise(r => setImmediate(r))
    expect(agent.sent).toEqual([])
-    ctx.emit('agent/session-start', agent, 'startup')
+    emitAgentSessionStart(ctx, agent, 'startup')
    await new Promise(r => setImmediate(r))
    expect(agent.sent).toEqual([[{ type: 'text', text: 'nobody home' }]])
  })
@@ -860,9 +876,9 @@ describe('createStdioChat EOF exit', () => {
    // Work submitted but no 'running' observed yet — must NOT exit.
    expect(exit).not.toHaveBeenCalled()
    // The turn starts, then settles.
-    ctx.emit('agent/status', agent, 'running')
+    emitAgentStatus(ctx, agent, 'running')
    ;(agent as { status: AgentStatus }).status = 'idle'
-    ctx.emit('agent/status', agent, 'idle')
+    emitAgentStatus(ctx, agent, 'idle')
    await flushExit()
    expect(exit).toHaveBeenCalledWith(0)
  })
@@ -878,12 +894,12 @@ describe('createStdioChat EOF exit', () => {
    ctx.agents.register(agent)
    await new Promise(r => setImmediate(r))
    expect(agent.sent).toEqual([])
-    ctx.emit('agent/session-start', agent, 'startup')
+    emitAgentSessionStart(ctx, agent, 'startup')
    await new Promise(r => setImmediate(r))
    expect(agent.sent).toEqual([[{ type: 'text', text: 'work' }]])
-    ctx.emit('agent/status', agent, 'running')
+    emitAgentStatus(ctx, agent, 'running')
    ;(agent as { status: AgentStatus }).status = 'idle'
-    ctx.emit('agent/status', agent, 'idle')
+    emitAgentStatus(ctx, agent, 'idle')
    await flushExit()
    expect(exit).toHaveBeenCalledWith(0)
  })
@@ -913,14 +929,14 @@ describe('createStdioChat EOF exit', () => {
    registerReady(ctx, agent)
    input.feed('work')
    await new Promise(r => setImmediate(r))
-    ctx.emit('agent/status', agent, 'running') // sawRunning = true
+    emitAgentStatus(ctx, agent, 'running') // sawRunning = true
    input.finish()
    await new Promise(r => setImmediate(r)) // let readline 'close' set stdinClosed
    ;(agent as { status: AgentStatus }).status = 'idle'
    // Two idle signals while stdin is already closed: the first arms the timer,
    // the second must hit the already-scheduled guard, not arm a second.
-    ctx.emit('agent/status', agent, 'idle')
-    ctx.emit('agent/status', agent, 'idle')
+    emitAgentStatus(ctx, agent, 'idle')
+    emitAgentStatus(ctx, agent, 'idle')
    await flushExit()
    expect(exit).toHaveBeenCalledTimes(1)
  })
@@ -933,8 +949,8 @@ describe('createStdioChat EOF exit', () => {
    await new Promise(r => setImmediate(r))
    input.finish()
    const other = makeAgent('other')
-    ctx.emit('agent/status', other, 'running')
-    ctx.emit('agent/status', other, 'idle')
+    emitAgentStatus(ctx, other, 'running')
+    emitAgentStatus(ctx, other, 'idle')
    await flushExit()
    expect(exit).not.toHaveBeenCalled()
  })
@@ -945,11 +961,11 @@ describe('createStdioChat EOF exit', () => {
    registerReady(ctx, agent)
    input.feed('work')
    await new Promise(r => setImmediate(r))
-    ctx.emit('agent/status', agent, 'running')
+    emitAgentStatus(ctx, agent, 'running')
    ;(agent as { status: AgentStatus }).status = 'running'
    input.finish()
    // sawRunning is true, but the agent is still running — the idle gate holds.
-    ctx.emit('agent/status', agent, 'idle') // a stale/duplicate signal while status stays 'running'
+    emitAgentStatus(ctx, agent, 'idle') // a stale/duplicate signal while status stays 'running'
    await flushExit()
    expect(exit).not.toHaveBeenCalled()
  })
@@ -998,8 +1014,8 @@ describe('createStdioChat disposal (HMR safety)', () => {
    // After dispose, status transitions must neither throw nor schedule an exit
    // (the listener and the EOF-exit path are both torn down).
    expect(() => {
-      ctx.emit('agent/status', agent, 'running')
-      ctx.emit('agent/status', agent, 'idle')
+      emitAgentStatus(ctx, agent, 'running')
+      emitAgentStatus(ctx, agent, 'idle')
    }).not.toThrow()
    await flushExit()
    expect(exit).not.toHaveBeenCalled()
--- a/packages/ui/stdio/tsconfig.json
+++ b/packages/ui/stdio/tsconfig.json
@@ -28,6 +28,9 @@
    },
    {
      "path": "../user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/tool-ask-user/package.json
+++ b/packages/ui/tool-ask-user/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,12 +28,14 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
--- a/packages/ui/tool-ask-user/src/invariant.ts
+++ b/packages/ui/tool-ask-user/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-tool-ask-user`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-tool-ask-user/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-ask-user'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-ask-user-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/tool-ask-user/tsconfig.json
+++ b/packages/ui/tool-ask-user/tsconfig.json
@@ -31,6 +31,9 @@
    },
    {
      "path": "../user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/tui/package.json
+++ b/packages/ui/tui/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"
@@ -24,6 +29,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -38,6 +44,7 @@
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/ui/tui/src/invariant.ts
+++ b/packages/ui/tui/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-tui`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-tui/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tui'
+
+/** Cordis companion plugin name. */
+export const name = 'tui-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -63,6 +63,11 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
    sessionId,
    options.cwd === null ? undefined : { meta: { cwd: options.cwd ?? '/workspace' } },
  )
+  session.append('turn/start', {
+    turn: 1,
+    trigger: { kind: 'message', source: { kind: 'user' } },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
  options.beforeMount?.(session)
  const sent: ContentBlock[][] = []
  const steered: ContentBlock[][] = []
@@ -120,10 +125,10 @@ export function appendAssistant(
  session: Session,
  content: ContentBlock[],
  usage?: { inputTokens: number; outputTokens: number },
+  position: { turn: number; step: number } = { turn: 1, step: 1 },
 ): void {
  session.append('assistant/message', {
-    turn: 1,
-    step: 0,
+    ...position,
    provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
    content,
    ...usage === undefined ? {} : { usage },
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -3,6 +3,7 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
+import { agentEvents } from '@deepseek-ai/dsh-agent'
 import { CallId, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Session } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -114,7 +115,7 @@ function appendToolCalls(session: Session, calls: readonly ToolCallFixture[]): v
  for (const call of calls) {
    session.append('tool/call', {
      turn: 1,
-      step: 0,
+      step: 1,
      callId: CallId(call.id),
      name: call.name,
      arguments: JSON.stringify(call.arguments),
@@ -130,7 +131,7 @@ function appendToolResult(
 ): void {
  session.append('tool/result', {
    turn: 1,
-    step: 0,
+    step: 1,
    callId: CallId(id),
    content,
    isError: options.isError ?? false,
@@ -198,23 +199,23 @@ describe('TUI terminal-state snapshots', () => {
    await renderAfter(harness, () => {
      appendUser(harness.session, 'Show the live update.')
      harness.session.append('assistant/chunk', {
-        turn: 2,
-        step: 0,
+        turn: 1,
+        step: 1,
        chunk: { type: 'block-start', index: 0, blockType: 'reasoning' },
      })
      harness.session.append('assistant/chunk', {
-        turn: 2,
-        step: 0,
+        turn: 1,
+        step: 1,
        chunk: { type: 'reasoning-delta', index: 0, text: 'Inspecting width and styles.' },
      })
      harness.session.append('assistant/chunk', {
-        turn: 2,
-        step: 0,
+        turn: 1,
+        step: 1,
        chunk: { type: 'block-start', index: 1, blockType: 'text' },
      })
      harness.session.append('assistant/chunk', {
-        turn: 2,
-        step: 0,
+        turn: 1,
+        step: 1,
        chunk: { type: 'text-delta', index: 1, text: 'Streaming **visible state**…' },
      })
    })
@@ -345,9 +346,10 @@ describe('TUI terminal-state snapshots', () => {
          source: { kind: 'user' },
          reason: `Unsafe policy ${CONTROL_PROBE}`,
        })
+        session.append('step/end', { turn: 1, step: 1 })
        session.append('turn/end', {
-          turn: 7,
-          reason: { kind: 'error', step: 2, message: `Unsafe turn error ${CONTROL_PROBE}` },
+          turn: 1,
+          reason: { kind: 'error', step: 1, message: `Unsafe turn error ${CONTROL_PROBE}` },
        })
      },
    }, { columns: 100, rows: 34 })
@@ -369,7 +371,7 @@ describe('TUI terminal-state snapshots', () => {
    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    await harness.terminal.waitForFrame(beforeQuestion)
    await renderAfter(harness, () => {
-      harness.ctx.emit('agent/error', harness.agent, 8, 3, new Error(`Unsafe live error ${CONTROL_PROBE}`))
+      agentEvents(harness.ctx, harness.agent).emit('agent/error', 8, 3, new Error(`Unsafe live error ${CONTROL_PROBE}`))
    })
    await checkpoint('untrusted-controls', harness.terminal, { includeScrollback: true })

@@ -427,14 +429,14 @@ describe('TUI terminal-state snapshots', () => {
        }, { surfaceOp: 'append' })
        const assistant = session.append('assistant/message', {
          turn: 1,
-          step: 0,
+          step: 1,
          provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
          content: [{ type: 'tool-call', id: CallId('old-tool'), name: 'bash', arguments: '{}' }],
        }, { surfaceOp: 'append' })
-        session.append('tool/call', { turn: 1, step: 0, callId: CallId('old-tool'), name: 'bash', arguments: '{}' })
+        session.append('tool/call', { turn: 1, step: 1, callId: CallId('old-tool'), name: 'bash', arguments: '{}' })
        const result = session.append('tool/result', {
          turn: 1,
-          step: 0,
+          step: 1,
          callId: CallId('old-tool'),
          content: [{ type: 'text', text: 'obsolete output that must disappear' }],
          isError: false,
@@ -470,13 +472,15 @@ describe('TUI terminal-state snapshots', () => {
      harness.terminal.send('\r')
      harness.terminal.send('/unknown-advanced-command')
      harness.terminal.send('\r')
-      harness.ctx.emit('agent/error', harness.agent, 3, 1, new Error('provider stream failed after partial output'))
+      agentEvents(harness.ctx, harness.agent).emit('agent/error', 1, 1, new Error('provider stream failed after partial output'))
+      harness.session.append('step/end', { turn: 1, step: 1 })
      harness.session.append('turn/end', {
-        turn: 3,
+        turn: 1,
        reason: { kind: 'error', step: 1, message: 'provider stream failed after partial output' },
      })
+      harness.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
      harness.session.append('turn/end', {
-        turn: 4,
+        turn: 2,
        reason: { kind: 'interrupted' },
      })
    })
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -3,7 +3,7 @@ import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -174,7 +174,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    expect(result.terminal.output).toContain('↑1.3k ↓42')

    result.agent.status = 'running'
-    result.ctx.emit('agent/status', result.agent, 'running')
+    agentEvents(result.ctx, result.agent).emit('agent/status', 'running')
    result.session.append('user/message', { content: [{ type: 'text', text: '   ' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: 'steering note' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
@@ -182,69 +182,77 @@ describe('pi-tui chat lifecycle and transcript', () => {
    result.session.append('context/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    result.session.append('prompt/blocked', { content: [{ type: 'text', text: 'blocked' }], source: { kind: 'user' }, reason: 'test policy' })
    appendAssistant(result.session, [])
-    result.session.append('turn/end', { turn: 9, reason: { kind: 'aborted' } })
-    result.session.append('turn/end', { turn: 10, reason: { kind: 'completed' } })
-    result.session.append('step/start', { turn: 11, step: 0 })
+    result.session.append('step/end', { turn: 1, step: 1 })
+    result.session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } })
+    result.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    result.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+    result.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+    result.session.append('step/start', { turn: 3, step: 1 })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-start', index: 0, blockType: 'reasoning' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'reasoning-delta', index: 0, text: 'live thought' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'reasoning-delta', index: 9, text: 'unannounced thought' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'live thought complete' } },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-start', index: 1, blockType: 'text' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'text-delta', index: 1, text: 'live answer' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-end', index: 1, block: { type: 'text', text: 'live answer done' } },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-start', index: 2, blockType: 'tool-call' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'block-end', index: 2, block: { type: 'tool-call', id: 'stream-tool' as never, name: 'tool', arguments: '{}' } },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'tool-call-delta', index: 2, id: 'stream-tool' as never, argumentsDelta: '{}' },
    })
    result.session.append('assistant/chunk', {
-      turn: 2,
-      step: 0,
+      turn: 3,
+      step: 1,
      chunk: { type: 'usage', usage: { inputTokens: 1, outputTokens: 2 } },
    })
    await tick()
    expect(result.terminal.output).toContain('live thought')
    result.terminal.send('\x12')
    await tick()
-    appendAssistant(result.session, [{ type: 'text', text: 'final live answer' }], { inputTokens: 500, outputTokens: 8 })
+    appendAssistant(
+      result.session,
+      [{ type: 'text', text: 'final live answer' }],
+      { inputTokens: 500, outputTokens: 8 },
+      { turn: 3, step: 1 },
+    )
    await tick()

    expect(result.terminal.output).toContain('Working')
@@ -258,17 +266,17 @@ describe('pi-tui chat lifecycle and transcript', () => {

    result.session.append('assistant/chunk', {
      turn: 3,
-      step: 0,
+      step: 1,
      chunk: { type: 'text-delta', index: 0, text: 'cleared stream' },
    })
    result.terminal.send('/clear')
    result.terminal.send('\r')
-    appendAssistant(result.session, [{ type: 'text', text: 'answer after clear' }])
+    appendAssistant(result.session, [{ type: 'text', text: 'answer after clear' }], undefined, { turn: 3, step: 1 })
    await tick()
    expect(result.terminal.output).toContain('answer after clear')

    result.agent.status = 'idle'
-    result.ctx.emit('agent/status', result.agent, 'idle')
+    agentEvents(result.ctx, result.agent).emit('agent/status', 'idle')
    await tick()
    expect(result.terminal.progress.at(-1)).toBe(false)
    await dispose(result)
@@ -324,8 +332,8 @@ describe('pi-tui chat lifecycle and transcript', () => {
        appendUser(session, 'first prompt')
        appendUser(session, 'second prompt')
        session.append('assistant/chunk', {
-          turn: 2,
-          step: 0,
+          turn: 1,
+          step: 1,
          chunk: { type: 'text-delta', index: 0, text: 'stale partial response' },
        })
      },
@@ -442,18 +450,25 @@ describe('pi-tui chat lifecycle and transcript', () => {
    const events = await setup()
    const unrelatedSession = events.ctx.sessions.create(SessionId('unrelated-session'))
    const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession }
+    unrelatedSession.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] })
-    events.ctx.emit('agent/status', unrelatedAgent, 'running')
-    events.ctx.emit('agent/error', unrelatedAgent, 1, 1, new Error('hidden error'))
-    events.ctx.emit('agent/disposed', unrelatedAgent)
-    events.ctx.emit('agent/error', events.agent, 3, 2, new Error('live failure'))
-    events.session.append('turn/end', { turn: 3, reason: { kind: 'error', step: 2, message: 'live failure' } })
-    events.session.append('turn/end', { turn: 4, reason: { kind: 'error', step: 1, message: 'durable failure' } })
-    events.session.append('turn/end', { turn: 5, reason: { kind: 'aborted', reason: 'stopped' } })
-    events.session.append('turn/end', { turn: 6, reason: { kind: 'max-tokens' } })
-    events.session.append('turn/end', { turn: 7, reason: { kind: 'rejected', reason: 'policy' } })
-    events.session.append('turn/end', { turn: 8, reason: { kind: 'interrupted' } })
-    events.ctx.emit('agent/disposed', events.agent)
+    agentEvents(events.ctx, unrelatedAgent).emit('agent/status', 'running')
+    agentEvents(events.ctx, unrelatedAgent).emit('agent/error', 1, 1, new Error('hidden error'))
+    agentEvents(events.ctx, unrelatedAgent).emit('agent/disposed')
+    agentEvents(events.ctx, events.agent).emit('agent/error', 1, 1, new Error('live failure'))
+    events.session.append('step/end', { turn: 1, step: 1 })
+    events.session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'live failure' } })
+    events.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/end', { turn: 2, reason: { kind: 'error', step: 1, message: 'durable failure' } })
+    events.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/end', { turn: 3, reason: { kind: 'aborted', reason: 'stopped' } })
+    events.session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/end', { turn: 4, reason: { kind: 'max-tokens' } })
+    events.session.append('turn/start', { turn: 5, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/end', { turn: 5, reason: { kind: 'rejected', reason: 'policy' } })
+    events.session.append('turn/start', { turn: 6, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/end', { turn: 6, reason: { kind: 'interrupted' } })
+    agentEvents(events.ctx, events.agent).emit('agent/disposed')
    await tick()
    expect(events.terminal.output).toContain('live failure')
    expect(events.terminal.output).toContain('durable failure')
@@ -546,7 +561,7 @@ describe('tool cards and surface replay', () => {
      })),
    ])
    for (const [id, name, args] of calls) {
-      result.session.append('tool/call', { turn: 1, step: 0, callId: id as never, name, arguments: args })
+      result.session.append('tool/call', { turn: 1, step: 1, callId: id as never, name, arguments: args })
    }
    await tick()
    expect(result.terminal.output).toContain('$ raw command')
@@ -556,23 +571,23 @@ describe('tool cards and surface replay', () => {
    expect(result.terminal.output).toContain('call presenter boom')
    expect(result.terminal.output).toContain('Symbol(input)')
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c1' as never, content: [{ type: 'text', text: 'raw bash' }], isError: false,
+      turn: 1, step: 1, callId: 'c1' as never, content: [{ type: 'text', text: 'raw bash' }], isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c2' as never, content: [{ type: 'text', text: 'stopped' }], isError: true,
+      turn: 1, step: 1, callId: 'c2' as never, content: [{ type: 'text', text: 'stopped' }], isError: true,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c3' as never, content: [{ type: 'text', text: 'done' }], isError: false,
+      turn: 1, step: 1, callId: 'c3' as never, content: [{ type: 'text', text: 'done' }], isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c4' as never, content: [{ type: 'text', text: 'raw generic' }], isError: false,
+      turn: 1, step: 1, callId: 'c4' as never, content: [{ type: 'text', text: 'raw generic' }], isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c5' as never, content: [{ type: 'text', text: 'raw throwing' }], isError: false,
+      turn: 1, step: 1, callId: 'c5' as never, content: [{ type: 'text', text: 'raw throwing' }], isError: false,
      meta: { value: 1 },
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c7' as never,
+      turn: 1, step: 1, callId: 'c7' as never,
      content: [
        { type: 'tool-call', id: 'inner' as never, name: 'inner', arguments: '{}' },
        { type: 'tool-result', toolCallId: 'inner' as never, content: [{ type: 'text', text: 'nested output' }] },
@@ -581,13 +596,18 @@ describe('tool cards and surface replay', () => {
      isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c8' as never, content: [{ type: 'text', text: '\nundefined presenter output\n\nkept tail\n' }], isError: false,
+      turn: 1, step: 1, callId: 'c8' as never, content: [{ type: 'text', text: '\nundefined presenter output\n\nkept tail\n' }], isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'c11' as never, content: [{ type: 'text', text: '\nconverted terminal\n\nfinished\n' }], isError: false,
+      turn: 1, step: 1, callId: 'c11' as never, content: [{ type: 'text', text: '\nconverted terminal\n\nfinished\n' }], isError: false,
    }, { surfaceOp: 'append' })
    result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'orphan' as never, content: [{ type: 'text', text: 'orphan result' }], isError: false,
+      turn: 1,
+      step: 1,
+      callId: 'orphan' as never,
+      content: [{ type: 'text', text: 'orphan result' }],
+      isError: true,
+      error: { name: 'InterruptedError', code: 'interrupted' },
    }, { surfaceOp: 'append' })
    await tick()

@@ -623,15 +643,15 @@ describe('tool cards and surface replay', () => {
    appendUser(result.session, 'old prompt')
    const assistant = result.session.append('assistant/message', {
      turn: 1,
-      step: 0,
+      step: 1,
      provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
      content: [{ type: 'tool-call', id: 'old-call' as never, name: 'bash', arguments: '{}' }],
    }, { surfaceOp: 'append' })
    result.session.append('tool/call', {
-      turn: 1, step: 0, callId: 'old-call' as never, name: 'bash', arguments: '{}',
+      turn: 1, step: 1, callId: 'old-call' as never, name: 'bash', arguments: '{}',
    })
    const toolResult = result.session.append('tool/result', {
-      turn: 1, step: 0, callId: 'old-call' as never, content: [{ type: 'text', text: 'old output' }], isError: false,
+      turn: 1, step: 1, callId: 'old-call' as never, content: [{ type: 'text', text: 'old output' }], isError: false,
    }, { surfaceOp: 'append' })
    const start = result.session.surface.nodes[0] as number
    result.session.append('context/message', {
@@ -904,6 +924,8 @@ describe('terminal mounting', () => {
    await ctx.plugin(UserInteractionService)
    ctx.provide('tools', { get: () => undefined } as never)
    const session = ctx.sessions.create(SessionId('failed-start-session'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'running', ctx,
      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
@@ -919,7 +941,7 @@ describe('terminal mounting', () => {
      .rejects.toMatchObject({ code: 'NO_PROVIDER' })
    session.append('assistant/chunk', {
      turn: 1,
-      step: 0,
+      step: 1,
      chunk: { type: 'text-delta', index: 0, text: 'must not render' },
    })
    await tick()
--- a/packages/ui/tui/tsconfig.json
+++ b/packages/ui/tui/tsconfig.json
@@ -31,6 +31,9 @@
    },
    {
      "path": "../user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/user-approval/package.json
+++ b/packages/ui/user-approval/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"
@@ -24,6 +29,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@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",
@@ -36,6 +42,7 @@
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@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:^",
--- a/packages/ui/user-approval/src/invariant.ts
+++ b/packages/ui/user-approval/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-user-approval`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-user-approval/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-user-approval'
+
+/** Cordis companion plugin name. */
+export const name = 'user-approval-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- 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 type { Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, 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'
@@ -371,7 +371,7 @@ describe('approval policy (the approval/policy fold)', () => {
  }

  const preStep = (ctx: Context, agent: Agent): Promise<void> =>
-    ctx.serial('agent/pre-step', agent, 1, 1, new AbortController().signal)
+    agentEvents(ctx, agent).serial('agent/pre-step', 1, 1, new AbortController().signal)

  /** Append a `request/header` snapshot whose system text is exactly `system`. */
  function appendHeader(session: Session, system: string): void {
--- a/packages/ui/user-approval/tsconfig.json
+++ b/packages/ui/user-approval/tsconfig.json
@@ -34,6 +34,9 @@
    },
    {
      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/ui/user-interaction/package.json
+++ b/packages/ui/user-interaction/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,11 +28,13 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
--- a/packages/ui/user-interaction/src/invariant.ts
+++ b/packages/ui/user-interaction/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Generated invariant ownership companion for `@deepseek-ai/dsh-user-interaction`.
+ * Replace this file with package-owned checks while preserving its registration.
+ *
+ * @generated scripts/gen-package-invariants.ts
+ * @module @deepseek-ai/dsh-user-interaction/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-user-interaction'
+
+/** Cordis companion plugin name. */
+export const name = 'user-interaction-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Reserve this package's invariant ownership until it adds relational checks. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's 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))
+/* jscpd:ignore-end */
--- a/packages/ui/user-interaction/tsconfig.json
+++ b/packages/ui/user-interaction/tsconfig.json
@@ -19,6 +19,9 @@
    },
    {
      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }