Merge refreshed rfc/pty into feature/persistent-pty-sessions

# Conflicts:
#	docs/architecture.md
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/module-graph.md
#	docs/tool-catalog.md
#	examples/acp-agent/tests/acp.snapshot.ts
#	examples/headless-agent/tests/headless.snapshot.ts
#	examples/package.json
#	packages/README.md
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	pnpm-lock.yaml
#	pnpm-workspace.yaml
#	scripts/gen-tool-catalog.ts
#	scripts/type-equiv.manifest.json
#	website/.vitepress/config/api-sidebar.json

scripts/gen-cordis-catalog.ts

@@ -5,9 +5,10 @@
  * curated table below. `--check` verifies both committed artifacts.
  */
 
-import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve, sep } from 'node:path'
+import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, sep } from 'node:path'
 import ts from 'typescript'
+import { renderCordisCoreApiPages } from './cordis-core-api.ts'
 import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
 import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
@@ -27,6 +28,7 @@ const FENCE = 'ts cordis-catalog'
  */
 export const LINK_MAP: Record<string, string> = {
   Agent: 'core.md',
+  AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
   ContentBlock: 'core.md',
@@ -34,6 +36,8 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
   LlmCallConfig: 'core.md',
+  LlmModelContext: 'core.md',
+  LlmFailure: 'llm-streaming.md',
   LlmModelInfo: 'core.md',
   LlmProviderInfo: 'core.md',
   Message: 'core.md',
@@ -57,6 +61,7 @@ export const LINK_MAP: Record<string, string> = {
   CodeRunResult: 'code-runtime.md',
   CompactionResult: 'compaction.md',
   CompactionTrigger: 'compaction.md',
+  PruneResult: 'compaction.md',
   FileReadOutcome: 'filesystem.md',
   FsDirEntry: 'filesystem.md',
   FsEditOutcome: 'filesystem.md',
@@ -68,6 +73,16 @@ export const LINK_MAP: Record<string, string> = {
   FsVersion: 'filesystem.md',
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
+  CreateGoalRequest: 'goal.md',
+  EditGoalRequest: 'goal.md',
+  GoalBlockReason: 'goal.md',
+  GoalChanged: 'goal.md',
+  GoalRef: 'goal.md',
+  GoalView: 'goal.md',
+  CommandDefinition: 'commands.md',
+  CommandDescriptor: 'commands.md',
+  CommandResult: 'commands.md',
+  CommandSurface: 'commands.md',
   LlmAdapter: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
   StreamChunk: 'llm-streaming.md',
@@ -91,8 +106,11 @@ export const LINK_MAP: Record<string, string> = {
   ScopeKey: 'scope.md',
   Scoped: 'scope.md',
   EpochHeader: 'session.md',
+  OutOfBandSessionEventType: 'session.md',
   Session: 'session.md',
+  SessionEventMap: 'session.md',
   TurnEndReason: 'session.md',
+  TurnTrigger: 'session.md',
   SessionEventReadRequest: 'session-query.md',
   SessionEventRecord: 'session-query.md',
   SessionEventTrace: 'session-query.md',
@@ -100,6 +118,8 @@ export const LINK_MAP: Record<string, string> = {
   SessionEventWindow: 'session-query.md',
   SessionLineageTrace: 'session-query.md',
   SessionRecord: 'session-query.md',
+  SessionTitleProvider: 'session-title.md',
+  SessionTitleSnapshot: 'session-title.md',
   SkillDefinition: 'skills.md',
   SkillLookupOptions: 'skills.md',
   SkillProvider: 'skills.md',
@@ -125,6 +145,7 @@ export const LINK_MAP: Record<string, string> = {
   PreToolDecision: 'tools.md',
   ToolDefinition: 'tools.md',
   ToolExecution: 'tools.md',
+  ToolDispatchExecution: 'tools.md',
   ToolExecutionInput: 'tools.md',
   ToolExecutionMode: 'tools.md',
   ToolExecutionResult: 'tools.md',
@@ -166,6 +187,11 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
+  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
+  LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
+  ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
+  Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
+  InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
   PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
@@ -276,8 +302,7 @@ interface InheritedEntry {
   source: string
 }
 
-// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts,
-// shared with gen-website-api.ts — one walk, two renderers.
+// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
 
 /** The signature text of a method-signature member (everything but a body). */
 function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
@@ -515,7 +540,7 @@ export function renderEvents(events: EventEntry[]): string {
     '',
     GATE_NOTICE,
     '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely.',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
     '',
     'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).',
     '',
@@ -550,7 +575,7 @@ export function renderServices(services: ServiceEntry[]): string {
     '',
     GATE_NOTICE,
     '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely.',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
     '',
   ]
   for (const s of services) lines.push(...renderService(s))
@@ -574,6 +599,7 @@ function main(): void {
   const outputs: [string, string][] = [
     [OUT_EVENTS, renderEvents(collectEvents())],
     [OUT_SERVICES, renderServices(collectServices())],
+    ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
     const stale: string[] = []
@@ -590,15 +616,19 @@ function main(): void {
       if (committed !== content) stale.push(out)
     }
     if (stale.length === 0) {
-      console.log(`gen-cordis-catalog: ${OUT_EVENTS} and ${OUT_SERVICES} are up to date.`)
+      console.log(`gen-cordis-catalog: ${outputs.length} generated file(s) are up to date.`)
       process.exit(0)
     }
     console.error(`gen-cordis-catalog: ${stale.join(' and ')} ${stale.length === 1 ? 'is' : 'are'} stale. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
     process.exit(1)
   }
 
-  for (const [out, content] of outputs) writeFileSync(resolve(root, out), content)
-  console.log(`gen-cordis-catalog: wrote ${OUT_EVENTS} and ${OUT_SERVICES}.`)
+  for (const [out, content] of outputs) {
+    const destination = resolve(root, out)
+    mkdirSync(dirname(destination), { recursive: true })
+    writeFileSync(destination, content)
+  }
+  console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
 // Run only when invoked as a script, not when imported by a test.