Merge remote-tracking branch 'origin/master' into codex/enforce-tool-cancellation

# Conflicts:
#	docs/event-producer-consumer.md
#	examples/acp-agent/tests/snapshots/bash-spill/session.jsonl
#	examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl
#	examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
#	packages/context/workspace-context/tests/workspace-context.spec.ts
#	packages/core/agent/src/index.ts
#	packages/support/invariants/tests/invariants.spec.ts
#	packages/ui/acp/src/index.ts
#	packages/ui/tui/tests/harness.ts
#	packages/ui/tui/tests/tui.spec.ts

packages/todo/tool-todo/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-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -31,6 +37,7 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",

packages/todo/tool-todo/src/invariant.ts

@@ -0,0 +1,61 @@
+/** Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-todo'
+const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed'])
+
+/** Cordis companion plugin name. */
+export const name = 'tool-todo-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Validate one whole-list todo snapshot before it reaches the durable log. */
+function validateTodos(value: unknown, fail: InvariantFailure): void {
+  if (!Array.isArray(value)) fail('todo/write todos must be an array')
+  const seen = new Set<string>()
+  let active = 0
+  for (const item of value) {
+    if (typeof item !== 'object' || item === null) fail('todo/write entries must be objects')
+    const { content, status } = item as Record<string, unknown>
+    if (typeof content !== 'string' || content.length === 0 || content.trim() !== content) {
+      fail('todo/write content must be non-empty and already trimmed')
+    }
+    if (seen.has(content)) fail(`todo/write repeats content ${JSON.stringify(content)}`)
+    seen.add(content)
+    if (typeof status !== 'string' || !TODO_STATUSES.has(status)) {
+      fail(`todo/write carries unknown status ${JSON.stringify(status)}`)
+    }
+    if (status === 'in_progress') active += 1
+  }
+  if (active > 1) fail(`todo/write contains ${active} in-progress entries; at most one is allowed`)
+}
+
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate the package-owned event shape and ignore unrelated events. */
+function validateEvent(event: SessionEvent, fail: InvariantFailure): void {
+  if (event.type === 'todo/write') validateTodos(event.data.todos, fail)
+}
+
+/** Install validation for loaded and newly appended whole-list todo snapshots. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  for (const session of ctx.sessions.list()) {
+    for (const event of session.events) validateEvent(event, fail)
+  }
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const event = (args as [Session, SessionEvent])[1]
+    validateEvent(event, fail)
+  }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the todo 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/todo/tool-todo/tests/invariant.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
+import * as TodoInvariant from '@deepseek-ai/dsh-tool-todo/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService, { enabled: true })
+  await ctx.plugin(TodoInvariant)
+  return ctx
+}
+
+function event(todos: unknown): SessionEvent {
+  return { type: 'todo/write', seq: 0, time: 0, data: { todos } } as SessionEvent
+}
+
+describe('todo snapshot invariants', () => {
+  it('accepts a unique whole-list snapshot with one active item', async () => {
+    const ctx = await setup()
+    expect(() => { ctx.emit('session/event', {} as Session, event([
+      { content: 'Inspect state', status: 'completed' },
+      { content: 'Apply fix', status: 'in_progress' },
+      { content: 'Run checks', status: 'pending' },
+    ])) }).not.toThrow()
+  })
+
+  it.each([
+    ['not-an-array', /must be an array/],
+    [[null], /entries must be objects/],
+    [[42], /entries must be objects/],
+    [[{ content: 42, status: 'pending' }], /content must be non-empty/],
+    [[{ content: '', status: 'pending' }], /content must be non-empty/],
+    [[{ content: ' padded ', status: 'pending' }], /already trimmed/],
+    [[{ content: 'same', status: 'pending' }, { content: 'same', status: 'completed' }], /repeats content/],
+    [[{ content: 'task', status: 42 }], /unknown status/],
+    [[{ content: 'task', status: 'paused' }], /unknown status/],
+    [[{ content: 'one', status: 'in_progress' }, { content: 'two', status: 'in_progress' }], /at most one/],
+  ])('rejects an incoherent durable todo snapshot', async (todos, message) => {
+    const ctx = await setup()
+    expect(() => { ctx.emit('session/event', {} as Session, event(todos)) }).toThrow(message)
+  })
+
+  it('ignores unrelated dispatches and session events', async () => {
+    const ctx = await setup()
+    expect(() => {
+      ctx.emit('tools/change')
+      ctx.emit('session/event', {} as Session, {
+        type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      })
+    }).not.toThrow()
+  })
+
+  it('rejects an invalid existing snapshot on late registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    ctx.sessions.create().append('todo/write', {
+      todos: [
+        { content: 'duplicate', status: 'pending' },
+        { content: 'duplicate', status: 'completed' },
+      ],
+    })
+    await ctx.plugin(InvariantService, { enabled: true })
+
+    await expect(ctx.plugin(TodoInvariant).then(() => undefined)).rejects.toThrow(/repeats content "duplicate"/)
+  })
+})

packages/todo/tool-todo/tsconfig.json

@@ -22,6 +22,9 @@
     },
     {
       "path": "../../core/session"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }