Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

136 KB
Raw Blame
/**
 * Active Session runtime.
 *
 * Responsibilities:
 *   - get-or-resume-or-heal: use it directly on an active-table hit; with a Trace,
 *     recover via `agent.resumeSession`; a stale Session that was created but never run
 *     and survived a process restart (no Trace) **self-heals** — recreated via
 *     createSession using the index row's workspace/modelId, yielding a new session_id
 *     and updating the index's primary key; the Task response body always returns the
 *     current actual id;
 *   - Credential effectiveness: a Project's models/credentials change bumps every affected
 *     Agent's config generation (invalidateProjectRuntimes); runtimes built earlier are
 *     discarded on their next idle access and re-resumed, so the next Task runs with the
 *     new api_key / base_url. Agent State changes (vault, AGENTS.md, tools, …) take no
 *     such shortcut: core assembles them into the next model context — at the Session's
 *     next compaction — exactly as the CLI does, so a running context never changes;
 *   - Per-Session mutual exclusion: only one Task/compaction/model switch may be in
 *     progress at a time;
 *   - run/compact/switch drive: consumes the output stream in the background, publishing
 *     each message to the SSE channel and handing it to usage-recorder for persistence;
 *     on completion (including errors) resets to idle and pushes a `task_state` server
 *     event. A model switch (startSwitch) is a compaction whose next context opens on
 *     another model: the entry's (provider, modelId) — the pair usage is attributed to —
 *     and the index row follow the runtime, moving as the new context's session_meta passes
 *     through the drive;
 *   - Approval registration and interrupt convergence: each approval decision re-reads
 *     approval_mode from the DB (takes effect immediately); an interrupt first
 *     converges pending approvals to deny, then aborts. An organization's sessions have
 *     nobody to ask, so a call their mode would hand to a person is denied at once
 *     (see entryApprove).
 *
 * The underlying implementation of get-or-resume-or-heal is injected via
 * `SessionLoader`: production uses the core SDK (createCoreSessionLoader), tests inject
 * a fake Session (issuing no real LLM requests).
 */
import { randomUUID } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import {
  createAgent,
  findLatestTraceFile,
  isHookContinue,
  isHookInput,
  isSessionMeta,
  ModelSwitchRefusedError,
  normalizeSessionSource,
  parseUserSteeringText,
  tracesDir,
  userText,
} from "@adelie/core";
import type {
  ApproveFn,
  BackgroundCommandInfo,
  BackgroundSubagentInfo,
  CompactAvailability,
  ControlEnvContext,
  AgentAssembly,
  OmniMessage,
  ProxyEnvPolicy,
  SpawnConfiner,
  SessionMetaPayload,
  SessionTitleResult,
  StopReason,
  SubagentMessageOptions,
  SubagentMessageOutcome,
  SwitchFailurePolicy,
  TextPayload,
  ThinkingLevelName,
  ToolDetachResult,
} from "@adelie/core";
import type {
  ModelRefDto,
  PendingFollowUpInfo,
  PendingSteeringInfo,
  ServerEvent,
  SessionBackgroundTasks,
  SessionStatus,
} from "../api/types.js";
import type { RecallableFile } from "../services/task-attachments.js";
import { cliShimDir } from "../services/cli-shim.js";
import { HttpError, isMissingCredential, modelCredentialMissing } from "../http/errors.js";
import type { SessionRow } from "../db/repos/sessions.js";
import { ApprovalRegistry, makeApprove } from "./approvals.js";
import { goalOutcomeOf, goalProgressOf } from "./goal-events.js";
import type { PendingApproval } from "./approvals.js";
import type { ChannelHub } from "./channel.js";
import type { ErrorSink } from "./error-recorder.js";
import { LiveTailTracker } from "./live-tail.js";
import { unrunSource } from "./session-sources.js";
import { StreamErrorWatcher } from "./stream-error-watcher.js";
import type { TitleNotifier } from "./title-generator.js";
import type { UsageContext } from "./usage-recorder.js";
import { Component, Interface, Module, Provide, Use } from "@adelie/core/kernel";
import type { SessionService as SessionServiceImpl } from "../services/session-service.js";
import type { ClassCtx, Opaque } from "@adelie/core/kernel";
import { Sandbox, SandboxModule } from "../sandbox/service.js";
import { SANDBOX_GROUP } from "../sandbox/settings-store.js";
import { sandboxEnabledOf, sandboxPresetsOf, sandboxStartOf } from "../sandbox/settings-policy.js";
import { PluginConfig } from "../plugin/config.js";
import { SessionService } from "../services/session-service.js";
import { ModelScopeAuth } from "../services/modelscope-auth-service.js";
import { TitleGenerator } from "./title-generator.js";
import { loopbackHostRoles } from "../services/preview-token.js";
import { mergedNoProxy } from "../net/proxy.js";
import type { SandboxService } from "../sandbox/service.js";
import type { AuthState, Channels, Clock, Config, Log } from "../hmr/capabilities.js";
import type { ProjectConfigStore, ProjectEvents } from "../mechanisms/projects.js";
import type { SessionIndex, SessionOrigins } from "../mechanisms/sessions.js";
import type { Errors, UsageRecording } from "../mechanisms/observability.js";
import type { TraceIndex, TraceIndexStore } from "../mechanisms/traces.js";
import type { Settings } from "../mechanisms/settings.js";
import type { MessagingBindings } from "../mechanisms/messaging.js";
import type { OrgCache } from "../mechanisms/organization.js";
import { enabledMessagingChannel } from "./messaging/enabled-channel.js";
import { MODELSCOPE_PROVIDER_ID } from "@adelie/core/model-catalog";

/**
 * 409 for when there's nothing to compact: give the specific reason rather than a
 * one-size-fits-none message.
 *
 * Each reason carries its **own code**, not just its own message. Clients localize by code
 * (the Web's `apiErrorText` looks the code up in a table and falls back to the raw English
 * message), so one shared code leaves exactly two bad options: flatten three unrelated
 * explanations into one vague sentence, or let English prose reach a non-English UI. One code
 * per sub-reason is how the rest of this API splits a refusal — `dir_not_absolute` /
 * `dir_not_found` / `not_a_dir` are three codes for three ways of rejecting one directory.
 */
function compactUnavailable(why: Exclude<CompactAvailability, "ok">): HttpError {
  const reasons: Record<typeof why, { code: string; message: string }> = {
    unsupported: {
      code: "compaction_not_configured",
      message: "This Agent does not have context compaction configured.",
    },
    empty: {
      code: "nothing_to_compact",
      message: "The current context has nothing to compact (no completed conversation turns yet).",
    },
    just_compacted: {
      code: "already_compacted",
      message:
        "The context was just compacted and there is no new conversation since; no need to compact again.",
    },
  };
  const { code, message } = reasons[why];
  return new HttpError(409, code, message);
}

/**
 * Core's refusal of a model switch — a typed `ModelSwitchRefusedError`, thrown before its
 * first event (see `Session.switchModel`) — as the 409 the HTTP contract names for it: each
 * reason is its own code (see `SessionSwitchModelRequest`). A missing credential reads as the
 * remedy the Web App can act on rather than the loader's own wording. Anything else core
 * throws is not a refusal but a failure — an Agent State that no longer parses, a bootstrap
 * that broke — and is rethrown, so it reaches the 500 path and its logging instead of being
 * dressed up as a target problem.
 */
function switchRefusal(err: unknown, ref: ModelRefDto): HttpError {
  if (!(err instanceof ModelSwitchRefusedError)) throw err;
  const message =
    err.reason === "model_unavailable" && isMissingCredential(err)
      ? `Model ${ref.modelId} has no API key yet. Configure it on the Models page first.`
      : err.message;
  return new HttpError(409, err.reason, message);
}

/** A stream whose head was already pulled, whole again: `head`, then the rest of `rest`. */
async function* resumeFrom<T>(head: T, rest: AsyncGenerator<T, unknown>): AsyncGenerator<T> {
  yield head;
  yield* rest;
}

/** The model a runtime Session reports itself on, or null for one that reports none (test fakes). */
function runtimeModelOf(session: RuntimeSession): ModelRefDto | null {
  const { provider, modelId } = session;
  if (provider === undefined || modelId === undefined) return null;
  return { provider, modelId };
}

/** Minimal interface for a runtime Session (satisfied by core Session; tests may inject a fake implementation). */
export interface RuntimeSession {
  readonly sessionId: string;
  run(
    newMessages: OmniMessage[],
    opts: {
      approve: ApproveFn;
      signal: AbortSignal;
    },
  ): AsyncGenerator<OmniMessage>;
  compact(opts: { signal: AbortSignal }): AsyncGenerator<OmniMessage>;
  /**
   * The running context's model (core `Session.provider` / `Session.modelId`, getters over
   * the context's session_meta): the row's pair at creation, moved by each in-session switch
   * — and, after a restart, whatever the Trace resumed on. Optional: test fakes may omit them,
   * in which case the entry keeps the row's pair.
   */
  readonly provider?: string;
  readonly modelId?: string;
  /**
   * Switches the Session's model in place (core `Session.switchModel`): closes the running
   * context on the model it ran on, then opens the next one on the target. A completed switch
   * streams the new context's main-session `session_meta` last, and the getters above answer
   * the target by then; a refusal is thrown before the first event; a Session that never ran
   * switches without streaming anything. Optional: test fakes may omit it, reading as
   * "switching is not available".
   *
   * `onCompactionFailure` is core's own field of the same name (`"discard"` drops the context
   * and switches anyway); the manager passes it straight through and never reads it.
   */
  switchModel?(opts: {
    provider: string;
    modelId: string;
    signal: AbortSignal;
    onCompactionFailure?: SwitchFailurePolicy;
  }): AsyncGenerator<OmniMessage, StopReason>;
  /**
   * The Session's thinking level (core `Session.thinkingLevel`, plain state): soft-limited —
   * an assignment applies from the Session's very next LLM request. Optional: test fakes may
   * omit it.
   */
  thinkingLevel?: ThinkingLevelName;
  /** Whether compaction is possible and why; when not ok, compact() yields no messages (see core ContextEngine.compactability). */
  compactability(): CompactAvailability;
  /** Queues a mid-run steering input (core `Session.steer`); false when no Task is running. */
  steer(input: OmniMessage[]): boolean;
  /**
   * Withdraws a steering input queued via `steer` before core delivers it (core
   * `Session.unsteer`, matched by input-list identity); false when it is no longer queued —
   * already delivered, or the run exited. Optional: test fakes may omit it, in which case
   * every recall reports "already delivered".
   */
  unsteer?(input: OmniMessage[]): boolean;
  /** Skips the in-progress reconnect backoff, firing the next retry immediately (core `Session.skipReconnectWait`); false when no wait is in progress. */
  skipReconnectWait(): boolean;
  /**
   * Runs the named package's `user_prompt` hook (core `Session.runUserPromptHook` — hooks
   * run in core and nowhere else); null = the package is not installed or names no such
   * command. Optional: test fakes may omit it, reading as not installed.
   */
  runUserPromptHook?(
    name: string,
    prompt: string,
    extras?: Record<string, string | number | boolean>,
  ): Promise<{ context?: string } | null>;
  /** A tool's permission level from the running context's toolset (core `Session.toolPermission`; strict-tier — rebuilt at rotation). */
  toolPermission(name: string): "r" | "rw" | undefined;
  /**
   * Out-of-band one-shot request for title generation (core `Session.generateTitle`,
   * writes no history/Trace). Material defaults to what the Session collects itself
   * (the first Task's text gathered during run); `material` overrides this for
   * subagents.
   */
  generateTitle(args?: {
    material?: { userText: string; assistantText: string };
    signal?: AbortSignal;
  }): Promise<SessionTitleResult>;
  /**
   * Subscribes the idle-arrival signal for background-task completion notices (core
   * `Session.onBackgroundNotice`): fired when a `run_in_background` launch settles while no
   * Task is running — the manager then takes the queue and submits it as an ordinary task.
   * Optional: test fakes may omit it.
   */
  onBackgroundNotice?(listener: () => void): void;
  /** Takes the queued background completion notices as task input (core `Session.takeBackgroundNotices`). Optional, like onBackgroundNotice. */
  takeBackgroundNotices?(): OmniMessage[];
  /** Whether completion notices are still queued (core `Session.hasPendingBackgroundNotices`); pins the entry against idle eviction. Optional, like onBackgroundNotice. */
  hasPendingBackgroundNotices?(): boolean;
  /** Refreshes the listen-port probes behind the process list's `serviceUrl` (core `Session.probeBackgroundCommandServices`). Optional: test fakes may omit it. */
  probeBackgroundCommandServices?(): Promise<void>;
  /** Subscribes live-forwarded background-subagent messages (core `Session.onBackgroundMessage`); the manager publishes them to the session channel. Optional: test fakes may omit it. */
  onBackgroundMessage?(listener: (msg: OmniMessage) => void): void;
  /** Background command processes owned by the Session's environment (core `Session.listBackgroundCommands`). Optional: test fakes may omit it. */
  listBackgroundCommands?(): BackgroundCommandInfo[];
  /** Kills one background command process (core `Session.killBackgroundCommand`); false when the id is unknown. Optional, like listBackgroundCommands. */
  killBackgroundCommand?(processId: string): boolean;
  /** Hands one EXECUTING tool call back as a background task (core `Session.detachToolCall`). Optional: test fakes may omit it, reading as "not_running". */
  detachToolCall?(toolCallId: string): ToolDetachResult;
  /** Whether a background subagent is mid-round (core `Session.hasRunningBackgroundSubagents`); pins the entry against idle eviction. Optional, like listBackgroundCommands. */
  hasRunningBackgroundSubagents?(): boolean;
  /** All live subagent child sessions of the Session's environment (core `Session.listBackgroundSubagents`). Optional, like listBackgroundCommands. */
  listBackgroundSubagents?(): BackgroundSubagentInfo[];
  /** Host message to one child session — steering mid-run, a follow-up run when idle, a revival when released (core `Session.sendToBackgroundSubagent`). Optional. */
  sendToBackgroundSubagent?(
    childSessionId: string,
    messages: OmniMessage[],
    opts?: SubagentMessageOptions,
  ): Promise<SubagentMessageOutcome>;
  /** Subscribes the host's session-lifetime fallback approval sink for child sessions (core `Session.setSubagentApprovalFallback`). Optional. */
  setSubagentApprovalFallback?(approve: ApproveFn): void;
  /** Aborts one child session's current run, keeping the session (core `Session.abortBackgroundSubagentRun`); false when unknown or idle. Optional. */
  abortBackgroundSubagentRun?(childSessionId: string): boolean;
  /** Pins one live child session's thinking level (core `Session.setBackgroundSubagentThinkingLevel`); false when the child is not live. Optional. */
  setBackgroundSubagentThinkingLevel?(childSessionId: string, level: ThinkingLevelName): boolean;
  /** Subscribes subagent run-state changes (core `Session.onSubagentState`): the manager republishes `task_state` with the fresh live listing. Optional. */
  onSubagentState?(listener: () => void): void;
  /** Subscribes background-task state changes (core `Session.onBackgroundState`): the manager re-counts the live registries and publishes `session_background` when the counts moved. Optional. */
  onBackgroundState?(listener: () => void): void;
  /** Releases environment resources — kills the remaining background processes (core `Session.dispose`). Optional, idempotent. */
  dispose?(): void;
}

/** The underlying loader behind get-or-resume-or-heal. */
export interface SessionLoader {
  /**
   * Load a runtime Session from an index row: recover (with a Trace) or self-heal
   * rebuild (no Trace, session_id will change). Throws HttpError(409) for unrecoverable
   * cases such as a missing Workspace.
   */
  load(row: SessionRow): Promise<RuntimeSession>;
}

/**
 * Production loader: the core SDK's resumeSession / createSession. `sources` (when given)
 * lets the no-Trace self-heal rebuild re-record a known origin into the fresh session_meta;
 * with no registry entry (e.g. the process restarted and no Trace was ever written) the
 * rebuilt Session is unsourced — session_meta is the single source of truth, and none survived.
 * `opts.proxyEnv` threads the admin proxy settings into core (a live getter returning the
 * agent-command-subprocess policy: strip the proxy variables, inject the explicit proxy
 * address, or null = pass the environment through). `opts.controlEnv` threads the
 * harness-control injection the same way (the server's API URL/token plus the Session's
 * coordinates; core evaluates it per Session — see CreateAgentOptions.controlEnv), and
 * `opts.pathPrepend` the directories every command of a resumed Session finds at the front
 * of its PATH (the harness's own CLI shim — see CreateAgentOptions.pathPrepend).
 */
export function createCoreSessionLoader(
  root: string,
  sources?: SessionOrigins,
  opts: {
    proxyEnv?: () => ProxyEnvPolicy | null;
    controlEnv?: (ctx: ControlEnvContext) => Record<string, string>;
    pathPrepend?: () => string[];
    confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null;
    assembly?: AgentAssembly;
  } = {},
): SessionLoader {
  return {
    async load(row: SessionRow): Promise<RuntimeSession> {
      const agent = await createAgent({
        root,
        projectId: row.projectId,
        agentId: row.agentId,
        ...(opts.proxyEnv ? { proxyEnv: opts.proxyEnv } : {}),
        ...(opts.controlEnv ? { controlEnv: opts.controlEnv } : {}),
        ...(opts.pathPrepend ? { pathPrepend: opts.pathPrepend } : {}),
        ...(opts.confineSpawn ? { confineSpawn: opts.confineSpawn } : {}),
        ...(opts.assembly ? { assembly: opts.assembly } : {}),
      });
      const located = await findLatestTraceFile(
        tracesDir(root, row.projectId, row.agentId),
        row.sessionId,
      );
      if (located) {
        // With a Trace: rebuild via "Session Recovery" (history injected via setHistory,
        // carrying over any residual state).
        // core's recognizable recovery failures (Workspace deleted / Model removed from
        // config / Trace missing session_meta, etc.) are converged to 409, preserving
        // the original message rather than bubbling up as 500.
        try {
          const session = await agent.resumeSession({ sessionId: row.sessionId });
          // The row's stored level — the knob position the user last chose — restored onto
          // the runtime as a plain assignment: it rides the resumed Session's requests.
          if (row.thinkingLevel) session.thinkingLevel = row.thinkingLevel;
          return session;
        } catch (err) {
          // The credential key was deleted after the Session was created: only caught
          // here at recovery time; give the same actionable message.
          if (isMissingCredential(err)) throw modelCredentialMissing(row.modelId);
          throw toUnrecoverableError(err);
        }
      }
      // No Trace (created but never run, and the process has restarted since): self-heal
      // rebuild. A missing Workspace → 409.
      try {
        const stat = await fs.stat(row.workspace);
        if (!stat.isDirectory()) throw new Error("not a directory");
      } catch {
        throw new HttpError(
          409,
          "workspace_missing",
          `This Session's Workspace no longer exists: ${row.workspace}, so it cannot continue. Create a new Session.`,
        );
      }
      // The source this process recorded at creation, else the one the row stands for: the
      // organization runtime's are `company`, the Agent API's `api` (unrunSource), the list's
      // reading of the same row.
      const knownSource = sources?.get(row.sessionId) ?? unrunSource(row.client);
      try {
        return await agent.createSession({
          workspaceDir: row.workspace,
          modelId: row.modelId,
          provider: row.provider,
          // The rebuilt Session records that source in its fresh session_meta (an unknown one
          // is core's default, `user`), and starts its first context at the row's pinned level.
          ...(knownSource !== undefined ? { source: knownSource } : {}),
          ...(row.thinkingLevel ? { thinkingLevel: row.thinkingLevel } : {}),
        });
      } catch (err) {
        if (isMissingCredential(err)) throw modelCredentialMissing(row.modelId);
        throw toUnrecoverableError(err);
      }
    },
  };
}

/** A plain Error thrown by core recovery/self-heal rebuild → 409 (preserving the original, actionable message). */
function toUnrecoverableError(err: unknown): HttpError {
  if (err instanceof HttpError) return err;
  return new HttpError(
    409,
    "session_unrecoverable",
    err instanceof Error ? err.message : String(err),
  );
}

export interface UsageRecorderLike {
  record(ctx: UsageContext, msg: OmniMessage): Promise<void>;
}

export interface SessionManagerDeps {
  sessions: SessionIndex;
  channels: ChannelHub;
  loader: SessionLoader;
  /** Session-origin registry (session_meta is the single source of truth; subagent registration records the forwarded meta's source here). */
  sources: SessionOrigins;
  recorder: UsageRecorderLike;
  /** Automatic Session title generation (optional: not injected in tests or when disabled). */
  titles?: TitleNotifier;
  /** Error persistence (optional: without it, only logs — same as before this was wired up). */
  errors?: ErrorSink;
  /** Provider auth refresh (optional for tests that do not exercise external model credentials). */
  modelScopeAuth?: ModelScopeAuth;
  log?: (line: string) => void;
  /** Goal run-state persistence (optional like `titles`: without it, goals run but leave no restorable record). */
  /**
   * Publishes a Session-scoped event on the user-level channel of everyone who can see the
   * Project. The audience lookup (owner + members) and the `user:<id>` channel binding stay in
   * the app layer, the same split the scheduler's `notify` uses — this class holds no Project
   * membership repos. Optional: without it only the per-Session channel is served, which is
   * what unit tests that don't wire it get.
   */
  notifyProjectUsers?: (projectId: string, event: ServerEvent) => void;
  /**
   * Clock for persisted timestamps (last_active_at). Injected like the other services' so a
   * stubbed clock moves this and `usage_records.ts` together — the pairing the legacy
   * backfill assumes when it reads MAX(ts) as a session's last activity.
   */
  now?: () => Date;
  /**
   * Called when a Task starts (or is queued) from a PERSON's input — a message typed in the
   * Web App, the CLI or a bound messaging bot, as opposed to one the harness injected
   * (`sender: "server"` / `"harness"`). Company mode uses it to reset the desk's @-chain
   * accounting: a person's message opens a fresh chain (hop 0), whatever mention last woke
   * the desk. Optional; unit tests that do not wire it get nothing.
   */
  onHumanInput?: (sessionId: string) => void;
}

/**
 * Whether a Task's input came from a person: every text payload either carries no sender or
 * `sender: "user"`. A harness-injected turn (`"server"`, `"harness"`, `"parent_agent"`) on any
 * message makes the whole input non-human — the org scheduler's trigger and a subagent's
 * prompt both arrive that way.
 */
export function isHumanInput(input: readonly OmniMessage[]): boolean {
  return input.every((m) => {
    const p = m.payload as { sender?: string };
    return p.sender === undefined || p.sender === "user";
  });
}

/**
 * A queued message's original content, held while it waits in a queue so a recall (DELETE
 * /steer/:id, DELETE /follow-ups/:id) can hand it back to the composer for editing (#287).
 * `text`, `images` and `videos` are the same strings the queued input already references (no
 * extra copy); files stay on disk in the Session scratchpad and are read back only at recall.
 * `videos` holds the inline ones only — a video the Session's model cannot take was turned
 * into a file before it ever got here (see the task route).
 */
export interface RecallStore {
  text: string;
  images: string[];
  videos: string[];
  files: RecallableFile[];
}

/** One queued follow-up task (`queueIfBusy`): the task input, held until the session is idle. */
interface QueuedFollowUp {
  /** Recall handle (PendingFollowUpInfo.id), assigned at queue time. */
  id: string;
  input: OmniMessage[];
  /**
   * Original content for recall, and the content `task_state` shows on the queued line.
   * Always present: a caller that knows more than the input carries (the HTTP route, which
   * also knows where the file attachments landed on disk) supplies it, and every other
   * queueing path gets it derived from the input — what can be recalled must not depend on
   * which door the message came through.
   */
  recall: RecallStore;
}

/** One undelivered steering entry: the display info broadcast on task_state, plus what a recall needs — the exact input list core queued (its unsteer handle) and the original content. */
interface PendingSteeringEntry {
  info: PendingSteeringInfo;
  input: OmniMessage[];
  recall: RecallStore;
}

/** Active-table entry: a loaded runtime Session plus its running state. */
interface RuntimeEntry {
  sessionId: string;
  projectId: string;
  agentId: string;
  /**
   * The Session's current model (provider group paired with modelId): what the next drive
   * attributes usage to. The row's pair, kept in step with the runtime's own answer (see
   * `syncEntryModel`) — at load, and whenever a model switch moves it.
   */
  provider: string;
  modelId: string;
  session: RuntimeSession;
  status: SessionStatus;
  approvals: ApprovalRegistry;
  abort: AbortController | null;
  /** The in-flight drive Promise (awaited during graceful shutdown). */
  running: Promise<void> | null;
  /**
   * Agent config generation this runtime was built under (see
   * invalidateAgentRuntimes): once it falls behind the Agent's current generation,
   * the entry is discarded on its next idle access and re-resumed via the loader.
   */
  generation: number;
  /**
   * Queued follow-up tasks (`queueIfBusy`): task inputs accepted while a Task/compaction was
   * in progress, auto-started one at a time (in order) once the session returns to idle —
   * ordinary tasks with normal semantics, unlike the mid-run steering queue.
   * Deliberately NOT discarded on abort: they are future tasks the user explicitly queued.
   */
  followUps: QueuedFollowUp[];
  /**
   * The running Task's input messages, held from launch until the run ends. The engine
   * writes these exact envelopes to the Trace only after the session bootstrap (MCP
   * connect + discovery on the first run), so a history read during that window would
   * miss the user's own message — and the draft flow subscribes to the stream only after
   * the input publish, so the live channel cannot backfill it either. GET /messages
   * appends the ones the Trace has not caught up to yet (exact-envelope dedup).
   */
  pendingInputs: OmniMessage[];
  /**
   * The running Task's streamed bootstrap records (mcp_connect begin/end,
   * tool_list_ready), held until the run ends. Their Trace writes are deferred by the
   * engine until after the input lands (turn attribution), and the draft flow subscribes
   * only after they were published — so a history rebuild during the MCP connect would
   * otherwise show nothing at all (a silent blank while a slow server times out).
   * GET /messages appends whichever of them the Trace has not caught up to.
   */
  pendingBootstrap: OmniMessage[];
  /**
   * Steering messages queued on core but not yet delivered to the model — a display mirror
   * of core's steering queue (same FIFO order), so the composer's "steering queued" hint and
   * its content survive reloads: pushed on `steer`, shifted as each `[user_steering]`
   * message appears on the drive stream, dropped wholesale when the run exits (core
   * discards undelivered steering on abort/completion). The `info` halves are broadcast on
   * every `task_state`; the rest is the recall handle (see recallSteering).
   */
  pendingSteering: PendingSteeringEntry[];
  /**
   * Steering the run ended without ever delivering — handed back to the user instead of
   * discarded (#287 follow-up). An interrupt mid-tool-call is the ordinary way to get here:
   * core drops its queue when the run exits, so the message would otherwise vanish with the
   * text the user had already typed.
   *
   * Entries move here from `pendingSteering` when the run exits and stay recallable by the
   * same handle, so the composer pulls them back into its draft (auto-recall on observing
   * them, a reload included). They are deliberately NOT cleared when the next run starts:
   * the message was never delivered whatever happens later, and dropping it there would
   * reintroduce exactly the loss this list exists to prevent. Only a recall — or the entry's
   * idle eviction — removes one.
   */
  returnedSteering: PendingSteeringEntry[];
  /** Timestamp of last activity (refreshed on load / status flip / drive completion / background-task change), used for idle-eviction checks. */
  lastActivityMs: number;
  /**
   * Background-task counts as last read from the runtime — at entry creation, then on every
   * background-state ping. The baseline `session_background` is published against: a ping
   * that leaves the counts where they were (a foreground-window child settling, an exited
   * process being removed from the list) publishes nothing.
   */
  backgroundTasks: SessionBackgroundTasks;
}

/** Active-table idle eviction: same convention as the SSE channel (an idle entry with no activity for 30 minutes releases its memory). */
const ENTRY_IDLE_MS = 30 * 60 * 1000;
const ENTRY_SWEEP_INTERVAL_MS = 60 * 1000;

/**
 * Queue depth cap per session. Every queued follow-up is a full model run waiting to
 * happen, and the queue has no other brake: org triggers always ask to queue
 * (queueIfBusy), so a mention storm or an @all fan-out against a busy desk would grow it
 * without bound and then replay every entry as a model call. The cap refuses the overflow
 * loudly instead (429 queue_full): the org trigger path records org_dispatch_failed, and
 * the HTTP caller sees the refusal directly.
 */
export const FOLLOW_UP_QUEUE_LIMIT = 16;

/** Composite Agent key (used as a Set key, avoiding projectId/agentId concatenation ambiguity). */
function agentKey(projectId: string, agentId: string): string {
  return `${projectId}\0${agentId}`;
}

/**
 * The runtime's background-task counts, read live from its registries: command sessions
 * whose process is still running (exited rows stay listed until removed and do not count),
 * and subagent sessions that hold a `subagent_id` — promoted to the background by a yield
 * window expiring or a `run_in_background` launch — and are mid-round. A child still inside
 * a foreground collect window has no id yet and is the running Task's own work, not
 * background work.
 */
function backgroundTaskCounts(session: RuntimeSession): SessionBackgroundTasks {
  const processes = session.listBackgroundCommands?.().filter((p) => p.running).length ?? 0;
  const subagents =
    session.listBackgroundSubagents?.().filter((s) => s.running && s.subagentId !== null).length ??
    0;
  return { processes, subagents };
}

/** The `task_state` display info of one queued follow-up (see PendingFollowUpInfo). */
function followUpInfo(f: QueuedFollowUp): PendingFollowUpInfo {
  return {
    id: f.id,
    text: f.recall.text,
    images: f.recall.images.length,
    videos: f.recall.videos.length,
    files: f.recall.files.length,
  };
}

/**
 * The recall store of a queued input whose caller supplied none: everything recallable is
 * already in the input itself — the user's text and the inline image / video URLs, the only
 * shapes a task input is ever built from.
 *
 * `files` is empty because the path a written attachment landed on is known only to
 * whoever wrote it. A caller that wrote some therefore builds its store on top of this one
 * instead of leaving it to be derived, and passes the input as it stood BEFORE the
 * `[attached file: …]` lines were folded in — derived from the folded input, `text` would
 * hand a recall back a raw scratchpad path in place of the chip it was meant to restore.
 */
export function recallStoreOf(input: OmniMessage[]): RecallStore {
  const text = input
    .filter(isPlainText("user"))
    .map((m) => m.payload.text)
    .join("\n");
  const images: string[] = [];
  const videos: string[] = [];
  for (const msg of input) {
    const payload = msg.payload as { type?: string; image_url?: unknown; video_url?: unknown };
    if (msg.type !== "model_msg") continue;
    if (payload.type === "image_url" && typeof payload.image_url === "string") {
      images.push(payload.image_url);
    } else if (payload.type === "video_url" && typeof payload.video_url === "string") {
      videos.push(payload.video_url);
    }
  }
  return { text, images, videos, files: [] };
}

/** If msg is a run_subagent tool call carrying a `prompt`, return its id and prompt (for use as the subagent's title); otherwise null. */
/** Whether this main-stream message is a delivered `[user_steering]` user text (one per queued steering entry, see core's steeringMessages). */
function isDeliveredSteering(msg: OmniMessage): boolean {
  const p = msg.payload as { type?: string; role?: string; text?: string };
  if (msg.type !== "model_msg" || p.type !== "text" || p.role !== "user") return false;
  return typeof p.text === "string" && parseUserSteeringText(p.text) !== null;
}

function runSubagentCall(msg: OmniMessage): { toolCallId: string; prompt: string } | null {
  const p = msg.payload as {
    type?: string;
    name?: string;
    arguments?: string;
    tool_call_id?: string;
  };
  if (msg.type !== "model_msg" || p.type !== "tool_call" || p.name !== "run_subagent") return null;
  if (typeof p.arguments !== "string" || typeof p.tool_call_id !== "string") return null;
  try {
    const args = JSON.parse(p.arguments) as { prompt?: unknown };
    if (typeof args.prompt !== "string" || !args.prompt.trim()) return null;
    return { toolCallId: p.tool_call_id, prompt: args.prompt };
  } catch {
    return null; // Arguments were truncated/malformed: this call is doomed, no subagent will result
  }
}

/** The denied tool_call_id (approval_decision with decision ≠ allow); otherwise null. */
function deniedToolCallId(msg: OmniMessage): string | null {
  const p = msg.payload as { type?: string; decision?: string; tool_call_id?: string };
  if (msg.type !== "event_msg" || p.type !== "approval_decision") return null;
  if (p.decision === "allow" || typeof p.tool_call_id !== "string") return null;
  return p.tool_call_id;
}

/** The tool_call_id of a parent-level tool call that has settled (a complete tool_call_output); otherwise null. */
function settledToolCallId(msg: OmniMessage): string | null {
  const p = msg.payload as { type?: string; tool_call_id?: string };
  if (msg.type !== "model_msg" || p.type !== "tool_call_output") return null;
  return typeof p.tool_call_id === "string" ? p.tool_call_id : null;
}

/** A subagent registered during this run, plus its title material. */
interface ChildSession {
  sessionId: string;
  agentId: string;
  /** The prompt of the run_subagent call that spawned it (user material for title generation, and the fallback title). */
  prompt: string;
}

/** Predicate for a plain-text message on the main session (no origin): title material is drawn only from user/model text. */
function isPlainText(role: "user" | "assistant") {
  return (msg: OmniMessage): msg is OmniMessage<TextPayload> => {
    const payload = msg.payload as { type?: string; role?: string };
    return (
      msg.type === "model_msg" &&
      payload.type === "text" &&
      payload.role === role &&
      (!msg.origin || msg.origin.length === 0)
    );
  };
}

export class SessionManager {
  private readonly entries = new Map<string, RuntimeEntry>();
  /**
   * Each registered subagent Session's ROOT Session: a subagent runs under its root's
   * sandbox policy, as it runs under its root's approval mode, so a change the person makes
   * in the composer reaches the children already running.
   */
  private readonly childRoots = new Map<string, string>();

  /** The Session whose policy governs `sessionId`: its root for a subagent, else itself. */
  rootSessionOf(sessionId: string): string {
    return this.childRoots.get(sessionId) ?? sessionId;
  }
  /** Per-Session mutex (serializes get-or-load and status flips); auto-cleaned once the chain drains. */
  private readonly locks = new Map<string, Promise<unknown>>();
  private readonly log: (line: string) => void;
  /** Graceful-shutdown flag: once set, new Tasks/compactions are rejected (503). */
  private closed = false;
  /** Agents currently being deleted (key = agentKey): new Tasks/compactions are always rejected with 409 during this window. */
  private readonly deletingAgents = new Set<string>();
  /** Sessions currently being deleted (guards against the entry/Trace file being rebuilt and reviving it inside the deletion race window). */
  private readonly deletingSessions = new Set<string>();
  /** Per-Agent config generation (key = agentKey), bumped by invalidateAgentRuntimes when a Project's credentials change. */
  private readonly agentGenerations = new Map<string, number>();
  /** Open streaming fragments of running sessions (fed by drive, served to GET /messages; see live-tail.ts). */
  private readonly liveTail = new LiveTailTracker();
  private readonly sweepTimer: NodeJS.Timeout;
  /** Clock for persisted timestamps (see SessionManagerDeps.now); wall clock unless injected. */
  private readonly now: () => Date;

  constructor(private readonly deps: SessionManagerDeps) {
    this.log = deps.log ?? ((line) => console.error(line));
    this.now = deps.now ?? (() => new Date());
    this.sweepTimer = setInterval(() => this.sweepIdle(), ENTRY_SWEEP_INTERVAL_MS);
    this.sweepTimer.unref?.();
  }

  // —— Query surface (used by Session listing / Agent active-count / SSE subscription replay) ——

  statusOf(sessionId: string): SessionStatus {
    return this.entries.get(sessionId)?.status ?? "idle";
  }

  /**
   * Every Session this process holds in a live state — running or compacting — across all
   * Projects and Agents. `statusOf` answers one id at a time, and a Session nobody is looking
   * at has no row in any client's list; the account menu's "what is running right now" asks
   * the whole table instead, which is a walk over the entries this process already keeps.
   */
  liveSessions(): Array<{
    sessionId: string;
    projectId: string;
    agentId: string;
    status: SessionStatus;
  }> {
    const out: Array<{
      sessionId: string;
      projectId: string;
      agentId: string;
      status: SessionStatus;
    }> = [];
    for (const e of this.entries.values()) {
      if (e.status === "idle") continue;
      out.push({
        sessionId: e.sessionId,
        projectId: e.projectId,
        agentId: e.agentId,
        status: e.status,
      });
    }
    return out;
  }

  pendingApprovalCount(sessionId: string): number {
    return this.entries.get(sessionId)?.approvals.size ?? 0;
  }

  pendingApprovals(sessionId: string): PendingApproval[] {
    return this.entries.get(sessionId)?.approvals.list() ?? [];
  }

  /** Number of queued follow-up tasks (`queueIfBusy`) awaiting auto-start. */
  pendingFollowUpCount(sessionId: string): number {
    return this.entries.get(sessionId)?.followUps.length ?? 0;
  }

  /**
   * Background-task counts of a LOADED session, read live (see SessionInfo.backgroundTasks);
   * undefined when the session is not in the active table or nothing is running — the list
   * row and the single GET omit the field in both cases.
   */
  backgroundTasksOf(sessionId: string): SessionBackgroundTasks | undefined {
    const entry = this.entries.get(sessionId);
    if (!entry) return undefined;
    const counts = backgroundTaskCounts(entry.session);
    return counts.processes > 0 || counts.subagents > 0 ? counts : undefined;
  }

  /** Steering messages queued but not yet delivered to the model (display mirror; see RuntimeEntry.pendingSteering). */
  pendingSteeringOf(sessionId: string): PendingSteeringInfo[] {
    return (this.entries.get(sessionId)?.pendingSteering ?? []).map((p) => p.info);
  }

  /** Steering a finished run never delivered, waiting for the composer to take it back (see RuntimeEntry.returnedSteering). */
  returnedSteeringOf(sessionId: string): PendingSteeringInfo[] {
    return (this.entries.get(sessionId)?.returnedSteering ?? []).map((p) => p.info);
  }

  /**
   * Live subagent children of an ACTIVE runtime entry (empty when the session is not loaded
   * — after a restart there is no in-process child left to report, so empty is the truth).
   * Rides `task_state` events and the SSE subscribe snapshot; the panel renders child
   * running marks from this instead of parsing tool-output text.
   */
  subagentsOf(sessionId: string): BackgroundSubagentInfo[] {
    return this.entries.get(sessionId)?.session.listBackgroundSubagents?.() ?? [];
  }

  /**
   * Host message to one child session — a user input on the child, whatever its state:
   * steering while it runs, a follow-up run while it is idle, a revival (resume-session
   * semantics) when it is no longer live (core `Session.sendToBackgroundSubagent`). The
   * parent runtime itself is loaded on demand (ensureEntry — the same get-or-resume path a
   * task uses), so messaging a child of a long-idle conversation works after a restart too;
   * the resume fallback names the child's owning Agent from its own session row, which must
   * belong to the parent's project.
   */
  async sendToSubagent(
    sessionId: string,
    childSessionId: string,
    messages: OmniMessage[],
  ): Promise<SubagentMessageOutcome> {
    const entry = await this.ensureEntry(sessionId);
    entry.lastActivityMs = Date.now();
    const childRow = this.deps.sessions.findById(childSessionId);
    const resume =
      childRow && childRow.projectId === entry.projectId
        ? { agentId: childRow.agentId }
        : undefined;
    return (
      (await entry.session.sendToBackgroundSubagent?.(childSessionId, messages, {
        ...(resume ? { resume } : {}),
      })) ?? "gone"
    );
  }

  /**
   * Sets a Session's thinking level on its loaded runtime (core `Session.thinkingLevel`,
   * plain state): the row's value is what the loader applies at load, so this only needs to
   * reach a runtime that is already in the active table — or a live child session, which
   * has an index row and a panel picker of its own but runs inside its parent's runtime.
   * The level is soft-limited: it applies from the Session's very next LLM request
   * (mid-context — the UI advises compacting first, since the change invalidates the
   * provider's cached context). No-op when nothing is loaded.
   */
  setThinkingLevel(sessionId: string, level: ThinkingLevelName): void {
    const session = this.entries.get(sessionId)?.session;
    if (session) {
      session.thinkingLevel = level;
      return;
    }
    for (const entry of this.entries.values()) {
      if (entry.session.setBackgroundSubagentThinkingLevel?.(sessionId, level)) return;
    }
  }

  /** Host abort of one child session's current run (core `Session.abortBackgroundSubagentRun`); false when the parent runtime is not loaded, the child is unknown, or it is idle. */
  abortSubagentRun(sessionId: string, childSessionId: string): boolean {
    const entry = this.entries.get(sessionId);
    if (!entry) return false;
    entry.lastActivityMs = Date.now();
    return entry.session.abortBackgroundSubagentRun?.(childSessionId) ?? false;
  }

  /** Queued follow-up tasks awaiting auto-start, as their display/recall info (id + content summary). */
  pendingFollowUpsOf(sessionId: string): PendingFollowUpInfo[] {
    return (this.entries.get(sessionId)?.followUps ?? []).map(followUpInfo);
  }

  /**
   * Live tail of a running session: one synthetic `partial_* start` OmniMessage per open
   * streaming fragment, carrying the full accumulated content so far (see live-tail.ts).
   * Empty when idle or when nothing is streaming. GET /messages attaches this (with a
   * channel cursor) so a client joining mid-stream can render the in-progress message.
   */
  liveFragments(sessionId: string): OmniMessage[] {
    return this.liveTail.fragments(sessionId);
  }

  /**
   * The running Task's input messages as published at launch; empty when idle. The engine
   * writes these exact envelopes to the Trace only after the first run's bootstrap (MCP
   * connect + discovery), so GET /messages appends whichever of them the Trace read has
   * not caught up to yet — without this, a client rebuilding history during the connect
   * (the draft flow subscribes only after the input publish) loses the user's own message.
   */
  pendingInputs(sessionId: string): OmniMessage[] {
    return this.entries.get(sessionId)?.pendingInputs ?? [];
  }

  /** The running Task's streamed bootstrap records (see RuntimeEntry.pendingBootstrap); empty when idle. */
  pendingBootstrap(sessionId: string): OmniMessage[] {
    return this.entries.get(sessionId)?.pendingBootstrap ?? [];
  }

  /** Number of Sessions for this Agent that are currently running / compacting. */
  activeCountForAgent(projectId: string, agentId: string): number {
    let n = 0;
    for (const e of this.entries.values()) {
      if (e.projectId === projectId && e.agentId === agentId && e.status !== "idle") n++;
    }
    return n;
  }

  /** Add a newly created Session to the active table (status idle), avoiding a redundant load on the next Task. */
  adopt(row: SessionRow, session: RuntimeSession): void {
    const entry: RuntimeEntry = {
      sessionId: row.sessionId,
      projectId: row.projectId,
      agentId: row.agentId,
      provider: row.provider,
      modelId: row.modelId,
      session,
      status: "idle",
      approvals: new ApprovalRegistry(() => this.publishApprovals(entry)),
      abort: null,
      running: null,
      generation: this.generationOf(row.projectId, row.agentId),
      followUps: [],
      pendingInputs: [],
      pendingBootstrap: [],
      pendingSteering: [],
      returnedSteering: [],
      lastActivityMs: Date.now(),
      backgroundTasks: backgroundTaskCounts(session),
    };
    this.entries.set(row.sessionId, entry);
    // Same wiring as ensureEntry: adopt IS the entry path for a session created in this
    // process (POST /sessions), and a listener registered only on the loader path left
    // freshly created sessions unable to deliver idle-arrival completion reports.
    this.registerNoticeListener(row.sessionId, session);
  }

  /**
   * Subscribes the background hooks on a runtime Session entering the active table — every
   * insertion path must call it (ensureEntry's loads, adopt's fresh creations):
   * - the idle-arrival signal for completion notices (mid-run arrivals are delivered inside
   *   the run by core; this signal is the only trigger left when the session sits idle);
   * - live-forwarded background-subagent messages, published to the session channel (the
   *   same feed SSE relays) and recorded for usage — a background child streams to the
   *   frontend in real time past the launching turn's end, until its terminal state;
   * - subagent run-state changes, republished as `task_state` so the panel's running
   *   marks track child rounds structurally instead of parsing tool-output text;
   * - background-task state changes (a command promoted or exited, a subagent promoted,
   *   settling or released), re-counted and published as `session_background` on the user
   *   channel so every Session list shows which rows still own background work.
   */
  private registerNoticeListener(sessionId: string, session: RuntimeSession): void {
    session.onBackgroundNotice?.(() => void this.startBackgroundNoticeTask(sessionId));
    session.onBackgroundMessage?.((msg) => this.forwardBackgroundMessage(sessionId, msg));
    session.onSubagentState?.(() => {
      const entry = this.entries.get(sessionId);
      if (entry) this.publishState(entry, entry.status);
    });
    session.onBackgroundState?.(() => this.publishBackgroundTasks(sessionId));
    // The entry-lifetime approve doubles as the children's fallback approval sink: a child
    // approval with no window and no background-launch standing sink escalates to the user
    // (SSE approval_request) instead of parking until the model's next poll — the parent
    // session idle included.
    const entry = this.entries.get(sessionId);
    if (entry) session.setSubagentApprovalFallback?.(this.entryApprove(entry));
  }

  /**
   * The entry-lifetime approval callback: the registry, the per-decision approval-mode
   * re-read, and the SSE escalation are all entry-scoped, so one instance serves every run
   * of the entry and the children's session-lifetime fallback sink alike.
   *
   * This is also where the one cross-cutting approval override lives — wrapping the callback
   * handed to `Session.run` rather than teaching the engine anything: an organization's
   * sessions run with nobody watching, so a call their approval mode would hand to a person
   * is denied here instead of waiting for an answer that is never coming (see `unattended`
   * in approvals.ts). The marker is the row's durable `client = "org"` stamp — desk, ticket
   * and the sub-sessions that inherit it — read per decision, so a row the reconcile pass
   * stamps later is covered from its next decision on.
   */
  private entryApprove(entry: RuntimeEntry): ApproveFn {
    return makeApprove({
      // Re-reads approval_mode from the DB on every decision (a PATCH takes effect immediately).
      getMode: () => this.deps.sessions.findById(entry.sessionId)?.approvalMode ?? "always-ask",
      toolPermission: (name) => entry.session.toolPermission(name),
      registry: entry.approvals,
      unattended: () => this.deps.sessions.findById(entry.sessionId)?.client === "org",
      publishRequest: (pending) =>
        this.publishEvent(entry, {
          type: "approval_request",
          toolCall: pending.toolCall,
          ...(pending.origin !== undefined ? { origin: pending.origin } : {}),
        }),
    });
  }

  /** Publishes one live background-subagent message and records its usage (fire-and-forget; the child's own Trace is the durable record). */
  private forwardBackgroundMessage(sessionId: string, msg: OmniMessage): void {
    const entry = this.entries.get(sessionId);
    if (!entry) return;
    // A child producing messages IS session activity: without this stamp the idle sweep
    // measures only the launching task, and a long background run ages into eviction.
    entry.lastActivityMs = Date.now();
    this.deps.channels.get(entry.sessionId).publish(msg);
    const ctx: UsageContext = {
      projectId: entry.projectId,
      agentId: entry.agentId,
      sessionId: entry.sessionId,
      provider: entry.provider,
      modelId: entry.modelId,
    };
    void this.deps.recorder.record(ctx, msg).catch((err: unknown) => {
      this.log(`[usage] Insert failed: ${err instanceof Error ? err.message : String(err)}`);
      this.deps.errors?.record({ source: "usage", err, ctx, code: "usage_insert_failed" });
    });
  }

  /**
   * Bumps one Agent's config generation so every runtime built before it is discarded on
   * its next idle access and re-resumed via the loader (history is preserved through the
   * Trace). What warrants it is a Session-fixed fact changing under the runtime — the
   * Project's credentials (see invalidateProjectRuntimes). Agent State changes never do:
   * core reads them into the next model context itself. A Task already in flight is neither
   * aborted nor hot-swapped: it keeps the values it started with, and its entry is rebuilt
   * on the first access after it returns to idle (see ensureEntry).
   */
  invalidateAgentRuntimes(projectId: string, agentId: string): void {
    const key = agentKey(projectId, agentId);
    this.agentGenerations.set(key, this.generationOf(projectId, agentId) + 1);
  }

  /**
   * After a Project's models/credentials change: invalidate every cached runtime in this
   * Project, so the next Task re-resumes with the new api_key / base_url. Same
   * effective-value semantics as invalidateAgentRuntimes — no hot swap into a Task already
   * in flight. Iterating the active table is complete here, not a shortcut: the generation
   * map only matters for runtimes that are already cached, and an Agent with no cached
   * entry builds fresh through the loader anyway.
   */
  invalidateProjectRuntimes(projectId: string): void {
    const agentIds = new Set<string>();
    for (const e of this.entries.values()) {
      if (e.projectId === projectId) agentIds.add(e.agentId);
    }
    for (const agentId of agentIds) this.invalidateAgentRuntimes(projectId, agentId);
  }

  // —— Task / compaction drive ——

  /**
   * Cheap, lock-free rehearsal of the 409/503 conditions startTask checks, throwing exactly the
   * same HttpErrors. **Advisory only**: it neither takes the Session lock nor loads an entry, so
   * a session that isn't in the active table reads as acceptable and a status change racing this
   * call is not caught — the authoritative check is still the one inside startTask.
   *
   * It exists so a caller that has irreversible work to do first (POST /tasks writes the
   * message's file attachments to disk) can find out about the ordinary "a Task is already
   * running" rejection before doing it, instead of undoing it afterwards.
   */
  assertCanAcceptTask(sessionId: string, opts?: { queueIfBusy?: boolean }): void {
    this.assertOpen();
    this.assertAgentNotDeleting(sessionId);
    this.assertSessionNotDeleting(sessionId);
    const entry = this.entries.get(sessionId);
    if (entry && !opts?.queueIfBusy) this.assertIdle(entry);
  }

  /**
   * Run a metadata operation at an idle Session boundary under the same mutex as Task and
   * compaction starts. Session fork uses this to snapshot an append-only Trace without a Task
   * beginning between its status check and final read. An uncached Session is idle by definition;
   * unlike startTask this path deliberately does not load a heavyweight runtime.
   */
  async atIdleBoundary<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
    return this.withLock(sessionId, async () => {
      this.assertOpen();
      this.assertAgentNotDeleting(sessionId);
      this.assertSessionNotDeleting(sessionId);
      const entry = this.entries.get(sessionId);
      if (entry) this.assertIdle(entry);
      return operation();
    });
  }

  /**
   * Start a Task: get-or-load → 409
   * mutual-exclusion check → publish the input messages first → drive run in the
   * background. Returns the current actual session_id (the new id after self-heal).
   * With `queueIfBusy`, a busy session (running/compacting) enqueues the input as a
   * follow-up instead of 409: it auto-starts as an ordinary next task once the session
   * returns to idle (`queued: true` in the result; see startQueuedFollowUp).
   * `opts.recall` is that queued message's original
   * content — optional, because only the HTTP route knows the parts of it the input does
   * not carry (the pre-attachment text and where each file landed on disk); every other
   * caller's store is read off the input, so a queued follow-up is recallable and shows
   * its content whichever path queued it.
   */
  async startTask(
    sessionId: string,
    input: OmniMessage[],
    opts?: { queueIfBusy?: boolean; recall?: RecallStore },
  ): Promise<{ sessionId: string; queued: boolean }> {
    return this.withLock(sessionId, async () => {
      this.assertOpen();
      this.assertAgentNotDeleting(sessionId);
      this.assertSessionNotDeleting(sessionId);
      const entry = await this.ensureEntry(sessionId);
      // A person's message opens a fresh chain for company mode's hop accounting, whether the
      // Task starts now or waits in the queue (see SessionManagerDeps.onHumanInput).
      if (isHumanInput(input)) this.deps.onHumanInput?.(sessionId);
      if (entry.status !== "idle" && opts?.queueIfBusy) {
        // The cap refuses the overflow rather than enqueuing it: see FOLLOW_UP_QUEUE_LIMIT.
        if (entry.followUps.length >= FOLLOW_UP_QUEUE_LIMIT) {
          throw new HttpError(
            429,
            "queue_full",
            `Session ${entry.sessionId} already has ${entry.followUps.length} queued follow-ups (cap ${FOLLOW_UP_QUEUE_LIMIT}); wait for the session to drain.`,
          );
        }
        entry.followUps.push({
          id: randomUUID(),
          input,
          // The original content rides the queue so a recall can hand it back, and so the
          // queued line shows what is waiting (see recallFollowUp). Callers that know more
          // than the input carries pass their own; the rest get it read off the input.
          recall: opts.recall ?? recallStoreOf(input),
        });
        entry.lastActivityMs = Date.now();
        // Re-publish the current state so subscribers pick up the new queued count (the
        // input itself is published when the follow-up actually starts).
        this.publishState(entry, entry.status);
        return { sessionId: entry.sessionId, queued: true };
      }
      this.assertIdle(entry);
      this.launchTask(entry, input);
      return { sessionId: entry.sessionId, queued: false };
    });
  }

  /**
   * Start a goal run: like startTask, but the goal plugin composes the input and its stop
   * hook drives every later round inside this one `session.run` call — so the Session
   * stays `running` for the whole goal (every round), the existing abort endpoint
   * interrupts the entire loop and schedules queue behind it as usual. The plugin's
   * `user_prompt` hook (hooks run in core and nowhere else — `Session.runUserPromptHook`)
   * writes the Session's goal file and answers the round-1 protocol message; it runs under
   * the session lock AFTER the idle check, since it overwrites the goal file a running goal
   * is reading. Not installed (null) is the route's 409; an empty answer a 500. Round inputs
   * are yielded by core and published like any streamed message; progress additionally goes
   * out as goal_* server events (the run state itself is the goal file the plugin maintains).
   */
  async startGoal(
    sessionId: string,
    args: {
      /** The user's own message(s) exactly as submitted — text and images, no wrapping. */
      messages: OmniMessage[];
      /** The user's own objective text (leading marker blocks stripped): what the plugin records, the goal_started event and the title material. */
      objective: string;
      budget: number;
    },
  ): Promise<{ sessionId: string }> {
    return this.withLock(sessionId, async () => {
      this.assertOpen();
      this.assertAgentNotDeleting(sessionId);
      this.assertSessionNotDeleting(sessionId);
      const entry = await this.ensureEntry(sessionId);
      this.assertIdle(entry);
      const objective = args.objective;
      const started = await entry.session.runUserPromptHook?.("goal", objective, {
        budget: args.budget,
      });
      if (!started) {
        throw new HttpError(
          409,
          "goal_plugin_not_installed",
          "Goal mode needs the goal plugin installed on this agent.",
        );
      }
      if (!started.context) {
        throw new HttpError(
          500,
          "goal_start_failed",
          "The goal plugin's user_prompt hook gave no round-1 context.",
        );
      }
      // Round 1 is the user's own message(s) followed by the hook's expansion context stamped
      // as harness-injected (the protocol text points back at the user message as the
      // objective). Later rounds are the stop hook's continues, which core stamps the same way.
      const input = [...args.messages, userText(started.context, "harness")];
      const ac = new AbortController();
      entry.status = "running";
      entry.abort = ac;
      entry.lastActivityMs = Date.now();
      // Round-1 input: same publish + pendingInputs hold as launchTask. Core never yields
      // a run's own initial input (only the stop hook's later injections), so without this
      // publish the round-1 messages reach only the Trace — a page already subscribed (a
      // second goal on the session) would not see the user's message or the protocol
      // message until a reload. Append + bootstrap reset for the same abort-mid-bootstrap
      // reasons as launchTask.
      entry.pendingInputs = [...entry.pendingInputs, ...input];
      entry.pendingBootstrap = [];
      const channel = this.deps.channels.get(entry.sessionId);
      for (const msg of input) channel.publish(msg);
      this.publishState(entry, "running");
      const approve = this.entryApprove(entry);
      this.publishEvent(entry, {
        type: "goal_started",
        sessionId: entry.sessionId,
        objective,
        budget: args.budget,
      });
      const gen = this.goalStream(entry, {
        input,
        budget: args.budget,
        approve,
        signal: ac.signal,
      });
      // The objective doubles as the title material (same role as a task's input text).
      entry.running = this.drive(entry, gen, { userExcerpt: objective });
      return { sessionId: entry.sessionId };
    });
  }

  /**
   * Taps a goal run's stream for `drive`: round boundaries become goal_round events —
   * round 1 from the seeded input (core never yields a run's initial input, so it is
   * counted here, where startGoal published it), later rounds from the stop-hook continues
   * core yields, each announced by the hook's `continue` event; a harness-stamped input
   * nothing announced is another package's user_prompt context riding behind the
   * objective, not a round — and the goal hook's `stop` event becomes the
   * goal_finished server event. `used` is what the hook last recorded in its event's
   * `output` — the same number its budget check used — so the UI never shows a different
   * figure. A stream that ends without the hook's terminal event (a cut-off run, an
   * infrastructure failure) closes as `aborted`.
   */
  private async *goalStream(
    entry: RuntimeEntry,
    args: {
      input: OmniMessage[];
      budget: number;
      approve: ApproveFn;
      signal: AbortSignal;
    },
  ): AsyncGenerator<OmniMessage> {
    const gen = entry.session.run(args.input, {
      approve: args.approve,
      signal: args.signal,
    });
    let round = 0;
    let used = 0;
    let finished = false;
    // Round 1's boundary is the seeded input itself: it never comes back out of `gen`.
    for (const msg of args.input) {
      if (isHookInput(msg)) {
        round++;
        this.publishEvent(entry, {
          type: "goal_round",
          sessionId: entry.sessionId,
          round,
          used,
          budget: args.budget,
        });
      }
    }
    // Set by a stop hook's `continue` event, spent by the input that follows it.
    let continued = false;
    try {
      for await (const msg of gen) {
        if (isHookContinue(msg)) continued = true;
        if (continued && isHookInput(msg)) {
          continued = false;
          round++;
          this.publishEvent(entry, {
            type: "goal_round",
            sessionId: entry.sessionId,
            round,
            used,
            budget: args.budget,
          });
        }
        const progress = goalProgressOf(msg);
        if (progress) used = progress.tokensUsed;
        const outcome = goalOutcomeOf(msg);
        if (outcome) {
          finished = true;
          this.publishEvent(entry, {
            type: "goal_finished",
            sessionId: entry.sessionId,
            outcome: outcome.outcome,
            rounds: outcome.rounds,
            used: outcome.tokensUsed,
          });
        }
        yield msg;
      }
      if (!finished) this.finishAborted(entry, round, used);
    } catch (err) {
      // Core throws only on infrastructure failures: close the goal
      // as aborted, then let drive's defensive catch record the error. Guarded on
      // `finished`: a throw after the terminal event must not publish a contradicting event.
      if (!finished) this.finishAborted(entry, round, used);
      throw err;
    }
  }

  /** Closes a goal as aborted for the UI (stream cut off / infrastructure failure). */
  private finishAborted(entry: RuntimeEntry, round: number, used: number): void {
    this.publishEvent(entry, {
      type: "goal_finished",
      sessionId: entry.sessionId,
      outcome: "aborted",
      rounds: round,
      used,
    });
  }

  /** Shared task launch (fresh tasks and auto-started follow-ups): flips to running, publishes the input, and drives the run. Caller holds the session lock and has verified idle. */
  private launchTask(entry: RuntimeEntry, input: OmniMessage[]): void {
    const channel = this.deps.channels.get(entry.sessionId);
    const ac = new AbortController();
    entry.status = "running";
    entry.abort = ac;
    entry.lastActivityMs = Date.now();
    // Publish the input messages first (visible to other subscribers; the Trace is
    // persisted by the SDK), then flip the running status. The same envelopes are held as
    // pendingInputs so GET /messages can serve them before the engine's Trace write
    // catches up (delayed by the first run's MCP connect). APPEND, don't replace: inputs
    // of a run aborted mid-bootstrap are still held (nothing reached the Trace; core
    // carries them into this run) and must stay served until this run persists them.
    // The previous attempt's bootstrap records are dropped instead — this run streams
    // its own connect phase, and a stale aborted pair would render as an extra row.
    entry.pendingInputs = [...entry.pendingInputs, ...input];
    entry.pendingBootstrap = [];
    for (const msg of input) channel.publish(msg);
    this.publishState(entry, "running");

    const approve = this.entryApprove(entry);
    const gen = entry.session.run(input, {
      approve,
      signal: ac.signal,
    });
    // This call's input user text is the whole title source: drive persists its first
    // words as the immediate fallback and hands it to the LLM as the generation material
    // (user input only — generation never waits for model output).
    const userExcerpt = input
      .filter(isPlainText("user"))
      .map((m) => m.payload.text)
      .join("\n");
    entry.running = this.drive(entry, gen, { userExcerpt });
  }

  /**
   * Auto-start of queued follow-ups: called from drive's finally whenever a Task or
   * compaction finishes (abort included — follow-ups are future tasks the user queued, so
   * an abort of the current run does not discard them). Re-validates everything under the
   * session lock (another task may have snuck in, the server may be shutting down, the
   * session may be getting deleted) and launches exactly one queued input — the next
   * finish picks up the one after, keeping order and one-at-a-time semantics.
   */
  private async startQueuedFollowUp(sessionId: string): Promise<void> {
    try {
      await this.withLock(sessionId, async () => {
        if (this.closed || this.deletingSessions.has(sessionId)) return;
        const row = this.deps.sessions.findById(sessionId);
        if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) return;
        const entry = this.entries.get(sessionId);
        if (!entry || entry.status !== "idle" || entry.followUps.length === 0) return;
        const next = entry.followUps.shift()!;
        this.launchTask(entry, next.input);
      });
    } catch (err) {
      this.log(`[followup] auto-start failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  }

  /** Manually compact the context: 409 if already running; compaction output also flows into the SSE channel. */
  async startCompact(sessionId: string): Promise<{ sessionId: string }> {
    return this.withLock(sessionId, async () => {
      this.assertOpen();
      this.assertAgentNotDeleting(sessionId);
      this.assertSessionNotDeleting(sessionId);
      const entry = await this.ensureEntry(sessionId);
      this.assertIdle(entry);
      // When there's nothing to compact, core's compact() yields no messages at all: we
      // can't just return 202 and walk away, or the frontend would wait forever for a
      // compaction banner that never comes (this is exactly the "/compact does nothing
      // after an interrupt" complaint). Reject explicitly, and **say why** clearly —
      // "just compacted" and "haven't talked yet" share the same internal state
      // (sessionTurns === 0), but are two completely different messages to the user:
      // telling someone who just compacted that there's "no completed conversation turn
      // yet" tells them nothing.
      const why = entry.session.compactability();
      if (why !== "ok") throw compactUnavailable(why);
      const ac = new AbortController();
      entry.status = "compacting";
      entry.abort = ac;
      entry.lastActivityMs = Date.now();
      this.publishState(entry, "compacting");
      const gen = entry.session.compact({ signal: ac.signal });
      entry.running = this.drive(entry, gen);
      return { sessionId: entry.sessionId };
    });
  }

  /**
   * Switches the Session's model in place (`POST /switch-model`) — core `Session.switchModel`,
   * gated like a compaction (open, not deleting, idle). Core decides everything before its
   * first event, so the head of its stream is pulled here, under the lock, and tells the three
   * outcomes apart:
   *
   * - it throws — a refusal, answered 409 with the code of its reason (see `switchRefusal`);
   * - it is already done — a Session that never ran has no context to close: core re-assembled
   *   its first context on the target, nothing streams, and the row carries the new pair by
   *   the time this returns (`switched: true`; the route answers with the fresh DTO);
   * - it yields — a driven run like a compaction (`switched: false`): status `compacting`,
   *   idle when it ends. The head is a compaction's begin, the first record of a bootstrap (a
   *   Session loaded from its Trace opens its context first), or — for a context with no
   *   completed turn, which streams no pair — the opener's first record.
   *
   * The switch is the entry's run from that pull on — it can be stopped, and a deletion or a
   * shutdown waits for it — while the entry only reads `compacting` once there is something
   * to stream, so a refusal never flickers a state.
   *
   * The entry and the row follow the runtime as the new context's `session_meta` passes
   * through the drive (see `drive`); a switch that does not complete streams no meta and
   * leaves them where they were. Usage: a drive bills to the model it started on, so the
   * switch's compaction request goes to the model that served it and the next run to the new
   * one.
   *
   * `opts.onCompactionFailure` is passed straight to core (`"discard"` drops the context and
   * switches anyway): it is the route's answer to a model whose requests all fail, where the
   * closing summarize could never succeed. Nothing here reads it — the events the drive streams
   * say which of the two happened.
   */
  async startSwitch(
    sessionId: string,
    ref: ModelRefDto,
    opts?: { onCompactionFailure?: SwitchFailurePolicy },
  ): Promise<{ sessionId: string; switched: boolean }> {
    return this.withLock(sessionId, async () => {
      this.assertOpen();
      this.assertAgentNotDeleting(sessionId);
      this.assertSessionNotDeleting(sessionId);
      const entry = await this.ensureEntry(sessionId);
      this.assertIdle(entry);
      if (entry.provider === ref.provider && entry.modelId === ref.modelId) {
        throw new HttpError(
          409,
          "same_model",
          `This Session already runs on ${ref.provider} / ${ref.modelId}.`,
        );
      }
      if (!entry.session.switchModel) {
        throw new HttpError(
          409,
          "model_unavailable",
          "Switching the model is not available for this Session.",
        );
      }
      const ac = new AbortController();
      const gen = entry.session.switchModel({
        ...ref,
        signal: ac.signal,
        ...(opts?.onCompactionFailure !== undefined
          ? { onCompactionFailure: opts.onCompactionFailure }
          : {}),
      });
      const head = gen.next();
      const settled = (): void => {
        entry.abort = null;
        entry.running = null;
      };
      // One promise for the whole switch — the pull, then the drive behind it — so whoever
      // waits for this entry's run to end waits for both.
      entry.abort = ac;
      entry.running = head.then((first) => {
        if (first.done) return settled();
        entry.status = "compacting";
        this.publishState(entry, "compacting");
        return this.drive(entry, resumeFrom(first.value, gen));
      }, settled);
      let first: IteratorResult<OmniMessage, StopReason>;
      try {
        first = await head;
      } catch (err) {
        throw switchRefusal(err, ref);
      }
      entry.lastActivityMs = Date.now();
      if (!first.done) return { sessionId: entry.sessionId, switched: false };
      this.syncEntryModel(entry);
      return { sessionId: entry.sessionId, switched: true };
    });
  }

  /** Who is told when a Session's model moves (see `onModelChanged`). */
  private readonly modelListeners = new Set<(sessionId: string, model: ModelRefDto) => void>();

  /**
   * Subscribes to a Session's model moving: an in-session switch completing, or a row brought
   * back in step with its Trace when the Session loads. The listener runs once the entry and
   * the row carry the new pair. Returns the unsubscribe. Company mode listens: an employee's
   * model is its desk Session's.
   */
  onModelChanged(listener: (sessionId: string, model: ModelRefDto) => void): () => void {
    this.modelListeners.add(listener);
    return () => void this.modelListeners.delete(listener);
  }

  /**
   * Moves the entry — and the row it caches into — to the model the runtime reports itself on,
   * when that differs: the pair the next drive attributes usage to, and the one
   * `GET /sessions/:id` describes. A runtime that reports none (test fakes) leaves the entry
   * alone. The row write is guarded like the other bookkeeping writes (see `touchRow`): a
   * switch must not be stranded mid-drive by a closed DB handle, and the entry is right either
   * way. The same holds for whoever listens: a listener that throws is recorded, not rethrown.
   */
  private syncEntryModel(entry: RuntimeEntry): void {
    const model = runtimeModelOf(entry.session);
    if (!model) return;
    if (entry.provider === model.provider && entry.modelId === model.modelId) return;
    entry.provider = model.provider;
    entry.modelId = model.modelId;
    const ctx = { projectId: entry.projectId, agentId: entry.agentId, sessionId: entry.sessionId };
    try {
      this.deps.sessions.updateModel(entry.sessionId, model.provider, model.modelId);
    } catch (err) {
      this.log(
        `[session] model bookkeeping failed: ${err instanceof Error ? err.message : String(err)}`,
      );
      this.deps.errors?.record({
        source: "session",
        err,
        ctx,
        code: "session_model_update_failed",
      });
    }
    for (const listener of this.modelListeners) {
      try {
        listener(entry.sessionId, model);
      } catch (err) {
        this.deps.errors?.record({
          source: "session",
          err,
          ctx,
          code: "session_model_listener_failed",
        });
      }
    }
  }

  /** Submit an approval decision; returns false if the pending approval doesn't exist (already decided/unknown). */
  decideApproval(sessionId: string, toolCallId: string, decision: "allow" | "deny"): boolean {
    const entry = this.entries.get(sessionId);
    if (!entry) return false;
    return entry.approvals.decide(toolCallId, decision);
  }

  /**
   * Mid-run steering: forward the message to the running Session (core delivers it between
   * turns as a standalone `[user_steering]` user message followed by its images — no SSE
   * event of its own; the messages arrive through the stream the drive loop already
   * publishes). 409 when the Session isn't running a Task (idle / compacting / not loaded)
   * or the run finished in the race window — the caller falls back to submitting a normal
   * task, which carries the same text and images.
   *
   * `recall` is the queued message's original content: its summary (with a fresh id) is
   * mirrored on the entry and broadcast via `task_state` (and the SSE subscribe snapshot)
   * until the delivered `[user_steering]` message is observed on the stream — that is what
   * keeps the composer's "steering queued" hint, content included, alive across reloads —
   * and the content itself is what a recall (recallSteering) hands back to the composer.
   */
  steer(sessionId: string, input: OmniMessage[], recall: RecallStore): void {
    const entry = this.entries.get(sessionId);
    if (!entry || entry.status !== "running" || !entry.session.steer(input)) {
      throw new HttpError(
        409,
        "not_running",
        "This Session has no Task in progress; send the message as a new task instead.",
      );
    }
    entry.pendingSteering.push({
      info: {
        id: randomUUID(),
        text: recall.text,
        images: recall.images.length,
        videos: recall.videos.length,
        files: recall.files.length,
      },
      input,
      recall,
    });
    entry.lastActivityMs = Date.now();
    this.publishState(entry, entry.status);
  }

  /**
   * Recall an undelivered steering message (#287): withdraw it from core's queue and the
   * display mirror, re-broadcast state, and hand back its original content for the composer
   * to restore. 409 `not_pending` when the entry is no longer queued — already delivered to
   * the model (core's `unsteer` says so authoritatively; the mirror can lag behind delivery
   * until the `[user_steering]` message is observed on the stream), the run exited, or the
   * id is unknown — all the same outcome for the caller: nothing left to take back.
   */
  recallSteering(sessionId: string, steerId: string): RecallStore {
    const entry = this.entries.get(sessionId);
    if (entry) {
      const queued = entry.pendingSteering.findIndex((p) => p.info.id === steerId);
      if (queued >= 0) {
        const pending = entry.pendingSteering[queued]!;
        // Still queued on a live run: core decides, since the mirror can lag a delivery that
        // has not reached the stream yet.
        if (entry.session.unsteer?.(pending.input) ?? false) {
          entry.pendingSteering.splice(queued, 1);
          entry.lastActivityMs = Date.now();
          this.publishState(entry, entry.status);
          return pending.recall;
        }
      }
      // Handed back when the run exited without delivering it: core's queue is gone, so there
      // is nothing to unsteer and the mirror is the only authority left — it holds exactly
      // what the drained stream never showed as delivered (see RuntimeEntry.returnedSteering).
      const returned = entry.returnedSteering.findIndex((p) => p.info.id === steerId);
      if (returned >= 0) {
        const [taken] = entry.returnedSteering.splice(returned, 1);
        entry.lastActivityMs = Date.now();
        this.publishState(entry, entry.status);
        return taken!.recall;
      }
    }
    throw new HttpError(
      409,
      "not_pending",
      "This steering message was already delivered to the model and can no longer be recalled.",
    );
  }

  /**
   * Recall a queued follow-up task (#287): remove it from the queue before it auto-starts,
   * re-broadcast state, and hand back its original content (plus the thinking level it was
   * queued with). Being in the queue is the whole condition — every queued entry carries a
   * recall store (see QueuedFollowUp.recall), so no queued message is ever refused. 409
   * `follow_up_started` when the id is not in the queue: it already auto-started, or the
   * runtime was released and took the queue with it. Its own code, distinct from steering's
   * `not_pending`, because the two mean different things to the user — a follow-up became a
   * task of its own, a steering message reached the model mid-run.
   */
  recallFollowUp(sessionId: string, followUpId: string): { recall: RecallStore } {
    const entry = this.entries.get(sessionId);
    const i = entry?.followUps.findIndex((f) => f.id === followUpId) ?? -1;
    const queued = i >= 0 ? entry!.followUps[i]! : undefined;
    if (!entry || !queued) {
      throw new HttpError(
        409,
        "follow_up_started",
        "This follow-up message already started and can no longer be recalled.",
      );
    }
    entry.followUps.splice(i, 1);
    entry.lastActivityMs = Date.now();
    this.publishState(entry, entry.status);
    return { recall: queued.recall };
  }

  /**
   * "Retry now" on the reconnect countdown: skip the in-progress backoff wait and fire
   * the next retry immediately (the attempt counter is unchanged — the skipped wait does
   * not consume an extra attempt). Returns false as a benign no-op when the session has
   * no active runtime or no reconnect wait is in progress — timing races (the wait
   * elapsed right before the click) must not surface as errors. Mirrors the steer seam:
   * manager → RuntimeSession → core Session → engine.
   */
  retryNow(sessionId: string): boolean {
    const entry = this.entries.get(sessionId);
    // Both running Tasks and compactions can be parked in a reconnect backoff.
    if (!entry || entry.status === "idle") return false;
    const skipped = entry.session.skipReconnectWait();
    if (skipped) entry.lastActivityMs = Date.now();
    return skipped;
  }

  /**
   * Interrupt the current Task/compaction: pending approvals converge to deny first,
   * then the AbortSignal fires. Returns false if nothing is in progress (the route
   * treats this as a 204 no-op).
   */
  abortTask(sessionId: string): boolean {
    const entry = this.entries.get(sessionId);
    if (!entry || !entry.abort) return false;
    // Deny only the MAIN session's pending approvals: an approval blocks the run the user is
    // stopping. A subagent child survives the parent's stop, and so does its question.
    entry.approvals.denyMain();
    entry.abort.abort();
    return true;
  }

  /**
   * Background command processes of a LOADED session (empty when the entry is not in
   * the active table — a resumed entry starts with a fresh environment and can only
   * ever report an empty list, so nothing is resurrected just to answer a poll).
   */
  listProcesses(sessionId: string): BackgroundCommandInfo[] {
    return this.entries.get(sessionId)?.session.listBackgroundCommands?.() ?? [];
  }

  /**
   * Refreshes the listen-port probes behind the process list's `serviceUrl` (core
   * `Session.probeBackgroundCommandServices`): called by the processes route before
   * listing, so the first fetch already carries probed URLs. Bounded by core's own probe
   * timeout and TTL; a session that isn't loaded has no processes to probe.
   */
  async probeProcessServices(sessionId: string): Promise<void> {
    await this.entries.get(sessionId)?.session.probeBackgroundCommandServices?.();
  }

  /**
   * Hands one EXECUTING tool call of a loaded session back as a background task (core
   * `Session.detachToolCall`): the call closes with a registry handle, its work keeps
   * running, and the turn carries on. An unloaded session has nothing executing, so it
   * answers "not_running" like an unknown id.
   */
  detachToolCall(sessionId: string, toolCallId: string): ToolDetachResult {
    const entry = this.entries.get(sessionId);
    if (!entry) return "not_running";
    const result = entry.session.detachToolCall?.(toolCallId) ?? "not_running";
    if (result === "detached") entry.lastActivityMs = Date.now();
    return result;
  }

  /** Kills one background command process of a loaded session; false when the session isn't loaded or the id is unknown. */
  killProcess(sessionId: string, processId: string): boolean {
    const entry = this.entries.get(sessionId);
    if (!entry) return false;
    const killed = entry.session.killBackgroundCommand?.(processId) ?? false;
    if (killed) entry.lastActivityMs = Date.now();
    return killed;
  }

  /**
   * Removes one EXITED background command entry from a loaded session's process list.
   * A running process is refused ("running") — stopping is killProcess's job, and a
   * bare removal must never surprise-signal a live process group. "not_found" covers
   * an unloaded session and an unknown id alike: the entry is gone either way. The
   * removal itself reuses the kill path — core's registry removal signals the (dead)
   * group defensively and drops the row, exactly like input_command's post-exit reap.
   * The only race, an entry observed running that exits before a retry, is benign:
   * the caller gets "running", refreshes, and sees the row exited on the next look.
   *
   * Note what leaves with the row: the registry entry owns the ManagedSession holding
   * that process's captured output, so after a removal input_command on the same
   * process_id answers "unknown process_id". Removal is a deliberate discard, not just
   * a list tidy-up — the Web App says so at the button and in the docs.
   */
  removeProcess(sessionId: string, processId: string): "removed" | "running" | "not_found" {
    const entry = this.entries.get(sessionId);
    if (!entry) return "not_found";
    const info = entry.session.listBackgroundCommands?.().find((p) => p.processId === processId);
    if (!info) return "not_found";
    if (info.running) return "running";
    const removed = entry.session.killBackgroundCommand?.(processId) ?? false;
    if (!removed) return "not_found";
    entry.lastActivityMs = Date.now();
    return "removed";
  }

  /**
   * Disposes a just-removed entry's runtime — after its in-flight drive (if any)
   * settles, so interrupt cleanup never races a dying environment. Deleting a Session /
   * Agent / Project is the one intent that must also end the background processes the
   * conversation started (a dev server surviving its deleted conversation is
   * unreachable from every UI, running forever).
   */
  private disposeRemoved(entry: RuntimeEntry): void {
    const dispose = (): void => entry.session.dispose?.();
    if (entry.running) void entry.running.then(dispose, dispose);
    else dispose();
  }

  /**
   * Before deleting a Project, converge all its active runs and clear them out of the
   * active table. Returns the in-flight drive Promises of the affected entries: the
   * caller (deleteProject) should await them before removing the directory, so that
   * interrupt-cleanup Trace writes don't recreate the directory after deletion.
   */
  abortProject(projectId: string): Promise<void>[] {
    const runnings: Promise<void>[] = [];
    for (const [key, entry] of [...this.entries]) {
      if (entry.projectId !== projectId) continue;
      entry.approvals.denyAll();
      entry.abort?.abort();
      if (entry.running) runnings.push(entry.running);
      this.entries.delete(key);
      this.disposeRemoved(entry);
    }
    return runnings;
  }

  /**
   * Before deleting an Agent, converge all its active runs and clear them out of the
   * active table (same semantics as abortProject). Also marks this Agent as "being
   * deleted": new Tasks/compactions entering during the deletion process are always
   * rejected with 409 (assertAgentNotDeleting), closing the race window where a new
   * task recreates the directory and revives an already-deleted Agent between the
   * abortAgent snapshot and the directory removal. The caller must call
   * endAgentDeletion once deletion finishes (success or failure).
   */
  beginAgentDeletion(projectId: string, agentId: string): Promise<void>[] {
    this.deletingAgents.add(agentKey(projectId, agentId));
    const runnings: Promise<void>[] = [];
    for (const [key, entry] of [...this.entries]) {
      if (entry.projectId !== projectId || entry.agentId !== agentId) continue;
      entry.approvals.denyAll();
      entry.abort?.abort();
      if (entry.running) runnings.push(entry.running);
      this.entries.delete(key);
      this.disposeRemoved(entry);
    }
    return runnings;
  }

  endAgentDeletion(projectId: string, agentId: string): void {
    this.deletingAgents.delete(agentKey(projectId, agentId));
  }

  /**
   * Before deleting a single Session, converge its active run and clear it out of the
   * active table (same semantics as beginAgentDeletion). Also marks this Session as
   * "being deleted": new Tasks/compactions entering during the deletion process are
   * always rejected with 409 (assertSessionNotDeleting), closing the race window where
   * a new task recreates the entry and Trace file, reviving an already-deleted Session
   * between the abort snapshot and the file removal. The caller must call
   * endSessionDeletion once deletion finishes (success or failure). Returns the
   * in-flight drive Promise: the caller should await it before deleting the Trace file,
   * so cleanup writes don't recreate the file.
   */
  beginSessionDeletion(sessionId: string): Promise<void>[] {
    this.deletingSessions.add(sessionId);
    const entry = this.entries.get(sessionId);
    if (!entry) return [];
    entry.approvals.denyAll();
    entry.abort?.abort();
    this.entries.delete(sessionId);
    this.disposeRemoved(entry);
    return entry.running ? [entry.running] : [];
  }

  endSessionDeletion(sessionId: string): void {
    this.deletingSessions.delete(sessionId);
  }

  /** Graceful shutdown: reject new tasks (503), interrupt all active runs, and wait for them to finish (default ≤5s). */
  async shutdown(timeoutMs = 5000): Promise<void> {
    this.closed = true;
    clearInterval(this.sweepTimer);
    const pending: Promise<void>[] = [];
    for (const entry of this.entries.values()) {
      entry.approvals.denyAll();
      entry.abort?.abort();
      if (entry.running) pending.push(entry.running);
      // Suspend means the environment too: dispose kills the Session's remaining
      // background processes (a dev server the conversation started, etc.). Without
      // this, a hot swap orphans them — the OS process keeps running while the next
      // App's freshly resumed Session starts with an empty process list, so the stop
      // control has gone blind. Sequenced after the in-flight drive settles, the same
      // ordering disposeRemoved uses.
      const dispose = (): void => entry.session.dispose?.();
      if (entry.running) void entry.running.then(dispose, dispose);
      else dispose();
    }
    this.entries.clear();
    if (pending.length === 0) return;
    await Promise.race([
      Promise.allSettled(pending).then(() => undefined),
      new Promise<void>((resolve) => setTimeout(resolve, timeoutMs).unref?.()),
    ]);
  }

  /**
   * Active-table idle eviction: removes entries that are idle (idle status, no pending
   * approvals, no in-flight drive) and have been inactive past the timeout, releasing
   * the core Session's full in-memory history. This is purely memory reclamation: the
   * next access re-resumes via the loader, so correctness is unaffected. Lock-table
   * entries are auto-cleaned by withLock once their chain drains (including leftover
   * entries under the old id after self-heal). `now` / `idleMs` are injectable for
   * tests and timers.
   */
  sweepIdle(now: number = Date.now(), idleMs: number = ENTRY_IDLE_MS): void {
    for (const [key, entry] of this.entries) {
      if (entry.status !== "idle" || entry.approvals.size !== 0 || entry.running !== null) continue;
      if (entry.followUps.length > 0) continue; // queued follow-ups must not be evicted with the entry
      // A live background process (e.g. a dev server the conversation started) pins the
      // entry: eviction would strand the process — a resumed entry starts with a fresh
      // environment, so the process list and its stop control would go blind while the
      // OS process kept running. Exited-but-listed processes don't pin anything.
      if (entry.session.listBackgroundCommands?.().some((p) => p.running)) continue;
      // A background subagent still working pins it for the same reason: a run_in_background
      // child outlives the call that launched it, and its completion report and live messages
      // are delivered through the very Session object eviction would drop.
      if (entry.session.hasRunningBackgroundSubagents?.()) continue;
      // Undelivered background completion notices pin the entry too: they live in the core
      // Session object, so evicting it would silently drop them.
      if (entry.session.hasPendingBackgroundNotices?.()) continue;
      if (now - entry.lastActivityMs <= idleMs) continue;
      this.entries.delete(key);
    }
  }

  // —— Internal ——

  private assertOpen(): void {
    if (this.closed) {
      throw new HttpError(
        503,
        "shutting_down",
        "Server is shutting down; not accepting new Tasks.",
      );
    }
  }

  /** The Agent owning this Session is being deleted → 409 (guards against directory recreation inside the deletion race window). */
  private assertAgentNotDeleting(sessionId: string): void {
    const row = this.deps.sessions.findById(sessionId);
    if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) {
      throw new HttpError(
        409,
        "agent_deleting",
        "This Agent is being deleted; not accepting new Tasks.",
      );
    }
  }

  /** This Session is being deleted → 409 (guards against the entry/Trace being rebuilt and reviving it inside the deletion race window). */
  private assertSessionNotDeleting(sessionId: string): void {
    if (this.deletingSessions.has(sessionId)) {
      throw new HttpError(
        409,
        "session_deleting",
        "This Session is being deleted; not accepting new Tasks.",
      );
    }
  }

  private assertIdle(entry: RuntimeEntry): void {
    if (entry.status === "running") {
      throw new HttpError(409, "task_in_progress", "This Session already has a Task in progress.");
    }
    if (entry.status === "compacting") {
      throw new HttpError(
        409,
        "compacting",
        "This Session is compacting its context; not accepting new input.",
      );
    }
  }

  private generationOf(projectId: string, agentId: string): number {
    return this.agentGenerations.get(agentKey(projectId, agentId)) ?? 0;
  }

  private async refreshProviderCredentialIfNeeded(row: {
    projectId: string;
    agentId: string;
    provider: string;
  }): Promise<void> {
    const refreshed = await this.deps.modelScopeAuth?.ensureFresh({
      projectId: row.projectId,
      provider: row.provider,
    });
    if (refreshed?.changed) this.invalidateProjectRuntimes(row.projectId);
  }

  /** get-or-resume-or-heal: use directly on an active-table hit; otherwise load via the loader, updating the index's primary key on self-heal. */
  private async ensureEntry(sessionId: string): Promise<RuntimeEntry> {
    const existing = this.entries.get(sessionId);
    /** Background-task counts the discarded runtime last reported (see the publish below). */
    let discardedBackgroundTasks: SessionBackgroundTasks | undefined;
    if (existing) {
      await this.refreshProviderCredentialIfNeeded(existing);
      if (existing.generation === this.generationOf(existing.projectId, existing.agentId)) {
        return existing;
      }
      // Built before the last credential change: discard once idle and fall through to a
      // fresh load (resume re-reads the Project config). A busy entry is returned as-is — the
      // in-flight run keeps its values and assertIdle rejects the new Task anyway;
      // it is rebuilt on the first access after it finishes.
      if (
        existing.status !== "idle" ||
        existing.running !== null ||
        existing.approvals.size !== 0
      ) {
        return existing;
      }
      this.entries.delete(sessionId);
      discardedBackgroundTasks = existing.backgroundTasks;
    }
    const row = this.deps.sessions.findById(sessionId);
    if (!row) {
      throw new HttpError(
        404,
        "session_not_found",
        "Session does not exist or you do not have access.",
      );
    }
    await this.refreshProviderCredentialIfNeeded(row);
    // Captured before the (awaited) load: an invalidation racing with the load leaves
    // this entry stale, so the access after next rebuilds it with the new values.
    const generation = this.generationOf(row.projectId, row.agentId);
    const session = await this.deps.loader.load(row);
    // The Session/Agent was marked for deletion while loading: discard the load result,
    // don't rebuild the entry (avoids reviving an orphaned Trace).
    this.assertSessionNotDeleting(row.sessionId);
    this.assertAgentNotDeleting(row.sessionId);
    // A thinking-level PATCH that landed during the (awaited) load updated the row but found
    // no entry to assign, and the loader applied the snapshot's level: re-read the pin.
    const pin = this.deps.sessions.findById(row.sessionId)?.thinkingLevel;
    if (pin && pin !== row.thinkingLevel) session.thinkingLevel = pin;
    let currentId = row.sessionId;
    if (session.sessionId !== row.sessionId) {
      // Self-heal produced a new session_id: update the index's primary key; the SSE
      // channel and pending state are naturally empty for it.
      this.deps.sessions.replaceId(row.sessionId, session.sessionId);
      currentId = session.sessionId;
    }
    const entry: RuntimeEntry = {
      sessionId: currentId,
      projectId: row.projectId,
      agentId: row.agentId,
      provider: row.provider,
      modelId: row.modelId,
      session,
      status: "idle",
      approvals: new ApprovalRegistry(() => this.publishApprovals(entry)),
      abort: null,
      running: null,
      generation,
      followUps: [],
      pendingInputs: [],
      pendingBootstrap: [],
      pendingSteering: [],
      returnedSteering: [],
      lastActivityMs: Date.now(),
      // Baselined on the DISCARDED runtime's counts when there was one: the replacement
      // resumes with empty registries, so a client that saw the old counts would keep its
      // background-task mark with no ping left to clear it. Publishing against that baseline
      // below reports whatever the fresh runtime actually owns — nothing, in every case the
      // discard path produces today.
      backgroundTasks: discardedBackgroundTasks ?? backgroundTaskCounts(session),
    };
    // The runtime's model is the truth the row caches: a Session that switched models and
    // crashed between the Trace write and the row update resumes (from the Trace) on the new
    // model, and the row is brought back in step here.
    this.syncEntryModel(entry);
    this.entries.set(currentId, entry);
    this.registerNoticeListener(currentId, session);
    if (discardedBackgroundTasks !== undefined) this.publishBackgroundTasks(currentId);
    return entry;
  }

  /**
   * Auto-start of queued background completion notices: called when core signals an
   * idle-session arrival, and from drive's finally for notices that raced a run's exit.
   * Revalidates under the session lock; only an idle entry launches, and only when the
   * queue is non-empty — a busy entry skips, because the running/queued task's engine
   * drains the same queue at its own boundaries (each notice is delivered exactly once).
   */
  private async startBackgroundNoticeTask(sessionId: string): Promise<void> {
    try {
      await this.withLock(sessionId, async () => {
        if (this.closed || this.deletingSessions.has(sessionId)) return;
        const row = this.deps.sessions.findById(sessionId);
        if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) return;
        const entry = this.entries.get(sessionId);
        if (!entry) {
          // The runtime entry left the active table between the signal and this lock —
          // the queued notices left with the released Session object. Say so instead of
          // dropping the report invisibly (the sweep pins entries with pending notices,
          // so this is a genuine anomaly worth a trace in the log).
          this.log(`[background] notice for ${sessionId} dropped: runtime entry not loaded`);
          return;
        }
        // Busy or queued-behind: not a loss — the running/next run's engine drains the
        // same notice queue at its own input-assembly boundaries.
        if (entry.status !== "idle" || entry.followUps.length > 0) return;
        const input = entry.session.takeBackgroundNotices?.() ?? [];
        if (input.length === 0) return;
        this.launchTask(entry, input);
      });
    } catch (err) {
      this.log(
        `[background] notice task start failed: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  }

  /**
   * Drive the output stream in the background: publish each message + persist usage +
   * persist LLM/tool errors; on completion (including errors) resets to idle and pushes
   * the status. `titleSource` is passed only for Task runs (compaction doesn't generate
   * a title): its user text drives automatic title generation at run start.
   */
  private async drive(
    entry: RuntimeEntry,
    gen: AsyncGenerator<OmniMessage>,
    titleSource?: { userExcerpt: string },
  ): Promise<void> {
    const ctx: UsageContext = {
      projectId: entry.projectId,
      agentId: entry.agentId,
      sessionId: entry.sessionId,
      provider: entry.provider,
      modelId: entry.modelId,
    };
    // Title policy fires at run start, from the user input alone: the generator persists
    // the input's first words as an immediate fallback and issues the LLM replacement
    // request without waiting for any model output (maybeGenerate self-guards: manual
    // renames are final, one generation in flight per session).
    if (titleSource?.userExcerpt.trim()) {
      this.deps.titles?.maybeGenerate(ctx, entry.session, {
        fallbackText: titleSource.userExcerpt,
        material: { userText: titleSource.userExcerpt, assistantText: "" },
      });
    }
    // Every driven run (a Task, a compaction, or a whole goal loop — startGoal hands all of
    // its rounds to ONE drive) writes Trace lines: flip the row's has_trace cache here, the
    // single choke point, so listing can serve it from the DB without a directory walk (see
    // SessionService.listSessions). The same statement stamps last_active_at, so a run costs
    // one row write here and one more when it ends (see the finally) — never one per streamed
    // message; activity during the run (steering, approvals, queued follow-ups) rides on the
    // run-end stamp. Guarded: this runs BEFORE the try below, so an unexpected DB failure
    // (a closed handle after shutdown) would otherwise reject drive() with no finally to
    // reach — leaving the entry pinned "running" and every later Task 409ing for the
    // process's lifetime.
    this.touchRow(ctx, (repo, at) => repo.markDriven(ctx.sessionId, at));
    // LLM request failures and tool execution failures aren't expressed via throw (core
    // converges them into the message stream), so the try/catch below can't catch them:
    // the watcher inspects messages one by one and fishes them out for persistence
    // (subagent failures flow through this same stream too; see stream-error-watcher).
    const watcher = this.deps.errors
      ? new StreamErrorWatcher(this.deps.errors, {
          projectId: entry.projectId,
          agentId: entry.agentId,
          sessionId: entry.sessionId,
        })
      : null;
    // Subagent (origin) registration: as soon as session_meta arrives, the child Session
    // is persisted so it appears immediately in the sidebar (the frontend picks it up
    // when it refreshes the list at task completion). The title material is "the prompt
    // of the run_subagent call that spawned this subagent" — the subagent's user input
    // is never replayed onto the parent stream (ContextEngine writes the Trace but never
    // yields it), so we can't rely on the subagent's first user message; instead we use
    // the run_subagent tool_call arguments immediately preceding it on the parent stream
    // (depth limited to 1, spawned in order, so taking the most recent one suffices).
    /** Subagents registered during this run (keyed by session id); each gets its title generated at registration, from its spawning prompt alone. */
    const children = new Map<string, ChildSession>();
    // Unclaimed run_subagent prompts, queued in call order: a single round may spawn
    // multiple subagents in parallel, and a subagent's session_meta only carries the
    // session id (no tool_call_id), so pairing can only be approximated via FIFO (when
    // spawned in parallel and session_meta arrives out of order, two subagents' titles
    // may end up swapped — this only affects the displayed title). A call that will
    // never produce a subagent must be dequeued, or its prompt would be mismatched onto
    // the next subagent: this covers denied calls (approval_decision ≠ allow), and calls
    // that were approved but failed before spawning the subagent (e.g. agent_id doesn't
    // exist) — the latter is cleaned up when the parent-level tool_call_output settles;
    // if the call is still in the queue at that point, it never produced a session_meta.
    const subagentPrompts = new Map<string, string>();
    try {
      for await (const msg of gen) {
        // A parent-level (no origin) run_subagent call: record its prompt for the child
        // session_meta that arrives later to use as its title.
        if (!msg.origin || msg.origin.length === 0) {
          const call = runSubagentCall(msg);
          if (call) subagentPrompts.set(call.toolCallId, call.prompt);
          const denied = deniedToolCallId(msg);
          if (denied) subagentPrompts.delete(denied);
          const settled = settledToolCallId(msg);
          if (settled) subagentPrompts.delete(settled);
          // Steering delivery: core emits exactly one `[user_steering]` user text per queued
          // entry, in queue order — shift the display mirror and re-broadcast so the
          // composer's "steering queued" hint retires the moment the message is on stream.
          if (entry.pendingSteering.length > 0 && isDeliveredSteering(msg)) {
            entry.pendingSteering.shift();
            this.publishState(entry, entry.status);
          }
          // The main session's own session_meta is streamed when a model switch opens its new
          // context, and the runtime is on that context's model by then: the entry and the row
          // follow it here, ahead of the publish below, so a client that re-reads the Session
          // on this record already finds the new model. The new context's file is open too, its
          // records on it, and what the context it replaced still held pending went with it.
          if (isSessionMeta(msg)) {
            this.syncEntryModel(entry);
            entry.pendingBootstrap = [];
          }
        } else if (isSessionMeta(msg)) {
          // Subagent registration is only a "side effect" — it must never interrupt the
          // main run flow on error: wrap the whole thing in a defensive try/catch.
          try {
            const child = this.registerChildSession(entry, msg, children);
            // Only a **direct** subagent (origin length 1) claims a queued parent-level
            // run_subagent prompt; deeper sessions are spawned by their own parent and
            // shouldn't consume from this queue.
            if (child && msg.origin!.length === 1) {
              const [pendingId] = subagentPrompts.keys();
              if (pendingId !== undefined) {
                child.prompt = subagentPrompts.get(pendingId) ?? "";
                subagentPrompts.delete(pendingId); // Consumed by this session_meta
              }
              // The subagent's title is generated right here at registration, from the
              // spawning prompt alone (its "user input") — never waiting for the
              // subagent's own output. It piggybacks a one-shot request on the parent
              // Session's bare LLM (the child Session object never leaves the SDK):
              // Session/Agent record the subagent (the title belongs to it), but the
              // model reference keeps ctx's parent-Session (provider, modelId) pair —
              // a subagent may switch models via run_subagent's model_id.
              if (child.prompt.trim()) {
                this.deps.titles?.maybeGenerate(
                  { ...ctx, agentId: child.agentId, sessionId: child.sessionId },
                  entry.session,
                  {
                    fallbackText: child.prompt,
                    material: { userText: child.prompt, assistantText: "" },
                    notifyOn: entry.sessionId, // Notify the frontend via the parent Session's SSE channel
                  },
                );
              }
            }
          } catch (err) {
            this.log(
              `[subagent] Failed to register child session: ${err instanceof Error ? err.message : String(err)}`,
            );
            this.deps.errors?.record({
              source: "subagent",
              err,
              ctx,
              code: "subagent_register_failed",
            });
          }
        }
        // Bootstrap records (first-run MCP connect + toolset): held for GET /messages
        // until the engine's deferred Trace write catches up (see pendingBootstrap).
        if (!msg.origin || msg.origin.length === 0) {
          const bt = (msg.payload as { type?: string }).type;
          if (bt === "mcp_connect_begin" || bt === "mcp_connect_end" || bt === "tool_list_ready") {
            entry.pendingBootstrap.push(msg);
          }
          // First request of the run: the engine writes input → bootstrap records → tool
          // list to the Trace BEFORE issuing the request, so both holds are persisted by
          // now — end them here rather than at idle. Holding for the whole run would
          // outlive the messages endpoint's tail-window dedup: once the Task appends
          // more records than the window, the input would be judged "not yet in the
          // Trace" and served a second time at the end of history.
          if (bt === "request_begin") {
            entry.pendingInputs = [];
            entry.pendingBootstrap = [];
          }
        }
        // Live-tail bookkeeping in the same synchronous tick as the publish below: the
        // messages endpoint captures "channel cursor + open fragments" between two
        // publishes, so the pair is always a consistent snapshot (see live-tail.ts).
        this.liveTail.observe(entry.sessionId, msg);
        // Re-fetch the channel before every publish (matches publishEvent): the channel
        // may have been recycled and recreated during a long wait on approval, and
        // holding a stale reference would send output to an orphaned, detached channel.
        this.deps.channels.get(entry.sessionId).publish(msg);
        watcher?.observe(msg);
        try {
          await this.deps.recorder.record(ctx, msg);
        } catch (err) {
          this.log(`[usage] Insert failed: ${err instanceof Error ? err.message : String(err)}`);
          this.deps.errors?.record({ source: "usage", err, ctx, code: "usage_insert_failed" });
        }
      }
    } catch (err) {
      // The SDK doesn't normally throw (errors are converged into the message stream);
      // this is a defensive record here to avoid crashing the runtime.
      this.log(
        `[session] Run failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
      );
      this.deps.errors?.record({ source: "session", err, ctx, code: "session_run_failed" });
    } finally {
      // Wrap-up: persist any still-pending LLM failure and clear the tool-name cache (the watcher's state doesn't carry across runs).
      watcher?.close();
      // The run is over: no fragment will ever continue, so drop the live tail before the
      // idle flip (GET /messages stops attaching `live` the moment status reads idle).
      this.liveTail.clear(entry.sessionId);
      // The pending holds are NOT cleared here: a run aborted mid-bootstrap wrote nothing
      // to the Trace, so its held input (and the aborted connect pair) are the only copy
      // a reload can show until the next run carries the input forward and persists it.
      // Runs that issued a request already cleared them at their first request_begin.
      // Main approvals only: an origin-tagged approval belongs to a subagent child that
      // outlives this task — it stays pending for the user (see ApprovalRegistry.denyMain).
      entry.approvals.denyMain();
      entry.status = "idle";
      entry.abort = null;
      entry.running = null;
      // The run is over, so core has discarded any undelivered steering (see ContextEngine's
      // steeringQueue). What is still in the mirror was therefore never delivered — entries
      // are shifted out as their `[user_steering]` message appears on the stream, and this
      // runs after that stream is drained — so hand it back to the user rather than dropping
      // it: the composer recalls it into its draft. Interrupting while a tool runs is the
      // ordinary way to get here, and the typed message must survive it.
      if (entry.pendingSteering.length > 0) {
        entry.returnedSteering = [...entry.returnedSteering, ...entry.pendingSteering];
        entry.pendingSteering = [];
      }
      entry.lastActivityMs = Date.now();
      // Run-end stamp (see the run-start counterpart at the top of drive). Guarded like
      // every other write in this finally: what follows — the idle broadcast and the
      // auto-start of queued follow-ups (this is its only call site) — must not be
      // skippable by a DB failure, or SSE clients would sit on "running" forever with
      // their queue stranded. A no-op UPDATE when the row is already gone: deletion
      // normally awaits the drive first, so that only happens once its 5s wait times out.
      this.touchRow(ctx, (repo, at) => repo.touchLastActive(ctx.sessionId, at));
      this.publishState(entry, "idle");
      // Queued follow-ups: whenever a run finishes (Task or compaction, abort included),
      // the next queued input auto-starts as an ordinary task. Fire-and-forget — it
      // revalidates under the session lock.
      if (entry.followUps.length > 0) void this.startQueuedFollowUp(entry.sessionId);
      // Background completion notices that raced this run's exit (arrived after its last
      // input-assembly boundary): start their delivery task now. No-op when a follow-up
      // just launched — that run's engine drains the same queue.
      else void this.startBackgroundNoticeTask(entry.sessionId);
    }
  }

  /**
   * Register a subagent: persisted only when the origin message is session_meta
   * (agentId is derived from the agent_state path: `<…>/<agentId>/agent_state`).
   * **The title is left blank here** — the registration site in drive generates it
   * right away from the spawning prompt (fallback first words + LLM replacement), so
   * it never waits for the subagent's own output. Idempotent (children dedup +
   * insertOrIgnore); a subagent has its own Trace, so it's visible in both the list
   * and the trace view. On successful registration, the entry is put into `children`
   * and returned; a duplicate session_meta returns null.
   */
  private registerChildSession(
    entry: RuntimeEntry,
    msg: OmniMessage,
    children: Map<string, ChildSession>,
  ): ChildSession | null {
    if (!isSessionMeta(msg)) return null;
    const childSid = msg.origin![msg.origin!.length - 1]!;
    if (children.has(childSid)) return null;
    const p = msg.payload as SessionMetaPayload;
    const agentId = path.basename(path.dirname(p.agent_state));
    if (!agentId || agentId === "." || agentId === "..") return null;
    // The forwarded session_meta records the source where it is decided (core's spawn site
    // writes `subagent`); it is narrowed like any meta read back, so the registry holds what
    // the child's Trace head will answer after a restart. It goes into the in-process registry
    // only — the index row deliberately stores no source column.
    const source = normalizeSessionSource(p.source);
    this.deps.sources.set(childSid, source);
    const root = this.rootSessionOf(entry.sessionId);
    this.childRoots.set(childSid, root);
    const createdAt = this.now().toISOString();
    // A sub-session of an organization's Session is company mode's own as much as the desk
    // or ticket session that spawned it: it inherits the durable "org" stamp, which is the
    // only mark it can carry — the organization caches name desks and ticket sessions, never
    // what those spawn — and the one development mode's list leaves out. Every other parent
    // leaves the marker blank (read as web): the child was spawned by this server's run, not
    // opened through the CLI, whatever opened its parent.
    const parentClient = this.deps.sessions.findById(entry.sessionId)?.client;
    this.deps.sessions.insertOrIgnore({
      sessionId: childSid,
      projectId: entry.projectId,
      agentId,
      provider: p.provider,
      modelId: p.model_id,
      workspace: p.workspace,
      // A subagent's approvals are inherited from the parent Session; the index row is
      // inserted with defaults (matches the convention for Sessions discovered by the CLI).
      approvalMode: "allow-all",
      // The root's policy at registration, so the child row stands on its own if it is ever
      // resumed directly; while registered it follows the root (see rootSessionOf).
      sandbox: this.deps.sessions.findById(root)?.sandbox ?? null,
      title: null,
      ...(parentClient === "org" ? { client: "org" as const } : {}),
      // Its Trace exists by construction.
      hasTrace: true,
      // A subagent's own runs are driven through the PARENT entry's drive, so nothing ever
      // stamps this row: it stays at its registration time (see SessionRow.lastActiveAt).
      lastActiveAt: createdAt,
      createdAt,
    });
    // Make the subagent appear immediately in the sidebar: notify via the parent
    // Session's channel (a frontend currently watching the parent run refreshes its list in place).
    this.publishEvent(entry, {
      type: "session_created",
      projectId: entry.projectId,
      agentId,
      sessionId: childSid,
      source,
    });
    const child: ChildSession = {
      sessionId: childSid,
      agentId,
      prompt: "",
    };
    children.set(childSid, child);
    return child;
  }

  /**
   * Runs one `sessions` row write for a driven run's bookkeeping (has_trace /
   * last_active_at), swallowing failures the same way the per-message `recorder.record`
   * call does: bookkeeping must never take down a run's lifecycle. The two call sites both
   * sit outside a covering try — the run-start write precedes drive's try block, the
   * run-end one lives in its finally — and the realistic failure (the DatabaseSync handle
   * closed by shutdown while a run outlived its drain window) throws ERR_INVALID_STATE.
   */
  private touchRow(ctx: UsageContext, write: (repo: SessionIndex, at: string) => void): void {
    try {
      write(this.deps.sessions, this.now().toISOString());
    } catch (err) {
      this.log(
        `[session] last-active bookkeeping failed: ${err instanceof Error ? err.message : String(err)}`,
      );
      this.deps.errors?.record({ source: "session", err, ctx, code: "session_touch_failed" });
    }
  }

  private publishState(entry: RuntimeEntry, state: SessionStatus): void {
    // Every state flip also reports the queued follow-up count, the undelivered steering
    // mirror, and the live subagent children, so subscribers can render all three hints
    // without a dedicated event type.
    const subagents = entry.session.listBackgroundSubagents?.() ?? [];
    this.publishEvent(entry, {
      type: "task_state",
      state,
      queued: entry.followUps.length,
      ...(entry.pendingSteering.length > 0
        ? { pendingSteering: entry.pendingSteering.map((p) => p.info) }
        : {}),
      ...(entry.returnedSteering.length > 0
        ? { returnedSteering: entry.returnedSteering.map((p) => p.info) }
        : {}),
      ...(entry.followUps.length > 0
        ? { pendingFollowUps: entry.followUps.map(followUpInfo) }
        : {}),
      ...(subagents.length > 0 ? { subagents } : {}),
    });
    // The same flip again, this time on the user channel and carrying the Session id: a tab
    // subscribes to the ONE conversation it has open, so the event above can never move any
    // other row's badge. Only the queued/steering hints stay session-scoped — they belong to
    // the composer of the conversation being watched, not to a list row.
    const notify = this.deps.notifyProjectUsers;
    if (!notify) return;
    let lastActiveAt: string;
    let hasTrace: boolean;
    try {
      // Read the stamp back rather than reconstruct it: the run-end flip is published right
      // after the write that stamps it (touchLastActive in drive's finally), so this is what a
      // list fetch would return right now and no clock of ours has to agree with the one that
      // wrote it.
      const row = this.deps.sessions.findById(entry.sessionId);
      if (!row) return; // Row already deleted: no list row left to light up.
      lastActiveAt = row.lastActiveAt;
      // A running Session has by definition started a Task, whatever the row cache says yet:
      // markDriven (which sets has_trace) runs inside drive(), and startTask has already
      // published the first "running" by then. Reporting the raw flag there would tell a client
      // the Session has never run at the exact moment it visibly is running — and a client that
      // believed it would draw the hourglass, then nothing at all once the run settled.
      hasTrace = row.hasTrace === true || state !== "idle";
    } catch {
      // Same failure touchRow guards against (DB handle closed by shutdown while a run
      // outlives its drain window). A list badge is never worth breaking a run's finally over.
      return;
    }
    notify(entry.projectId, {
      type: "session_state",
      sessionId: entry.sessionId,
      projectId: entry.projectId,
      state,
      lastActiveAt,
      hasTrace,
    });
  }

  private publishEvent(entry: RuntimeEntry, event: ServerEvent): void {
    this.deps.channels.get(entry.sessionId).publish(event, "server_event");
  }

  /**
   * Re-counts a loaded session's background tasks and, when the counts moved, publishes
   * `session_background` on the user channel (the list's mark is a user-channel affair like
   * `session_state`; the open conversation reads the same row). A change is Session
   * activity for the idle sweep: the entry stays loaded for the usual idle window after its
   * last background task ends, so the finished process list can still be read. An entry
   * that already left the table (a delete disposing its runtime) publishes nothing — its
   * row is gone as well.
   */
  private publishBackgroundTasks(sessionId: string): void {
    const entry = this.entries.get(sessionId);
    if (!entry) return;
    const counts = backgroundTaskCounts(entry.session);
    const last = entry.backgroundTasks;
    if (counts.processes === last.processes && counts.subagents === last.subagents) return;
    entry.backgroundTasks = counts;
    entry.lastActivityMs = Date.now();
    this.deps.notifyProjectUsers?.(entry.projectId, {
      type: "session_background",
      sessionId: entry.sessionId,
      processes: counts.processes,
      subagents: counts.subagents,
    });
  }

  /**
   * Publishes `session_approvals` on the user channel: how many tool calls of this Session wait
   * for a person now. The Session's own stream carries the calls; this is what lets a list, or
   * a host watching every Session of a Project, see which one waits without subscribing to each.
   * Sent for an entry that is being disposed too, so a mark it had is cleared.
   */
  private publishApprovals(entry: RuntimeEntry): void {
    try {
      this.deps.notifyProjectUsers?.(entry.projectId, {
        type: "session_approvals",
        sessionId: entry.sessionId,
        count: entry.approvals.size,
      });
    } catch (err) {
      // The notifier reads the Project's audience from the database, which shutdown can close
      // while a run outlives its drain window (the failure publishState guards too). A list
      // mark is never worth throwing out of an approval's wait, answer or interrupt.
      this.log(
        `[session] approvals notice failed: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  }

  /** Serialize (mutually exclude) execution by sessionId; cleans up the lock-table entry once its chain drains (avoids unbounded growth). */
  private async withLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
    // What's stored in the chain is the already-caught version (used only for
    // sequencing, never propagates errors); the caller gets the original result from `next`.
    const prev = this.locks.get(sessionId) ?? Promise.resolve();
    const next = prev.then(fn);
    const settled: Promise<void> = next
      .then(
        () => undefined,
        () => undefined,
      )
      .then(() => {
        // Only delete if still the tail of the chain (no later waiter): preserves mutual-exclusion semantics.
        if (this.locks.get(sessionId) === settled) this.locks.delete(sessionId);
      });
    this.locks.set(sessionId, settled);
    return next;
  }
}

/** The session runtime: one entry per live Session, task mutex, approvals, streaming. */
export abstract class Sessions extends Interface<
  Pick<
    SessionManager,
    | "statusOf"
    | "liveSessions"
    | "pendingApprovalCount"
    | "pendingApprovals"
    | "pendingFollowUpCount"
    | "pendingSteeringOf"
    | "subagentsOf"
    | "sendToSubagent"
    | "abortSubagentRun"
    | "pendingFollowUpsOf"
    | "liveFragments"
    | "pendingInputs"
    | "pendingBootstrap"
    | "activeCountForAgent"
    | "invalidateAgentRuntimes"
    | "invalidateProjectRuntimes"
    | "assertCanAcceptTask"
    | "startTask"
    | "startGoal"
    | "startCompact"
    | "startSwitch"
    | "onModelChanged"
    | "decideApproval"
    | "steer"
    | "recallSteering"
    | "recallFollowUp"
    | "retryNow"
    | "abortTask"
    | "listProcesses"
    | "probeProcessServices"
    | "killProcess"
    | "removeProcess"
    | "abortProject"
    | "beginAgentDeletion"
    | "endAgentDeletion"
    | "beginSessionDeletion"
    | "endSessionDeletion"
    | "atIdleBoundary"
    | "shutdown"
    | "sweepIdle"
  >
>() {}

export abstract class SessionServiceIface extends Interface<
  Pick<
    SessionServiceImpl,
    | "toInfo"
    | "hasTrace"
    | "listSessions"
    | "sessionStats"
    | "createSession"
    | "defaultSandbox"
    | "pickSandbox"
    | "updateSandbox"
    | "latestTracePath"
    | "adoptUnmanagedTraceSessions"
  >
>() {}

/** The per-spawn policies every Session's command environment is built with. */
@Interface()
export abstract class SessionEnv {
  abstract proxyEnv(): ProxyEnvPolicy | null;
  abstract controlEnv(ctx: ControlEnvContext): Record<string, string>;
  /** The directories at the FRONT of every command's PATH: the harness's own CLI shim (see CreateAgentOptions.pathPrepend). */
  abstract pathPrepend(): string[];
  abstract confineSpawn(ctx: ControlEnvContext): SpawnConfiner | null;
}

@Module()
export class SessionsModule {
  @Use() private readonly config!: Config;
  @Use() private readonly channels!: Channels;
  @Use() private readonly authState!: AuthState;
  @Use() private readonly clock!: Clock;
  @Use() private readonly sessionLoaders!: SessionLoaders;
  @Use() private readonly titleGenerators!: TitleGenerators;
  @Use() private readonly log!: Log;
  @Use() private readonly settings!: Settings;
  @Use() private readonly sessionsRepo!: SessionIndex;
  @Use() private readonly sources!: SessionOrigins;
  @Use() private readonly recorder!: UsageRecording;
  @Use() private readonly errors!: Errors;
  @Use() private readonly modelScopeAuth!: ModelScopeAuth;
  @Use() private readonly projectConfig!: ProjectConfigStore;
  @Use() private readonly traceIndex!: TraceIndex;
  @Use() private readonly traceStore!: TraceIndexStore;
  @Use(SandboxModule) private readonly sandbox!: Sandbox;
  /** The Sandbox card's presets live in the sandbox's settings group. */
  @Use() private readonly pluginConfig!: PluginConfig;
  @Use() private readonly projectEvents!: ProjectEvents;
  @Use() private readonly messagingRepo!: MessagingBindings;
  /** Company-mode caches: which organization owns a Session (read at every command spawn). */
  @Use() private readonly orgCache!: OrgCache;
  @Provide() manager!: Sessions;
  @Provide() sessionService!: SessionServiceIface;
  @Provide() env!: SessionEnv;
  setup() {
    const { config, settings, authState } = this;
    const log = (line: string) => this.log.line(line);
    const channels = this.channels as ChannelHub;
    const sessionsRepo = this.sessionsRepo;
    const sources = this.sources;
    const recorder = this.recorder;
    const errors = this.errors;
    const projectConfig = this.projectConfig;
    const sandbox = this.sandbox as SandboxService;
    const pluginConfig = this.pluginConfig;
    const orgCache = this.orgCache;
    const modelScopeAuth = this.modelScopeAuth;

    const assembly: AgentAssembly = {
      resolveModelApiKey: async ({ projectId, provider, modelId }) => {
        if (provider !== MODELSCOPE_PROVIDER_ID) return undefined;
        await modelScopeAuth.ensureFresh({ projectId, provider });
        const apiKey = await projectConfig.getGroupApiKey(projectId, provider);
        if (apiKey === undefined) throw modelCredentialMissing(modelId);
        return apiKey;
      },
    };
    projectConfig.setModelApiKeyResolver(assembly.resolveModelApiKey!);

    // Which commands run confined, under which policy, by which backend is policy — the
    // sandbox module's; core only carries the spawn seam, reached through this getter.
    const env: SessionEnv = {
      proxyEnv: (): ProxyEnvPolicy | null => {
        if (!settings.getProxyForAgent()) return { mode: "strip" };
        const url = settings.getProxyUrl();
        return url === null ? null : { mode: "inject", url, noProxy: mergedNoProxy() };
      },
      controlEnv: (ctx: ControlEnvContext): Record<string, string> => {
        const host =
          config.host === "0.0.0.0" || config.host === "::"
            ? "127.0.0.1"
            : (loopbackHostRoles(config.host)?.app ?? config.host);
        const token = authState.apiToken;
        const orgId = orgCache.ownerOfSession(ctx.sessionId)?.orgId ?? null;
        return {
          ADELIE_API_URL: `http://${host}:${config.port}`,
          ...(token !== null ? { ADELIE_API_TOKEN: token } : {}),
          ADELIE_PROJECT_ID: ctx.projectId,
          ADELIE_AGENT_ID: ctx.agentId,
          ADELIE_SESSION_ID: ctx.sessionId,
          // A desk or ticket session also learns its organization, so `penguin org` needs no
          // --org-id inside it. Looked up per spawn from the cache the ledger and the tickets
          // project into.
          ...(orgId !== null ? { ADELIE_ORG_ID: orgId } : {}),
        };
      },
      // The directory core puts at the FRONT of PATH for every command an Agent runs (and for
      // its hook scripts): the shim directory bootAppDeps wrote this harness's own `penguin`
      // into. Derived from the config rather than passed along, so the platform half needs no
      // new capability — and read for truth rather than for null, because a runtime older than
      // this field publishes a config without it and wrote no shim either: no field, no
      // directory, feature off, rather than a push declined over a PATH entry.
      pathPrepend: (): string[] => (config.cliEntry ? [cliShimDir(config.root)] : []),
      // Each Session confines under its OWN policy — the snapshot on its row, its root's for a
      // subagent — so a settings change reaches only Sessions created after it. A row from
      // before snapshots takes the settings at its first command and keeps them from then on.
      confineSpawn: (ctx: ControlEnvContext) =>
        sandbox.confinerFor(() => {
          const root = manager.rootSessionOf(ctx.sessionId);
          const row = sessionsRepo.findById(root);
          if (row?.sandbox) return row.sandbox;
          const snapshot = sandbox.currentSettings();
          if (row !== null) sessionsRepo.updateSandbox(root, snapshot);
          return snapshot;
        }),
    };

    const notifyProjectUsers = (projectId: string, event: ServerEvent): void =>
      this.projectEvents.notifyProjectUsers(projectId, event);
    const titles = this.titleGenerators.create({
      sessions: sessionsRepo,
      channels,
      recorder,
      errors,
      log,
      notifyProjectUsers,
    });
    const manager = new SessionManager({
      sessions: sessionsRepo,
      channels,
      loader: this.sessionLoaders.create(config.root, sources, {
        proxyEnv: env.proxyEnv,
        controlEnv: env.controlEnv,
        pathPrepend: env.pathPrepend,
        confineSpawn: env.confineSpawn,
        assembly,
      }),
      sources,
      recorder,
      errors,
      modelScopeAuth: this.modelScopeAuth,
      titles,
      log,
      notifyProjectUsers,
      // A person talking to a desk (the chat page, a bound bot) starts a new @-chain: the
      // desk's next channel message is hop 1 again, whatever mention last woke it.
      onHumanInput: (sessionId) => {
        if (orgCache.ownerOfSession(sessionId) !== null) orgCache.setTriggerHop(sessionId, 0);
      },
      now: () => this.clock.now(),
    });
    const sessionService = new SessionService({
      root: config.root,
      sessions: sessionsRepo,
      manager,
      projectConfig,
      sources,
      traceIndex: this.traceIndex,
      traceStore: this.traceStore,
      proxyEnv: env.proxyEnv,
      controlEnv: env.controlEnv,
      notifyProjectUsers,
      messagingChannel: (sessionId) => enabledMessagingChannel(this.messagingRepo, sessionId),
      // Company mode: which organization owns a Session, so development mode's list can hide
      // organization sessions and the company sidebar can group its own. The caches are a
      // projection of the organization's files, rebuilt every reconcile pass, so a row that
      // has not been projected yet reads as an ordinary Session for one pass — never as the
      // wrong organization.
      orgIdOfSession: (sessionId) => orgCache.ownerOfSession(sessionId)?.orgId,
      orgIdsOfProject: (projectId) => orgCache.orgIdsOfProject(projectId),
      pathPrepend: env.pathPrepend,
      confineSpawn: env.confineSpawn,
      assembly,
      sandboxDefaults: () => sandbox.currentSettings(),
      sandboxDimensions: () => [...new Set(sandbox.backends().flatMap((b) => b.dimensions))],
      sandboxUnavailable: () => sandbox.failures(),
      sandboxBackends: () => sandbox.backends().map((b) => b.name),
      // The Sandbox card's presets, read per view: a rename there reaches the next read.
      sandboxPresets: () =>
        sandboxPresetsOf(pluginConfig.schema(SANDBOX_GROUP), pluginConfig.get(SANDBOX_GROUP)),
      sandboxSwitchOn: () => sandboxEnabledOf(pluginConfig.get(SANDBOX_GROUP)),
      // The default preset's approval mode, while the switch is on.
      sandboxDefaultApproval: () =>
        sandboxStartOf(pluginConfig.schema(SANDBOX_GROUP), pluginConfig.get(SANDBOX_GROUP))
          .approvalMode,
    });
    this.manager = manager;
    this.sessionService = sessionService;
    this.env = env;
  }
}

/** Builds the loader a manager runs sessions through; a test stands in a fake session. */
@Interface()
export abstract class SessionLoaders {
  abstract create(
    root: string,
    sources: Opaque<"SessionOrigins", SessionOrigins>,
    env: Opaque<"SessionLoaderEnv", Parameters<typeof createCoreSessionLoader>[2]>,
  ): Opaque<"SessionLoader", SessionLoader>;
}
@Component()
export class CoreSessionLoaders implements SessionLoaders {
  create(
    root: string,
    sources: SessionOrigins,
    env: Parameters<typeof createCoreSessionLoader>[2],
  ): SessionLoader {
    return createCoreSessionLoader(root, sources, env);
  }
}

/** Builds the title generator; a test stands in a notifier that never calls a model. */
@Interface()
export abstract class TitleGenerators {
  abstract create(
    deps: Opaque<"TitleGeneratorDeps", ConstructorParameters<typeof TitleGenerator>[0]>,
  ): Opaque<"TitleNotifier", TitleNotifier>;
}
@Component()
export class DefaultTitleGenerators implements TitleGenerators {
  create(deps: ConstructorParameters<typeof TitleGenerator>[0]): TitleNotifier {
    return new TitleGenerator(deps);
  }
}