Skip to content

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

76.7 KB
Raw Blame
/**
 * The Session runtime (SessionManager) over scripted runtime Sessions. No model is ever
 * called; one case drives a real core Session, with a scripted LLM, and a real OS process.
 *
 * Driving:
 * - An unknown Session is a 404. A Task publishes its input first, runs, returns to idle and
 *   pushes task_state; the row's last-active stamp moves at the start and the end of each run
 *   (a failing stamp write strands nothing); outputs reach the recorder with their context.
 * - The thinking level is runtime state the manager assigns, reaching a live child and a
 *   runtime still loading.
 * - Background notices arriving while idle auto-start a Task carrying them (adopted Sessions
 *   included); live subagent messages are published and their usage recorded; end to end, a
 *   real background command finishing after idle reaches the channel as a harness message.
 * - LLM and tool failures folded into the stream are recorded with the Session's context.
 * - A second Task or a compaction while running is a 409; each compact refusal has its own code.
 * - Steering reaches the running Session (idle or a lost race is a 409), with a mirror that is
 *   broadcast, shifted at delivery and dropped at the run's end; follow-ups queue while running
 *   or compacting and start in order afterwards, surviving an abort.
 *
 * Approvals:
 * - always-ask parks the call and pushes approval_request; deny-all and read-only decide
 *   without a person; an organization's Session denies what would wait for a person, while a
 *   development Session under the same mode still waits; a mode PATCHed mid-run applies to the
 *   next decision; an abort collapses pending approvals to deny before the signal fires.
 * - A sub-session inherits its parent's organization stamp and persists its session_meta.
 *
 * Lifecycle:
 * - Session deletion interrupts and blocks new Tasks until it ends; a loader answering a new id
 *   heals the index; a swept channel is re-read before every publish; a Project abort hands
 *   back its in-flight runs; a loader's HttpError passes through; shutdown disposes every
 *   environment and refuses new Tasks, and a run parked on an approval is denied, winds down,
 *   and is disposed only after it has, even once the database has closed under it.
 * - Idle entries are evicted (running ones, pending approvals and working subagents pin them);
 *   invalidating an Agent's or a Project's runtimes rebuilds them at next access, never
 *   mid-run, and publishes a discarded runtime's background count as cleared.
 *
 * Titles:
 * - Title generation fires at Task start, before any model output, from the user's input
 *   alone (never from a compaction); a subagent's fires at registration from its spawning
 *   prompt.
 */
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import type { DatabaseSync } from "node:sqlite";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import {
  Environment,
  Session,
  abortEvent,
  approvalDecision,
  assistantText,
  compactionBegin,
  compactionEnd,
  emptyTokenCounts,
  requestBegin,
  requestEnd,
  sessionMeta,
  thinkingMessage,
  tokenUsage,
  toolCall,
  toolCallOutput,
  userSteeringText,
  userText,
  withOrigin,
} from "@adelie/core";
import type {
  ApproveFn,
  GenerativeModelParameters,
  LLMInterface,
  LLMOutcome,
  OmniMessage,
  TextPayload,
} from "@adelie/core";
import type { ServerEvent } from "../src/api/types.js";
import { openDatabase } from "../src/db/database.js";
import { HttpError } from "../src/http/errors.js";
import { SessionsRepo } from "../src/db/repos/sessions.js";
import type { SessionRow } from "../src/db/repos/sessions.js";
import { ChannelHub } from "../src/runtime/channel.js";
import type { ChannelEvent } from "../src/runtime/channel.js";
import type { ErrorRecordArgs, ErrorSink } from "../src/runtime/error-recorder.js";
import { SessionManager, FOLLOW_UP_QUEUE_LIMIT } from "../src/runtime/session-manager.js";
import type { RuntimeSession, SessionLoader } from "../src/runtime/session-manager.js";
import { SessionSources } from "../src/runtime/session-sources.js";
import type { TitleRequest } from "../src/runtime/title-generator.js";
import type { UsageContext } from "../src/runtime/usage-recorder.js";
import { fakeSession } from "./fixtures/session.js";
import { waitFor } from "./helpers.js";
import { wire } from "@adelie/core/kernel";

const ROW: SessionRow = {
  sessionId: "session-1",
  projectId: "p1",
  agentId: "a1",
  modelId: "m1",
  provider: "custom",
  workspace: "/tmp/w",
  approvalMode: "always-ask",
  title: null,
  createdAt: "2026-07-06T00:00:00.000Z",
  lastActiveAt: "2026-07-06T00:00:00.000Z",
};

/** A simple, scriptable fake Session: run yields one tool_call and requests approval for it. */
function approvalFakeSession(sessionId: string, toolName = "write_file"): RuntimeSession {
  return fakeSession(sessionId, {
    toolPermission: (name) => (name === "read_tool" ? "r" : "rw"),
    async *run(_input: OmniMessage[], opts: { approve: ApproveFn; signal: AbortSignal }) {
      const tc = toolCall({ name: toolName, arguments: "{}", toolCallId: "tc-1" });
      yield tc;
      const decision = await opts.approve(tc);
      yield approvalDecision(decision, "tc-1");
      if (opts.signal.aborted) {
        yield abortEvent();
        return;
      }
      yield assistantText(`decision=${decision}`);
    },
    async *compact() {
      yield compactionBegin({ reason: "manual", mode: "summarize", context: 1, turns: 1 });
      yield compactionEnd({ reason: "manual", mode: "summarize", status: "completed" });
    },
  });
}

/**
 * A run that parks one call on a person, logging into `order` how the call was decided, whether
 * the run was aborted by then, when it ended, and when its environment was disposed.
 */
function parkedRunSession(order: string[]): RuntimeSession {
  const fake = fakeSession("session-1", {
    async *run(_input: OmniMessage[], opts: { approve: ApproveFn; signal: AbortSignal }) {
      try {
        const tc = toolCall({ name: "write_file", arguments: "{}", toolCallId: "tc-1" });
        yield tc;
        order.push(`decided ${await opts.approve(tc)}`);
        order.push(`aborted ${String(opts.signal.aborted)}`);
      } finally {
        order.push("run ended");
      }
    },
  });
  (fake as { dispose?: () => void }).dispose = () => {
    order.push("disposed");
  };
  return fake;
}

/**
 * A repo whose last-active writes always throw — the realistic failure being a
 * DatabaseSync handle closed by shutdown while a run outlived its drain window. Everything
 * else behaves normally, so a test can assert that the run's wrap-up survives it.
 */
function brokenTouchRepo(repo: SessionsRepo): SessionsRepo {
  return new Proxy(repo, {
    get(target, prop, receiver): unknown {
      if (prop === "markDriven" || prop === "touchLastActive") {
        return () => {
          throw new Error("database is not open");
        };
      }
      return Reflect.get(target, prop, receiver) as unknown;
    },
  });
}

describe("session-manager", () => {
  let db: DatabaseSync;
  let sessions: SessionsRepo;
  let channels: ChannelHub;
  let sources: SessionSources;
  let recorded: OmniMessage[];
  let recordedCtx: UsageContext[];

  const makeManager = (
    loader: SessionLoader,
    errors?: ErrorSink,
    /** Stubbed clock for persisted timestamps (see the last_active_at test). */
    now?: () => Date,
  ): SessionManager =>
    new SessionManager({
      sessions,
      channels,
      sources,
      loader,
      recorder: {
        record: async (ctx, msg) => {
          recordedCtx.push(ctx);
          recorded.push(msg);
        },
      },
      ...(errors ? { errors } : {}),
      ...(now ? { now } : {}),
      log: () => {},
    });

  const loaderOf = (session: RuntimeSession): SessionLoader => ({ load: async () => session });

  const capture = (sessionId: string): ChannelEvent[] => {
    const events: ChannelEvent[] = [];
    channels.get(sessionId).subscribe((e) => events.push(e));
    return events;
  };

  const serverEvents = (events: ChannelEvent[]): { type: string; [k: string]: unknown }[] =>
    events
      .filter((e) => e.event === "server_event")
      .map((e) => JSON.parse(e.data) as { type: string });

  beforeEach(() => {
    db = openDatabase(":memory:");
    sessions = wire(SessionsRepo, { db: db });
    sessions.insert(ROW);
    channels = new ChannelHub();
    sources = new SessionSources();
    recorded = [];
    recordedCtx = [];
  });
  afterEach(() => {
    channels.dispose();
    if (db.isOpen) db.close();
  });

  it("unknown Session → 404", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const err = await manager.startTask("session-ghost", [userText("x")]).catch((e: unknown) => e);
    expect((err as { status: number }).status).toBe(404);
  });

  it("startTask: publishes the input first; when driving ends it returns to idle and pushes task_state", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const events = capture("session-1");
    const { sessionId } = await manager.startTask("session-1", [userText("hello")]);
    expect(sessionId).toBe("session-1");
    await waitFor(() => manager.statusOf("session-1") === "idle" && recorded.length >= 3);

    // The first entry is the input message (visible to other subscribers), followed by task_state: running.
    const first = JSON.parse(events[0]!.data) as { payload: { text: string } };
    expect(first.payload.text).toBe("hello");
    const states = serverEvents(events).filter((e) => e.type === "task_state");
    expect(states.map((s) => s.state)).toEqual(["running", "idle"]);
    // Driving a run flips the row's has_trace cache (listing then never walks for it).
    expect(sessions.findById("session-1")!.hasTrace).toBe(true);
    // Outputs and events are forwarded one by one and handed to the recorder.
    expect(recordedCtx[0]).toEqual({
      projectId: "p1",
      agentId: "a1",
      sessionId: "session-1",
      modelId: "m1",
      provider: "custom",
    });
  });

  it("drive stamps last_active_at twice per run — once at the start, once at the end — and leaves other rows alone", async () => {
    sessions.insert({
      ...ROW,
      sessionId: "session-other",
      createdAt: "2026-07-07T00:00:00.000Z",
      lastActiveAt: "2026-07-07T00:00:00.000Z",
    });
    // A stubbed clock, one second per read, so each stamp has an exact expected value:
    // sampling only after the run (when both stamps have landed) cannot tell the two
    // apart, and a run-end stamp that stops happening would still look "advanced".
    let tick = 0;
    const at = (n: number): string => `2026-07-10T00:00:0${n}.000Z`;
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")), undefined, () => {
      const d = new Date(at(tick));
      tick += 1;
      return d;
    });
    const lastActive = (id: string): string => sessions.findById(id)!.lastActiveAt;
    // Insert default: last_active_at = created_at until the first driven run.
    expect(lastActive("session-1")).toBe(ROW.createdAt);

    // The session pauses mid-run on the always-ask approval — the one moment where the
    // run-start stamp is observable on its own.
    await manager.startTask("session-1", [userText("hello")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    const midRun = lastActive("session-1");
    expect(midRun).toBe(at(0));
    expect(midRun > ROW.createdAt).toBe(true);

    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    // Strictly greater: the run END must have its own stamp, or a long Task would report
    // the moment it began as its last activity for as long as it runs.
    expect(lastActive("session-1")).toBe(at(1));
    expect(lastActive("session-1") > midRun).toBe(true);

    // A compaction is a driven run too, and stamps its own pair.
    await manager.startCompact("session-1");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(lastActive("session-1")).toBe(at(3));
    // A session with no activity keeps its creation stamp.
    expect(lastActive("session-other")).toBe("2026-07-07T00:00:00.000Z");
  });

  it("a failing last-active write cannot strand a run: idle is still published and queued follow-ups still start", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const logs: string[] = [];
    const recordedErrors: ErrorRecordArgs[] = [];
    const manager = new SessionManager({
      sessions: brokenTouchRepo(sessions),
      channels,
      sources,
      loader: loaderOf(approvalFakeSession("session-1")),
      recorder: { record: async () => {} },
      errors: { record: (args) => recordedErrors.push(args) },
      log: (line) => logs.push(line),
    });
    const events = capture("session-1");
    await manager.startTask("session-1", [userText("hello")]);
    // Queue a follow-up while the first run is in flight: its auto-start lives in the same
    // finally, AFTER the stamp — a throw there would stall it forever.
    await manager.startTask("session-1", [userText("second")], { queueIfBusy: true });
    await waitFor(() => manager.statusOf("session-1") === "idle" && logs.length >= 4);
    const states = serverEvents(events)
      .filter((e) => e.type === "task_state")
      .map((s) => s.state);
    // Two runs reached their wrap-up — the queued one only ever starts from inside the
    // finally, after the failing write — and the session ends up idle, not stuck running.
    expect(states.filter((s) => s === "idle")).toHaveLength(2);
    expect(states.at(-1)).toBe("idle");
    expect(manager.pendingFollowUpCount("session-1")).toBe(0);
    // The failure is reported, not silent.
    expect(logs.some((l) => l.includes("last-active bookkeeping failed"))).toBe(true);
    expect(recordedErrors.map((e) => e.code)).toContain("session_touch_failed");
  });

  it("startTask carries no thinking level: the manager assigns runtime state instead", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const runOpts: Record<string, unknown>[] = [];
    const fake: RuntimeSession = fakeSession("session-1", {
      thinkingLevel: undefined,
      async *run(_input: OmniMessage[], opts: Record<string, unknown>) {
        runOpts.push(opts);
        yield assistantText("ok");
      },
    });
    const manager = makeManager(loaderOf(fake));
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle" && runOpts.length === 1);
    expect("thinkingLevel" in runOpts[0]!).toBe(false);
    // What the Web App's in-chat picker writes reaches the loaded runtime as a plain
    // assignment (core applies it from the next request); a Session that is not loaded is a
    // no-op — the loader assigns the row's level when it loads.
    manager.setThinkingLevel("session-1", "xhigh");
    manager.setThinkingLevel("session-nowhere", "low");
    expect(fake.thinkingLevel).toBe("xhigh");
  });

  it("setThinkingLevel reaches a live child session through its parent's runtime", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const childPins: [string, string][] = [];
    const fake: RuntimeSession = {
      ...approvalFakeSession("session-1"),
      setBackgroundSubagentThinkingLevel: (childSessionId, level) => {
        if (childSessionId !== "child-1") return false;
        childPins.push([childSessionId, level]);
        return true;
      },
    };
    const manager = makeManager(loaderOf(fake));
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    // A child has an index row and a panel picker of its own but no entry: the PATCH lands
    // on the child Session inside the parent runtime. An unknown id stays a no-op.
    manager.setThinkingLevel("child-1", "high");
    manager.setThinkingLevel("child-nowhere", "low");
    expect(childPins).toEqual([["child-1", "high"]]);
  });

  it("a thinking-level PATCH racing the runtime load reaches the loaded runtime", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const fake: RuntimeSession = { ...approvalFakeSession("session-1"), thinkingLevel: undefined };
    let release!: () => void;
    const gate = new Promise<void>((r) => (release = r));
    // The loader applies the row it was handed — a snapshot taken before the await.
    const loader: SessionLoader = {
      load: async (row) => {
        await gate;
        if (row.thinkingLevel) fake.thinkingLevel = row.thinkingLevel;
        return fake;
      },
    };
    const manager = makeManager(loader);
    const started = manager.startTask("session-1", [userText("a")]);
    // The PATCH route's two writes land while the load is in flight: the row updates, the
    // runtime assignment finds no entry yet.
    sessions.updateThinkingLevel("session-1", "xhigh");
    manager.setThinkingLevel("session-1", "xhigh");
    release();
    await started;
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(fake.thinkingLevel).toBe("xhigh");
  });

  it("a background notice arriving while idle auto-starts a task carrying the taken notices", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    let noticeCb: (() => void) | null = null;
    const queue: OmniMessage[] = [];
    const runInputs: OmniMessage[][] = [];
    const fake: RuntimeSession = fakeSession("session-1", {
      onBackgroundNotice: (cb) => (noticeCb = cb),
      takeBackgroundNotices: () => queue.splice(0),
      async *run(input: OmniMessage[]) {
        runInputs.push(input);
        yield assistantText("ok");
      },
    });
    const manager = makeManager(loaderOf(fake));
    // First task loads the entry (which registers the notice listener) and finishes.
    await manager.startTask("session-1", [userText("hi")]);
    await waitFor(() => manager.statusOf("session-1") === "idle" && runInputs.length === 1);
    expect(noticeCb).not.toBeNull();

    // A completion notice lands while idle: the manager takes the queue and starts a task with it.
    const events = capture("session-1");
    const notice = userText("[background_task_done]\nkind: command\n[/background_task_done]");
    queue.push(notice);
    noticeCb!();
    await waitFor(() => manager.statusOf("session-1") === "idle" && runInputs.length === 2);
    expect(runInputs[1]).toEqual([notice]);
    expect(queue).toHaveLength(0);
    // The notice input was published to subscribers like any task input.
    expect(events.some((e) => e.data.includes("background_task_done"))).toBe(true);

    // An empty queue signal is a no-op (no phantom task).
    noticeCb!();
    await new Promise((r) => setTimeout(r, 50));
    expect(runInputs).toHaveLength(2);
  });

  it("live-forwarded background-subagent messages publish to the channel and record usage", async () => {
    let forward: ((msg: OmniMessage) => void) | null = null;
    const fake: RuntimeSession = fakeSession("session-1", {
      onBackgroundMessage: (cb) => (forward = cb),
      async *run() {},
    });
    const manager = makeManager(loaderOf(fake));
    manager.adopt(sessions.findById("session-1")!, fake);
    expect(forward).not.toBeNull();
    const events = capture("session-1");
    const child = withOrigin(assistantText("child progress"), "session-child-1");
    forward!(child);
    expect(events.some((e) => e.data.includes("child progress"))).toBe(true);
    // Usage recording rode along (same recorder drive uses).
    expect(recorded).toContain(child);
  });

  it("adopt registers the notice listener too (a freshly created session, no loader involved)", async () => {
    // Regression guard: POST /sessions enters the active table through adopt, not
    // ensureEntry — a listener registered only on the loader path left brand-new sessions
    // unable to deliver idle-arrival completion reports (the real-app no-notification bug).
    sessions.updateApprovalMode("session-1", "allow-all");
    let noticeCb: (() => void) | null = null;
    const queue: OmniMessage[] = [];
    const runInputs: OmniMessage[][] = [];
    const fake: RuntimeSession = fakeSession("session-1", {
      onBackgroundNotice: (cb) => (noticeCb = cb),
      takeBackgroundNotices: () => queue.splice(0),
      async *run(input: OmniMessage[]) {
        runInputs.push(input);
        yield assistantText("ok");
      },
    });
    const manager = makeManager(loaderOf(fake));
    const row = sessions.findById("session-1")!;
    manager.adopt(row, fake);
    expect(noticeCb).not.toBeNull();
    queue.push(userText("[background_task_done]\nkind: command\n[/background_task_done]"));
    noticeCb!();
    await waitFor(() => manager.statusOf("session-1") === "idle" && runInputs.length === 1);
    expect(queue).toHaveLength(0);
  });

  it("end-to-end: a run_in_background command finishing after idle reaches the event channel as a harness user message", async () => {
    // Full production chain with the REAL core pieces — Session, engine, Environment and an
    // actual OS process — under the real SessionManager (loaded via the loader, which is
    // what registers the notice listener). Only the LLM is scripted. This is the frontend's
    // exact feed: the channel events asserted on are what SSE relays byte-for-byte.
    sessions.updateApprovalMode("session-1", "allow-all");
    const dir = await mkdtemp(path.join(tmpdir(), "penguin-bge2e-"));
    const environment = new Environment({
      workspaceDir: dir,
      toolConfig: {
        customTools: [
          {
            name: "exec_command",
            description: "run",
            permission: "rw",
            timeoutMs: 120000,
            maxOutputLength: 16000,
          },
        ],
        mcpServers: [],
      },
    });
    // Turn 1: launch a command that outlives the task; turn 2: final reply (task ends,
    // session idle, process still running); turn 3 is the auto-started notice task. The
    // command waits for a file the test writes once the Session is idle, so "finishing after
    // idle" is an ordering the test makes rather than a race against a sleep.
    const llm = new (class implements LLMInterface {
      calls = 0;
      inputs: OmniMessage[][] = [];
      async *streamGenerate(
        params: GenerativeModelParameters,
      ): AsyncGenerator<OmniMessage, LLMOutcome> {
        this.calls += 1;
        this.inputs.push(params.newMessages);
        if (this.calls === 1) {
          yield toolCall({
            name: "exec_command",
            arguments: JSON.stringify({
              cmd: "printf 'serving'; while [ ! -f release ]; do sleep 0.05; done",
              run_in_background: true,
            }),
            toolCallId: "tc_bg",
            stopReason: "completed",
          });
        } else {
          yield assistantText(`reply ${this.calls}`);
        }
        yield tokenUsage(emptyTokenCounts(), {
          cache_read: 0,
          cache_write: 0,
          output: 1,
          total: 2,
        });
        return { status: "completed" };
      }
    })();
    const session = new Session({
      meta: {
        session_id: "session-1",
        provider: "custom",
        model_id: "m1",
        model_context_window: 100000,
        system_prompt: "sp",
        agent_state: dir,
        workspace: dir,
        source: "user",
      },
      bootstrap: async () => ({ llm }),
      environment,
      imagesDir: path.join(dir, "images"),
      modelHasVision: true,
    });
    try {
      const manager = makeManager(loaderOf(session as unknown as RuntimeSession));
      const events = capture("session-1");
      await manager.startTask("session-1", [userText("start a dev server")]);
      await waitFor(() => manager.statusOf("session-1") === "idle" && llm.calls === 2, 5000);
      // The task is over, the background process is still alive, and no notice exists yet —
      // what follows is genuinely the idle-arrival path.
      expect(events.some((e) => e.data.includes("background_task_done"))).toBe(false);

      // Let the command finish: its completion report must land on the channel as a harness
      // user message and auto-start a task the model answers.
      await writeFile(path.join(dir, "release"), "");
      await waitFor(() => events.some((e) => e.data.includes("background_task_done")), 8000);
      const notice = events.find((e) => e.data.includes("background_task_done"))!;
      expect(notice.data).toContain('"sender":"harness"');
      expect(notice.data).toContain('"role":"user"');
      expect(notice.data).toContain("serving");
      await waitFor(() => llm.calls === 3 && manager.statusOf("session-1") === "idle", 5000);
      const turn3 = llm.inputs[2]!.map((m) => (m.payload as { text?: string }).text ?? "");
      expect(turn3.join("\n")).toContain("[background_task_done]");
      // The auto task's state flips were broadcast too (the frontend's input gating):
      // one running per task, so the notice task makes it at least two.
      const running = events.filter(
        (e) => e.data.includes('"type":"task_state"') && e.data.includes('"state":"running"'),
      );
      expect(running.length).toBeGreaterThan(1);
    } finally {
      session.dispose();
      await rm(dir, { recursive: true, force: true });
    }
  });

  it("LLM / tool failures in the message stream are persisted via drive (source=llm / environment, with the current Session context)", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const captured: ErrorRecordArgs[] = [];
    // core folds LLM / tool failures into the message stream (no throw): a tool
    // failure produces one tool_call_output(failed), an LLM failure produces one
    // request_end(failed) + an abort carrying the real reason.
    const failing: RuntimeSession = fakeSession("session-1", {
      async *run(): AsyncGenerator<OmniMessage> {
        yield requestBegin();
        yield toolCall({ name: "write_file", arguments: "{}", toolCallId: "tc-1" });
        yield toolCallOutput({
          output: "ls: /nope\n[tool error] exit code 2",
          toolCallId: "tc-1",
          stopReason: "fatal",
        });
        // The ladder's terminal failure: no retry planned (no retry_in_ms), the run ends
        // on this record — no abort event follows.
        yield requestEnd("retryable", {
          attempt: 6,
          errorCode: "network",
          errorMessage: "500 upstream",
        });
      },
    });
    const manager = makeManager(loaderOf(failing), { record: (args) => captured.push(args) });
    await manager.startTask("session-1", [userText("run")]);
    await waitFor(() => manager.statusOf("session-1") === "idle" && captured.length >= 2);

    expect(captured.map((a) => [a.source, a.code, a.kind])).toEqual([
      ["environment", "tool_fatal:write_file", "expected"], // error fed back to the model; the Agent adjusts on its own
      ["llm", "llm_failed", "unexpected"], // nothing followed it: the retries did not recover it, so a human is needed
    ]);
    expect(captured[0]!.ctx).toEqual({ projectId: "p1", agentId: "a1", sessionId: "session-1" });
    expect(String(captured[0]!.err)).toContain("[tool error] exit code 2");
    expect(String(captured[1]!.err)).toBe("llm request failed after 5 retries: 500 upstream");
  });

  it("mutual exclusion: startTask again while running → 409 task_in_progress; compact → 409", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    const again = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((again as { status: number; code: string }).status).toBe(409);
    expect((again as { code: string }).code).toBe("task_in_progress");
    const compact = await manager.startCompact("session-1").catch((e: unknown) => e);
    expect((compact as { status: number }).status).toBe(409);

    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => manager.statusOf("session-1") === "idle");
  });

  it("compact refusal: each reason gets its own error code, not one shared code", async () => {
    // Clients localize by code (the Web looks it up in a table and falls back to the raw
    // English message), so the three reasons cannot share one code: that forces either a
    // single vague sentence for all three, or untranslated English in a non-English UI.
    const cases = [
      ["unsupported", "compaction_not_configured"],
      ["empty", "nothing_to_compact"],
      ["just_compacted", "already_compacted"],
    ] as const;

    for (const [why, code] of cases) {
      const session: RuntimeSession = {
        ...approvalFakeSession("session-1"),
        compactability: () => why,
      };
      const manager = makeManager(loaderOf(session));
      const err = await manager.startCompact("session-1").catch((e: unknown) => e);
      expect((err as { status: number }).status).toBe(409);
      expect((err as { code: string }).code).toBe(code);
      // The message still names the reason, for a client that has not mapped the code.
      expect((err as { message: string }).message).not.toBe("");
    }
  });

  it("steer: forwards to the running session; idle / lost race → 409 not_running", async () => {
    const steered: string[] = [];
    const fake = approvalFakeSession("session-1");
    fake.steer = (input: OmniMessage[]) => {
      steered.push((input[0]!.payload as TextPayload).text);
      return true;
    };
    const manager = makeManager(loaderOf(fake));
    const steerErr = (text: string): unknown => {
      try {
        manager.steer("session-1", [userText(text)], { text, images: [], videos: [], files: [] });
        return null;
      } catch (e) {
        return e;
      }
    };

    // Not running (entry not even loaded): 409 not_running (typed like task_in_progress).
    const before = steerErr("early") as HttpError;
    expect(before.status).toBe(409);
    expect(before.code).toBe("not_running");

    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    // Running: forwarded to the core session (no SSE event of its own).
    expect(steerErr("focus on tests")).toBeNull();
    expect(steered).toEqual(["focus on tests"]);

    // The core session lost the race (its run just finished): also 409, so the
    // caller falls back to a normal task.
    fake.steer = () => false;
    expect((steerErr("late") as HttpError).code).toBe("not_running");

    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    // Idle again after the run: 409.
    expect((steerErr("post") as HttpError).code).toBe("not_running");
  });

  it("pendingSteering mirror: broadcast with task_state on steer, shifted at delivery, dropped at run end", async () => {
    // Two approval parks, with core's delivery shape — one `[user_steering]` user text —
    // yielded between them, so the mid-run shift is observable while the run keeps going.
    const fake: RuntimeSession = {
      ...approvalFakeSession("session-1"),
      steer: () => true,
      async *run(_input: OmniMessage[], opts: { approve: ApproveFn; signal: AbortSignal }) {
        const tc1 = toolCall({ name: "write_file", arguments: "{}", toolCallId: "tc-1" });
        yield tc1;
        yield approvalDecision(await opts.approve(tc1), "tc-1");
        yield userText(userSteeringText("focus on tests"));
        const tc2 = toolCall({ name: "write_file", arguments: "{}", toolCallId: "tc-2" });
        yield tc2;
        yield approvalDecision(await opts.approve(tc2), "tc-2");
        yield assistantText("done");
      },
    };
    const manager = makeManager(loaderOf(fake));
    const events = capture("session-1");
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    // Two queued steering messages: the mirror keeps both, in queue order.
    manager.steer("session-1", [userText("a")], {
      text: "focus on tests",
      images: [],
      videos: [],
      files: [],
    });
    manager.steer("session-1", [userText("b")], {
      text: "later",
      images: ["data:image/png;base64,aa"],
      videos: [],
      files: [
        { fileName: "a.txt", path: "/tmp/a.txt", mime: "text/plain" },
        { fileName: "b.txt", path: "/tmp/b.txt", mime: "text/plain" },
      ],
    });
    expect(manager.pendingSteeringOf("session-1")).toEqual([
      { id: expect.any(String), text: "focus on tests", images: 0, videos: 0, files: 0 },
      { id: expect.any(String), text: "later", images: 1, videos: 0, files: 2 },
    ]);

    // First delivery observed on the stream: the mirror shifts while the run is still going.
    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => manager.pendingSteeringOf("session-1").length === 1);
    expect(manager.statusOf("session-1")).toBe("running");
    expect(manager.pendingSteeringOf("session-1")).toEqual([
      { id: expect.any(String), text: "later", images: 1, videos: 0, files: 2 },
    ]);

    // Run end: core discards undelivered steering, and the mirror goes with it.
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    manager.decideApproval("session-1", "tc-2", "allow");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(manager.pendingSteeringOf("session-1")).toEqual([]);

    // task_state broadcasts traced the whole lifecycle: grow to 1, 2, shift to 1, gone at idle.
    const states = serverEvents(events).filter((e) => e.type === "task_state");
    const mirrored = states
      .filter((e) => e.pendingSteering !== undefined)
      .map((e) => (e.pendingSteering as unknown[]).length);
    expect(mirrored).toEqual([1, 2, 1]);
    const last = states[states.length - 1]!;
    expect(last.state).toBe("idle");
    expect(last.pendingSteering).toBeUndefined();
  });

  it("queueIfBusy: enqueues while running, auto-starts in order after each finish; abort keeps the queue", async () => {
    sessions.updateApprovalMode("session-1", "always-ask");
    const runInputs: string[][] = [];
    const fake = approvalFakeSession("session-1");
    const origRun = fake.run.bind(fake);
    fake.run = function (input: OmniMessage[], opts: { approve: ApproveFn; signal: AbortSignal }) {
      runInputs.push(input.map((m) => (m.payload as { text?: string }).text ?? ""));
      return origRun(input, opts);
    };
    const manager = makeManager(loaderOf(fake));
    const events = capture("session-1");

    const first = await manager.startTask("session-1", [userText("task 1")]);
    expect(first.queued).toBe(false);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    // Busy + queueIfBusy: held server-side instead of 409 (order preserved); without the
    // flag the 409 mutual exclusion is unchanged.
    const q1 = await manager.startTask("session-1", [userText("follow-up 1")], {
      queueIfBusy: true,
    });
    const q2 = await manager.startTask("session-1", [userText("follow-up 2")], {
      queueIfBusy: true,
    });
    expect([q1.queued, q2.queued]).toEqual([true, true]);
    expect(manager.pendingFollowUpCount("session-1")).toBe(2);
    const conflict = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((conflict as HttpError).code).toBe("task_in_progress");

    // Abort the running task: queued follow-ups are future tasks — NOT discarded; the next
    // one auto-starts as an ordinary task once the aborted run settles.
    manager.abortTask("session-1");
    await waitFor(() => runInputs.length === 2);
    expect(runInputs[1]).toEqual(["follow-up 1"]);
    expect(manager.pendingFollowUpCount("session-1")).toBe(1);

    // Finishing each run starts the next queued input, in order, one at a time.
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => runInputs.length === 3);
    expect(runInputs[2]).toEqual(["follow-up 2"]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(
      () =>
        manager.statusOf("session-1") === "idle" && manager.pendingFollowUpCount("session-1") === 0,
    );

    // task_state events report the queued count (for the input area's "N queued" hint).
    const states = serverEvents(events).filter((e) => e.type === "task_state");
    expect(states.some((s) => s.queued === 2)).toBe(true);
    expect(states[states.length - 1]).toMatchObject({ state: "idle", queued: 0 });
  });

  it("queueIfBusy: a full queue refuses with 429 instead of growing without bound", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const first = await manager.startTask("session-1", [userText("task 1")]);
    expect(first.queued).toBe(false);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    // Fill the queue to the cap; every entry still queues as before.
    for (let i = 0; i < FOLLOW_UP_QUEUE_LIMIT; i++) {
      const q = await manager.startTask("session-1", [userText(`follow-up ${i}`)], {
        queueIfBusy: true,
      });
      expect(q.queued).toBe(true);
    }
    expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);

    // The next one is refused loudly — not queued, not started, nothing dropped silently.
    const err = await manager
      .startTask("session-1", [userText("overflow")], { queueIfBusy: true })
      .catch((e: unknown) => e);
    expect((err as HttpError).status).toBe(429);
    expect((err as HttpError).code).toBe("queue_full");
    expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);
    // Without queueIfBusy the 409 mutual exclusion is unchanged.
    const conflict = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((conflict as HttpError).code).toBe("task_in_progress");

    // Draining one frees a slot for exactly one more.
    manager.abortTask("session-1");
    await waitFor(() => manager.pendingFollowUpCount("session-1") === FOLLOW_UP_QUEUE_LIMIT - 1);
    const refill = await manager.startTask("session-1", [userText("refill")], {
      queueIfBusy: true,
    });
    expect(refill.queued).toBe(true);
    expect(manager.pendingFollowUpCount("session-1")).toBe(FOLLOW_UP_QUEUE_LIMIT);
  });

  it("queueIfBusy during compaction: the queue drains once the compaction ends", async () => {
    const runInputs: string[][] = [];
    let releaseCompact: (() => void) | null = null;
    const fake: RuntimeSession = fakeSession("session-1", {
      // eslint-disable-next-line require-yield
      async *run(input: OmniMessage[]): AsyncGenerator<OmniMessage> {
        runInputs.push(input.map((m) => (m.payload as { text?: string }).text ?? ""));
      },
      async *compact(): AsyncGenerator<OmniMessage> {
        await new Promise<void>((resolve) => {
          releaseCompact = resolve;
        });
        yield compactionBegin({ reason: "manual", mode: "summarize", context: 1, turns: 1 });
        yield compactionEnd({ reason: "manual", mode: "summarize", status: "completed" });
      },
    });
    const manager = makeManager(loaderOf(fake));
    await manager.startCompact("session-1");
    await waitFor(() => releaseCompact !== null);

    const q = await manager.startTask("session-1", [userText("after compact")], {
      queueIfBusy: true,
    });
    expect(q.queued).toBe(true);
    expect(manager.pendingFollowUpCount("session-1")).toBe(1);

    releaseCompact!();
    await waitFor(() => runInputs.length === 1 && manager.pendingFollowUpCount("session-1") === 0);
    expect(runInputs[0]).toEqual(["after compact"]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
  });

  it("always-ask: registers a pending approval and pushes approval_request; continues after the decision", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const events = capture("session-1");
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    const requests = serverEvents(events).filter((e) => e.type === "approval_request");
    expect(requests).toHaveLength(1);
    expect(
      (requests[0]!.toolCall as { payload: { tool_call_id: string } }).payload.tool_call_id,
    ).toBe("tc-1");
    expect(manager.pendingApprovals("session-1")).toHaveLength(1);

    expect(manager.decideApproval("session-1", "tc-404", "allow")).toBe(false);
    expect(manager.decideApproval("session-1", "tc-1", "allow")).toBe(true);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(manager.pendingApprovalCount("session-1")).toBe(0);
    const texts = recorded
      .filter((m) => (m.payload as { type?: string }).type === "text")
      .map((m) => (m.payload as { text: string }).text);
    expect(texts).toContain("decision=allow");
  });

  it("deny-all / read-only decide automatically (no human handoff)", async () => {
    sessions.updateApprovalMode("session-1", "deny-all");
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(
      recorded.some(
        (m) =>
          (m.payload as { type?: string; decision?: string }).type === "approval_decision" &&
          (m.payload as { decision: string }).decision === "deny",
      ),
    ).toBe(true);

    // read-only: read-only tools are auto-approved.
    recorded = [];
    sessions.updateApprovalMode("session-1", "read-only");
    const manager2 = makeManager(loaderOf(approvalFakeSession("session-1", "read_tool")));
    await manager2.startTask("session-1", [userText("go")]);
    await waitFor(() => manager2.statusOf("session-1") === "idle");
    expect(recorded.some((m) => (m.payload as { text?: string }).text === "decision=allow")).toBe(
      true,
    );
  });

  it("an organization's session denies a call its mode would hand to a person, at once", async () => {
    // A desk or ticket session as the organization runtime opens it: the organization's
    // approval mode on the row, stamped `client: "org"`. Nobody is watching it.
    sessions.insert({
      ...ROW,
      sessionId: "session-org",
      approvalMode: "read-only",
      client: "org",
    });
    const manager = makeManager(loaderOf(approvalFakeSession("session-org")));
    const events = capture("session-org");
    await manager.startTask("session-org", [userText("go")]);
    // No decision is ever submitted here: the run settles on its own and ends normally.
    await waitFor(() => manager.statusOf("session-org") === "idle");
    expect(manager.pendingApprovalCount("session-org")).toBe(0);
    expect(serverEvents(events).filter((e) => e.type === "approval_request")).toEqual([]);
    expect(recorded.some((m) => (m.payload as { text?: string }).text === "decision=deny")).toBe(
      true,
    );

    // Only that one route changed: a read-only tool is still auto-approved there.
    recorded = [];
    const manager2 = makeManager(loaderOf(approvalFakeSession("session-org", "read_tool")));
    await manager2.startTask("session-org", [userText("go")]);
    await waitFor(() => manager2.statusOf("session-org") === "idle");
    expect(recorded.some((m) => (m.payload as { text?: string }).text === "decision=allow")).toBe(
      true,
    );
  });

  it("a development session under the same mode still waits for the person", async () => {
    // Same approval mode, same tool — the row carries no organization stamp.
    sessions.updateApprovalMode("session-1", "read-only");
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const events = capture("session-1");
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    expect(serverEvents(events).filter((e) => e.type === "approval_request")).toHaveLength(1);
    // Still parked on the question: no decision was made for it.
    expect(manager.statusOf("session-1")).toBe("running");
    expect(
      recorded.some((m) => (m.payload as { type?: string }).type === "approval_decision"),
    ).toBe(false);

    // Answer it, so the run finishes rather than hanging.
    expect(manager.decideApproval("session-1", "tc-1", "deny")).toBe(true);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(recorded.some((m) => (m.payload as { text?: string }).text === "decision=deny")).toBe(
      true,
    );
  });

  it("a sub-session registered under an organization's Session inherits its org stamp; one under an ordinary Session stays unmarked", async () => {
    // A desk session: the organization runtime stamped it at creation.
    sessions.insert({ ...ROW, sessionId: "session-org", client: "org" });
    const spawning = (sessionId: string, childId: string): RuntimeSession =>
      fakeSession(sessionId, {
        async *run() {
          yield withOrigin(
            sessionMeta({
              session_id: childId,
              model_id: "m-child",
              provider: "custom",
              model_context_window: 1000,
              system_prompt: "sys",
              agent_state: "/root/p1/child_agent/agent_state",
              workspace: "/tmp/w-child",
              source: "subagent",
            }),
            childId,
          );
          yield withOrigin(assistantText("child done"), childId);
          yield assistantText("done");
        },
      });
    const manager = makeManager({
      load: async (row) =>
        spawning(row.sessionId, row.sessionId === "session-org" ? "child-org" : "child-plain"),
    });
    await manager.startTask("session-org", [userText("go")]);
    await waitFor(() => manager.statusOf("session-org") === "idle");
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    // The child is company mode's own as much as the desk that spawned it: development
    // mode's list reads the stamp, and no organization cache ever names a sub-session.
    expect(sessions.findById("child-org")?.client).toBe("org");
    // An ordinary Session's child keeps the registration path's blank marker (read as web).
    expect(sessions.findById("child-plain")?.client).toBeNull();
  });

  it("sub-session (origin) registration: session_meta persists; the title is generated from the spawning prompt", async () => {
    const fake: RuntimeSession = fakeSession("session-1", {
      async *run() {
        // The parent-level run_subagent call (no origin): its prompt becomes the sub-session title.
        yield toolCall({
          name: "run_subagent",
          arguments: JSON.stringify({ prompt: "Research the background of this question" }),
          toolCallId: "sub-1",
        });
        const hop = "child-1";
        yield withOrigin(
          sessionMeta({
            session_id: "child-1",
            model_id: "m-child",
            provider: "custom",
            model_context_window: 1000,
            system_prompt: "sys",
            agent_state: "/root/p1/child_agent/agent_state",
            workspace: "/tmp/w-child",
            source: "subagent",
          }),
          hop,
        );
        yield withOrigin(assistantText("child done"), hop);
        yield assistantText("done");
      },
    });
    const notified: Array<{ ctx: UsageContext; req: TitleRequest }> = [];
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(fake),
      recorder: { record: async () => {} },
      titles: {
        maybeGenerate: (ctx, _session, req) => notified.push({ ctx, req }),
      },
      log: () => {},
    });
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    const child = sessions.findById("child-1");
    expect(child).not.toBeNull();
    expect(child?.agentId).toBe("child_agent");
    expect(child?.modelId).toBe("m-child");
    expect(child?.workspace).toBe("/tmp/w-child");
    // The source lands in the in-process registry (session_meta is the single source of
    // truth; the row stores no source column).
    expect(sources.get("child-1")).toBe("subagent");
    expect(child && "source" in child).toBe(false);
    // The row itself is inserted with a blank title: the title generator (faked here) is
    // notified at registration and owns the write.
    expect(child?.title).toBeNull();

    await waitFor(() => notified.length === 2);
    const childTitle = notified.find((n) => n.ctx.sessionId === "child-1");
    expect(childTitle).toBeTruthy();
    // Explicit material override for the sub-session: the prompt that spawned it, alone — its own output is never waited for.
    expect(childTitle!.req.material).toEqual({
      userText: "Research the background of this question",
      assistantText: "",
    });
    expect(childTitle!.req.fallbackText).toBe("Research the background of this question");
    // Session/Agent record the sub-session, but modelId records the parent — the request runs on the parent's bare LLM.
    expect(childTitle!.ctx).toMatchObject({ agentId: "child_agent", modelId: "m1" });
    // The sub-session has no SSE channel of its own: title events are delivered over the parent session's channel.
    expect(childTitle!.req.notifyOn).toBe("session-1");
  });

  it("approval mode takes effect immediately: after a mid-run PATCH, the next decision uses the new mode", async () => {
    // A fake Session that requests approval twice.
    const fake: RuntimeSession = fakeSession("session-1", {
      async *run(_input, opts) {
        const tc1 = toolCall({ name: "t1", arguments: "{}", toolCallId: "tc-1" });
        yield tc1;
        yield approvalDecision(await opts.approve(tc1), "tc-1");
        const tc2 = toolCall({ name: "t2", arguments: "{}", toolCallId: "tc-2" });
        yield tc2;
        yield approvalDecision(await opts.approve(tc2), "tc-2");
      },
    });
    const manager = makeManager(loaderOf(fake));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    // Switch to allow-all while the first request is pending human review: the second no longer needs one.
    sessions.updateApprovalMode("session-1", "allow-all");
    manager.decideApproval("session-1", "tc-1", "deny");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    const decisions = recorded
      .filter((m) => (m.payload as { type?: string }).type === "approval_decision")
      .map((m) => (m.payload as { decision: string }).decision);
    expect(decisions).toEqual(["deny", "allow"]);
    expect(manager.pendingApprovalCount("session-1")).toBe(0);
  });

  it("abort: pending approvals collapse to deny before the AbortSignal fires", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    expect(manager.abortTask("session-1")).toBe(false); // no Task in progress → no-op
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    expect(manager.abortTask("session-1")).toBe(true);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    const payloads = recorded.map((m) => m.payload as { type?: string; decision?: string });
    expect(payloads.some((p) => p.type === "approval_decision" && p.decision === "deny")).toBe(
      true,
    );
    expect(payloads.some((p) => p.type === "abort")).toBe(true);
  });

  it("beginSessionDeletion: interrupts active runs, clears the active table and marks deleting (new Tasks 409); recovers after end", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    expect(manager.beginSessionDeletion("session-1")).toEqual([]); // no active entry
    // While deletion is in progress: a new Task is rejected with 409 (prevents resurrection).
    const rejected = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((rejected as { status?: number }).status).toBe(409);
    manager.endSessionDeletion("session-1");
    // Runs normally once the deletion flag is cleared.
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    const runnings = manager.beginSessionDeletion("session-1");
    expect(runnings.length).toBe(1);
    await Promise.allSettled(runnings);
    expect(manager.statusOf("session-1")).toBe("idle"); // entry has been removed
    manager.endSessionDeletion("session-1");
  });

  it("self-heal: when the loader returns a new session_id, the index primary key is updated and the actual current id returned", async () => {
    sessions.updateApprovalMode("session-1", "allow-all");
    const manager = makeManager(loaderOf(approvalFakeSession("session-2-healed")));
    const { sessionId } = await manager.startTask("session-1", [userText("go")]);
    expect(sessionId).toBe("session-2-healed");
    expect(sessions.findById("session-1")).toBeNull();
    expect(sessions.findById("session-2-healed")).not.toBeNull();
    await waitFor(() => manager.statusOf("session-2-healed") === "idle");
    // Usage is attributed under the new id.
    expect(recordedCtx[0]!.sessionId).toBe("session-2-healed");
  });

  it("load reconciles the row's model with the runtime's: a Session that switched and crashed before the row update resumes on the new model, and the row follows", async () => {
    // The Trace is the durable record of a switch (the file it opens is headed by the new
    // context's session_meta); the row is a cache of it that a crash in between leaves stale.
    // The loader resumes on the Trace's model, so what it reports wins — for the entry (usage
    // attribution) and for the row (what GET /sessions/:id shows).
    sessions.updateApprovalMode("session-1", "allow-all");
    const resumed: RuntimeSession = {
      ...approvalFakeSession("session-1"),
      provider: "other",
      modelId: "m-switched",
    };
    const manager = makeManager(loaderOf(resumed));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.statusOf("session-1") === "idle" && recorded.length >= 3);
    expect(sessions.findById("session-1")).toMatchObject({
      provider: "other",
      modelId: "m-switched",
    });
    expect(recordedCtx[0]).toMatchObject({ provider: "other", modelId: "m-switched" });

    // A runtime that reports no model (test fakes) keeps the row's pair.
    db.close();
    db = openDatabase(":memory:");
    sessions = wire(SessionsRepo, { db });
    sessions.insert({ ...ROW, approvalMode: "allow-all" });
    recordedCtx = [];
    const plain = makeManager(loaderOf(approvalFakeSession("session-1")));
    await plain.startTask("session-1", [userText("go")]);
    await waitFor(() => plain.statusOf("session-1") === "idle" && recordedCtx.length >= 1);
    expect(sessions.findById("session-1")).toMatchObject({ provider: "custom", modelId: "m1" });
    expect(recordedCtx[0]).toMatchObject({ provider: "custom", modelId: "m1" });
  });

  it("after the channel is swept and rebuilt, drive still sends to the current channel (re-get before every publish)", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    // No subscribers, no publish while waiting for approval: simulate idle sweeping removing the old channel.
    channels.sweep(Date.now() + 60 * 60 * 1000);
    // Reconnect: hub.get creates a brand-new channel, and we subscribe to it.
    const events = capture("session-1");
    manager.decideApproval("session-1", "tc-1", "allow");
    await waitFor(() => manager.statusOf("session-1") === "idle");

    // The remaining output and task_state after approval must land on the new channel (the old reference should already be stale).
    const texts = events
      .filter((e) => e.event === undefined)
      .map((e) => (JSON.parse(e.data) as { payload: { type?: string; text?: string } }).payload)
      .filter((p) => p.type === "text")
      .map((p) => p.text);
    expect(texts).toContain("decision=allow");
    const states = serverEvents(events).filter((e) => e.type === "task_state");
    expect(states.map((s) => s.state)).toContain("idle");
  });

  it("abortProject: returns the in-flight drive Promises; wrap-up completes after awaiting them", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    expect(manager.abortProject("p1")).toEqual([]); // no active runs → empty array
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    const runnings = manager.abortProject("p1");
    expect(runnings).toHaveLength(1);
    await Promise.allSettled(runnings);
    // Wrap-up complete: the abort cleanup (abort event) has been written, and the entry has been removed from the active table.
    expect(recorded.some((m) => (m.payload as { type?: string }).type === "abort")).toBe(true);
    expect(manager.statusOf("session-1")).toBe("idle");
  });

  it("loader throwing HttpError (e.g. workspace_missing 409) → passed through as-is, not re-wrapped", async () => {
    const loader: SessionLoader = {
      load: async () => {
        throw new HttpError(409, "workspace_missing", "Workspace no longer exists.");
      },
    };
    const manager = makeManager(loader);
    const err = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((err as { status: number; code: string }).status).toBe(409);
    expect((err as { code: string }).code).toBe("workspace_missing");
  });

  it("shutdown disposes each Session's environment, so background commands die with the App", async () => {
    // A hot swap that skipped this would orphan e.g. a dev server the conversation
    // started: the OS process keeps running while the successor's freshly resumed
    // Session starts with an empty process list — the stop control has gone blind.
    const fake = approvalFakeSession("session-1");
    let disposed = 0;
    (fake as { dispose?: () => void }).dispose = () => {
      disposed++;
    };
    const manager = makeManager(loaderOf(fake));
    manager.adopt(ROW, fake);
    await manager.shutdown();
    expect(disposed).toBe(1);
  });

  it("shutdown denies a call parked on a person, lets the run wind down, and disposes after it", async () => {
    // What a hot swap or an exit meets mid-conversation: a run waiting on an approval nobody
    // in this process will ever give.
    const order: string[] = [];
    const fake = parkedRunSession(order);
    const manager = makeManager(loaderOf(fake));
    await manager.startTask("session-1", [userText("write it")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    await manager.shutdown();
    // The environment goes only once the run has let go of it.
    expect(order).toEqual(["decided deny", "aborted true", "run ended", "disposed"]);
  });

  it("shutdown still denies, winds down and disposes once the database has closed", async () => {
    // The approvals count reaches the Project's users through a notifier that reads the
    // database first (who owns and shares the Project). A handle closed under a run that
    // outlived its drain window must not stop the shutdown that denies the call.
    const order: string[] = [];
    const fake = parkedRunSession(order);
    const counts: number[] = [];
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(fake),
      recorder: { record: async () => undefined },
      notifyProjectUsers: (_projectId, event) => {
        sessions.findById(ROW.sessionId); // the audience lookup: a database read
        if (event.type === "session_approvals") counts.push(event.count);
      },
      log: () => {},
    });
    await manager.startTask("session-1", [userText("write it")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    expect(counts).toEqual([1]);

    db.close();
    await manager.shutdown();
    expect(order).toEqual(["decided deny", "aborted true", "run ended", "disposed"]);
  });

  it("rejects new Tasks once shutdown is set (503 shutting_down)", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    await manager.shutdown();
    const err = await manager.startTask("session-1", [userText("x")]).catch((e: unknown) => e);
    expect((err as { status: number; code: string }).status).toBe(503);
    expect((err as { code: string }).code).toBe("shutting_down");
    const compactErr = await manager.startCompact("session-1").catch((e: unknown) => e);
    expect((compactErr as { status: number }).status).toBe(503);
  });

  it("sweepIdle: entries idle past the timeout are evicted (reloaded via the loader on next access)", async () => {
    let loads = 0;
    const loader: SessionLoader = {
      load: async () => {
        loads++;
        return approvalFakeSession("session-1");
      },
    };
    const manager = makeManager(loader);
    manager.adopt(ROW, approvalFakeSession("session-1"));
    // Not evicted before timeout: startTask reuses the active-table entry, bypassing the loader.
    manager.sweepIdle(Date.now() + 1000, 30 * 60 * 1000);
    sessions.updateApprovalMode("session-1", "allow-all");
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(0);

    // Evicted after timeout: once the entry is released, the next startTask reloads it.
    manager.sweepIdle(Date.now() + 31 * 60 * 1000, 30 * 60 * 1000);
    await manager.startTask("session-1", [userText("b")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(1);
  });

  it("invalidateAgentRuntimes: an idle entry is discarded and re-resumed on next access; other Agents unaffected", async () => {
    let loads = 0;
    const loader: SessionLoader = {
      load: async () => {
        loads++;
        return approvalFakeSession("session-1");
      },
    };
    const manager = makeManager(loader);
    sessions.updateApprovalMode("session-1", "allow-all");
    // Adopted after creation: records the current generation, so Tasks reuse it without loading.
    manager.adopt(ROW, approvalFakeSession("session-1"));

    // Another Agent's vault update leaves this entry alone.
    manager.invalidateAgentRuntimes("p1", "other_agent");
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(0);

    // This Agent's vault update: the next Task rebuilds the runtime via the loader.
    manager.invalidateAgentRuntimes("p1", "a1");
    await manager.startTask("session-1", [userText("b")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(1);

    // Rebuilt once only: the fresh entry is current again.
    await manager.startTask("session-1", [userText("c")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(1);
  });

  it("invalidateAgentRuntimes: the discarded runtime's background-task count is published as cleared", async () => {
    // The discard path drops the entry WITHOUT disposing it, so the replacement resumes with
    // empty registries. The counts move without any core ping to carry them: without the
    // publish below, a Session list that had drawn the background-task mark would sit on a
    // count nothing can move again, while a plain list fetch already reports none.
    const withProcess: RuntimeSession = {
      ...approvalFakeSession("session-1"),
      listBackgroundCommands: () => [
        {
          processId: "proc-11111111",
          pid: 4242,
          cmd: "pnpm dev",
          cwd: "/tmp/w",
          startedAt: Date.UTC(2026, 8, 2, 10, 0, 0),
          running: true,
        },
      ],
    };
    const published: ServerEvent[] = [];
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(approvalFakeSession("session-1")),
      recorder: { record: async () => undefined },
      notifyProjectUsers: (_projectId, event) => published.push(event),
      log: () => {},
    });
    sessions.updateApprovalMode("session-1", "allow-all");
    manager.adopt(ROW, withProcess);
    expect(manager.backgroundTasksOf("session-1")).toEqual({ processes: 1, subagents: 0 });

    manager.invalidateAgentRuntimes("p1", "a1");
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");

    expect(published.filter((e) => e.type === "session_background")).toEqual([
      { type: "session_background", sessionId: "session-1", processes: 0, subagents: 0 },
    ]);
    expect(manager.backgroundTasksOf("session-1")).toBeUndefined();
  });

  it("invalidateAgentRuntimes mid-run: the in-flight Task keeps its runtime; the first Task after it finishes re-resumes", async () => {
    let loads = 0;
    const loader: SessionLoader = {
      load: async () => {
        loads++;
        return approvalFakeSession("session-1");
      },
    };
    const manager = makeManager(loader);
    await manager.startTask("session-1", [userText("go")]); // built here: load #1
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);

    manager.invalidateAgentRuntimes("p1", "a1"); // vault updated while the Task waits on approval
    // The pending approval still targets the live entry: the run completes on the old runtime.
    expect(manager.decideApproval("session-1", "tc-1", "allow")).toBe(true);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(1);

    // First Task after it finished: the stale entry is discarded and re-resumed with current values.
    sessions.updateApprovalMode("session-1", "allow-all");
    await manager.startTask("session-1", [userText("next")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(2);
  });

  it("invalidateProjectRuntimes: every cached entry in the Project is rebuilt; other Projects unaffected", async () => {
    // Two Agents with cached runtimes in p1, one in p2 — a models/credential update to p1
    // must reach BOTH of p1's Agents (collected from the active table) and leave p2 alone.
    const rowA2: SessionRow = { ...ROW, sessionId: "session-2", agentId: "a2" };
    const rowP2: SessionRow = { ...ROW, sessionId: "session-3", projectId: "p2" };
    sessions.insert(rowA2);
    sessions.insert(rowP2);
    let loads = 0;
    const loader: SessionLoader = {
      load: async (row) => {
        loads++;
        return approvalFakeSession(row.sessionId);
      },
    };
    const manager = makeManager(loader);
    for (const sid of ["session-1", "session-2", "session-3"]) {
      sessions.updateApprovalMode(sid, "allow-all");
    }
    manager.adopt(ROW, approvalFakeSession("session-1"));
    manager.adopt(rowA2, approvalFakeSession("session-2"));
    manager.adopt(rowP2, approvalFakeSession("session-3"));

    manager.invalidateProjectRuntimes("p1");
    // Both p1 entries are stale and rebuild through the loader on their next Task.
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    await manager.startTask("session-2", [userText("b")]);
    await waitFor(() => manager.statusOf("session-2") === "idle");
    expect(loads).toBe(2);
    // The p2 entry keeps its cached runtime.
    await manager.startTask("session-3", [userText("c")]);
    await waitFor(() => manager.statusOf("session-3") === "idle");
    expect(loads).toBe(2);
  });

  it("sweepIdle: entries that are running / have pending approvals are not evicted", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    await manager.startTask("session-1", [userText("go")]);
    await waitFor(() => manager.pendingApprovalCount("session-1") === 1);
    manager.sweepIdle(Date.now() + 24 * 60 * 60 * 1000, 30 * 60 * 1000);
    // The entry is still there: the approval can be decided and wraps up normally.
    expect(manager.statusOf("session-1")).toBe("running");
    expect(manager.decideApproval("session-1", "tc-1", "allow")).toBe(true);
    await waitFor(() => manager.statusOf("session-1") === "idle");
  });

  it("sweepIdle: a working background subagent pins the entry, and its live messages count as activity", async () => {
    // A run_in_background child outlives the task that launched it. Evicting the entry
    // while it works drops the very Session its completion report is queued on.
    let running = true;
    let loads = 0;
    let forward: ((msg: OmniMessage) => void) | null = null;
    const fake = (): RuntimeSession =>
      fakeSession("session-1", {
        hasRunningBackgroundSubagents: () => running,
        onBackgroundMessage: (cb) => (forward = cb),
        async *run() {},
      });
    const manager = makeManager({
      load: async () => {
        loads++;
        return fake();
      },
    });
    manager.adopt(ROW, fake());
    const long = 31 * 60 * 1000;

    // Far past the idle timeout, but the child is still working: the entry stays.
    manager.sweepIdle(Date.now() + long, 30 * 60 * 1000);
    sessions.updateApprovalMode("session-1", "allow-all");
    await manager.startTask("session-1", [userText("a")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(0);

    // The child streaming is activity in its own right, so the idle clock restarts with it.
    expect(forward).not.toBeNull();
    const before = Date.now();
    forward!(withOrigin(assistantText("child progress"), "session-child-1"));
    manager.sweepIdle(before + long, 30 * 60 * 1000);
    await manager.startTask("session-1", [userText("b")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(0);

    // Once it settles, the entry is an ordinary idle one again and evicts on schedule.
    running = false;
    manager.sweepIdle(Date.now() + long, 30 * 60 * 1000);
    await manager.startTask("session-1", [userText("c")]);
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(loads).toBe(1);
  });

  it("compact: sets compacting, output goes to the channel, returns to idle at the end", async () => {
    const manager = makeManager(loaderOf(approvalFakeSession("session-1")));
    const events = capture("session-1");
    await manager.startCompact("session-1");
    await waitFor(() => manager.statusOf("session-1") === "idle" && recorded.length >= 2);
    const states = serverEvents(events).filter((e) => e.type === "task_state");
    expect(states.map((s) => s.state)).toEqual(["compacting", "idle"]);
    expect(recorded.map((m) => (m.payload as { type: string }).type)).toEqual([
      "compaction_begin",
      "compaction_end",
    ]);
  });

  it("notifies title generation at Task start: fallback and generation material are the user input alone; compaction doesn't notify", async () => {
    const notified: { ctx: UsageContext; session: unknown; req: TitleRequest }[] = [];
    const plainSession: RuntimeSession = fakeSession("session-1", {
      async *run() {
        yield thinkingMessage("thinking");
        yield assistantText("answer A");
        yield withOrigin(assistantText("sub-session text"), "session-sub");
        yield assistantText("answer B");
      },
      async *compact() {
        yield compactionBegin({ reason: "manual", mode: "summarize", context: 1, turns: 1 });
        yield compactionEnd({ reason: "manual", mode: "summarize", status: "completed" });
      },
    });
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(plainSession),
      recorder: { record: async () => {} },
      titles: {
        maybeGenerate: (ctx, session, req) => notified.push({ ctx, session, req }),
      },
      log: () => {},
    });

    await manager.startTask("session-1", [userText("question 1"), userText("question 2")]);
    await waitFor(() => notified.length === 1);
    expect(notified[0]!.req.fallbackText).toBe("question 1\nquestion 2");
    // The generation material is the user input alone — no assistant text, nothing waits on it.
    expect(notified[0]!.req.material).toEqual({
      userText: "question 1\nquestion 2",
      assistantText: "",
    });
    expect(notified[0]!.session).toBe(plainSession);
    expect(notified[0]!.ctx).toMatchObject({
      projectId: "p1",
      agentId: "a1",
      sessionId: "session-1",
      modelId: "m1",
      provider: "custom",
    });

    // The notification fires at start, so the Task is still running here — let it finish
    // (completion adds no second trigger), then compact.
    await waitFor(() => manager.statusOf("session-1") === "idle");
    expect(notified.length).toBe(1);
    await manager.startCompact("session-1");
    await waitFor(() => manager.statusOf("session-1") === "idle");
    await new Promise((r) => setTimeout(r, 10));
    expect(notified.length).toBe(1);
  });

  it("fires title generation at Task start, before any model output has streamed", async () => {
    const notified: { ctx: UsageContext; req: TitleRequest }[] = [];
    // Gate the run before its first yield: a notification while the gate is closed proves
    // generation starts without waiting on any model output.
    let release!: () => void;
    const gate = new Promise<void>((r) => (release = r));
    const gatedRun: RuntimeSession = fakeSession("session-1", {
      async *run() {
        await gate;
        yield assistantText("answer");
      },
    });
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(gatedRun),
      recorder: { record: async () => {} },
      titles: {
        maybeGenerate: (ctx, _session, req) => notified.push({ ctx, req }),
      },
      log: () => {},
    });

    await manager.startTask("session-1", [userText("long question")]);
    // The trigger fires while the run is still parked before its first message.
    await waitFor(() => notified.length === 1);
    expect(manager.statusOf("session-1")).toBe("running");
    expect(notified[0]!.req.fallbackText).toBe("long question");
    expect(notified[0]!.req.material).toEqual({ userText: "long question", assistantText: "" });

    // Completion adds no second trigger — the start is the only one.
    release();
    await waitFor(() => manager.statusOf("session-1") === "idle");
    await new Promise((r) => setTimeout(r, 10));
    expect(notified.length).toBe(1);
  });

  it("a subagent's title fires at registration (mid-run), from its spawning prompt alone", async () => {
    const notified: { ctx: UsageContext; req: TitleRequest }[] = [];
    const driven: OmniMessage[] = [];
    // Gate the run right after the sub-session's output: both notifications must already
    // be in by then, proving neither waited for the run to complete.
    let release!: () => void;
    const gate = new Promise<void>((r) => (release = r));
    const delegating: RuntimeSession = fakeSession("session-1", {
      async *run() {
        yield toolCall({
          name: "run_subagent",
          arguments: JSON.stringify({ prompt: "Research the background of this question" }),
          toolCallId: "sub-1",
        });
        const hop = "child-1";
        yield withOrigin(
          sessionMeta({
            session_id: "child-1",
            model_id: "m-child",
            provider: "custom",
            model_context_window: 1000,
            system_prompt: "sys",
            agent_state: "/root/p1/child_agent/agent_state",
            workspace: "/tmp/w-child",
            source: "subagent",
          }),
          hop,
        );
        yield withOrigin(assistantText("z".repeat(3000)), hop);
        await gate;
        yield assistantText("short answer");
      },
    });
    const manager = new SessionManager({
      sessions,
      channels,
      sources,
      loader: loaderOf(delegating),
      recorder: {
        record: async (_ctx, msg) => {
          driven.push(msg);
        },
      },
      titles: {
        maybeGenerate: (ctx, _session, req) => notified.push({ ctx, req }),
      },
      log: () => {},
    });

    await manager.startTask("session-1", [userText("delegate this")]);
    // By the time the sub-session's output has been driven through, both titles have
    // already fired: the parent's at Task start, the child's at registration.
    await waitFor(() => driven.length === 3);
    expect(manager.statusOf("session-1")).toBe("running");
    expect(notified.map((n) => n.ctx.sessionId)).toEqual(["session-1", "child-1"]);
    const child = notified[1]!;
    // The child's material is its spawning prompt alone — its own output is never waited for.
    expect(child.req.material).toEqual({
      userText: "Research the background of this question",
      assistantText: "",
    });
    expect(child.req.notifyOn).toBe("session-1");

    // Completion adds nothing further.
    release();
    await waitFor(() => manager.statusOf("session-1") === "idle");
    await new Promise((r) => setTimeout(r, 10));
    expect(notified.length).toBe(2);
  });
});