Merge remote-tracking branch 'origin/codex/package-readme-limitations-audit-20260712' into codex/model-experience-readmes-20260712

# Conflicts:
#	packages/AGENTS.md

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -54,11 +54,11 @@ export interface TypeApiEntry {
 export const SERVICE_API: readonly ServiceApiEntry[] = [
   {
     key: 'agentLoop',
-    summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.',
+    summary: 'Concrete ReactLoopAgent factory and driver service.',
     methods: [
       'create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): ReactLoopAgent',
-      'async createAgent(options: CreateAgentOptions): Promise<AgentHandle>',
-      'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
+      'async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>',
+      'async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>',
     ],
   },
   {
@@ -177,22 +177,21 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'subagents',
-    summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.',
+    summary: 'Named provider registry and capability-checked start surface.',
     methods: [
       'registerProvider(provider: SubagentProvider): () => Promise<void> | void',
       'getProvider(name: string): SubagentProvider | undefined',
       'list(): string[]',
-      'start(name: string, request: SubagentStartRequest): SubagentRun',
+      'async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>',
     ],
   },
   {
     key: 'systemPrompt',
-    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, named prompt variables, and authoritative contribution protections; the agent loop calls `assemble(context)` once per step.',
+    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, named prompt variables, and owner-final contributions; the agent loop calls `assemble(context)` once per step.',
     methods: [
       'section(section: PromptSection): () => Promise<void> | void',
       'tools(provider: (context: AssembleContext) => ToolProviderResult): () => Promise<void> | void',
       'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => Promise<void> | void',
-      'protect(protection: PromptProtection): () => Promise<void> | void',
       'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
     ],
   },
@@ -203,10 +202,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'register(definition: ToolDefinition): () => Promise<void> | void',
       'restrict(filter: ToolRestriction): () => Promise<void> | void',
       'guard(guard: ToolGuard): () => Promise<void> | void',
-      'visible(scope?: ScopeKey): ToolDefinition[]',
       'get(name: string, scope?: ScopeKey): ToolDefinition | undefined',
       'schemas(scope?: ScopeKey): ToolSchema[]',
-      'knownNames(scope?: ScopeKey): string[]',
       'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
     ],
   },
@@ -249,7 +246,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/disposed',
     mode: 'emit',
     signature: '\'agent/disposed\'(this: Scoped<Agent>, agent: Agent): void',
-    summary: 'An agent was removed from the registry after its driver and any in-flight turn reached quiescence.',
+    summary: 'An agent was removed from the registry.',
   },
   {
     name: 'agent/error',
@@ -353,6 +350,12 @@ export const EVENT_API: readonly EventApiEntry[] = [
     signature: '\'session/created\'(this: Scoped<Session>, session: Session): void',
     summary: 'A session was created in the store.',
   },
+  {
+    name: 'session/disposed',
+    mode: 'emit',
+    signature: '\'session/disposed\'(this: Scoped<Session>, session: Session): void',
+    summary: 'A previously announced session left the store.',
+  },
   {
     name: 'session/event',
     mode: 'emit',
@@ -381,25 +384,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'subagent/end',
     mode: 'emit',
     signature: '\'subagent/end\'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void',
-    summary: 'A started subagent run settled — emitted when SubagentRun.result resolves (any stop reason) or rejects (reported as `error`).',
+    summary: 'A ready child settled.',
   },
   {
     name: 'subagent/provider-added',
     mode: 'emit',
     signature: '\'subagent/provider-added\'(provider: SubagentProvider): void',
-    summary: 'A provider became resolvable in the SubagentService registry.',
+    summary: 'A provider became resolvable in the registry.',
   },
   {
     name: 'subagent/provider-removed',
     mode: 'emit',
     signature: '\'subagent/provider-removed\'(name: string): void',
-    summary: 'A provider left the registry (its plugin\'s fiber was disposed — an unload or an HMR reload).',
+    summary: 'A provider left the registry.',
   },
   {
     name: 'subagent/start',
     mode: 'emit',
     signature: '\'subagent/start\'(this: Scoped<SubagentService>, info: SubagentRunInfo): void',
-    summary: 'A subagent run started — emitted only after SubagentRun.started fulfills, when the provider has established a live child.',
+    summary: 'A provider established a ready child.',
   },
   {
     name: 'system-prompt/assemble',
@@ -411,7 +414,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'system-prompt/change',
     mode: 'emit',
     signature: '\'system-prompt/change\'(): void',
-    summary: 'A section, tool provider, variable provider, or protection was registered or unregistered (the assembly inputs changed — possibly for one scope only).',
+    summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed — possibly for one scope only).',
   },
   {
     name: 'tools/change',
@@ -428,7 +431,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'tools/post-execute',
     mode: 'waterfall',
-    signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
+    signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
     summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).',
   },
   {
@@ -489,7 +492,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'AgentFactory',
-    declaration: 'export interface AgentFactory {\n    createAgent(options: CreateAgentOptions): Promise<AgentHandle>;\n    resume(options: ResumeAgentOptions): Promise<AgentHandle>;\n}',
+    declaration: 'export interface AgentFactory {\n    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;\n    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;\n}',
   },
   {
     name: 'AgentHandle',
@@ -513,7 +516,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ApprovalRequest',
-    declaration: 'export interface ApprovalRequest {\n    agent: Agent;\n    toolName: string;\n    callId?: CallId;\n    reason?: string;\n    signal?: AbortSignal;\n}',
+    declaration: 'export interface ApprovalRequest {\n    readonly agent: Agent;\n    readonly toolName: string;\n    readonly callId?: CallId;\n    readonly reason?: string;\n    readonly signal?: AbortSignal;\n}',
   },
   {
     name: 'AskUserQuestionAnswer',
@@ -641,11 +644,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CreateAgentOptions',
-    declaration: 'export interface CreateAgentOptions {\n    agentId: AgentId;\n    sessionId: SessionId;\n    meta?: {\n        cwd?: string;\n        parentSession?: SessionId;\n        seedLength?: number;\n    };\n    seed?: SessionEvent[];\n    agentOptions?: AgentOptions;\n    setup?: (agentCtx: Context) => Promise<void> | void;\n}',
+    declaration: 'export interface CreateAgentOptions {\n    readonly agentId: AgentId;\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
   },
   {
     name: 'CreateSessionOptions',
-    declaration: 'export interface CreateSessionOptions {\n    seed?: SessionEvent[];\n    meta?: {\n        cwd?: string;\n        parentSession?: SessionId;\n        createdAt?: number;\n        seedLength?: number;\n    };\n}',
+    declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n    };\n}',
   },
   {
     name: 'DiffCallView',
@@ -743,13 +746,9 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'PromptAssembly',
     declaration: 'export interface PromptAssembly {\n    sections: AssembledSection[];\n    tools: ToolSchema[];\n    variables: Record<string, string | undefined>;\n}',
   },
-  {
-    name: 'PromptProtection',
-    declaration: 'export interface PromptProtection {\n    sections?: readonly string[];\n    tools?: readonly string[];\n}',
-  },
   {
     name: 'PromptSection',
-    declaration: 'export interface PromptSection {\n    name: string;\n    order: number;\n    text: string | ((context: AssembleContext) => string);\n}',
+    declaration: 'export interface PromptSection {\n    readonly name: string;\n    readonly order: number;\n    readonly text: string | ((context: AssembleContext) => string);\n    readonly ownerFinal?: boolean;\n}',
   },
   {
     name: 'ReasoningBlock',
@@ -757,7 +756,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ResumeAgentOptions',
-    declaration: 'export interface ResumeAgentOptions {\n    agentId: AgentId;\n    resumeSessionId: SessionId;\n    agentOptions?: AgentOptions;\n    setup?: (agentCtx: Context) => Promise<void> | void;\n}',
+    declaration: 'export interface ResumeAgentOptions {\n    readonly agentId: AgentId;\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
   },
   {
     name: 'SandboxEnforcement',
@@ -797,7 +796,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionHeader',
-    declaration: 'export interface SessionHeader {\n    version: number;\n    id: SessionId;\n    createdAt: number;\n    cwd?: string;\n    parentSession?: SessionId;\n    seedLength?: number;\n}',
+    declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n}',
   },
   {
     name: 'SessionId',
@@ -805,27 +804,27 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SkillCandidate',
-    declaration: 'export interface SkillCandidate extends SkillSummary {\n    rank: number;\n    locator: unknown;\n    path?: string;\n    metadata?: Record<string, unknown>;\n}',
+    declaration: 'export interface SkillCandidate extends SkillSummary {\n    readonly rank: number;\n    readonly locator: unknown;\n    readonly path?: string;\n    readonly metadata?: Readonly<Record<string, unknown>>;\n}',
   },
   {
     name: 'SkillDefinition',
-    declaration: 'export interface SkillDefinition extends SkillSummary {\n    content: string;\n    path?: string;\n    metadata?: Record<string, unknown>;\n}',
+    declaration: 'export interface SkillDefinition extends SkillSummary {\n    readonly content: string;\n    readonly path?: string;\n    readonly metadata?: Readonly<Record<string, unknown>>;\n}',
   },
   {
     name: 'SkillLookupOptions',
-    declaration: 'export interface SkillLookupOptions {\n    cwd?: string | undefined;\n    signal?: AbortSignal | undefined;\n}',
+    declaration: 'export interface SkillLookupOptions {\n    readonly cwd?: string | undefined;\n    readonly signal?: AbortSignal | undefined;\n}',
   },
   {
     name: 'SkillProvider',
-    declaration: 'export interface SkillProvider {\n    name: string;\n    list(options: SkillLookupOptions): Promise<SkillCandidate[]>;\n    get(candidate: SkillCandidate, options: SkillLookupOptions): Promise<SkillDefinition | undefined>;\n}',
+    declaration: 'export interface SkillProvider {\n    readonly name: string;\n    readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>;\n    readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>;\n}',
   },
   {
     name: 'SkillRegistration',
-    declaration: 'export type SkillRegistration = Omit<SkillDefinition, \'provider\'> & {\n    provider?: string;\n};',
+    declaration: 'export type SkillRegistration = Omit<SkillDefinition, \'provider\'> & {\n    readonly provider?: string;\n};',
   },
   {
     name: 'SkillResourceBase',
-    declaration: 'export type SkillResourceBase = {\n    kind: \'directory\';\n    path: string;\n} | {\n    kind: \'url\';\n    url: string;\n} | {\n    kind: \'opaque\';\n    description: string;\n};',
+    declaration: 'export type SkillResourceBase = {\n    readonly kind: \'directory\';\n    readonly path: string;\n} | {\n    readonly kind: \'url\';\n    readonly url: string;\n} | {\n    readonly kind: \'opaque\';\n    readonly description: string;\n};',
   },
   {
     name: 'SkillSource',
@@ -833,7 +832,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SkillSummary',
-    declaration: 'export interface SkillSummary {\n    name: string;\n    description: string;\n    whenToUse?: string;\n    disableModelInvocation?: boolean;\n    source: SkillSource;\n    provider: string;\n    resourceBase?: SkillResourceBase;\n}',
+    declaration: 'export interface SkillSummary {\n    readonly name: string;\n    readonly description: string;\n    readonly whenToUse?: string;\n    readonly disableModelInvocation?: boolean;\n    readonly source: SkillSource;\n    readonly provider: string;\n    readonly resourceBase?: SkillResourceBase;\n}',
   },
   {
     name: 'StreamChunk',
@@ -857,23 +856,23 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentCapabilities',
-    declaration: 'export interface SubagentCapabilities {\n    outputSchema: boolean;\n    depthLimit: boolean;\n    toolFilter: boolean;\n    persona: boolean;\n}',
+    declaration: 'export interface SubagentCapabilities {\n    readonly outputSchema: boolean;\n    readonly depthLimit: boolean;\n    readonly toolFilter: boolean;\n    readonly persona: boolean;\n}',
   },
   {
     name: 'SubagentProvider',
-    declaration: 'export interface SubagentProvider {\n    readonly name: string;\n    readonly capabilities: SubagentCapabilities;\n    readonly inheritsParentContext: boolean;\n    start(request: SubagentStartRequest): SubagentRun;\n}',
+    declaration: 'export interface SubagentProvider {\n    readonly name: string;\n    readonly capabilities: SubagentCapabilities;\n    readonly inheritsParentContext: boolean;\n    start(request: SubagentStartRequest): Promise<SubagentRun>;\n}',
   },
   {
     name: 'SubagentResult',
-    declaration: 'export interface SubagentResult {\n    output: ContentBlock[];\n    structured?: unknown;\n    stopReason: SubagentStopReason;\n}',
+    declaration: 'export interface SubagentResult {\n    readonly output: ContentBlock[];\n    readonly structured?: unknown;\n    readonly stopReason: SubagentStopReason;\n}',
   },
   {
     name: 'SubagentRun',
-    declaration: 'export interface SubagentRun {\n    readonly id: AgentId;\n    readonly started: Promise<void>;\n    readonly result: Promise<SubagentResult>;\n    cancel(reason?: string): void;\n    dispose(): Promise<void>;\n    sendMessage?(content: ContentBlock[]): void;\n    resume?(content: ContentBlock[]): SubagentRun;\n}',
+    declaration: 'export interface SubagentRun {\n    readonly id: AgentId;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n    sendMessage?(content: ContentBlock[]): void;\n    resume?(content: ContentBlock[]): Promise<SubagentRun>;\n}',
   },
   {
     name: 'SubagentStartRequest',
-    declaration: 'export interface SubagentStartRequest {\n    prompt: ContentBlock[];\n    parent: Agent;\n    signal?: AbortSignal;\n    agentOptions?: AgentOptions;\n    outputSchema?: StructuredOutputSchema;\n    maxDepth?: number;\n    toolFilter?: {\n        allow?: string[];\n        deny?: string[];\n    };\n    persona?: string;\n}',
+    declaration: 'export interface SubagentStartRequest {\n    readonly prompt: ContentBlock[];\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n    readonly agentOptions?: AgentOptions;\n    readonly outputSchema?: StructuredOutputSchema;\n    readonly maxDepth?: number;\n    readonly toolFilter?: ToolRestriction;\n    readonly persona?: string;\n}',
   },
   {
     name: 'SubagentStopReason',
@@ -921,7 +920,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolDefinition',
-    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    readonly ownerFinal?: boolean;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
   },
   {
     name: 'ToolErrorInfo',
@@ -945,7 +944,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecutionToken',
-    declaration: 'export interface ToolExecutionToken {\n    readonly [toolExecutionTokenBrand]: true;\n}',
+    declaration: 'export type ToolExecutionToken = symbol & {\n    readonly [toolExecutionTokenBrand]: true;\n};',
   },
   {
     name: 'ToolGuard',
@@ -953,11 +952,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolProviderResult',
-    declaration: 'export interface ToolProviderResult {\n    schemas: ToolSchema[];\n    knownNames?: readonly string[];\n}',
+    declaration: 'export interface ToolProviderResult {\n    readonly schemas: readonly ToolSchema[];\n    readonly knownNames?: readonly string[];\n    readonly ownerFinalNames?: readonly string[];\n}',
   },
   {
     name: 'ToolRestriction',
-    declaration: 'export interface ToolRestriction {\n    allow?: string[];\n    deny?: string[];\n}',
+    declaration: 'export interface ToolRestriction {\n    readonly allow?: readonly string[];\n    readonly deny?: readonly string[];\n}',
   },
   {
     name: 'ToolResult',

packages/cordis/tool-cordis/tests/cordis-lifecycle.spec.ts

@@ -0,0 +1,287 @@
+import { Context, CordisError, FiberState, type Fiber } from 'cordis'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Direct regressions for the vendored Cordis ownership substrate used by
+ * tool-cordis's dynamic plugin tree and every other harness plugin.
+ */
+
+describe('Cordis effect ownership', () => {
+  it('makes an effect visible to a reentrant owner restart and awaits setup plus cleanup', async () => {
+    const ctx = new Context()
+    const setupGate = Promise.withResolvers<undefined>()
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanupStarted = Promise.withResolvers<undefined>()
+    let restarted!: Promise<void>
+    let setupFinished = false
+    let cleanupFinished = false
+
+    ctx.effect(async () => {
+      restarted = ctx.fiber.restart()
+      await setupGate.promise
+      setupFinished = true
+      return async () => {
+        cleanupStarted.resolve(undefined)
+        await cleanupGate.promise
+        cleanupFinished = true
+      }
+    }, 'reentrant-restart')
+
+    let settled = false
+    void restarted.then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    setupGate.resolve(undefined)
+    await cleanupStarted.promise
+    expect(setupFinished).toBe(true)
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    cleanupGate.resolve(undefined)
+    await restarted
+    expect(cleanupFinished).toBe(true)
+    expect(ctx.fiber.getEffects()).toEqual([])
+  })
+
+  it('rolls back collected cleanup and its owner-list entry when setup throws synchronously', () => {
+    const ctx = new Context()
+    let cleanups = 0
+
+    expect(() => ctx.effect(function* () {
+      yield () => { cleanups += 1 }
+      throw new Error('setup failed')
+    }, 'throwing-setup')).toThrow('setup failed')
+
+    expect(cleanups).toBe(1)
+    expect(ctx.fiber.getEffects()).toEqual([])
+  })
+
+  it('makes a reentrant owner restart await asynchronous rollback after synchronous setup failure', async () => {
+    const ctx = new Context()
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanupStarted = Promise.withResolvers<undefined>()
+    let restarted!: Promise<void>
+
+    expect(() => ctx.effect(function* () {
+      yield async () => {
+        cleanupStarted.resolve(undefined)
+        await cleanupGate.promise
+      }
+      restarted = ctx.fiber.restart()
+      throw new Error('setup failed after restart')
+    }, 'reentrant-throw')).toThrow('setup failed after restart')
+
+    await cleanupStarted.promise
+    let settled = false
+    void restarted.then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    cleanupGate.resolve(undefined)
+    await restarted
+    expect(ctx.fiber.getEffects()).toEqual([])
+  })
+
+  it('keeps ordinary teardown synchronous and the public disposer single-shot', () => {
+    const ctx = new Context()
+    let cleanups = 0
+    const dispose = ctx.effect(() => () => { cleanups += 1 }, 'sync-effect')
+
+    expect(dispose()).toBeUndefined()
+    expect(cleanups).toBe(1)
+    expect(dispose()).toBeUndefined()
+    expect(cleanups).toBe(1)
+    expect(ctx.fiber.getEffects()).toEqual([])
+  })
+
+  it('rejects cleanup-time registration while a restart is unloading', async () => {
+    const ctx = new Context()
+    let registrationError: unknown
+
+    ctx.effect(() => () => {
+      try {
+        ctx.effect(() => () => {}, 'too-late')
+      } catch (error) {
+        registrationError = error
+      }
+    }, 'restart-cleanup')
+
+    await ctx.fiber.restart()
+    expect(registrationError).toBeInstanceOf(CordisError)
+    expect((registrationError as CordisError).code).toBe('INACTIVE_EFFECT')
+    expect(ctx.fiber.state).toBe(FiberState.ACTIVE)
+    expect(ctx.fiber.getEffects()).toEqual([])
+  })
+
+  it('keeps effect registration legal while child fibers are PENDING and LOADING', async () => {
+    const ctx = new Context()
+    let pendingCleanup = false
+    let loadingCleanup = false
+
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name !== 'state-probe' || fiber.uid === null) return
+      expect(fiber.state).toBe(FiberState.PENDING)
+      fiber.ctx.effect(() => () => { pendingCleanup = true }, 'pending-effect')
+    })
+
+    const fiber = await ctx.plugin({
+      name: 'state-probe',
+      apply(inner) {
+        expect(inner.fiber.state).toBe(FiberState.LOADING)
+        inner.effect(() => () => { loadingCleanup = true }, 'loading-effect')
+      },
+    })
+    await fiber.dispose()
+
+    expect(pendingCleanup).toBe(true)
+    expect(loadingCleanup).toBe(true)
+  })
+
+  it('resolves dependencies that internal/plugin adds before child activation', async () => {
+    const ctx = new Context()
+    ctx.provide('late-inject', {})
+    let applyCalls = 0
+
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name !== 'loader-shaped' || fiber.uid === null) return
+      fiber.inject['late-inject'] = {}
+    })
+
+    const fiber = await ctx.plugin({
+      name: 'loader-shaped',
+      apply() {
+        applyCalls += 1
+      },
+    })
+
+    expect(applyCalls).toBe(1)
+    expect(fiber.state).toBe(FiberState.ACTIVE)
+  })
+})
+
+describe('Cordis child publication ownership', () => {
+  it('rolls back parent and runtime ownership when internal/plugin publication throws', () => {
+    const ctx = new Context()
+    const plugin = { name: 'publication-failure', apply() {} }
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name === plugin.name) throw new Error('publication failed')
+    })
+
+    expect(() => ctx.plugin(plugin)).toThrow('publication failed')
+    expect(ctx.registry.has(plugin)).toBe(false)
+  })
+
+  it('contains teardown notification failures so ownership cleanup and peers complete', async () => {
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const observed: string[] = []
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name === 'contained-teardown' && fiber.uid === null) {
+        throw new Error('broken teardown observer')
+      }
+    })
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name === 'contained-teardown' && fiber.uid === null) observed.push('disposed')
+    })
+    const child = await ctx.plugin({ name: 'contained-teardown', apply() {} })
+
+    await expect(child.dispose()).resolves.toBeUndefined()
+    expect(observed).toEqual(['disposed'])
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toEqual(expect.objectContaining({ message: 'broken teardown observer' }))
+    expect(child.uid).toBeNull()
+  })
+
+  it('makes a LOADING parent join child cleanup started before its unload snapshot', async () => {
+    const ctx = new Context()
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanupStarted = Promise.withResolvers<undefined>()
+    let ownerFiber!: Fiber
+    let ownerDisposal!: Promise<void>
+    let childDisposal!: Promise<void>
+    let childFiber!: Fiber
+
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name !== 'loading-child' || fiber.uid === null) return
+      childFiber = fiber
+      fiber.ctx.effect(() => async () => {
+        cleanupStarted.resolve(undefined)
+        await cleanupGate.promise
+      }, 'loading-child-cleanup')
+      ownerDisposal = ownerFiber.dispose()
+      childDisposal = Promise.resolve(fiber.dispose())
+    })
+
+    const ownerMount = ctx.plugin({
+      name: 'loading-owner',
+      apply(inner) {
+        ownerFiber = inner.fiber
+        inner.plugin({ name: 'loading-child', apply() {} })
+      },
+    })
+
+    await cleanupStarted.promise
+    let ownerSettled = false
+    void ownerDisposal.then(() => { ownerSettled = true })
+    await Promise.resolve()
+    expect(ownerSettled).toBe(false)
+
+    cleanupGate.resolve(undefined)
+    await Promise.all([ownerDisposal, childDisposal, ownerMount])
+    expect(childFiber.uid).toBeNull()
+    expect(ownerFiber.uid).toBeNull()
+  })
+
+  it('lets parent disposal during internal/plugin await the unpublished child to quiescence', async () => {
+    const ctx = new Context()
+    let ownerCtx!: Context
+    const owner = await ctx.plugin({
+      name: 'owner',
+      apply(inner) {
+        ownerCtx = inner
+      },
+    })
+
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanupStarted = Promise.withResolvers<undefined>()
+    let cleanupFinished = false
+    let childApplyCalls = 0
+    let parentDisposal!: Promise<void>
+
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name !== 'child' || fiber.uid === null) return
+      expect(fiber.state).toBe(FiberState.PENDING)
+      fiber.ctx.effect(() => async () => {
+        cleanupStarted.resolve(undefined)
+        await cleanupGate.promise
+        cleanupFinished = true
+      }, 'pending-child-cleanup')
+    })
+    ctx.on('internal/plugin', (fiber) => {
+      if (fiber.name !== 'child' || fiber.uid === null) return
+      parentDisposal = owner.dispose()
+    })
+
+    const child = ownerCtx.plugin({
+      name: 'child',
+      apply() {
+        childApplyCalls += 1
+      },
+    })
+
+    await cleanupStarted.promise
+    let settled = false
+    void parentDisposal.then(() => { settled = true })
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    cleanupGate.resolve(undefined)
+    await parentDisposal
+    expect(cleanupFinished).toBe(true)
+    expect(childApplyCalls).toBe(0)
+    expect(child.uid).toBeNull()
+    expect(child.state).toBe(FiberState.DISPOSED)
+  })
+})