@sleepy-ai/cli 0.1.16 → 0.1.17

package/src/actor/spawn.ts

@@ -1,756 +0,0 @@
-import { Effect, Deferred, Context, Fiber, Layer, Scope, Cause } from "effect"
-import type { SessionID, MessageID } from "@/session/schema"
-import type { ProviderID, ModelID } from "@/provider/schema"
-import type { Tool as AITool, ModelMessage } from "ai"
-import { Session } from "@/session"
-import { SessionPrompt } from "@/session/prompt"
-import { SessionRunState } from "@/session/run-state"
-import { ActorRegistry } from "@/actor/registry"
-import { TaskRegistry } from "@/task/registry"
-import { TaskGate, MAX_TASK_GATE_SUBAGENT_REACT } from "@/task/gate"
-import { Agent } from "@/agent/agent"
-import { Permission } from "@/permission"
-import type { SpawnMode, ContextMode, ToolWhitelist, Lifecycle } from "@/actor/schema"
-import { runTurn } from "@/actor/turn"
-import { spawnRef } from "@/actor/spawn-ref"
-import { Bus } from "@/bus"
-import { MessageV2 } from "@/session/message-v2"
-import { Inbox } from "@/inbox"
-import { renderActorNotification } from "@/inbox/render"
-import { Plugin, HookEvent } from "@/plugin"
-import { parseReturnHeader, type ReturnStatus } from "./return-header"
-import { Log } from "@/util"
-
-const log = Log.create({ service: "actor.spawn" })
-
-/**
- * Cap on preStop ReAct re-entries per spawn — prevents infinite loops.
- * TODO: lift to sleepycode.json config (e.g. actor.maxPreReact) and add per-hook
- * `maxContinue` clamp at registration. Plan: platform cap = hard ceiling, hook
- * cap may only narrow, never widen. See spec Future work.
- */
-export const MAX_PRE_REACT = 3
-/** Cap on postStop ReAct re-entries per spawn. See MAX_PRE_REACT TODO. */
-export const MAX_POST_REACT = 3
-const RETURN_FORMAT_INSTRUCTION = `
-
----
-
-## Return format (required)
-
-Your FINAL assistant message — what the spawning agent will receive — MUST start with this header block:
-
-  **Status**: success | partial | failed | blocked
-  **Summary**: <one sentence describing what happened>
-
-After the header, include the actual deliverable (whatever the task asked for in its prompt).
-
-If applicable, also include below the deliverable:
-
-  **Files touched**: <comma-separated paths or "(none)">
-  **Findings worth promoting**: <bullet list of cross-task transferable facts; "(none)" if just routine work>
-
-This format lets the spawning agent and the checkpoint writer extract your progress without parsing free-form prose. Do NOT precede the header with an introduction — your final message must start with "**Status**:".
-`
-
-export interface ForkContext {
-  readonly system: string[]
-  /**
-   * Tool schema as parent would emit at watermark, captured for invariant
-   * verification only. NOT consumed by fork's runLoop for the actual LLM
-   * request — that uses `resolveTools(forkAgent)` for executable tools with
-   * dispatch closures. Schema parity is currently enforced because
-   * checkpoint-writer has no `toolAllowlist` (Task 2.6); both paths call
-   * `registry.tools` with equivalent agent inputs and produce identical
-   * schemas. If `toolAllowlist` is ever re-added, this field would still
-   * snapshot parent's schema while the runtime tools would diverge, silently
-   * breaking cache parity. Test guard: `test/agent/agent.test.ts` asserts
-   * `cp.toolAllowlist === undefined` for checkpoint-writer.
-   */
-  readonly tools: Record<string, AITool>
-  /**
-   * Parent agent's permission ruleset, captured at spawn. The fork evaluates
-   * permissions and filters its LLM-visible tool list against THIS (the parent's)
-   * ruleset rather than the checkpoint-writer agent's own — restoring prompt-cache
-   * tool-visibility parity with the parent and keeping permission semantics
-   * consistent with the captor. Memory-tree writes are still governed by
-   * memory-path-guard (see askEditUnlessMemory), so an inherited `edit:deny`
-   * does not block the writer's own checkpoint files.
-   */
-  readonly parentPermission: Permission.Ruleset
-  readonly inheritedMessages: ModelMessage[]
-  /**
-   * Boundary marker — the last main-slice message id at spawn. Used by fork's
-   * runLoop to filter ownNew messages (belt-and-braces alongside the agent_id
-   * check; agent_id is sufficient on its own, watermark is the documentary
-   * anchor). NEVER use this for slicing inheritedMessages — inheritedMessages
-   * is captured as a complete snapshot at spawn time.
-   * See docs/superpowers/specs/2026-05-26-fork-agent-prefix-cache-design.md
-   */
-  readonly watermarkMsgID: MessageID
-  readonly model: { providerID: ProviderID; modelID: ModelID }
-}
-
-export type AgentOutcome =
-  | {
-      status: "success"
-      finalText?: string
-      // Structured-output (json_schema) result — when the spawn requested a
-      // format, the validated object is surfaced here and takes precedence over
-      // finalText (DW spec P3).
-      structured?: unknown
-      // Subagent's self-reported header status (parsed from finalText), possibly
-      // overridden by the completion gate (DB truth wins — see onSuccess).
-      reportedStatus?: ReturnStatus
-      reportedSummary?: string
-      // Task IDs the subagent left non-terminal after the gate's cap. Present
-      // only when reportedStatus was downgraded to "partial"/"blocked".
-      incompleteTasks?: string[]
-    }
-  | { status: "failure"; error: string }
-  | { status: "cancelled" }
-
-export interface SpawnInput {
-  mode: SpawnMode
-  sessionID: SessionID
-  /**
-   * Parent session id when the actor runs in a child session (Axis A: checkpoint
-   * writer spawns under a child session keyed on parent_id but writes to the
-   * parent's checkpoint.md / memory.md). Hooks (actor.preStop / actor.postStop)
-   * receive this so plugins re-deriving paths from sessionID can fall back to
-   * `parentSessionID ?? sessionID` and reach the parent's artifacts.
-   *
-   * Defaults to `sessionID` inside spawnSubagent when omitted, so existing
-   * callers (peer / dream / distill / regular subagents where parent ===
-   * session) need no change.
-   */
-  parentSessionID?: SessionID
-  agentType: string
-  task: string
-  description?: string
-  context: ContextMode
-  tools: ToolWhitelist
-  model?: { providerID: ProviderID; modelID: ModelID }
-  background: boolean
-  parentActorID?: string
-  task_id?: string // Spec ②: bound user-task ID for postStop progress.md validation
-  cwd?: string
-  forkContext?: ForkContext // NEW
-  lifecycle?: Lifecycle
-  /**
-   * Optional structured-output format. When set to a json_schema format, the
-   * child's SessionPrompt.prompt requests structured output: the runLoop injects
-   * the StructuredOutput tool, forces toolChoice=required, and the validated
-   * object flows back via message.structured (see runAgentLoop). The validated
-   * object is surfaced on AgentOutcome.structured.
-   */
-  format?: MessageV2.OutputFormat
-  /**
-   * Fired SYNCHRONOUSLY with the freshly-allocated actorID inside the spawn
-   * Effect — right after the actor is registered, BEFORE its work fiber detaches
-   * (forkWork forks into the actor scope). Lets a caller record the child id the
-   * instant the actor exists, closing the window where an in-flight spawn would
-   * otherwise be invisible to a concurrent cancel/reclaim. The WorkflowRuntime
-   * uses this to add the id to its reclaim set before detach (MR104 #2). Best-
-   * effort: a throw is swallowed so a buggy callback can't fail the spawn. Only
-   * the subagent path invokes it (the workflow spawns subagents); spawnPeer does
-   * not — peers are not orchestrated by the workflow runtime.
-   */
-  onActorID?: (actorID: string) => void
-  /**
-   * Fired as an Effect BEFORE Fiber.join (for non-background spawns). Lets the
-   * caller emit metadata (sessionId/actorId) to the tool part state while the
-   * tool is still "running" — critical for the TUI to navigate into a running
-   * subagent. The callback receives the allocated actorID and sessionID.
-   * Swallowed on failure (best-effort, same as onActorID).
-   */
-  onReady?: (info: { actorID: string; sessionID: SessionID }) => Effect.Effect<void>
-}
-
-export interface SpawnResult {
-  actorID: string
-  sessionID: SessionID
-  outcome: Deferred.Deferred<AgentOutcome>
-}
-
-export interface Interface {
-  readonly spawn: (input: SpawnInput) => Effect.Effect<SpawnResult>
-  readonly cancel: (sessionID: SessionID, actorID: string, mode: "graceful" | "forced") => Effect.Effect<void>
-  readonly getForkContext: (actorID: string) => Effect.Effect<ForkContext | undefined>
-}
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/Actor") {}
-
-export const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const session = yield* Session.Service
-    const actorReg = yield* ActorRegistry.Service
-    const agents = yield* Agent.Service
-    const sessionPrompt = yield* SessionPrompt.Service
-    const inbox = yield* Inbox.Service
-    const state = yield* SessionRunState.Service
-    const plugin = yield* Plugin.Service
-    const bus = yield* Bus.Service
-    const taskRegistry = yield* TaskRegistry.Service
-    const scope = yield* Scope.Scope
-
-    // ForkContext snapshot per actor, captured at spawn for fork agents
-    // (contextMode = "full"). Read by fork's runLoop (see prompt.ts) and
-    // cleared on terminal status. Fiber tracking moved to SessionRunState.
-    const forkContexts = new Map<string, ForkContext>()
-
-    // Real agent loop: marks the actor running, then drives a SessionPrompt.prompt
-    // turn. The user message persisted by SessionPrompt carries the actor's
-    // agentID, which the projector writes to MessageTable.agent_id — that is the
-    // load-bearing piece this primitive exists for.
-    //
-    // Returns the assistant's final text (if any) so forkWork's onSuccess can
-    // pass it to inbox.send (notification body) and into the success Deferred.
-    const runAgentLoop = Effect.fn("Actor.runAgentLoop")(function* (input: {
-      sessionID: SessionID
-      actorID: string
-      agentType: string
-      task: string
-      task_id?: string
-      model?: { providerID: ProviderID; modelID: ModelID }
-      source: "spawn" | "hook"
-      provenance?: MessageV2.Provenance
-      format?: MessageV2.OutputFormat
-    }) {
-      const result = yield* sessionPrompt.prompt({
-        sessionID: input.sessionID,
-        agent: input.agentType,
-        agentID: input.actorID,
-        source: input.source,
-        provenance: input.provenance,
-        model: input.model,
-        task_id: input.task_id,
-        parts: [{ type: "text", text: input.task }],
-        ...(input.format ? { format: input.format } : {}),
-      })
-      // structured output (json_schema) takes precedence over finalText: when the
-      // child produced a validated object it IS the authoritative result and the
-      // last text part (often a pre-tool-call preamble) is dropped to avoid
-      // duplicating the result downstream. See spec §5.2.
-      const info = (result as MessageV2.WithParts | undefined)?.info
-      const structured = info?.role === "assistant" ? info.structured : undefined
-      const finalText =
-        structured !== undefined
-          ? undefined
-          : (result as MessageV2.WithParts | undefined)?.parts.findLast(
-              (p): p is Extract<MessageV2.Part, { type: "text" }> => p.type === "text",
-            )?.text
-      return { finalText, structured }
-    })
-
-    const forkWork = (input: {
-      sessionID: SessionID
-      parentSessionID: SessionID
-      parentActorID?: string
-      actorID: string
-      agentType: string
-      task: string
-      description?: string
-      background: boolean
-      model?: { providerID: ProviderID; modelID: ModelID }
-      lifecycle: "ephemeral" | "persistent"
-      task_id?: string
-      // True for non-specialized subagents (those that received
-      // RETURN_FORMAT_INSTRUCTION). Only these are subject to the completion
-      // gate; specialized/system agents and peers create no user tasks.
-      gateEligible?: boolean
-      format?: MessageV2.OutputFormat
-    }) =>
-      Effect.gen(function* () {
-        const outcome = yield* Deferred.make<AgentOutcome>()
-        const description = input.description ?? input.agentType
-        // Auto-start the bound task: spawning an actor for a task IS that task
-        // beginning work. Status transition is a structural side-effect of spawn,
-        // not a model action (the model maintains task status unreliably).
-        // `done` stays gate/model-driven. Uses parentSessionID because the task
-        // lives in the parent/main session, not a peer's child session.
-        // ignoreCause (not ignore): TaskRegistry.start raises a missing task_id as
-        // a *defect* (Effect.die), which Effect.ignore does NOT swallow — only
-        // ignoreCause does. A stale/missing task_id must never block the spawn,
-        // but log on swallow so a genuine bug in start() leaves a breadcrumb.
-        if (input.task_id) {
-          yield* taskRegistry
-            .start({ session_id: input.parentSessionID, id: input.task_id, owner: input.actorID })
-            .pipe(Effect.ignoreCause({ log: "Warn", message: `auto-start of task ${input.task_id} failed` }))
-        }
-        const notify = (
-          status: "completed" | "failed" | "cancelled",
-          extra: { result?: string; error?: string; reportedStatus?: ReturnStatus; reportedSummary?: string },
-        ) =>
-          input.background && input.agentType !== "checkpoint-writer"
-            ? inbox
-                .send({
-                  receiverSessionID: input.parentSessionID,
-                  receiverActorID: input.parentActorID ?? "main",
-                  senderSessionID: input.sessionID,
-                  senderActorID: input.actorID,
-                  type: "actor_notification",
-                  content: renderActorNotification({
-                    actorID: input.actorID,
-                    description,
-                    status,
-                    ...extra,
-                  }),
-                })
-                .pipe(Effect.ignore)
-            : Effect.void
-
-        // Derive actor mode from spawn shape: peer creates a new session, subagent shares parent's
-        const actorMode: "peer" | "subagent" = input.parentSessionID === input.sessionID ? "subagent" : "peer"
-
-        // Writability of THIS agent, derived from the same predicate the runtime uses to
-        // strip the Write tool (llm.ts resolveTools → Permission.disabled). Read-only agents
-        // (e.g. explore: "*":deny) → canWrite=false → postStop progress check is skipped for
-        // them (they cannot satisfy a "write the journal" nudge; their findings return via
-        // finalText). Agent-static: uses agentInfo.permission ONLY, not the session-merged
-        // ruleset resolveTools builds (merge(agent, session)). So canWrite diverges from
-        // runtime tool-stripping only under a session-level override — e.g. session "*":allow
-        // un-stripping a read-only agent's write (we skip though runtime allows), or session
-        // "*":deny on a writable agent (we nudge though runtime strips). Both are deliberately
-        // ignored: not reachable in normal usage (sleepy run sets no such rule, spawn doesn't
-        // rewrite session.permission). See spec §Decision. Unknown agent → fail-open (true).
-        const forkAgentInfo = yield* agents.get(input.agentType)
-        const canWrite = forkAgentInfo ? !Permission.disabled(["write"], forkAgentInfo.permission).has("write") : true
-
-        const work = Effect.gen(function* () {
-          let finalText: string | undefined
-          let structured: unknown | undefined
-          let iteration = 0
-          let lastDecision:
-            | { reason: string; contributingPluginNames: string[]; contributingHookIDs: string[] }
-            | undefined
-
-          while (true) {
-            const reentryDecision = iteration > 0 ? lastDecision : undefined
-            const turn = yield* runTurn(
-              input.sessionID,
-              input.actorID,
-              runAgentLoop({
-                ...input,
-                task: reentryDecision ? reentryDecision.reason : input.task,
-                source: reentryDecision ? "hook" : "spawn",
-                provenance: reentryDecision
-                  ? {
-                      hookPhase: "pre",
-                      hookIteration: iteration,
-                      pluginNames: reentryDecision.contributingPluginNames,
-                      hookIDs: reentryDecision.contributingHookIDs,
-                    }
-                  : undefined,
-              }),
-            )
-            finalText = turn.finalText
-            structured = turn.structured
-
-            iteration++
-            if (iteration > MAX_PRE_REACT) {
-              yield* bus.publish(HookEvent.ReActMaxReached, {
-                phase: "pre",
-                actorID: input.actorID,
-                agentType: input.agentType,
-              })
-              log.warn("actor.preStop hit MAX_PRE_REACT cap; skipping further hook checks", {
-                actorID: input.actorID,
-                totalTurns: iteration,
-              })
-              break
-            }
-
-            const decision = yield* plugin.triggerActorPreStop({
-              sessionID: input.sessionID,
-              parentSessionID: input.parentSessionID,
-              actorID: input.actorID,
-              parentActorID: input.parentActorID,
-              agentType: input.agentType,
-              mode: actorMode,
-              lifecycle: input.lifecycle,
-              finalText,
-              task: input.task,
-              description: input.description,
-              task_id: input.task_id,
-              iteration: iteration - 1,
-            })
-            if (!decision.continue) break
-            if (!decision.reason) break // defense-in-depth — T4 invariant guarantees this won't fire
-
-            yield* bus.publish(HookEvent.ReActReentered, {
-              phase: "pre",
-              actorID: input.actorID,
-              agentType: input.agentType,
-              iteration,
-              triggeredByPlugins: decision.contributingPluginNames,
-              reasonPreview: decision.reason.slice(0, 200),
-            })
-
-            lastDecision = {
-              reason: decision.reason,
-              contributingPluginNames: decision.contributingPluginNames,
-              contributingHookIDs: decision.contributingHookIDs,
-            }
-          }
-
-          return { finalText, structured }
-        }).pipe(
-          Effect.provideService(ActorRegistry.Service, actorReg),
-          Effect.matchCauseEffect({
-            onSuccess: ({ finalText, structured }) =>
-              Effect.gen(function* () {
-                // === COMPLETION GATE (B) + structured parse (A) ===
-                // Delegates the list/decide step to TaskGate.decide so the
-                // logic is shared with the main-session taskGate (prompt.ts).
-                // We retain the runTurn re-entry + delivered-text update here
-                // because that is gate-policy, not list-policy.
-                let deliveredText = finalText
-                if (input.gateEligible) {
-                  let gateIter = 0
-                  while (true) {
-                    const decision = yield* TaskGate.decide({
-                      session_id: input.parentSessionID,
-                      owner: input.actorID,
-                      reactCount: gateIter,
-                      maxReact: MAX_TASK_GATE_SUBAGENT_REACT,
-                      mode: "subagent",
-                    }).pipe(Effect.provideService(TaskRegistry.Service, taskRegistry))
-                    if (!decision.needReentry) break
-                    gateIter++
-                    const gateTurn = yield* runTurn(
-                      input.sessionID,
-                      input.actorID,
-                      runAgentLoop({
-                        ...input,
-                        task: decision.reentryText,
-                        source: "hook",
-                        provenance: { hookPhase: "post", hookIteration: gateIter, pluginNames: [], hookIDs: [] },
-                      }),
-                    ).pipe(
-                      Effect.catch(() =>
-                        Effect.gen(function* () {
-                          log.error("actor.gate runTurn failed", { actorID: input.actorID })
-                          return { finalText: undefined as string | undefined, structured: undefined as unknown }
-                        }),
-                      ),
-                      Effect.provideService(ActorRegistry.Service, actorReg),
-                    )
-                    // The gate re-run's re-emitted text updates the delivered body
-                    // (and structured, if it produced one) so the reconciliation +
-                    // delivery below see the latest turn.
-                    if (gateTurn.finalText !== undefined) deliveredText = gateTurn.finalText
-                    if (gateTurn.structured !== undefined) structured = gateTurn.structured
-                  }
-                }
-
-                // Reconcile: DB truth wins over the model's self-reported header.
-                const remaining = input.gateEligible
-                  ? yield* taskRegistry
-                      .list({ session_id: input.parentSessionID, owner: input.actorID, include_terminal: false })
-                      .pipe(Effect.orElseSucceed(() => []))
-                  : []
-                const stillActionable = remaining.filter((t) => t.status === "open" || t.status === "in_progress")
-                const downgrade: ReturnStatus | undefined =
-                  stillActionable.length > 0 ? "partial" : remaining.length > 0 ? "blocked" : undefined
-                const parsed = parseReturnHeader(deliveredText)
-                const reportedStatus = downgrade ?? parsed.status
-                const incompleteTasks = remaining.map((t) => t.id)
-                const reconciledText =
-                  downgrade && incompleteTasks.length > 0
-                    ? `${deliveredText ?? ""}\n\n**Incomplete tasks**: ${incompleteTasks.join(", ")}`
-                    : deliveredText
-
-                // === DELIVERY ===
-                // structured (json_schema result) takes precedence over text for the
-                // notification body (DW spec P3 §5.2); otherwise deliver the gate's
-                // reconciled text. The success outcome carries both the reconciled
-                // text + completion-gate fields AND structured when present.
-                const deliveryText =
-                  structured !== undefined ? JSON.stringify(structured) : (reconciledText ?? "(no output)")
-                yield* notify("completed", {
-                  result: deliveryText,
-                  ...(reportedStatus ? { reportedStatus } : {}),
-                  ...(parsed.summary ? { reportedSummary: parsed.summary } : {}),
-                })
-                yield* Deferred.succeed(outcome, {
-                  status: "success" as const,
-                  ...(reconciledText !== undefined ? { finalText: reconciledText } : {}),
-                  ...(structured !== undefined ? { structured } : {}),
-                  ...(reportedStatus ? { reportedStatus } : {}),
-                  ...(parsed.summary ? { reportedSummary: parsed.summary } : {}),
-                  ...(incompleteTasks.length > 0 ? { incompleteTasks } : {}),
-                })
-
-                // === postStop ReAct loop ===
-                // Caller has already resolved; new finalTexts are not propagated.
-                // NOTE: parallel structure to preStop loop above — pre runs turn THEN checks,
-                // post checks THEN runs turn. Both give 1 (delivery) + MAX_POST_REACT re-entries.
-                let postIter = 0
-                let lastFinalText = finalText
-                let postReentry:
-                  | { reason: string; contributingPluginNames: string[]; contributingHookIDs: string[] }
-                  | undefined
-
-                while (true) {
-                  const decision = yield* plugin.triggerActorPostStop({
-                    sessionID: input.sessionID,
-                    parentSessionID: input.parentSessionID,
-                    actorID: input.actorID,
-                    parentActorID: input.parentActorID,
-                    agentType: input.agentType,
-                    mode: actorMode,
-                    lifecycle: input.lifecycle,
-                    finalText: lastFinalText,
-                    task: input.task,
-                    description: input.description,
-                    task_id: input.task_id,
-                    outcome: "success",
-                    iteration: postIter,
-                    canWrite,
-                  })
-
-                  if (!decision.continue) break
-                  if (!decision.reason) break // defense-in-depth
-                  if (postIter >= MAX_POST_REACT) {
-                    yield* bus.publish(HookEvent.ReActMaxReached, {
-                      phase: "post",
-                      actorID: input.actorID,
-                      agentType: input.agentType,
-                    })
-                    log.warn("actor.postStop hit MAX_POST_REACT cap; skipping further hook checks", {
-                      actorID: input.actorID,
-                      totalTurns: postIter + 1,
-                    })
-                    break
-                  }
-                  postIter++
-
-                  yield* bus.publish(HookEvent.ReActReentered, {
-                    phase: "post",
-                    actorID: input.actorID,
-                    agentType: input.agentType,
-                    iteration: postIter,
-                    triggeredByPlugins: decision.contributingPluginNames,
-                    reasonPreview: decision.reason.slice(0, 200),
-                  })
-
-                  postReentry = {
-                    reason: decision.reason,
-                    contributingPluginNames: decision.contributingPluginNames,
-                    contributingHookIDs: decision.contributingHookIDs,
-                  }
-
-                  // Run another turn (new finalText is not written back to outcome)
-                  const newTurn = yield* runTurn(
-                    input.sessionID,
-                    input.actorID,
-                    runAgentLoop({
-                      ...input,
-                      task: postReentry.reason,
-                      source: "hook",
-                      provenance: {
-                        hookPhase: "post",
-                        hookIteration: postIter,
-                        pluginNames: postReentry.contributingPluginNames,
-                        hookIDs: postReentry.contributingHookIDs,
-                      },
-                    }),
-                  ).pipe(
-                    // postStop LLM failure: log + break loop, do NOT propagate
-                    Effect.catch(() =>
-                      Effect.gen(function* () {
-                        log.error("actor.postStop runTurn failed", {
-                          actorID: input.actorID,
-                        })
-                        return { finalText: undefined as string | undefined, structured: undefined as unknown }
-                      }),
-                    ),
-                    Effect.provideService(ActorRegistry.Service, actorReg),
-                  )
-
-                  if (newTurn.finalText === undefined) break
-                  lastFinalText = newTurn.finalText
-                }
-
-                yield* Effect.sync(() => forkContexts.delete(input.actorID))
-              }),
-            onFailure: (cause) =>
-              Effect.gen(function* () {
-                const cancelled = Cause.hasInterruptsOnly(cause)
-                const error = Cause.pretty(cause)
-                yield* notify(cancelled ? "cancelled" : "failed", cancelled ? {} : { error })
-                yield* Deferred.succeed(
-                  outcome,
-                  cancelled ? { status: "cancelled" as const } : { status: "failure" as const, error },
-                )
-                yield* Effect.sync(() => forkContexts.delete(input.actorID))
-              }),
-          }),
-        )
-        const fiber = yield* work.pipe(Effect.forkIn(scope))
-        return { fiber, outcome }
-      })
-
-    const spawnPeer = Effect.fn("Actor.spawnPeer")(function* (input: SpawnInput) {
-      const child = yield* session.create({
-        parentID: input.sessionID,
-        contextFrom: input.context === "full" ? input.sessionID : undefined,
-        title: `${input.agentType}: ${input.task.slice(0, 40)}`,
-      })
-      yield* actorReg.register({
-        sessionID: child.id,
-        actorID: child.id,
-        mode: "peer",
-        parentActorID: input.parentActorID,
-        agent: input.agentType,
-        description: input.description ?? input.agentType,
-        contextMode: input.context,
-        contextWatermark: undefined,
-        background: input.background,
-        lifecycle: input.lifecycle ?? "persistent",
-        tools: input.tools,
-      })
-      if (input.forkContext) {
-        forkContexts.set(child.id, input.forkContext) // peer's actorID === child.id
-      }
-      const { fiber, outcome } = yield* forkWork({
-        sessionID: child.id,
-        parentSessionID: input.sessionID,
-        parentActorID: input.parentActorID,
-        actorID: child.id,
-        agentType: input.agentType,
-        task: input.task,
-        description: input.description,
-        background: input.background,
-        model: input.model,
-        lifecycle: input.lifecycle ?? "persistent",
-        task_id: input.task_id,
-        format: input.format,
-      })
-      if (!input.background) yield* Fiber.join(fiber).pipe(Effect.ignore)
-      return { actorID: child.id, sessionID: child.id, outcome }
-    })
-
-    const spawnSubagent = Effect.fn("Actor.spawnSubagent")(function* (input: SpawnInput) {
-      const actorID = yield* actorReg.allocateActorID(input.sessionID, input.agentType)
-
-      const watermark = input.context === "full" ? yield* session.lastMainMessageID(input.sessionID) : undefined
-
-      yield* actorReg.register({
-        sessionID: input.sessionID,
-        actorID,
-        mode: "subagent",
-        parentActorID: input.parentActorID,
-        agent: input.agentType,
-        description: input.description ?? input.agentType,
-        contextMode: input.context,
-        contextWatermark: watermark,
-        background: input.background,
-        lifecycle: input.lifecycle ?? "ephemeral",
-        tools: input.tools,
-      })
-
-      // The actor now EXISTS in the registry. Hand the caller its id before the
-      // work fiber detaches below, so a concurrent reclaim can see it (MR104 #2).
-      // Synchronous + best-effort: a throwing callback must not fail the spawn.
-      if (input.onActorID) yield* Effect.sync(() => input.onActorID!(actorID)).pipe(Effect.ignore)
-
-      if (input.forkContext) {
-        forkContexts.set(actorID, input.forkContext)
-      }
-
-      // Auto-inject return-format instruction for non-specialized subagents.
-      // Excluded: agents with hardcoded `prompt` (explore/title/summary — own
-      // contracts), checkpoint-writer (special — task is itself a complete
-      // writer-instruction string), and peer mode (routes via spawnPeer).
-      const agentInfo = yield* agents.get(input.agentType)
-      const gateEligible =
-        agentInfo?.mode === "subagent" && !agentInfo?.prompt && input.agentType !== "checkpoint-writer"
-      const taskWithFormat = gateEligible ? input.task + RETURN_FORMAT_INSTRUCTION : input.task
-
-      const { fiber, outcome } = yield* forkWork({
-        sessionID: input.sessionID,
-        parentSessionID: input.parentSessionID ?? input.sessionID,
-        parentActorID: input.parentActorID,
-        actorID,
-        agentType: input.agentType,
-        task: taskWithFormat,
-        description: input.description,
-        background: input.background,
-        model: input.model,
-        lifecycle: input.lifecycle ?? "ephemeral",
-        task_id: input.task_id,
-        gateEligible,
-        format: input.format,
-      })
-      if (input.onReady) yield* Effect.ignore(input.onReady({ actorID, sessionID: input.sessionID }))
-      if (!input.background) yield* Fiber.join(fiber).pipe(Effect.ignore)
-      return { actorID, sessionID: input.sessionID, outcome }
-    })
-
-    const spawn = Effect.fn("Actor.spawn")(function* (input: SpawnInput) {
-      if (input.mode === "peer") return yield* spawnPeer(input)
-      return yield* spawnSubagent(input)
-    })
-
-    const cancel: (sessionID: SessionID, actorID: string, mode: "graceful" | "forced") => Effect.Effect<void> =
-      Effect.fn("Actor.cancel")(function* (sessionID: SessionID, actorID: string, mode: "graceful" | "forced") {
-        const children = yield* actorReg.listByParent(sessionID, actorID)
-        yield* Effect.forEach(children, (c) => cancel(sessionID, c.actorID, mode), {
-          concurrency: "unbounded",
-          discard: true,
-        })
-        yield* state.cancelActor(sessionID, actorID)
-        yield* actorReg
-          .updateStatus(sessionID, actorID, { status: "idle", lastOutcome: "cancelled" })
-          .pipe(Effect.ignore)
-        yield* Effect.sync(() => forkContexts.delete(actorID))
-      })
-
-    const getForkContext = Effect.fn("Actor.getForkContext")(function* (actorID: string) {
-      return forkContexts.get(actorID)
-    })
-
-    const impl = Service.of({ spawn, cancel, getForkContext })
-    // Late-bind the impl so SessionCheckpoint.tryStartCheckpointWriter can resolve it
-    // without forming a layer cycle. See spawn-ref.ts for rationale.
-    // Save the previous binding so the finalizer can restore it: when the same
-    // process initialises Actor.layer more than once (memo'd ManagedRuntimes,
-    // overlapping test runtimes, etc.) the inner scope's dispose must hand
-    // control back to the outer scope's impl instead of wiping the ref to
-    // `undefined` and breaking every subsequent tryStartCheckpointWriter call.
-    const prevSpawnRef = spawnRef.current
-    spawnRef.current = impl
-    yield* Effect.addFinalizer(() =>
-      Effect.sync(() => {
-        if (spawnRef.current === impl) spawnRef.current = prevSpawnRef
-      }),
-    )
-    return impl
-  }),
-)
-
-// Wrapped in Layer.suspend so the cross-module `.defaultLayer` reads defer to
-// first use instead of running at module load. Without this, the
-// spawn → prompt → app-runtime import cycle hits a load order where
-// AppLayer's mergeAll runs while SessionPrompt is mid-init and throws
-// "Cannot access 'defaultLayer' before initialization", breaking every
-// it.live test harness. Same pattern session/prompt, session/checkpoint,
-// tool/registry, provider, etc. already use.
-export const defaultLayer = Layer.suspend(() =>
-  layer.pipe(
-    Layer.provide(Session.defaultLayer),
-    Layer.provide(ActorRegistry.defaultLayer),
-    Layer.provide(Agent.defaultLayer),
-    Layer.provide(SessionPrompt.defaultLayer),
-    Layer.provide(SessionRunState.defaultLayer),
-    Layer.provide(Inbox.defaultLayer),
-    Layer.provide(Plugin.defaultLayer),
-    Layer.provide(Bus.layer),
-    Layer.provide(TaskRegistry.defaultLayer),
-  ),
-)
-
-export * as Actor from "./spawn"