Reorganize packages into a modular hierarchy

Move the 18 flat packages/<name> packages into role-grouped dirs:
core/, llm/, bash/, session-persistence/, ui/, support/. Group dirs are
pure containers; each package keeps its @deepseek-ai/dsh-* name.

Collapse the per-package tsconfig paths maps (base + typecheck) into one
@deepseek-ai/dsh-* wildcard with a candidate per group, and derive the
publint list from the hierarchy. Update all depth-coupled globs/configs
(workspace, tsdown, vitest, eslint, knip, tsconfig includes/refs,
per-package tsconfigs, generators, doc-script scopes, type-equiv manifest)
and the cross-package/script relative imports in tests.

Fix doc-typecheck's workspacePaths() to parse tsconfig JSONC via the
TypeScript API instead of a regex comment-strip, which corrupted the
new wildcard `/*/` path candidates.

WIP: doc cross-links and package/RFC docs still to update.

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

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+
+function stubAgent(rawId: string): Agent {
+  const id = AgentId(rawId)
+  return {
+    id,
+    options: {},
+    session: new Session(SessionId(`${id}-session`)),
+    status: 'idle',
+    send() {},
+    steer() {},
+    inject() {},
+    abort() {},
+    cancel() {},
+    whenIdle() { return Promise.resolve() },
+  }
+}
+
+describe('AgentRegistry', () => {
+  it('registers agents and emits created/disposed events', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+
+    const created: string[] = []
+    const disposed: string[] = []
+    ctx.on('agent/created', agent => void created.push(agent.id))
+    ctx.on('agent/disposed', agent => void disposed.push(agent.id))
+
+    const agent = stubAgent('a1')
+    const dispose = ctx.agents.register(agent)
+    expect(created).toEqual(['a1'])
+    expect(ctx.agents.get('a1')).toBe(agent)
+    expect(ctx.agents.list()).toEqual([agent])
+
+    dispose()
+    expect(disposed).toEqual(['a1'])
+    expect(ctx.agents.get('a1')).toBeUndefined()
+  })
+
+  it('rejects duplicate ids and unregisters on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    ctx.agents.register(stubAgent('main'))
+    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('already registered')
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.agents.register(stubAgent('scoped'))
+    }, { inject: ['agents'] }))
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main', 'scoped'])
+
+    await fiber.dispose()
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+  })
+
+  it('rolls back the agent entry when an agent/created listener throws (P1-1)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+
+    let threw = false
+    ctx.on('agent/created', () => {
+      if (!threw) { threw = true; throw new Error('boom created listener') }
+    })
+
+    // The throwing emit must roll the entry back, not leak it.
+    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('boom created listener')
+    expect(ctx.agents.get('main')).toBeUndefined() // rolled back, not leaked
+
+    // A subsequent listener-free register of the SAME id succeeds and is
+    // tracked exactly once (the duplicate-id check is not wedged).
+    const dispose = ctx.agents.register(stubAgent('main'))
+    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+    dispose()
+    expect(ctx.agents.get('main')).toBeUndefined()
+  })
+})
+
+describe('AgentRegistry factory seam', () => {
+  /** A stub AgentFactory that records calls and returns a stub agent. */
+  function stubFactory() {
+    const calls: { create: unknown[]; resume: unknown[] } = { create: [], resume: [] }
+    const factory: import('@deepseek-ai/dsh-agent').AgentFactory = {
+      createAgent(options) {
+        calls.create.push(options)
+        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+      },
+      resume(options) {
+        calls.resume.push(options)
+        return Promise.resolve({ agent: stubAgent(options.agentId), dispose: () => Promise.resolve() })
+      },
+    }
+    return { factory, calls }
+  }
+
+  it('create()/resume() throw when no factory is registered', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    expect(() => ctx.agents.create({ agentId: 'a', sessionId: 's' })).toThrow(/no agent factory/)
+    await expect(ctx.agents.resume({ agentId: 'a', resumeSessionId: 's' })).rejects.toThrow(/no agent factory/)
+  })
+
+  it('setFactory registers a factory; create/resume delegate to it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const { factory, calls } = stubFactory()
+    ctx.agents.setFactory(factory)
+
+    const created = ctx.agents.create({ agentId: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } })
+    expect(created.agent.id).toBe('c1')
+    expect(calls.create).toEqual([{ agentId: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } }])
+
+    const resumed = await ctx.agents.resume({ agentId: 'r1', resumeSessionId: 'old-sess' })
+    expect(resumed.agent.id).toBe('r1')
+    expect(calls.resume).toEqual([{ agentId: 'r1', resumeSessionId: 'old-sess' }])
+  })
+
+  it('setFactory rejects a second factory', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    ctx.agents.setFactory(stubFactory().factory)
+    expect(() => ctx.agents.setFactory(stubFactory().factory)).toThrow(/already registered/)
+  })
+
+  it('disposing the setFactory fiber clears the factory (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    let dispose!: () => void
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      dispose = inner.agents.setFactory(stubFactory().factory)
+    }, { inject: ['agents'] }))
+    expect(() => ctx.agents.create({ agentId: 'a', sessionId: 's' })).not.toThrow()
+    void dispose
+    await fiber.dispose()
+    // factory slot cleared → create throws again
+    expect(() => ctx.agents.create({ agentId: 'a2', sessionId: 's2' })).toThrow(/no agent factory/)
+  })
+})

packages/core/agent/tests/gen-cordis-catalog.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
+ *
+ * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
+ * the freshness half is exercised by `pnpm run verify-cordis-catalog` in CI.
+ * What a freshness diff CANNOT prove is that the generator REJECTS malformed
+ * source the way it promises to — a missing `@mode` tag, or a tag that
+ * contradicts the signature shape. These tests drive `collectEvents()` against
+ * synthetic fixture packages to prove each guard fires (and that a well-formed
+ * event passes), mirroring the drift-guard negative tests for verify-type-equiv.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectEvents } from '../../../../scripts/gen-cordis-catalog.ts'
+
+/** Write a fixture package exposing one `interface Events` block and return the
+ * scan root to hand `collectEvents`. */
+function fixtureRoot(eventsBlock: string): string {
+  const root = mkdtempSync(join(tmpdir(), 'cordis-catalog-'))
+  const dir = join(root, 'packages', 'group', 'fix', 'src')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(
+    join(dir, 'index.ts'),
+    `declare module 'cordis' {\n  interface Events {\n${eventsBlock}\n  }\n}\n`,
+  )
+  return root
+}
+
+const roots: string[] = []
+const make = (block: string): string => {
+  const r = fixtureRoot(block)
+  roots.push(r)
+  return r
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+describe('gen-cordis-catalog collectEvents', () => {
+  it('extracts a well-formed event with its @mode and JSDoc', () => {
+    const events = collectEvents(make(
+      '    /**\n     * A thing happened.\n     * @mode emit\n     */\n    \'fix/happened\'(id: string): void',
+    ))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toMatchObject({ name: 'fix/happened', scope: 'fix', mode: 'emit', doc: 'A thing happened.' })
+  })
+
+  it('classifies a trailing-next signature as a waterfall', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Intercept it.\n     * @mode waterfall\n     */\n    \'fix/intercept\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))
+    expect(events[0]?.mode).toBe('waterfall')
+  })
+
+  it('accepts a parallel (awaited, no next) event by trusting the tag', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Flush.\n     * @mode parallel\n     */\n    \'fix/flush\'(): Promise<void> | void',
+    ))
+    expect(events[0]?.mode).toBe('parallel')
+  })
+
+  it('hard-errors when an event is missing its @mode tag', () => {
+    expect(() => collectEvents(make(
+      '    /** No mode here. */\n    \'fix/untagged\'(id: string): void',
+    ))).toThrow(/missing an @mode tag/)
+  })
+
+  it('hard-errors when @mode contradicts a trailing-next (waterfall) shape', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Mislabeled.\n     * @mode emit\n     */\n    \'fix/wrong\'(x: number, next: () => Promise<number>): Promise<number>',
+    ))).toThrow(/trailing 'next' parameter .* tagged '@mode emit'/)
+  })
+
+  it('hard-errors when @mode waterfall has no trailing next to delegate to', () => {
+    expect(() => collectEvents(make(
+      '    /**\n     * Not actually a waterfall.\n     * @mode waterfall\n     */\n    \'fix/nonext\'(id: string): void',
+    ))).toThrow(/tagged '@mode waterfall' but has no trailing 'next'/)
+  })
+})