Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

172 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest';
import {
  mkdirSync,
  mkdtempSync,
  promises as fsPromises,
  realpathSync,
  symlinkSync,
  unlinkSync,
  rmSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';

import { snapshotDisabledSkillPaths } from './agents/shared/skill-activation.js';
import { Maker, SessionCreationCleanupPendingError, type CreateSessionOptions, type SessionStartFailureContext } from './maker.js';
import { Session } from './session.js';
import { createAsyncQueue } from './agents/shared/async-queue.js';
import {
  AgentNotAuthenticatedError,
  AgentStartupCleanupPendingError,
  AgentStartupStoppedError,
  LOCAL_AGENT_CLIENT,
  TurnPermissionPolicyUnsupportedError,
  type AgentSessionHandle,
  BaseAgent,
} from './agents/base-agent.js';
import type { SessionMeta, SessionStorage } from './interfaces/session-storage.js';
import type { AgentKind, PermissionMode } from './types/common.js';
import type { AgentEvent } from './types/events.js';
import { fingerprintPiProjectSkillEntrypoint } from './agents/pi/project-resource-assembly.js';

/** A generator that never completes — simulates a live session handle. */
async function* neverEndingIterator(): AsyncGenerator<AgentEvent> {
  await new Promise<never>(() => {}); // never resolves
  yield undefined as never;
}

function createStorage(): SessionStorage {
  const rows = new Map<string, SessionMeta>();
  return {
    async create(meta) {
      const now = Date.now();
      const row = { ...meta, createdAt: now, updatedAt: now };
      rows.set(row.id, row);
      return row;
    },
    async get(id) {
      return rows.get(id) ?? null;
    },
    async list() {
      return [...rows.values()];
    },
    async update(id, patch) {
      const row = rows.get(id);
      if (!row) throw new Error(`missing ${id}`);
      const next = { ...row, ...patch, updatedAt: Date.now() };
      rows.set(id, next);
      return next;
    },
    async compareAndClearSdkSessionId(id, expectedSdkSessionId) {
      const row = rows.get(id);
      if (!row || row.sdkSessionId !== expectedSdkSessionId) return false;
      rows.set(id, { ...row, sdkSessionId: undefined, updatedAt: Date.now() });
      return true;
    },
    async delete(id) {
      rows.delete(id);
    },
  };
}

function createLogger() {
  const logger = {
    trace() {},
    debug() {},
    info() {},
    warn: vi.fn(),
    error() {},
    fatal() {},
    child() {
      return logger;
    },
  };
  return logger;
}

describe('Maker agent status', () => {
  it('represents an optional unregistered runtime as binary-missing', async () => {
    const maker = new Maker({
      agents: {},
      storage: createStorage(),
      logger: createLogger(),
    });
    await expect(maker.getAgentStatus('pi')).resolves.toEqual({
      binaryReady: false,
      binaryPath: null,
      authReady: false,
    });
  });

  it('registers an optional agent after construction idempotently', () => {
    const maker = new Maker({
      agents: {},
      storage: createStorage(),
      logger: createLogger(),
    });
    const pi = createAgent(async () => undefined, 'pi');

    expect(maker.registerAgent('pi', pi)).toBe(true);
    expect(maker.registerAgent('pi', pi)).toBe(false);
    expect(maker.listAvailableAgents()).toEqual(['pi']);
  });
});

function createAgent(
  startSession: (opts: CreateSessionOptions) => Promise<unknown>,
  kind: AgentKind = 'codex',
): BaseAgent {
  return {
    kind,
    capabilities: {
      availableModels: [],
      effortLevels: [],
      permissionModes: [],
      reasoning: { supported: false },
      images: { supported: false },
      slashCommands: { supported: false },
      customSlashCommands: { supported: false },
      memory: { supported: false },
      fork: { supported: false },
      rewind: { supported: false },
      extraDirs: { supported: false },
    },
    startSession,
    filterActiveSkillCommands: (result: unknown) => result,
    async dispose() {},
  } as unknown as BaseAgent;
}

describe('Maker Pi managed-package skill boundary', () => {
  it('uses the runtime Skill view for host authorization checks', async () => {
    const agent = createAgent(async () => {
      throw new Error('not used');
    }, 'claude-code');
    agent.listRuntimeSkills = vi.fn(async () => ({ skills: [{
      kind: 'agent-skill' as const,
      name: 'learn',
      source: 'skill' as const,
      path: '/repo/.claude/skills/learn/SKILL.md',
    }] }));
    const maker = new Maker({
      agents: { 'claude-code': agent },
      storage: createStorage(),
      logger: createLogger(),
    });

    const result = await maker.listAgentRuntimeSkills('claude-code', {
      workingDir: '/repo/src',
      runtimeConfigDir: '/runtime/claude-home',
    });

    expect(result.skills.map((skill) => skill.name)).toEqual(['learn']);
    expect(agent.listRuntimeSkills).toHaveBeenCalledWith({
      workingDir: '/repo/src',
      runtimeConfigDir: '/runtime/claude-home',
    });
    await maker.shutdown();
  });

  it.each(['claude-code', 'codex', 'pi'] as const)('keeps %s live palettes on their startup Skill snapshot', async (agentKind) => {
    const source = '/fixture/disabled-skill';
    let disabled: string[] = [source];
    const agent = createAgent(async (opts) => ({
      ...createHandle({ id: opts.sessionId ?? 'fixture', agentKind }),
      disabledSkillPaths: snapshotDisabledSkillPaths(disabled),
    }), agentKind);
    agent.listAgentSkills = vi.fn(async () => ({ skills: [{
      kind: 'agent-skill' as const, name: 'demo', source: 'skill' as const, path: source,
    }] }));
    agent.filterActiveSkillCommands = (result, remoteHostId, snapshot) => BaseAgent.prototype.filterActiveSkillCommands.call(
      { deps: { getDisabledSkillPaths: () => disabled } } as unknown as BaseAgent, result, remoteHostId, snapshot,
    );
    const maker = new Maker({ agents: { [agentKind]: agent }, storage: createStorage(), logger: createLogger() });
    await maker.createSession({ id: 'disabled-start', agentKind, workingDir: '/repo', model: 'm' });
    disabled = [];
    expect((await maker.listAgentSkills(agentKind, { workingDir: '/repo' })).skills).toHaveLength(1);
    expect((await maker.listAgentSkills(agentKind, { workingDir: '/repo', sessionId: 'disabled-start' })).skills).toEqual([]);
    await maker.createSession({ id: 'enabled-start', agentKind, workingDir: '/repo', model: 'm' });
    disabled = [source];
    expect((await maker.listAgentSkills(agentKind, { workingDir: '/repo' })).skills).toEqual([]);
    expect((await maker.listAgentSkills(agentKind, { workingDir: '/repo', sessionId: 'enabled-start' })).skills).toHaveLength(1);
    await maker.shutdown();
  });

  it.each(['claude-code', 'codex', 'pi'] as const)('keeps %s disabled identities stable after alias retargeting', async (agentKind) => {
    const root = mkdtempSync(path.join(tmpdir(), 'cindy-disabled-snapshot-'));
    const a = path.join(root, 'a');
    const b = path.join(root, 'b');
    const alias = path.join(root, 'alias');
    mkdirSync(a);
    mkdirSync(b);
    symlinkSync(a, alias, process.platform === 'win32' ? 'junction' : 'dir');
    const agent = createAgent(async (opts) => ({
      ...createHandle({ id: opts.sessionId ?? 'fixture', agentKind }),
      disabledSkillPaths: snapshotDisabledSkillPaths([alias]),
    }), agentKind);
    agent.listAgentSkills = vi.fn(async () => ({ skills: [a, b].map((source) => ({
      kind: 'agent-skill' as const, name: path.basename(source), source: 'skill' as const, path: source,
    })) }));
    agent.filterActiveSkillCommands = (result, remoteHostId, snapshot) => BaseAgent.prototype.filterActiveSkillCommands.call(
      { deps: { getDisabledSkillPaths: () => [alias] } } as unknown as BaseAgent, result, remoteHostId, snapshot,
    );
    const maker = new Maker({ agents: { [agentKind]: agent }, storage: createStorage(), logger: createLogger() });
    try {
      await maker.createSession({ id: 'stable-disabled', agentKind, workingDir: root, model: 'm' });
      unlinkSync(alias);
      symlinkSync(b, alias, process.platform === 'win32' ? 'junction' : 'dir');
      const live = await maker.listAgentSkills(agentKind, { workingDir: root, sessionId: 'stable-disabled' });
      expect(live.skills.map((skill) => skill.name)).toEqual(['b']);
      const preview = await maker.listAgentSkills(agentKind, { workingDir: root });
      expect(preview.skills.map((skill) => skill.name)).toEqual(['a']);
    } finally { await maker.shutdown(); rmSync(root, { recursive: true, force: true }); }
  });

  it('allows package skills only for previews and ordinary local Pi tasks', async () => {
    const storage = createStorage();
    const base = {
      agentKind: 'pi' as const,
      workDir: '/repo',
      title: 'Pi',
      model: 'm',
    };
    await storage.create({ id: 'local', ...base });
    await storage.create({ id: 'review', ...base, reviewMode: true });
    await storage.create({ id: 'remote', ...base, remoteHostId: 'ssh-host' });
    const agent = createAgent(async () => {
      throw new Error('not used');
    }, 'pi');
    agent.listAgentSkills = vi.fn(async () => ({ skills: [] }));
    const maker = new Maker({ agents: { pi: agent }, storage, logger: createLogger() });

    await maker.listAgentSkills('pi', { workingDir: '/repo' });
    await maker.listAgentSkills('pi', { workingDir: '/repo', sessionId: 'local' });
    await maker.listAgentSkills('pi', { workingDir: '/repo', sessionId: 'review' });
    await maker.listAgentSkills('pi', { workingDir: '/repo', sessionId: 'remote' });

    expect(vi.mocked(agent.listAgentSkills).mock.calls.map(([options]) => (
      options.includeManagedPiPackages
    ))).toEqual([true, true, false, false]);
  });
});

function createHandle(args: {
  id: string;
  agentKind?: AgentKind;
  delivery?: { threadId: string; historyHasProductPrompt: boolean };
}): AgentSessionHandle {
  return {
    id: args.id,
    agentKind: args.agentKind ?? 'codex',
    model: 'gpt-5.4',
    codexProductPromptDelivery: args.delivery,
    async send() {},
    async steer() {},
    async abort() {},
    async close() {},
    async *events() { yield* neverEndingIterator(); },
    getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
    setInteractionResolver() {},
    isTurnRunning: () => false,
  };
}

function createDeferred<T = void>(): {
  promise: Promise<T>;
  resolve: (value: T) => void;
} {
  let resolve!: (value: T) => void;
  const promise = new Promise<T>((done) => {
    resolve = done;
  });
  return { promise, resolve };
}

describe('application-owned session lifecycle', () => {
  // PR #7697 / 4401270741: visible apps enter createSession, not the already
  // covered startLocalAgentSession. Unit: no local runtime, a remote handle,
  // and an application capability must still produce a persisted usable task.
  it.each(['device-one', 'share:one'])('creates a visible application task on %s without a local engine', async deviceId => {
    const storage = createStorage(), handle = createHandle({ id: 'remote-visible' });
    handle.send = vi.fn(async () => {});
    handle.close = vi.fn(async () => {});
    const startDeviceAgentSession = vi.fn(async () => handle);
    const maker = new Maker({ agents: {}, storage, logger: createLogger(), startDeviceAgentSession });
    try {
      const session = await maker.createSession({ id: 'visible-client', agentKind: 'codex', workingDir: '/repo',
        model: 'm', providerId: 'openai', agentDeviceId: deviceId,
        [LOCAL_AGENT_CLIENT]: { agentDeviceId: deviceId, url: 'http://127.0.0.1:1/mcp/client',
          token: 'fixture', hostToolsOnly: true } });
      expect(session.sdkSessionId).toBe('remote-visible');
      expect(await storage.get('visible-client')).toMatchObject({ agentDeviceId: deviceId, agentKind: 'codex' });
      await session.send('hello');
      expect(handle.send).toHaveBeenCalledOnce();
      expect(startDeviceAgentSession).toHaveBeenCalledOnce();
      await expect(maker.createSession({ id: 'local-client', agentKind: 'codex', workingDir: '/repo', model: 'm',
        [LOCAL_AGENT_CLIENT]: { url: 'http://127.0.0.1:1/mcp/client', token: 'fixture', hostToolsOnly: true },
      })).rejects.toThrow('not registered');
    } finally { await maker.shutdown(); }
    expect(handle.close).toHaveBeenCalledOnce();
  });
  it('routes an application session to its selected device without requiring a local engine', async () => {
    const storage = createStorage(), handle = createHandle({ id: 'remote-native' });
    const startDeviceAgentSession = vi.fn(async () => handle);
    const maker = new Maker({ agents: {}, storage, logger: createLogger(), startDeviceAgentSession });
    const opts = { sessionId: 'remote-client', workingDir: '/repo', model: 'm', providerId: 'openai',
      [LOCAL_AGENT_CLIENT]: { agentDeviceId: 'share:one', url: 'http://127.0.0.1:1/mcp/client', token: 'fixture', hostToolsOnly: true } };
    const session = await maker.startLocalAgentSession('codex', opts);
    expect(startDeviceAgentSession).toHaveBeenCalledWith({ agentKind: 'codex', deviceId: 'share:one', options: opts });
    expect(session.sdkSessionId).toBe('remote-native');
    expect(await storage.list()).toEqual([]);
    await maker.shutdown();
  });
  // Production entry: Maker.startLocalAgentSession. Core rules §1/§2 require the
  // existing Session lifecycle, without creating or enumerating private task rows.
  // Existing createSession tests exercise persistent tasks, not this entry (unit).
  it('uses normal continuation settlement without storing an application transcript in Cindy tasks', async () => {
    const storage = createStorage(), queue = createAsyncQueue<AgentEvent>();
    const handle = createHandle({ id: 'native-client' });
    handle.events = () => queue;
    handle.close = vi.fn(async () => { queue.end(); });
    handle.beginTurnContinuationWait = id => id === 7 ? 'active' : null;
    const maker = new Maker({ agents: { codex: createAgent(async () => handle) }, storage, logger: createLogger() });
    const session = await maker.startLocalAgentSession('codex', { sessionId: 'client', workingDir: '/repo', model: 'm',
      [LOCAL_AGENT_CLIENT]: { url: 'http://127.0.0.1:1', token: 'invalid-fixture', hostToolsOnly: false } });
    const observed: string[] = [];
    session.onEvent(event => { if (event.type === 'done') observed.push(session.getObservedCurrentTurnTerminal().kind); });
    await session.send('hello');
    queue.push({ type: 'done', turnContinuationId: 7, data: { status: 'completed' } });
    await vi.waitFor(() => expect(observed).toEqual(['none']));
    queue.push({ type: 'done', data: { status: 'completed' } });
    await vi.waitFor(() => expect(observed).toEqual(['none', 'done']));
    expect(session.sdkSessionId).toBe('native-client');
    expect(await storage.list()).toEqual([]);
    expect(maker.listActiveSessions()).toEqual([]);
    await maker.shutdown({ reason: 'account-boundary' });
    expect(handle.close).toHaveBeenCalledWith({ reason: 'account-boundary' });
  });

  it('closes an application handle that finishes starting after shutdown instead of publishing it', async () => {
    const ready = createDeferred<AgentSessionHandle>(), storage = createStorage();
    const handle = createHandle({ id: 'late-client' });
    handle.close = vi.fn(async () => {});
    const maker = new Maker({ agents: { codex: createAgent(() => ready.promise) }, storage, logger: createLogger() });
    const opening = maker.startLocalAgentSession('codex', { workingDir: '/repo', model: 'm',
      [LOCAL_AGENT_CLIENT]: { url: 'http://127.0.0.1:1', token: 'invalid-fixture', hostToolsOnly: true } });
    const rejected = expect(opening).rejects.toThrow('stopped');
    const stopping = maker.shutdown({ reason: 'account-boundary' });
    ready.resolve(handle);
    await stopping; await rejected;
    expect(handle.close).toHaveBeenCalledWith({ reason: 'account-boundary' });
    expect(await storage.list()).toEqual([]);
  });
});

describe('Maker local Pi package generation fence', () => {
  it.each(['disable', 'remove', 'update'])(
    'closes an in-flight local Pi startup before publish after %s',
    async () => {
      const started = createDeferred<AgentSessionHandle>();
      const handle = createHandle({ id: 'pi-thread', agentKind: 'pi' });
      handle.close = vi.fn(async () => undefined);
      const startSession = vi.fn(async () => started.promise);
      const storage = createStorage();
      const maker = new Maker({
        agents: { pi: createAgent(startSession, 'pi') },
        storage,
        logger: createLogger(),
      });
      const creating = maker.createSession({
        id: 'local-pi',
        agentKind: 'pi',
        workingDir: '/repo',
        model: 'pi-model',
      });
      await vi.waitFor(() => expect(startSession).toHaveBeenCalledTimes(1));

      maker.advanceLocalPiPackageRuntimeGeneration();
      started.resolve(handle);

      await expect(creating).rejects.toThrow('invalidated by a package change');
      expect(handle.close).toHaveBeenCalledWith({ reason: 'navigation' });
      expect(maker.listActiveSessions()).toEqual([]);
      expect(await storage.get('local-pi')).toBeNull();
    },
  );

  it('rolls back a task created after package generation changes inside storage.get', async () => {
    const baseStorage = createStorage();
    const getEntered = createDeferred();
    const allowGet = createDeferred();
    const storage: SessionStorage = {
      ...baseStorage,
      async get(id) {
        getEntered.resolve();
        await allowGet.promise;
        return baseStorage.get(id);
      },
    };
    const handle = createHandle({ id: 'pi-thread-get-race', agentKind: 'pi' });
    handle.close = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn(async () => handle), 'pi') },
      storage,
      logger: createLogger(),
    });
    const creating = maker.createSession({
      id: 'get-race',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    await getEntered.promise;
    maker.advanceLocalPiPackageRuntimeGeneration();
    allowGet.resolve();

    await expect(creating).rejects.toThrow('invalidated by a package change');
    expect(handle.close).toHaveBeenCalledWith({ reason: 'navigation' });
    expect(await storage.get('get-race')).toBeNull();
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('rolls back a task created while package generation changes inside storage.create', async () => {
    const baseStorage = createStorage();
    const createEntered = createDeferred();
    const allowCreate = createDeferred();
    const storage: SessionStorage = {
      ...baseStorage,
      async create(meta) {
        createEntered.resolve();
        await allowCreate.promise;
        return baseStorage.create(meta);
      },
    };
    const handle = createHandle({ id: 'pi-thread-created-race', agentKind: 'pi' });
    handle.close = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn(async () => handle), 'pi') },
      storage,
      logger: createLogger(),
    });

    const creating = maker.createSession({
      id: 'created-during-race',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    await createEntered.promise;
    maker.advanceLocalPiPackageRuntimeGeneration();
    allowCreate.resolve();

    await expect(creating).rejects.toThrow('invalidated by a package change');
    expect(handle.close).toHaveBeenCalledWith({ reason: 'navigation' });
    expect(await storage.get('created-during-race')).toBeNull();
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('preserves existing metadata when generation changes inside storage.update', async () => {
    const baseStorage = createStorage();
    await baseStorage.create({
      id: 'updated-during-race',
      agentKind: 'pi',
      workDir: '/repo',
      title: 'Existing Pi task',
      model: 'pi-model',
      sdkSessionId: 'pi-thread-existing',
    });
    const updateEntered = createDeferred();
    const allowUpdate = createDeferred();
    const storage: SessionStorage = {
      ...baseStorage,
      async update(id, patch) {
        updateEntered.resolve();
        await allowUpdate.promise;
        return baseStorage.update(id, patch);
      },
    };
    const handle = createHandle({ id: 'pi-thread-replacement', agentKind: 'pi' });
    handle.close = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn(async () => handle), 'pi') },
      storage,
      logger: createLogger(),
    });

    const creating = maker.createSession({
      id: 'updated-during-race',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
      resumeSessionId: 'pi-thread-existing',
    });
    await updateEntered.promise;
    maker.advanceLocalPiPackageRuntimeGeneration();
    allowUpdate.resolve();

    await expect(creating).rejects.toThrow('invalidated by a package change');
    expect(await storage.get('updated-during-race')).toMatchObject({
      title: 'Existing Pi task',
      sdkSessionId: 'pi-thread-existing',
    });
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('rejects a mutation during async onStartSucceeded without closing unpublished task ownership', async () => {
    const hookEntered = createDeferred();
    const allowHook = createDeferred();
    const onClose = vi.fn();
    const handle = createHandle({ id: 'pi-thread-hook-race', agentKind: 'pi' });
    handle.close = vi.fn(async () => undefined);
    const storage = createStorage();
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn(async () => handle), 'pi') },
      storage,
      logger: createLogger(),
      lifecycleHooks: {
        async onStartSucceeded() {
          hookEntered.resolve();
          await allowHook.promise;
        },
        onClose,
      },
    });

    const creating = maker.createSession({
      id: 'hook-race',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    await hookEntered.promise;
    maker.advanceLocalPiPackageRuntimeGeneration();
    allowHook.resolve();

    await expect(creating).rejects.toThrow('invalidated by a package change');
    expect(handle.close).toHaveBeenCalledWith({ reason: 'navigation' });
    expect(onClose).not.toHaveBeenCalled();
    expect(await storage.get('hook-race')).toBeNull();
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('publishes a local Pi startup when generation stays unchanged across async hooks', async () => {
    const allowHook = createDeferred();
    const handle = createHandle({ id: 'pi-thread-current', agentKind: 'pi' });
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn(async () => handle), 'pi') },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: { onStartSucceeded: async () => allowHook.promise },
    });
    const creating = maker.createSession({
      id: 'current-local-pi',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    allowHook.resolve();

    await expect(creating).resolves.toBeInstanceOf(Session);
    expect(maker.listActiveSessions()).toHaveLength(1);
  });

  it('preserves an existing task sdkSessionId when its replacement startup becomes stale', async () => {
    const storage = createStorage();
    await storage.create({
      id: 'existing-local-pi',
      agentKind: 'pi',
      workDir: '/repo',
      title: 'Existing Pi task',
      model: 'pi-model',
      sdkSessionId: 'pi-thread-existing',
    });
    const started = createDeferred<AgentSessionHandle>();
    const staleHandle = createHandle({ id: 'pi-thread-stale', agentKind: 'pi' });
    staleHandle.close = vi.fn(async () => undefined);
    const startSession = vi.fn(async () => started.promise);
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage,
      logger: createLogger(),
    });
    const creating = maker.createSession({
      id: 'existing-local-pi',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
      resumeSessionId: 'pi-thread-existing',
    });
    await vi.waitFor(() => expect(startSession).toHaveBeenCalledTimes(1));

    maker.advanceLocalPiPackageRuntimeGeneration();
    started.resolve(staleHandle);

    await expect(creating).rejects.toThrow('invalidated by a package change');
    expect(staleHandle.close).toHaveBeenCalledWith({ reason: 'navigation' });
    expect(await storage.get('existing-local-pi')).toMatchObject({
      title: 'Existing Pi task',
      sdkSessionId: 'pi-thread-existing',
    });
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it.each([
    ['remote', { remoteHostId: 'ssh-host' }],
    ['Review', { reviewMode: true as const }],
  ])('does not fence an in-flight %s Pi startup', async (_label, boundary) => {
    const started = createDeferred<AgentSessionHandle>();
    const handle = createHandle({ id: 'pi-thread', agentKind: 'pi' });
    handle.close = vi.fn(async () => undefined);
    const startSession = vi.fn(async () => started.promise);
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage: createStorage(),
      logger: createLogger(),
    });
    const creating = maker.createSession({
      id: 'excluded-pi',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
      ...boundary,
    });
    await vi.waitFor(() => expect(startSession).toHaveBeenCalledTimes(1));

    maker.advanceLocalPiPackageRuntimeGeneration();
    started.resolve(handle);

    await expect(creating).resolves.toBeInstanceOf(Session);
    expect(handle.close).not.toHaveBeenCalled();
    expect(maker.listActiveSessions()).toHaveLength(1);
  });
});

describe('Maker initial plan persistence', () => {
  it.each([true, false, undefined])('stores initial plan mode %s with the new task', async (planMode) => {
    const storage = createStorage();
    const create = vi.spyOn(storage, 'create');
    const update = vi.spyOn(storage, 'update');
    const maker = new Maker({
      agents: { codex: createAgent(async () => createHandle({ id: 'plan-handle' })) },
      storage,
      logger: createLogger(),
    });
    try {
      const session = await maker.createSession({
        agentKind: 'codex', workingDir: '/repo', model: 'm', planMode,
      });
      expect(create).toHaveBeenCalledTimes(1);
      expect(create.mock.calls[0][0].planMode).toBe(planMode);
      expect((await storage.get(session.id))?.planMode).toBe(planMode);
      expect(update).not.toHaveBeenCalled();
    } finally {
      await maker.shutdown();
    }
  });

  it.each(['codex', 'claude-code', 'pi'] as const)(
    'cleans up %s after a failed plan-bearing insert and permits retry without an orphan',
    async (agentKind) => {
      const close = vi.fn(async () => undefined);
      const start = vi.fn(async () => ({ ...createHandle({ id: 'plan-handle', agentKind }), close }));
      const storage = createStorage();
      const create = storage.create.bind(storage);
      const insert = vi.spyOn(storage, 'create')
        .mockRejectedValueOnce(new Error('storage unavailable'))
        .mockImplementation(create);
      const maker = new Maker({ agents: { [agentKind]: createAgent(start, agentKind) }, storage, logger: createLogger() });
      const opts: CreateSessionOptions = { agentKind, workingDir: '/repo', model: 'm', planMode: true };
      try {
        await expect(maker.createSession(opts)).rejects.toThrow('storage unavailable');
        expect(insert.mock.calls[0][0].planMode).toBe(true);
        expect(close).toHaveBeenCalledTimes(1);
        expect(maker.listActiveSessions()).toEqual([]);
        expect(await storage.list()).toEqual([]);
        const session = await maker.createSession(opts);
        expect(await storage.list()).toEqual([expect.objectContaining({ id: session.id, planMode: true })]);
        expect(maker.listActiveSessions()).toHaveLength(1);
      } finally {
        await maker.shutdown();
      }
    },
  );
});

describe('Maker session creation singleflight', () => {
  it('persists the durable resume id while exposing a distinct transient request id', async () => {
    const storage = createStorage();
    const handle = { ...createHandle({ id: 'sdk-source', agentKind: 'claude-code' }), requestSessionId: 'sdk-unaccepted-fork' };
    const maker = new Maker({
      agents: { 'claude-code': createAgent(async () => handle, 'claude-code') },
      storage, logger: createLogger(),
    });
    const session = await maker.createSession({ id: 'fork-task', agentKind: 'claude-code', workingDir: '/fixture', model: 'grok-4.6' });
    expect(session.sdkSessionId).toBe('sdk-source');
    expect(session.requestSessionId).toBe('sdk-unaccepted-fork');
    expect((await storage.get('fork-task'))?.sdkSessionId).toBe('sdk-source');
    await maker.closeSession('fork-task');
    expect((await storage.get('fork-task'))?.sdkSessionId).toBe('sdk-source');
  });

  it('reports the effective runtime cwd when recovering an existing task elsewhere', async () => {
    const storage = createStorage();
    await storage.create({ id: 'recovered-cwd', agentKind: 'codex', workDir: '/original', title: 'Existing task', model: 'test-model' });
    const startSession = vi.fn(async () => createHandle({ id: 'recovered-native' }));
    const maker = new Maker({ agents: { codex: createAgent(startSession) }, storage, logger: createLogger() });
    const session = await maker.createSession({ id: 'recovered-cwd', agentKind: 'codex', workingDir: '/conversation', model: 'test-model' });
    expect(startSession).toHaveBeenCalledWith(expect.objectContaining({ workingDir: '/conversation' }));
    expect(session.workDir).toBe('/conversation');
    expect((await storage.get('recovered-cwd'))?.workDir).toBe('/original');
  });

  it('binds each rebuilt business session to a fresh runtime instance id', async () => {
    const seenInstanceIds: string[] = [];
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      seenInstanceIds.push(opts.sessionInstanceId ?? '');
      return createHandle({ id: `thread-${seenInstanceIds.length}` });
    });
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-rebuilt',
      sessionInstanceId: 'caller-must-not-control-this',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    };

    const first = await maker.createSession(options);
    expect(first.instanceId).toBe(seenInstanceIds[0]);
    expect(first.instanceId).not.toBe('caller-must-not-control-this');

    await maker.closeSession(options.id!);
    const second = await maker.createSession(options);

    expect(second.instanceId).toBe(seenInstanceIds[1]);
    expect(second.instanceId).not.toBe(first.instanceId);
  });

  it('shares one startup when the same business session is restored concurrently', async () => {
    let resolveStart!: (handle: AgentSessionHandle) => void;
    const startPending = new Promise<AgentSessionHandle>((resolve) => {
      resolveStart = resolve;
    });
    const startSession = vi.fn(() => startPending);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const created = vi.fn();
    maker.on((event) => {
      if (event.type === 'session:created') created(event.session);
    });
    const options: CreateSessionOptions = {
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-1',
    };

    const preferences = { userPrompt: 'Original caller prompt', makerMemoryEnabled: true };
    const first = maker.createSession({ ...options, hostStartupPreferences: preferences });
    const second = maker.createSession({ ...options, hostStartupPreferences: { makerMemoryEnabled: false } });

    expect(startSession).toHaveBeenCalledTimes(1);
    resolveStart(createHandle({ id: 'thread-1' }));
    const [firstSession, secondSession] = await Promise.all([first, second]);

    expect(firstSession.hostStartupPreferences).toEqual(preferences);
    preferences.makerMemoryEnabled = false;
    const existingSession = await maker.createSession(options);
    expect(existingSession.hostStartupPreferences).toMatchObject({ userPrompt: 'Original caller prompt', makerMemoryEnabled: true });
    expect(secondSession).toBe(firstSession);
    expect(maker.listActiveSessions()).toEqual([firstSession]);
    expect(created).toHaveBeenCalledTimes(1);
    expect(created).toHaveBeenCalledWith(firstSession);
  });

  it('clears a failed startup so the same business session can be retried', async () => {
    const startupError = new Error('start failed');
    const startSession = vi.fn()
      .mockRejectedValueOnce(startupError)
      .mockResolvedValueOnce(createHandle({ id: 'thread-recovered' }));
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-1',
    };

    const first = maker.createSession(options);
    const joined = maker.createSession({ ...options });
    await expect(Promise.all([first, joined])).rejects.toBe(startupError);
    expect(startSession).toHaveBeenCalledTimes(1);
    expect(maker.listActiveSessions()).toEqual([]);

    await expect(maker.createSession({ ...options })).resolves.toBeInstanceOf(Session);
    expect(startSession).toHaveBeenCalledTimes(2);
  });

  // 轮 40-w4-t5 CRITICAL:agent-agnostic 回滚 —— startSession 成功后 storage 写
  // 失败时, PI(无 codexThreadClaim)的 handle 也必须 close, 否则远端残留。
  it('closes the agent handle when session storage fails (non-Codex/PI path)', async () => {
    const closeSpy = vi.fn(async () => undefined);
    const startSession = vi.fn(async () => {
      const h = createHandle({ id: 'pi-handle', agentKind: 'pi' });
      h.close = closeSpy;
      return h;
    });
    const storage = createStorage();
    const origCreate = storage.create;
    storage.create = vi.fn(async () => {
      throw new Error('db lock');
    });
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage,
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-storage-fail',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    await expect(maker.createSession(options)).rejects.toThrow('db lock');
    // handle 被 close(agent-agnostic 回滚) —— 即使没有 codexThreadClaim。
    expect(closeSpy).toHaveBeenCalledTimes(1);
    expect(startSession).toHaveBeenCalledTimes(1);
    void origCreate;
  });

  it('blocks a replacement spawn until an unpublished handle is confirmed closed', async () => {
    let cleanupCanSucceed = false;
    const firstClose = vi.fn(async () => {
      if (!cleanupCanSucceed) throw new Error('termination unconfirmed');
    });
    const firstHandle = createHandle({ id: 'pi-orphan', agentKind: 'pi' });
    firstHandle.close = firstClose;
    const replacementHandle = createHandle({ id: 'pi-replacement', agentKind: 'pi' });
    const startSession = vi.fn()
      .mockResolvedValueOnce(firstHandle)
      .mockResolvedValueOnce(replacementHandle);
    const storage = createStorage();
    const originalCreate = storage.create;
    storage.create = vi
      .fn()
      .mockRejectedValueOnce(new Error('db lock'))
      .mockImplementation((input) => originalCreate.call(storage, input));
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage,
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-storage-cleanup-fail',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    await expect(maker.createSession(options)).rejects.toThrow('db lock');
    const pendingCleanup = await maker.createSession(options).catch(error => error);
    expect(pendingCleanup).toBeInstanceOf(SessionCreationCleanupPendingError);
    expect(pendingCleanup.cause).toMatchObject({ message: 'termination unconfirmed' });
    expect(startSession).toHaveBeenCalledTimes(1);

    cleanupCanSucceed = true;
    await expect(maker.createSession(options)).resolves.toBeInstanceOf(Session);
    expect(firstClose).toHaveBeenCalledTimes(3);
    expect(startSession).toHaveBeenCalledTimes(2);
  });

  it('retries quarantined unpublished handles during shutdown and remains idempotent', async () => {
    let cleanupCanSucceed = false;
    const close = vi.fn(async () => {
      if (!cleanupCanSucceed) throw new Error('termination unconfirmed');
    });
    const failedHandle = createHandle({ id: 'pi-orphan', agentKind: 'pi' });
    failedHandle.close = close;
    const storage = createStorage();
    storage.create = vi.fn(async () => {
      throw new Error('db lock');
    });
    const maker = new Maker({
      agents: { pi: createAgent(async () => failedHandle, 'pi') },
      storage,
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-shutdown-cleanup',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    await expect(maker.createSession(options)).rejects.toThrow('db lock');
    expect(close).toHaveBeenCalledTimes(1);

    cleanupCanSucceed = true;
    await maker.shutdown();
    await maker.shutdown();

    expect(close).toHaveBeenCalledTimes(2);
  });

  it('reclaims a cleanup entry registered after shutdown begins', async () => {
    const storageStarted = createDeferred();
    const storageGate = createDeferred();
    let closeAttempt = 0;
    const close = vi.fn(async () => {
      closeAttempt += 1;
      if (closeAttempt === 1) throw new Error('termination unconfirmed');
    });
    const failedHandle = createHandle({ id: 'pi-late-orphan', agentKind: 'pi' });
    failedHandle.close = close;
    const storage = createStorage();
    storage.create = vi.fn(async () => {
      storageStarted.resolve();
      await storageGate.promise;
      throw new Error('db lock');
    });
    const maker = new Maker({
      agents: { pi: createAgent(async () => failedHandle, 'pi') },
      storage,
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-late-shutdown-cleanup',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    const creating = maker.createSession(options);
    await storageStarted.promise;
    const shuttingDown = maker.shutdown();
    storageGate.resolve();

    await expect(creating).rejects.toThrow('db lock');
    await shuttingDown;
    expect(close).toHaveBeenCalledTimes(2);
  });

  it('retains an active session owner when shutdown detach is unconfirmed and retries it later', async () => {
    let closeAttempts = 0;
    const close = vi.fn(async () => {
      closeAttempts += 1;
      if (closeAttempts === 1) throw new Error('termination unconfirmed');
    });
    const handle = createHandle({ id: 'active-pi-thread', agentKind: 'pi' });
    handle.close = close;
    const maker = new Maker({
      agents: { pi: createAgent(async () => handle, 'pi') },
      storage: createStorage(),
      logger: createLogger(),
    });
    const session = await maker.createSession({
      id: 'session-active-cleanup-retry',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });

    await maker.shutdown();
    expect(close).toHaveBeenCalledTimes(1);
    expect(session.getStatus()).toBe('error');
    expect(maker.listActiveSessions()).toEqual([session]);

    await maker.shutdown();
    expect(close).toHaveBeenCalledTimes(2);
    expect(session.getStatus()).toBe('closed');
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('reports which sessions failed to detach instead of resolving as if none did', async () => {
    // The caller that matters is the account boundary: it hands the runtime to
    // a different owner right after this resolves. A PI session whose detach
    // threw may still have a live process owning durable children that hold
    // credentials the outgoing account cannot revoke, so "shutdown resolved"
    // was never the same statement as "nothing survived".
    const failing = createHandle({ id: 'stuck-pi-thread', agentKind: 'pi' });
    failing.close = vi.fn(async () => { throw new Error('termination unconfirmed'); });
    const clean = createHandle({ id: 'clean-claude-thread', agentKind: 'claude-code' });
    const maker = new Maker({
      agents: {
        pi: createAgent(async () => failing, 'pi'),
        'claude-code': createAgent(async () => clean, 'claude-code'),
      },
      storage: createStorage(),
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'session-detach-report-pi', agentKind: 'pi', workingDir: '/repo', model: 'pi-model',
    });
    await maker.createSession({
      id: 'session-detach-report-cc', agentKind: 'claude-code', workingDir: '/repo', model: 'cc-model',
    });

    const report = await maker.shutdown();

    expect(report.sessionFailures).toHaveLength(1);
    expect(report.sessionFailures[0]).toMatchObject({
      sessionId: 'session-detach-report-pi',
      agentKind: 'pi',
    });
    expect((report.sessionFailures[0]!.error as Error).message).toMatch(/termination unconfirmed/);
  });

  it('detaches active sessions before the creation barrier and reclaims late publications', async () => {
    const lifecycleStarted = createDeferred();
    const lifecycleGate = createDeferred();
    const initialClose = vi.fn(async () => undefined);
    const lateClose = vi.fn(async () => undefined);
    const initialHandle = createHandle({ id: 'initial-pi-thread', agentKind: 'pi' });
    initialHandle.close = initialClose;
    const lateHandle = createHandle({ id: 'late-pi-thread', agentKind: 'pi' });
    lateHandle.close = lateClose;
    const startSession = vi.fn(async (opts: CreateSessionOptions) =>
      opts.id === 'session-initial' ? initialHandle : lateHandle,
    );
    const agent = createAgent(startSession, 'pi');
    const dispose = vi.fn(async () => undefined);
    agent.dispose = dispose;
    const maker = new Maker({
      agents: { pi: agent },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: async (sessionId) => {
          if (sessionId !== 'session-late') return;
          lifecycleStarted.resolve();
          await lifecycleGate.promise;
        },
      },
    });

    await maker.createSession({
      id: 'session-initial',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    const creatingLate = maker.createSession({
      id: 'session-late',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    });
    await lifecycleStarted.promise;

    const shuttingDown = maker.shutdown();
    await vi.waitFor(() => expect(initialClose).toHaveBeenCalledTimes(1));
    await vi.waitFor(() => expect(dispose).toHaveBeenCalledTimes(1));
    expect(lateClose).not.toHaveBeenCalled();

    lifecycleGate.resolve();
    await creatingLate;
    await shuttingDown;

    expect(initialClose).toHaveBeenCalledTimes(1);
    expect(lateClose).toHaveBeenCalledTimes(1);
    expect(dispose).toHaveBeenCalledTimes(2);
    expect(maker.listActiveSessions()).toEqual([]);

    await maker.shutdown();
    expect(initialClose).toHaveBeenCalledTimes(1);
    expect(lateClose).toHaveBeenCalledTimes(1);
  });

  it('disposes an agent again after a lifecycle-blocked startup clears the creation barrier', async () => {
    const lifecycleStarted = createDeferred();
    const lifecycleGate = createDeferred();
    const close = vi.fn(async () => undefined);
    const handle = createHandle({ id: 'late-codex-thread' });
    handle.close = close;
    const startSession = vi.fn(async () => handle);
    const agent = createAgent(startSession);
    const dispose = vi.fn(async () => undefined);
    agent.dispose = dispose;
    const maker = new Maker({
      agents: { codex: agent },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: async () => {
          lifecycleStarted.resolve();
          await lifecycleGate.promise;
        },
      },
    });
    const options: CreateSessionOptions = {
      id: 'session-late-codex-host',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    };

    const creating = maker.createSession(options);
    await lifecycleStarted.promise;
    const shuttingDown = maker.shutdown();
    await vi.waitFor(() => expect(dispose).toHaveBeenCalledTimes(1));
    expect(startSession).not.toHaveBeenCalled();

    lifecycleGate.resolve();
    await creating;
    await shuttingDown;

    expect(startSession).toHaveBeenCalledTimes(1);
    expect(dispose).toHaveBeenCalledTimes(2);
    expect(close).toHaveBeenCalledTimes(1);
  });

  it('fences replacement creation while late shutdown cleanup is in flight', async () => {
    const closeGate = createDeferred();
    let closeAttempt = 0;
    const failedClose = vi.fn(async () => {
      closeAttempt += 1;
      if (closeAttempt === 1) throw new Error('termination unconfirmed');
      await closeGate.promise;
    });
    const failedHandle = createHandle({ id: 'pi-orphan', agentKind: 'pi' });
    failedHandle.close = failedClose;
    const startSession = vi.fn().mockResolvedValue(failedHandle);
    const storage = createStorage();
    storage.create = vi.fn(async () => {
      throw new Error('db lock');
    });
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage,
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-shutdown-owner-race',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    await expect(maker.createSession(options)).rejects.toThrow('db lock');
    const shuttingDown = maker.shutdown();
    await vi.waitFor(() => expect(failedClose).toHaveBeenCalledTimes(2));
    await expect(maker.createSession(options)).rejects.toThrow(/shutting down/);
    expect(startSession).toHaveBeenCalledTimes(1);

    closeGate.resolve();
    await shuttingDown;
    expect(failedClose).toHaveBeenCalledTimes(2);
  });

  it('rejects a second business task using the same live Codex thread until close completes', async () => {
    const threadId = '11111111-1111-1111-1111-111111111111';
    const closeGate = createDeferred();
    const firstHandle = createHandle({ id: threadId });
    firstHandle.close = vi.fn(() => closeGate.promise);
    const secondHandle = createHandle({ id: threadId });
    const startSession = vi.fn()
      .mockResolvedValueOnce(firstHandle)
      .mockResolvedValueOnce(secondHandle);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const options = (id: string): CreateSessionOptions => ({
      id,
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: threadId,
    });

    await maker.createSession(options('session-a'));
    await expect(maker.createSession(options('session-b'))).rejects.toThrow(
      /already active in another Cindy task/i,
    );
    expect(startSession).toHaveBeenCalledTimes(1);

    const closing = maker.closeSession('session-a');
    await vi.waitFor(() => expect(firstHandle.close).toHaveBeenCalledTimes(1));
    await expect(maker.createSession(options('session-b'))).rejects.toThrow(
      /already active in another Cindy task/i,
    );
    expect(startSession).toHaveBeenCalledTimes(1);

    closeGate.resolve();
    await closing;
    const replacement = await maker.createSession(options('session-b'));
    expect(replacement.sdkSessionId).toBe(threadId);
    expect(startSession).toHaveBeenCalledTimes(2);
    await replacement.close();
  });

  it('scopes Codex thread claims by remote target and permits different threads', async () => {
    const sharedThread = '22222222-2222-2222-2222-222222222222';
    const otherThread = '33333333-3333-3333-3333-333333333333';
    const startSession = vi.fn(async (opts: CreateSessionOptions) =>
      createHandle({ id: opts.resumeSessionId! }),
    );
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const base = {
      agentKind: 'codex' as const,
      workingDir: '/repo',
      model: 'gpt-5.4',
    };

    const local = await maker.createSession({
      ...base,
      id: 'session-local',
      resumeSessionId: sharedThread,
    });
    const remote = await maker.createSession({
      ...base,
      id: 'session-remote',
      remoteHostId: 'remote-1',
      resumeSessionId: sharedThread,
    });
    const other = await maker.createSession({
      ...base,
      id: 'session-other-thread',
      resumeSessionId: otherThread,
    });

    expect(startSession).toHaveBeenCalledTimes(3);
    await Promise.all([local.close(), remote.close(), other.close()]);
  });

  it('releases a provisional Codex thread claim when startup fails', async () => {
    const threadId = '44444444-4444-4444-4444-444444444444';
    const startSession = vi.fn()
      .mockRejectedValueOnce(new Error('resume failed'))
      .mockResolvedValueOnce(createHandle({ id: threadId }));
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const options = (id: string): CreateSessionOptions => ({
      id,
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: threadId,
    });

    await expect(maker.createSession(options('session-failed'))).rejects.toThrow('resume failed');
    const recovered = await maker.createSession(options('session-recovered'));

    expect(startSession).toHaveBeenCalledTimes(2);
    await recovered.close();
  });

  it('moves the Codex thread claim when the live handle reports a replacement id', async () => {
    const firstThread = '55555555-5555-5555-5555-555555555555';
    const nextThread = '66666666-6666-6666-6666-666666666666';
    const firstEvents = createAsyncQueue<AgentEvent>();
    const firstHandle = createHandle({ id: firstThread });
    firstHandle.events = () => firstEvents;
    const startSession = vi.fn(async (opts: CreateSessionOptions) =>
      opts.id === 'session-a'
        ? firstHandle
        : createHandle({ id: opts.resumeSessionId! }),
    );
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    const base = {
      agentKind: 'codex' as const,
      workingDir: '/repo',
      model: 'gpt-5.4',
    };
    const first = await maker.createSession({
      ...base,
      id: 'session-a',
      resumeSessionId: firstThread,
    });
    const moved = new Promise<void>((resolve) => {
      const unsubscribe = first.onEvent((event) => {
        if (event.type !== 'session_id' || event.data !== nextThread) return;
        unsubscribe();
        resolve();
      });
    });

    firstEvents.push({ type: 'session_id', data: nextThread, source: 'codex' });
    await moved;

    const oldThreadReuse = await maker.createSession({
      ...base,
      id: 'session-old-thread-reuse',
      resumeSessionId: firstThread,
    });
    await expect(maker.createSession({
      ...base,
      id: 'session-next-thread-conflict',
      resumeSessionId: nextThread,
    })).rejects.toThrow(/already active in another Cindy task/i);

    await Promise.all([first.close(), oldThreadReuse.close()]);
  });

  it('closes the Codex handle and releases its claim when session storage fails', async () => {
    const threadId = '77777777-7777-7777-7777-777777777777';
    const storage = createStorage();
    const create = storage.create.bind(storage);
    storage.create = vi.fn()
      .mockRejectedValueOnce(new Error('storage unavailable'))
      .mockImplementation(create);
    const failedHandle = createHandle({ id: threadId });
    failedHandle.close = vi.fn(async () => {});
    const startSession = vi.fn()
      .mockResolvedValueOnce(failedHandle)
      .mockResolvedValueOnce(createHandle({ id: threadId }));
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage,
      logger: createLogger(),
    });
    const options = (id: string): CreateSessionOptions => ({
      id,
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: threadId,
    });

    await expect(maker.createSession(options('session-storage-failed'))).rejects.toThrow(
      'storage unavailable',
    );
    expect(failedHandle.close).toHaveBeenCalledTimes(1);

    const recovered = await maker.createSession(options('session-storage-recovered'));
    expect(startSession).toHaveBeenCalledTimes(2);
    await recovered.close();
  });
});

describe('Maker session close events', () => {
  it('defers retirement of only the captured runtime and ignores its stale identity after rebuild', async () => {
    const queue = createAsyncQueue<AgentEvent>();
    let running = false;
    const handle = createHandle({ id: 'old-thread', agentKind: 'pi' });
    handle.send = vi.fn(async () => { running = true; });
    handle.isTurnRunning = () => running;
    handle.events = () => queue;
    const replacement = createHandle({ id: 'new-thread', agentKind: 'pi' });
    replacement.close = vi.fn(replacement.close);
    const start = vi.fn().mockResolvedValueOnce(handle).mockResolvedValue(replacement);
    const maker = new Maker({ agents: { pi: createAgent(start, 'pi') }, storage: createStorage(), logger: createLogger() });
    const opts = { id: 'retiring', agentKind: 'pi' as const, workingDir: '/repo', model: 'm' };
    const old = await maker.createSession(opts);
    await old.send('work');
    expect(await maker.closeSessionIfCurrent(old, 'requested', { afterCurrentTurn: true })).toBe('deferred');
    expect(maker.getSession(old.id)).toBe(old);
    running = false;
    queue.push({ type: 'done', source: 'pi', data: { status: 'completed', result: 'done' } });
    await vi.waitFor(() => expect(maker.getSession(old.id)).toBeUndefined());
    const next = await maker.createSession(opts);
    await maker.closeSessionIfCurrent(old, 'requested', { afterCurrentTurn: true });
    expect(maker.getSession(next.id)).toBe(next);
    expect(replacement.close).not.toHaveBeenCalled();
    await next.close();
    queue.end();
  });

  it.each([
    { initial: 'runtime-refresh', begun: false, next: 'agent-switch', expected: 'agent-switch' },
    { initial: 'runtime-refresh', begun: false, next: 'requested', expected: 'requested' },
    { initial: 'runtime-refresh', begun: true, next: 'agent-switch', expected: 'runtime-refresh' },
    { initial: 'requested', begun: false, next: 'agent-switch', expected: 'requested' },
    { initial: 'agent-switch', begun: false, next: 'runtime-refresh', expected: 'agent-switch' },
  ] as const)('preserves actual close ownership: $initial, begun=$begun, next=$next', async ({ initial, begun, next, expected }) => {
    const queue = createAsyncQueue<AgentEvent>();
    const exit = createDeferred();
    const handle = createHandle({ id: 'retiring-thread', agentKind: 'pi' });
    handle.events = () => queue;
    handle.close = vi.fn(async () => { await exit.promise; queue.end(); });
    const maker = new Maker({ agents: { pi: createAgent(async () => handle, 'pi') },
      storage: createStorage(), logger: createLogger() });
    const session = await maker.createSession({ id: 'retiring', agentKind: 'pi', workingDir: '/repo', model: 'm' });
    const closed = vi.fn();
    maker.on(event => { if (event.type === 'session:closed') closed(event); });
    const release = session.acquireTurnLease()!;
    expect(await maker.closeSessionIfCurrent(session, initial, { afterCurrentTurn: true })).toBe('deferred');
    if (begun) {
      release();
      await vi.waitFor(() => expect(handle.close).toHaveBeenCalledOnce());
    }
    const closing = maker.closeSession(session.id, next);
    exit.resolve();
    await closing;
    release();
    expect(closed).toHaveBeenCalledExactlyOnceWith({
      type: 'session:closed', sessionId: session.id, session, reason: expected,
    });
    expect(handle.close).toHaveBeenCalledOnce();
  });

  it('keeps the original cause when an unconfirmed close is retried as a switch', async () => {
    const handle = createHandle({ id: 'failed-close', agentKind: 'pi' });
    handle.close = vi.fn().mockRejectedValueOnce(new Error('exit unconfirmed')).mockResolvedValue(undefined);
    const maker = new Maker({ agents: { pi: createAgent(async () => handle, 'pi') },
      storage: createStorage(), logger: createLogger() });
    const session = await maker.createSession({ id: 'failed-close', agentKind: 'pi', workingDir: '/repo', model: 'm' });
    await expect(maker.closeSession(session.id, 'runtime-refresh')).rejects.toThrow('exit unconfirmed');
    expect(session.getStatus()).toBe('error');
    await maker.closeSession(session.id, 'agent-switch');
    expect(maker.getSessionCloseReason(session)).toBe('runtime-refresh');
    expect(handle.close).toHaveBeenCalledTimes(2);
  });

  it('preserves the explicit close reason and exact Session identity', async () => {
    const maker = new Maker({
      agents: {
        codex: createAgent(async () => createHandle({ id: 'thread-1' })),
      },
      storage: createStorage(),
      logger: createLogger(),
    });
    const closed = vi.fn();
    maker.on((event) => {
      if (event.type === 'session:closed') closed(event);
    });
    const session = await maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    });

    await maker.closeSession('session-1', 'agent-switch');

    expect(maker.getSessionCloseReason(session)).toBe('agent-switch');
    expect(closed).toHaveBeenCalledWith({
      type: 'session:closed',
      sessionId: 'session-1',
      session,
      reason: 'agent-switch',
    });
  });

  it('removes a session whose event iterator crashes and recreates it on the next request', async () => {
    const crashingHandle = createHandle({ id: 'thread-crashed' });
    crashingHandle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<AgentEvent>> {
            throw new Error('iterator crashed');
          },
        };
      },
    });
    crashingHandle.close = vi.fn(async () => undefined);
    const healthyHandle = createHandle({ id: 'thread-rebuilt' });
    const startSession = vi.fn()
      .mockResolvedValueOnce(crashingHandle)
      .mockResolvedValueOnce(healthyHandle);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
    });
    let resolveClosed!: () => void;
    const closed = new Promise<void>((resolve) => {
      resolveClosed = resolve;
    });
    maker.on((event) => {
      if (event.type === 'session:closed' && event.sessionId === 'session-crash') {
        expect(event.reason).toBe('unexpected');
        expect(maker.getSessionCloseReason(event.session)).toBe('unexpected');
        expect(event.session.wasClosedByRuntime()).toBe(true);
        resolveClosed();
      }
    });
    const options: CreateSessionOptions = {
      id: 'session-crash',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    };

    await maker.createSession(options);
    await closed;
    expect(maker.getSession('session-crash')).toBeUndefined();
    expect(maker.listActiveSessions()).toEqual([]);

    const rebuilt = await maker.createSession(options);
    expect(rebuilt.sdkSessionId).toBe('thread-rebuilt');
    expect(startSession).toHaveBeenCalledTimes(2);
  });

  it('retries a retained Pi error handle before recreating the session', async () => {
    const crashingHandle = createHandle({
      id: 'thread-crashed-close-retry',
      agentKind: 'pi',
    });
    crashingHandle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<AgentEvent>> {
            throw new Error('iterator crashed');
          },
        };
      },
    });
    let closeAttempts = 0;
    crashingHandle.close = vi.fn(async () => {
      closeAttempts += 1;
      if (closeAttempts === 1) throw new Error('transport close failed');
    });
    const healthyHandle = createHandle({
      id: 'thread-rebuilt-after-close-retry',
      agentKind: 'pi',
    });
    const startSession = vi.fn()
      .mockResolvedValueOnce(crashingHandle)
      .mockResolvedValueOnce(healthyHandle);
    const maker = new Maker({
      agents: { pi: createAgent(startSession, 'pi') },
      storage: createStorage(),
      logger: createLogger(),
    });
    const options: CreateSessionOptions = {
      id: 'session-crash-close-retry',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'pi-model',
    };

    const crashed = await maker.createSession(options);
    await vi.waitFor(() => expect(crashed.getStatus()).toBe('error'));
    expect(maker.getSession('session-crash-close-retry')).toBe(crashed);
    expect(maker.listActiveSessions()).toEqual([crashed]);

    const rebuilt = await maker.createSession(options);
    expect(rebuilt.sdkSessionId).toBe('thread-rebuilt-after-close-retry');
    expect(maker.getSession('session-crash-close-retry')).toBe(rebuilt);
    expect(maker.listActiveSessions()).toEqual([rebuilt]);
    expect(maker.listActiveSessions()).not.toContain(crashed);
    expect(closeAttempts).toBe(2);
    expect(startSession).toHaveBeenCalledTimes(2);
  });
});

describe('Maker before-start lifecycle hook', () => {
  it('awaits host preparation before starting the agent', async () => {
    const order: string[] = [];
    const onBeforeStart = vi.fn(async () => {
      order.push('prepare');
    });
    const startSession = vi.fn(async () => {
      order.push('start');
      return createHandle({ id: 'thread-1' });
    });
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: { onBeforeStart },
    });

    await maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    });

    expect(order).toEqual(['prepare', 'start']);
    expect(onBeforeStart).toHaveBeenCalledWith({
      agentKind: 'codex',
      workingDir: '/repo',
    });
  });

  it('keeps session startup fail-soft when host preparation fails', async () => {
    const logger = createLogger();
    const startSession = vi.fn(async () => createHandle({ id: 'thread-1' }));
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger,
      lifecycleHooks: {
        onBeforeStart: async () => {
          throw new Error('prepare failed');
        },
      },
    });

    await expect(maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    })).resolves.toBeInstanceOf(Session);
    expect(startSession).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      'lifecycleHooks.onBeforeStart threw; continuing session startup',
      expect.objectContaining({ sessionId: 'session-1', workingDir: '/repo' }),
    );
  });
});

describe('Maker start-option lifecycle hooks', () => {
  it('prepares mutable start options before the agent and marks success before publish', async () => {
    const order: string[] = [];
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      order.push('start');
      expect(opts.vendorOptions).toMatchObject({ orcaRole: 'lead' });
      expect(opts.userPrompt).toBe('orca instructions');
      return createHandle({ id: 'thread-1' });
    });
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: async (_sessionId, opts) => {
          order.push('prepare');
          opts.vendorOptions = { orcaRole: 'lead' };
          opts.userPrompt = 'orca instructions';
        },
        onStartSucceeded: async (sessionId, opts) => {
          order.push('succeeded');
          expect(sessionId).toBe('session-1');
          expect(opts.vendorOptions).toMatchObject({ orcaRole: 'lead' });
          expect(maker.getSession(sessionId)).toBeUndefined();
        },
      },
    });
    maker.on((event) => {
      if (event.type === 'session:created') order.push('publish');
    });

    await maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    });

    expect(order).toEqual(['prepare', 'start', 'succeeded', 'publish']);
  });

  it('blocks agent startup when start-option preparation fails', async () => {
    const startSession = vi.fn(async () => createHandle({ id: 'thread-1' }));
    const onStartSucceeded = vi.fn();
    const onStartFailed = vi.fn();
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: async () => {
          throw new Error('prepare failed');
        },
        onStartSucceeded,
        onStartFailed,
      },
    });

    await expect(maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    })).rejects.toThrow('prepare failed');
    expect(startSession).not.toHaveBeenCalled();
    expect(onStartSucceeded).not.toHaveBeenCalled();
    expect(onStartFailed).toHaveBeenCalledWith(
      expect.objectContaining({ sessionId: 'session-1', stage: 'prepare' }),
    );
    expect(maker.listActiveSessions()).toEqual([]);
  });

  it('binds a delayed close and a failed rebuild to their own startup options', async () => {
    const closeEntered = createDeferred();
    const allowClose = createDeferred();
    const prepared: CreateSessionOptions[] = [];
    const disposed: CreateSessionOptions[] = [];
    const startSession = vi.fn(async () => createHandle({ id: 'thread-lifecycle' }));
    const onStartFailed = vi.fn();
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: async (_id, options) => {
          prepared.push(options);
          if (prepared.length === 2) {
            await Promise.resolve();
            throw new Error('replacement preparation failed');
          }
        },
        onStartFailed,
        onClose: async (_id, options) => {
          closeEntered.resolve();
          await allowClose.promise;
          disposed.push(options);
        },
      },
    });
    const options: CreateSessionOptions = {
      id: 'same-task', agentKind: 'codex', workingDir: '/repo', model: 'gpt-5.4',
    };
    const first = await maker.createSession(options);
    await first.close();
    await closeEntered.promise;
    await expect(maker.createSession(options)).rejects.toThrow('replacement preparation failed');
    const replacement = await maker.createSession(options);
    allowClose.resolve();
    await vi.waitFor(() => expect(disposed).toHaveLength(1));
    expect(new Set(prepared).size).toBe(3);
    expect(prepared).not.toContain(options);
    expect(disposed[0]).toBe(prepared[0]);
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      options: prepared[1], stage: 'prepare', runtimeMayBeAlive: false,
    }));
    expect(maker.getSession('same-task')).toBe(replacement);
    await replacement.close();
    await vi.waitFor(() => expect(disposed).toHaveLength(2));
    expect(disposed[1]).toBe(prepared[2]);
  });

  it.each([false, true])('reports whether a failed startup still has a live handle: %s', async (cleanupFails) => {
    const handle = createHandle({ id: 'failed-storage' });
    handle.close = vi.fn(async () => {
      if (cleanupFails) throw new Error('termination unconfirmed');
    });
    const storage = createStorage();
    storage.create = vi.fn().mockRejectedValue(new Error('storage unavailable'));
    const onStartFailed = vi.fn();
    const maker = new Maker({
      agents: { codex: createAgent(async () => handle) },
      storage, logger: createLogger(), lifecycleHooks: { onStartFailed },
    });
    await expect(maker.createSession({
      id: 'storage-failure', agentKind: 'codex', workingDir: '/repo', model: 'gpt-5.4',
    })).rejects.toThrow('storage unavailable');
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      stage: 'storage', runtimeMayBeAlive: cleanupFails,
    }));
  });

  it('runs startup cleanup when a prepared runtime cannot claim its thread', async () => {
    const threadId = '11111111-1111-4111-8111-111111111111';
    const startSession = vi.fn(async () => createHandle({ id: threadId }));
    const onStartFailed = vi.fn();
    const maker = new Maker({
      agents: { codex: createAgent(startSession) }, storage: createStorage(), logger: createLogger(),
      lifecycleHooks: { onStartFailed },
    });
    const options: CreateSessionOptions = {
      id: 'thread-owner', agentKind: 'codex', workingDir: '/repo', model: 'gpt-5.4',
      resumeSessionId: threadId,
    };
    const owner = await maker.createSession(options);
    await expect(maker.createSession({ ...options, id: 'thread-conflict' })).rejects.toThrow('already active');
    expect(startSession).toHaveBeenCalledOnce();
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      sessionId: 'thread-conflict', stage: 'agent-start', runtimeMayBeAlive: false,
    }));
    await owner.close();
  });

  it('releases deferred failed-start resources without touching the successful replacement', async () => {
    const cleanupEntered = createDeferred();
    const allowCleanup = createDeferred();
    const leased = new Set<CreateSessionOptions>();
    const prepared: CreateSessionOptions[] = [];
    const failedHandle = createHandle({ id: 'failed-pi', agentKind: 'pi' });
    failedHandle.close = vi.fn().mockRejectedValueOnce(new Error('still alive')).mockResolvedValue(undefined);
    const storage = createStorage();
    const create = storage.create.bind(storage);
    storage.create = vi.fn().mockRejectedValueOnce(new Error('storage failed')).mockImplementation(create);
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn()
        .mockResolvedValueOnce(failedHandle)
        .mockResolvedValueOnce(createHandle({ id: 'replacement-pi', agentKind: 'pi' })), 'pi') },
      storage, logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: (_id, options) => { prepared.push(options); leased.add(options); },
        onStartFailed: ({ options, runtimeMayBeAlive }) => { if (!runtimeMayBeAlive) leased.delete(options); },
        onStartCleanupSucceeded: async (_id, options) => {
          cleanupEntered.resolve();
          await allowCleanup.promise;
          leased.delete(options);
        },
        onClose: (_id, options) => { leased.delete(options); },
      },
    });
    const options: CreateSessionOptions = {
      id: 'same-failed-task', agentKind: 'pi', workingDir: '/repo', model: 'pi-model',
    };
    await expect(maker.createSession(options)).rejects.toThrow('storage failed');
    expect(leased.size).toBe(1);
    const replacement = await maker.createSession(options);
    await cleanupEntered.promise;
    expect(leased.size).toBe(2);
    allowCleanup.resolve();
    await vi.waitFor(() => expect(leased).toEqual(new Set([prepared[1]])));
    expect(maker.getSession(options.id!)).toBe(replacement);
    await replacement.close();
    await vi.waitFor(() => expect(leased.size).toBe(0));
  });

  it('keeps an adapter-owned unpublished runtime protected until its own close completes', async () => {
    const stopped = createDeferred();
    const cleanupEntered = createDeferred();
    const allowCleanup = createDeferred();
    const pending = new AgentStartupCleanupPendingError('opaque adapter failure', {
      cause: new Error('startup RPC failed'), whenStopped: stopped.promise,
    });
    const leased = new Set<CreateSessionOptions>();
    const prepared: CreateSessionOptions[] = [];
    const onStartFailed = vi.fn(({ options, runtimeMayBeAlive }: SessionStartFailureContext) => {
      if (!runtimeMayBeAlive) leased.delete(options);
    });
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn().mockRejectedValueOnce(pending)
        .mockResolvedValueOnce(createHandle({ id: 'recovered-pi', agentKind: 'pi' })), 'pi') },
      storage: createStorage(), logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: (_id, options) => { prepared.push(options); leased.add(options); },
        onStartFailed,
        onStartCleanupSucceeded: async (_id, options) => {
          cleanupEntered.resolve();
          await allowCleanup.promise;
          leased.delete(options);
        },
        onClose: (_id, options) => { leased.delete(options); },
      },
    });
    const options: CreateSessionOptions = {
      id: 'adapter-cleanup', agentKind: 'pi', workingDir: '/repo', model: 'pi-model',
    };
    await expect(maker.createSession(options)).rejects.toBe(pending);
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      stage: 'agent-start', runtimeMayBeAlive: true,
    }));
    expect(leased).toEqual(new Set([prepared[0]]));
    stopped.resolve();
    await cleanupEntered.promise;
    const replacement = await maker.createSession(options);
    expect(leased.size).toBe(2);
    allowCleanup.resolve();
    await vi.waitFor(() => expect(leased).toEqual(new Set([prepared[1]])));
    await replacement.close();
    await vi.waitFor(() => expect(leased.size).toBe(0));
  });

  it('does not release adapter startup resources when exit confirmation fails', async () => {
    let rejectStopped!: (error: unknown) => void;
    const whenStopped = new Promise<void>((_resolve, reject) => { rejectStopped = reject; });
    const pending = new AgentStartupCleanupPendingError('adapter failed', {
      cause: new Error('startup RPC failed'), whenStopped,
    });
    const logger = createLogger();
    const onStartFailed = vi.fn();
    const onStartCleanupSucceeded = vi.fn();
    const maker = new Maker({
      agents: { pi: createAgent(vi.fn().mockRejectedValue(pending), 'pi') },
      storage: createStorage(), logger,
      lifecycleHooks: { onStartFailed, onStartCleanupSucceeded },
    });
    await expect(maker.createSession({
      id: 'unconfirmed-exit', agentKind: 'pi', workingDir: '/repo', model: 'pi-model',
    })).rejects.toBe(pending);
    rejectStopped(new Error('exit could not be verified'));
    await vi.waitFor(() => expect(logger.warn).toHaveBeenCalledWith(
      'adapter startup cleanup remains unconfirmed', expect.objectContaining({ sessionId: 'unconfirmed-exit' }),
    ));
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({ runtimeMayBeAlive: true }));
    expect(onStartCleanupSucceeded).not.toHaveBeenCalled();
  });

  it.each((['codex', 'claude-code', 'pi'] as const).flatMap((kind) =>
    [new TypeError('startup RPC failed'), 'non-Error startup failure'].map((error) => ({ kind, error }))))(
    'releases only the confirmed-stopped $kind startup and permits a fresh task: $error', async ({ kind, error: startupError }) => {
      const otherStartup = {} as CreateSessionOptions;
      const leased = new Set<CreateSessionOptions>([otherStartup]);
      const onStartFailed = vi.fn(({ options, runtimeMayBeAlive }: SessionStartFailureContext) => {
        if (!runtimeMayBeAlive) leased.delete(options);
      });
      const onStartCleanupSucceeded = vi.fn();
      const startSession = vi.fn()
        .mockRejectedValueOnce(new AgentStartupStoppedError(startupError))
        .mockResolvedValueOnce(createHandle({ id: 'fresh-sdk-session' }));
      const maker = new Maker({
        agents: { [kind]: createAgent(startSession, kind) },
        storage: createStorage(), logger: createLogger(),
        lifecycleHooks: {
          prepareStartOptions: (_id, options) => { leased.add(options); },
          onStartFailed, onStartCleanupSucceeded,
        },
      });
      await expect(maker.createSession({
        id: 'confirmed-exit', agentKind: kind, workingDir: '/repo', model: 'test-model',
      })).rejects.toBe(startupError);
      expect(onStartFailed).toHaveBeenCalledOnce();
      expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
        stage: 'agent-start', error: startupError, runtimeMayBeAlive: false,
      }));
      expect(leased).toEqual(new Set([otherStartup]));
      expect(onStartCleanupSucceeded).not.toHaveBeenCalled();
      const replacement = await maker.createSession({
        id: 'fresh-task', agentKind: kind, workingDir: '/repo', model: 'test-model',
      });
      expect(maker.getSession('fresh-task')).toBe(replacement);
      expect(startSession).toHaveBeenCalledTimes(2);
      await replacement.close();
    },
  );

  it.each([
    new Error('ordinary startup failure'),
    Object.assign(new Error('ordinary startup failure'), { name: 'AgentStartupStoppedError' }),
  ])('preserves runtime protection for an adapter failure without exit evidence: %s', async (error) => {
    const onStartFailed = vi.fn();
    const onStartCleanupSucceeded = vi.fn();
    const startSession = vi.fn().mockRejectedValue(error);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) }, storage: createStorage(), logger: createLogger(),
      lifecycleHooks: { onStartFailed, onStartCleanupSucceeded },
    });
    await expect(maker.createSession({
      id: 'unknown-startup-exit', agentKind: 'codex', workingDir: '/repo', model: 'gpt-5.4',
    })).rejects.toThrow('ordinary startup failure');
    expect(startSession).toHaveBeenCalledOnce();
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      sessionId: 'unknown-startup-exit', stage: 'agent-start', runtimeMayBeAlive: true,
    }));
    expect(onStartCleanupSucceeded).not.toHaveBeenCalled();
  });

  it('does not run the success hook when agent startup fails', async () => {
    const onStartSucceeded = vi.fn();
    const onStartFailed = vi.fn();
    const maker = new Maker({
      agents: { codex: createAgent(vi.fn().mockRejectedValue(new Error('start failed'))) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: { onStartSucceeded, onStartFailed },
    });

    await expect(maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    })).rejects.toThrow('start failed');
    expect(onStartSucceeded).not.toHaveBeenCalled();
    expect(onStartFailed).toHaveBeenCalledWith(
      expect.objectContaining({ sessionId: 'session-1', stage: 'agent-start' }),
    );
  });

  it('releases the startup lease when authentication fails before spawning an agent', async () => {
    const leased = new Set<CreateSessionOptions>();
    const onStartFailed = vi.fn(({ options, runtimeMayBeAlive }: SessionStartFailureContext) => {
      if (!runtimeMayBeAlive) leased.delete(options);
    });
    const authError = new AgentNotAuthenticatedError('claude-code', 'not authenticated');
    const maker = new Maker({
      agents: { 'claude-code': createAgent(vi.fn().mockRejectedValue(authError), 'claude-code') },
      storage: createStorage(), logger: createLogger(),
      lifecycleHooks: {
        prepareStartOptions: (_id, options) => { leased.add(options); },
        onStartFailed,
      },
    });
    await expect(maker.createSession({
      id: 'auth-failure', agentKind: 'claude-code', workingDir: '/repo', model: 'claude-model',
    })).rejects.toBe(authError);
    expect(onStartFailed).toHaveBeenCalledWith(expect.objectContaining({
      stage: 'agent-start', error: authError, runtimeMayBeAlive: false,
    }));
    expect(leased).toHaveLength(0);
  });

  it('preserves the original startup error when the failure hook also fails', async () => {
    const logger = createLogger();
    const maker = new Maker({
      agents: { codex: createAgent(vi.fn().mockRejectedValue(new Error('start failed'))) },
      storage: createStorage(),
      logger,
      lifecycleHooks: {
        onStartFailed: async () => {
          throw new Error('audit failed');
        },
      },
    });

    await expect(maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    })).rejects.toThrow('start failed');
    expect(logger.warn).toHaveBeenCalledWith(
      'lifecycleHooks.onStartFailed threw; preserving original startup error',
      expect.objectContaining({ sessionId: 'session-1', stage: 'agent-start' }),
    );
  });
});

describe('Maker codex prompt lifecycle hooks', () => {
  it('hydrates codex history prompt state before startSession and persists delivery facts after success', async () => {
    const startSession = vi.fn(async () => ({
      id: 'thread-1',
      agentKind: 'codex',
      model: 'gpt-5.4',
      codexProductPromptDelivery: {
        threadId: 'thread-1',
        historyHasProductPrompt: false,
      },
      async send() {},
      async steer() {},
      async abort() {},
      async close() {},
      async *events() {},
      getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
      setInteractionResolver() {},
      isTurnRunning: () => false,
    }));
    const getCodexHistoryHasProductPrompt = vi.fn(async () => false);
    const onCodexProductPromptDelivery = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        getCodexHistoryHasProductPrompt,
        onCodexProductPromptDelivery,
      },
    });

    await maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-1',
    });

    expect(getCodexHistoryHasProductPrompt).toHaveBeenCalledWith('session-1');
    expect(startSession).toHaveBeenCalledWith(expect.objectContaining({
      sessionId: 'session-1',
      codexHistoryHasProductPrompt: false,
    }));
    expect(onCodexProductPromptDelivery).toHaveBeenCalledWith({
      sessionId: 'session-1',
      threadId: 'thread-1',
      historyHasProductPrompt: false,
    });
  });

  it('does not persist codex prompt state for broken handles', async () => {
    const startSession = vi.fn(async () => ({
      id: '<failed>',
      agentKind: 'codex',
      model: 'gpt-5.4',
      codexProductPromptDelivery: {
        threadId: 'thread-1',
        historyHasProductPrompt: true,
      },
      async send() {},
      async abort() {},
      async close() {},
      async *events() {},
      getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
      setInteractionResolver() {},
      isTurnRunning: () => false,
    }));
    const onCodexProductPromptDelivery = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: { codex: createAgent(startSession) },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: { onCodexProductPromptDelivery },
    });

    await maker.createSession({
      id: 'session-1',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-1',
    });

    expect(onCodexProductPromptDelivery).not.toHaveBeenCalled();
  });

  it('routes codex prompt lifecycle hooks only through createSession resume success paths', async () => {
    const codexStartSession = vi.fn(async (opts: CreateSessionOptions) => {
      if (opts.id === 'codex-resume') {
        return createHandle({
          id: 'thread-resume',
          delivery: { threadId: 'thread-resume', historyHasProductPrompt: true },
        });
      }
      if (opts.id === 'codex-failed') {
        return createHandle({
          id: '<failed>',
          delivery: { threadId: 'thread-failed', historyHasProductPrompt: false },
        });
      }
      return createHandle({ id: 'thread-new' });
    });
    const claudeStartSession = vi.fn(async () => createHandle({
      id: 'claude-thread',
      agentKind: 'claude-code',
    }));
    const getCodexHistoryHasProductPrompt = vi.fn(async () => false);
    const onCodexProductPromptDelivery = vi.fn(async () => undefined);
    const maker = new Maker({
      agents: {
        codex: createAgent(codexStartSession),
        'claude-code': createAgent(claudeStartSession, 'claude-code'),
      },
      storage: createStorage(),
      logger: createLogger(),
      lifecycleHooks: {
        getCodexHistoryHasProductPrompt,
        onCodexProductPromptDelivery,
      },
    });

    await maker.createSession({
      id: 'codex-resume',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-resume',
    });
    await maker.createSession({
      id: 'codex-failed',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
      resumeSessionId: 'thread-failed',
    });
    await maker.createSession({
      id: 'codex-new',
      agentKind: 'codex',
      workingDir: '/repo',
      model: 'gpt-5.4',
    });
    await maker.createSession({
      id: 'claude-resume',
      agentKind: 'claude-code',
      workingDir: '/repo',
      model: 'claude-sonnet-4-5',
      resumeSessionId: 'claude-thread',
    });

    expect(getCodexHistoryHasProductPrompt).toHaveBeenCalledTimes(2);
    expect(getCodexHistoryHasProductPrompt).toHaveBeenNthCalledWith(1, 'codex-resume');
    expect(getCodexHistoryHasProductPrompt).toHaveBeenNthCalledWith(2, 'codex-failed');
    expect(codexStartSession).toHaveBeenCalledWith(expect.objectContaining({
      id: 'codex-resume',
      sessionId: 'codex-resume',
      resumeSessionId: 'thread-resume',
      codexHistoryHasProductPrompt: false,
    }));
    expect(onCodexProductPromptDelivery).toHaveBeenCalledTimes(1);
    expect(onCodexProductPromptDelivery).toHaveBeenCalledWith({
      sessionId: 'codex-resume',
      threadId: 'thread-resume',
      historyHasProductPrompt: true,
    });
  });
});

describe('Maker session capabilities', () => {
  it('persists dialogue workspace kind separately from the allocated working directory', async () => {
    const storage = createStorage();
    const maker = new Maker({
      agents: { codex: createAgent(async () => createHandle({ id: 'dialogue-thread' }), 'codex') },
      storage,
      logger: createLogger(),
    });

    await maker.createSession({
      id: 'dialogue-session',
      agentKind: 'codex',
      workingDir: '/userData/dialogues/2026-06-29/dialogue-session',
      workspaceKind: 'dialogue',
      model: 'gpt-5.4',
    });

    await expect(maker.getSessionMeta('dialogue-session')).resolves.toMatchObject({
      id: 'dialogue-session',
      workDir: '/userData/dialogues/2026-06-29/dialogue-session',
      workspaceKind: 'dialogue',
    });
  });

  it('marks remote Codex session rewind as platform-limited without mutating agent capabilities', async () => {
    const agent = createAgent(async () => createHandle({ id: 'remote-thread' }), 'codex');
    agent.capabilities.rewind = { supported: true };
    const maker = new Maker({
      agents: { codex: agent },
      storage: createStorage(),
      logger: createLogger(),
    });

    const session = await maker.createSession({
      id: 'remote-session',
      agentKind: 'codex',
      workingDir: '/remote/repo',
      model: 'gpt-5.4',
      remoteHostId: 'remote-1',
    });

    expect(session.capabilities.rewind).toMatchObject({
      supported: false,
      reason: 'platform-limited',
    });
    expect(agent.capabilities.rewind).toEqual({ supported: true });
  });
});

describe('Session engine MCP tool status', () => {
  it('reads the live engine and reports an engine without a status entry as null', async () => {
    const read = vi.fn(async () => ({ state: 'connected' as const, tools: [{ name: 'search' }] }));
    const codex = createAgent(async (opts) => ({
      ...createHandle({ id: opts.sessionId ?? 'with-status' }), readMcpServerTools: read,
    }));
    const pi = createAgent(async (opts) => createHandle({ id: opts.sessionId ?? 'plain', agentKind: 'pi' }), 'pi');
    const maker = new Maker({ agents: { codex, pi }, storage: createStorage(), logger: createLogger() });
    try {
      const withStatus = await maker.createSession({ id: 'with-status', agentKind: 'codex', workingDir: '/repo', model: 'm' });
      const plain = await maker.createSession({ id: 'plain', agentKind: 'pi', workingDir: '/repo', model: 'm' });
      expect(await withStatus.readMcpServerTools('custom_omc')).toEqual({ state: 'connected', tools: [{ name: 'search' }] });
      expect(read).toHaveBeenCalledWith('custom_omc');
      expect(await plain.readMcpServerTools('custom_omc')).toBeNull();
    } finally { await maker.shutdown(); }
  });
});

describe('Maker Pi runtime skill status', () => {
  it('keeps managed skills pinned to the active session launch snapshot', async () => {
    const managedPath = '/managed/context-mode/SKILL.md';
    const agent = createAgent(async (opts) => {
      const handle = createHandle({ id: `pi-${opts.sessionId}`, agentKind: 'pi' });
      handle.getRuntimeCapabilities = () => ({
        sessionId: opts.sessionId,
        capturedAt: '2026-08-16T00:00:00.000Z',
        generation: 1,
        status: 'loaded',
        source: 'pi:get_commands',
        commands: [],
        managedPackageSkills: [
          {
            sourcePath: managedPath,
            name: 'context-mode-old',
            description: 'Launch-time name',
            runtimeCommandName: 'skill:context-mode-old',
          },
          {
            sourcePath: '/managed/unproven/SKILL.md',
            name: 'unproven-at-launch',
          },
        ],
      });
      return handle;
    }, 'pi');
    agent.listAgentSkills = vi.fn(async () => ({
      skills: [
        {
          kind: 'agent-skill' as const,
          name: 'context-mode-renamed',
          source: 'skill' as const,
          scope: 'user' as const,
          path: managedPath,
          runtimeStatus: 'approved' as const,
          runtimeCommandName: 'skill:context-mode-renamed',
        },
        {
          kind: 'agent-skill' as const,
          name: 'installed-after-start',
          source: 'skill' as const,
          scope: 'user' as const,
          path: '/managed/new/SKILL.md',
          runtimeStatus: 'approved' as const,
          runtimeCommandName: 'skill:installed-after-start',
        },
      ],
    }));
    const maker = new Maker({
      agents: { pi: agent },
      storage: createStorage(),
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'managed-snapshot',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'm',
    });

    const active = await maker.listAgentSkills('pi', {
      workingDir: '/repo',
      sessionId: 'managed-snapshot',
    });
    const preview = await maker.listAgentSkills('pi', { workingDir: '/repo' });

    expect(active.skills).toEqual([
      expect.objectContaining({
        name: 'context-mode-old',
        path: managedPath,
        origin: 'package',
        runtimeStatus: 'loaded',
        runtimeCommandName: 'skill:context-mode-old',
      }),
      expect.objectContaining({
        name: 'unproven-at-launch',
        runtimeStatus: 'unknown',
        origin: 'package',
      }),
    ]);
    expect(active.skills.some((skill) => skill.name === 'installed-after-start')).toBe(false);
    expect(preview.skills.map((skill) => skill.name)).toEqual([
      'context-mode-renamed',
      'installed-after-start',
    ]);
    expect(preview.skills.every((skill) => skill.runtimeStatus === 'approved')).toBe(true);
  });

  it('fails partial project mappings closed without leaking them across live sessions', async () => {
    const agent = createAgent(async (opts) => {
      const handle = createHandle({ id: `pi-${opts.sessionId}`, agentKind: 'pi' });
      handle.getRuntimeCapabilities = () => ({
        sessionId: opts.sessionId,
        capturedAt: '2026-08-08T00:00:00.000Z',
        generation: 1,
        status: 'loaded',
        source: 'pi:get_commands',
        projectResources: {
          status: 'approved',
          reason: 'runtime-skills-confirmed',
          approvalRevision: `rev-${opts.sessionId}`,
          requestedSkillCount: 1,
          loadedSkillCount: 1,
          loadedSkills: [{
            sourcePath: `/repo/.pi/skills/${opts.sessionId}-skill`,
            runtimePath: `/isolated/${opts.sessionId}/project-resources/skills/0/${opts.sessionId}-skill`,
            commandName: `skill:${opts.sessionId}-frontmatter-name`,
          }],
        },
        commands: [
          {
            name: `skill:${opts.sessionId}-frontmatter-name`,
            source: 'skill',
            sourceInfo: {
              source: 'local',
              scope: 'temporary',
              baseDir: `/isolated/${opts.sessionId}/project-resources/skills/0/${opts.sessionId}-skill`,
              path: `/isolated/${opts.sessionId}/project-resources/skills/0/${opts.sessionId}-skill/SKILL.md`,
            },
          },
          {
            name: 'skill:single-file-frontmatter-name',
            source: 'skill',
            sourceInfo: {
              source: 'local',
              scope: 'temporary',
              baseDir: '/repo/.pi/skills',
              path: '/repo/.pi/skills/single-file.md',
            },
          },
          {
            name: 'skill:user-collision',
            source: 'skill',
            sourceInfo: { source: 'auto', scope: 'user', baseDir: '/home/.agents/skills' },
          },
          {
            name: 'skill:malformed-collision',
            source: 'skill',
            sourceInfo: {
              source: 'local',
              scope: 'temporary',
              baseDir: '/repo/.pi/skills/malformed-collision',
              path: '/other/SKILL.md',
            },
          },
        ],
      });
      return handle;
    }, 'pi');
    const projectSkill = (name: string, skillPath: string) => ({
      kind: 'agent-skill' as const,
      name,
      source: 'skill' as const,
      scope: 'repo' as const,
      path: skillPath,
      runtimeStatus: 'discovered' as const,
    });
    agent.listAgentSkills = vi.fn(async () => ({
      skills: [
        projectSkill('one-skill', '/repo/.pi/skills/one-skill'),
        projectSkill('one-skill', '/repo/.agents/skills/one-skill'),
        projectSkill('two-skill', '/repo/.pi/skills/two-skill'),
        projectSkill('single-file', '/repo/.pi/skills/single-file.md'),
        projectSkill('user-collision', '/repo/.pi/skills/user-collision'),
        projectSkill('malformed-collision', '/repo/.pi/skills/malformed-collision'),
      ],
    }));
    const maker = new Maker({
      agents: { pi: agent },
      storage: createStorage(),
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'one',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'm',
    });
    await maker.createSession({
      id: 'two',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'm',
    });

    const one = await maker.listAgentSkills('pi', { workingDir: '/repo', sessionId: 'one' });
    const two = await maker.listAgentSkills('pi', { workingDir: '/repo', sessionId: 'two' });
    const preview = await maker.listAgentSkills('pi', { workingDir: '/repo' });
    const wrongProject = await maker.listAgentSkills('pi', {
      workingDir: '/other-repo',
      sessionId: 'one',
    });

    expect(one.skills.map((skill) => [skill.name, skill.runtimeStatus])).toEqual([
      ['one-skill', 'discovered'],
      ['one-skill', 'discovered'],
      ['two-skill', 'discovered'],
      ['single-file', 'loaded'],
      ['user-collision', 'discovered'],
      ['malformed-collision', 'discovered'],
    ]);
    expect(one.skills[0]).toMatchObject({
      name: 'one-skill',
      runtimeStatus: 'discovered',
    });
    expect(one.skills[3]).toMatchObject({
      name: 'single-file',
      runtimeStatus: 'loaded',
      runtimeCommandName: 'skill:single-file-frontmatter-name',
    });
    expect(two.skills.map((skill) => [skill.name, skill.runtimeStatus])).toEqual([
      ['one-skill', 'discovered'],
      ['one-skill', 'discovered'],
      ['two-skill', 'discovered'],
      ['single-file', 'loaded'],
      ['user-collision', 'discovered'],
      ['malformed-collision', 'discovered'],
    ]);
    expect(one.errors).toContainEqual(expect.objectContaining({
      path: '/repo/.pi/skills/one-skill',
    }));
    expect(two.errors).toContainEqual(expect.objectContaining({
      path: '/repo/.pi/skills/two-skill',
    }));
    expect(preview.skills.every((skill) => skill.runtimeStatus === 'discovered')).toBe(true);
    expect(wrongProject.skills.every((skill) => skill.runtimeStatus === 'discovered')).toBe(true);
  });

  it('marks Windows project-scope --skill loaded when frontmatter name differs from the folder', async () => {
    const agent = createAgent(async (opts) => {
      const handle = createHandle({ id: `pi-${opts.sessionId}`, agentKind: 'pi' });
      handle.getRuntimeCapabilities = () => ({
        sessionId: opts.sessionId,
        capturedAt: '2026-09-14T00:00:00.000Z',
        generation: 1,
        status: 'loaded',
        source: 'pi:get_commands',
        commands: [{
          name: 'skill:frontmatter-alias',
          source: 'skill',
          sourceInfo: {
            source: 'local',
            scope: 'project',
            baseDir: '/repo/.pi/skills/folder-name',
            path: '/repo/.pi/skills/folder-name/SKILL.md',
          },
        }],
      });
      return handle;
    }, 'pi');
    agent.listAgentSkills = vi.fn(async () => ({
      skills: [{
        kind: 'agent-skill' as const,
        name: 'folder-name',
        source: 'skill' as const,
        scope: 'repo' as const,
        path: '/repo/.pi/skills/folder-name/SKILL.md',
        runtimeStatus: 'discovered' as const,
      }],
    }));
    const maker = new Maker({
      agents: { pi: agent },
      storage: createStorage(),
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'win-alias',
      agentKind: 'pi',
      workingDir: '/repo',
      model: 'm',
    });
    const listed = await maker.listAgentSkills('pi', {
      workingDir: '/repo',
      sessionId: 'win-alias',
    });
    expect(listed.skills[0]).toMatchObject({
      name: 'folder-name',
      runtimeStatus: 'loaded',
      runtimeCommandName: 'skill:frontmatter-alias',
    });
  });

  it('keeps a project skill discovered when its source no longer matches the launch snapshot', async () => {
    const root = realpathSync.native(mkdtempSync(path.join(tmpdir(), 'maker-pi-skill-source-')));
    const repoRoot = path.join(root, 'repo');
    const sourcePath = path.join(repoRoot, '.pi', 'skills', 'demo');
    const runtimePath = path.join(root, 'config-home', 'project-resources', 'skills', '0', 'demo');
    const writeSkill = (skillRoot: string, skillContent: string, assetContent: string): void => {
      mkdirSync(path.join(skillRoot, 'assets'), { recursive: true });
      writeFileSync(path.join(skillRoot, 'SKILL.md'), skillContent);
      writeFileSync(path.join(skillRoot, 'assets', 'fixture.txt'), assetContent);
    };
    try {
      writeSkill(sourcePath, '# approved\n', 'approved asset\n');
      writeSkill(runtimePath, '# approved\n', 'approved asset\n');
      const snapshotFingerprint = await fingerprintPiProjectSkillEntrypoint(runtimePath, runtimePath);
      const sourceFingerprint = await fingerprintPiProjectSkillEntrypoint(sourcePath, repoRoot);
      expect(snapshotFingerprint?.contentDigest).toMatch(/^[a-f0-9]{64}$/);
      expect(sourceFingerprint?.sourceStateDigest).toMatch(/^[a-f0-9]{64}$/);

      const agent = createAgent(async (opts) => {
        const handle = createHandle({ id: `pi-${opts.sessionId}`, agentKind: 'pi' });
        handle.getRuntimeCapabilities = () => ({
          sessionId: opts.sessionId,
          capturedAt: '2026-08-11T00:00:00.000Z',
          generation: 1,
          status: 'loaded',
          source: 'pi:get_commands',
          projectResources: {
            status: 'approved',
            reason: 'runtime-skills-confirmed',
            approvalRevision: 'rev-source-snapshot',
            requestedSkillCount: 1,
            loadedSkillCount: 1,
            loadedSkills: [{
              sourcePath,
              runtimePath,
              commandName: 'skill:demo',
              snapshotDigest: snapshotFingerprint!.contentDigest,
              sourceFingerprint: sourceFingerprint!.sourceStateDigest,
              canonicalRepoRoot: repoRoot,
            }],
          },
          commands: [{
            name: 'skill:demo',
            source: 'skill',
            sourceInfo: {
              source: 'local',
              scope: 'temporary',
              baseDir: runtimePath,
              path: path.join(runtimePath, 'SKILL.md'),
            },
          }],
        });
        return handle;
      }, 'pi');
      agent.listAgentSkills = vi.fn(async () => ({
        skills: [{
          kind: 'agent-skill' as const,
          name: 'demo',
          source: 'skill' as const,
          scope: 'repo' as const,
          path: sourcePath,
          runtimeStatus: 'discovered' as const,
        }],
      }));
      const maker = new Maker({
        agents: { pi: agent },
        storage: createStorage(),
        logger: createLogger(),
      });
      await maker.createSession({
        id: 'source-snapshot',
        agentKind: 'pi',
        workingDir: repoRoot,
        model: 'm',
      });

      const initial = await maker.listAgentSkills('pi', {
        workingDir: repoRoot,
        sessionId: 'source-snapshot',
      });
      expect(initial.skills[0]).toMatchObject({ runtimeStatus: 'loaded' });

      const realRealpath = fsPromises.realpath.bind(fsPromises);
      let delayed = false;
      vi.spyOn(fsPromises, 'realpath').mockImplementation(async (...args) => {
        if (!delayed) {
          delayed = true;
          // real-wait: keep the realpath operation pending to exercise the cancellation race.
          await new Promise((resolve) => setTimeout(resolve, 300));
        }
        return realRealpath(...args);
      });
      const slowFilesystem = await maker.listAgentSkills('pi', {
        workingDir: repoRoot,
        sessionId: 'source-snapshot',
      });
      expect(delayed).toBe(true);
      expect(slowFilesystem.skills[0]).toMatchObject({ runtimeStatus: 'loaded' });
      vi.restoreAllMocks();

      writeFileSync(path.join(sourcePath, 'assets', 'fixture.txt'), 'changed! asset\n');
      const changedAsset = await maker.listAgentSkills('pi', {
        workingDir: repoRoot,
        sessionId: 'source-snapshot',
      });
      expect(changedAsset.skills[0]).toMatchObject({ runtimeStatus: 'discovered' });
      expect(changedAsset.errors).toContainEqual(expect.objectContaining({ path: sourcePath }));

      writeFileSync(path.join(sourcePath, 'SKILL.md'), '# changed in place\n');
      const changedFile = await maker.listAgentSkills('pi', {
        workingDir: repoRoot,
        sessionId: 'source-snapshot',
      });
      expect(changedFile.skills[0]).toMatchObject({ runtimeStatus: 'discovered' });
      expect(changedFile.errors).toContainEqual(expect.objectContaining({ path: sourcePath }));

      rmSync(sourcePath, { recursive: true, force: true });
      writeSkill(sourcePath, '# approved\n', 'replacement asset\n');
      const replacedDirectory = await maker.listAgentSkills('pi', {
        workingDir: repoRoot,
        sessionId: 'source-snapshot',
      });
      expect(replacedDirectory.skills[0]).toMatchObject({ runtimeStatus: 'discovered' });
      expect(replacedDirectory.errors?.[0]?.message).toContain('restart the session');
    } finally {
      vi.restoreAllMocks();
      rmSync(root, { recursive: true, force: true });
    }
  });
});

describe('Session turn send guard', () => {
  it('reserves the turn synchronously while handle.send is still awaiting', async () => {
    let publishRelease!: (release: () => void) => void;
    const releaseReady = new Promise<() => void>((resolve) => {
      publishRelease = resolve;
    });
    let handleTurnRunning = false;
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => {
      await new Promise<void>((resolve) => {
        publishRelease(resolve);
      });
      handleTurnRunning = true;
    });
    handle.isTurnRunning = () => handleTurnRunning;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: path.join('workspace', 'repo'),
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first');
    await Promise.resolve();

    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });
    expect(handle.send).toHaveBeenCalledTimes(1);

    const releaseSend = await releaseReady;
    releaseSend();
    await firstSend;

    expect(session.isTurnRunning()).toBe(true);
  });

  it('keeps the reservation when abort runs before handle.send observes a running turn', async () => {
    let publishRelease!: (release: () => void) => void;
    const releaseReady = new Promise<() => void>((resolve) => {
      publishRelease = resolve;
    });
    let handleTurnRunning = false;
    let sendCalls = 0;
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => {
      sendCalls += 1;
      if (sendCalls > 1) {
        throw new Error('second send reached handle');
      }
      await new Promise<void>((resolve) => {
        publishRelease(() => {
          handleTurnRunning = true;
          resolve();
        });
      });
    });
    handle.isTurnRunning = () => handleTurnRunning;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: path.join('workspace', 'repo'),
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first');
    const releaseSend = await releaseReady;

    await session.abort();

    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });
    expect(handle.send).toHaveBeenCalledTimes(1);

    releaseSend();
    await firstSend;
  });

  it('cancels a dispatching reservation before handle.send accepts input', async () => {
    let releaseSend!: () => void;
    let resolveSendStarted!: () => void;
    let sendOpts: Parameters<AgentSessionHandle['send']>[1];
    const sendStarted = new Promise<void>((resolve) => {
      resolveSendStarted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async (_message, opts) => {
      sendOpts = opts;
      resolveSendStarted();
      await new Promise<void>((resolve, reject) => {
        releaseSend = resolve;
        opts?.signal?.addEventListener('abort', () => reject(new Error('send cancelled')), { once: true });
      });
    });
    handle.abort = vi.fn(async () => undefined);
    handle.isTurnRunning = () => false;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: path.join('workspace', 'repo'),
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first');
    await sendStarted;
    await session.abort();
    const signalWasAborted = sendOpts?.signal?.aborted;
    releaseSend();

    await expect(firstSend).resolves.toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
    expect(signalWasAborted).toBe(true);
    expect(handle.abort).toHaveBeenCalledTimes(1);
  });

  it('does not release a dispatching reservation from an older terminal event', async () => {
    let releaseSend!: () => void;
    let resolveSendStarted!: () => void;
    let sendCalls = 0;
    const sendStarted = new Promise<void>((resolve) => {
      resolveSendStarted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    const events = createAsyncQueue<AgentEvent>();
    handle.events = () => events;
    handle.send = vi.fn(async () => {
      sendCalls += 1;
      if (sendCalls > 1) {
        throw new Error('second send reached handle');
      }
      resolveSendStarted();
      await new Promise<void>((resolve) => {
        releaseSend = resolve;
      });
    });
    handle.isTurnRunning = () => false;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalEventObserved = new Promise<void>((resolveEvent) => {
      const unsubscribe = session.onEvent(() => {
        unsubscribe();
        resolveEvent();
      });
    });

    const firstSend = session.send('first');
    await sendStarted;
    events.push({ type: 'done', data: {}, source: 'codex' });
    await terminalEventObserved;

    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });

    releaseSend();
    await expect(firstSend).resolves.toEqual({ accepted: true });
    events.end();
  });

  it('does not start handle.send when onAccepted fails', async () => {
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    const acceptError = new Error('accept failed');
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    await expect(session.send('first', { onAccepted: () => { throw acceptError; } })).rejects.toBe(acceptError);
    expect(handle.send).not.toHaveBeenCalled();
    await expect(session.send('second')).resolves.toEqual({ accepted: true });
    expect(handle.send).toHaveBeenCalledTimes(1);
  });

  it('does not run accepted persistence or provider send when beforeProviderStart fails', async () => {
    const beforeError = new Error('durable acceptance CAS failed');
    const handle = createHandle({ id: 'thread-before-provider-start' });
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'before-provider-start-failure',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const onAccepted = vi.fn();

    await expect(
      session.send('first', {
        beforeProviderStart: () => {
          throw beforeError;
        },
        onAccepted,
      }),
    ).rejects.toBe(beforeError);

    expect(onAccepted).not.toHaveBeenCalled();
    expect(handle.send).not.toHaveBeenCalled();
    await expect(session.send('second')).resolves.toEqual({ accepted: true });
  });

  it('keeps the session reusable when provider option preflight rejects before dispatch', async () => {
    vi.useFakeTimers();
    const preflightError = new TurnPermissionPolicyUnsupportedError('pi', 'ask');
    const handle = createHandle({ id: 'thread-send-preflight' });
    handle.validateSendOptions = vi.fn(() => {
      throw preflightError;
    });
    handle.send = vi.fn(async () => undefined);
    handle.close = vi.fn(async () => undefined);
    const session = new Session({
      id: 'send-preflight',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const beforeProviderStart = vi.fn();
    const onAccepted = vi.fn();
    const send = () => session.send('message', { beforeProviderStart, onAccepted });

    try {
      await expect(send()).rejects.toBe(preflightError);
      await expect(send()).rejects.toBe(preflightError);
      expect(session.isTurnRunning()).toBe(false);
      expect(session.getStatus()).toBe('active');

      // A pure validateSendOptions failure happens before origin installation,
      // so it must not arm the 250 ms terminal-drain fence or close the Session.
      await vi.advanceTimersByTimeAsync(300);
      await expect(send()).rejects.toBe(preflightError);

      expect(handle.validateSendOptions).toHaveBeenCalledTimes(3);
      expect(beforeProviderStart).not.toHaveBeenCalled();
      expect(onAccepted).not.toHaveBeenCalled();
      expect(handle.send).not.toHaveBeenCalled();
      expect(handle.close).not.toHaveBeenCalled();
      expect(session.getStatus()).toBe('active');
    } finally {
      vi.useRealTimers();
    }
  });

  it('runs reservation state preparation before provider option preflight', async () => {
    const order: string[] = [];
    const handle = createHandle({ id: 'thread-reserved-preflight' });
    handle.validateSendOptions = vi.fn(() => {
      order.push('preflight');
    });
    handle.send = vi.fn(async () => {
      order.push('provider');
    });
    const session = new Session({
      id: 'reserved-preflight',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    await expect(
      session.send('first', {
        afterTurnReserved: () => {
          order.push('reserved');
        },
      }),
    ).resolves.toEqual({ accepted: true });

    expect(order).toEqual(['reserved', 'preflight', 'provider']);
  });

  it('stops before validation or durable acceptance when cancelled during reservation preparation', async () => {
    let releasePreparation!: () => void;
    const preparation = new Promise<void>((resolve) => {
      releasePreparation = resolve;
    });
    const handle = createHandle({ id: 'thread-reserved-cancelled' });
    handle.validateSendOptions = vi.fn();
    handle.send = vi.fn(async () => undefined);
    handle.abort = vi.fn(async () => undefined);
    const session = new Session({
      id: 'reserved-cancelled',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const beforeProviderStart = vi.fn();
    const onAccepted = vi.fn();
    const sending = session.send('first', {
      afterTurnReserved: () => preparation,
      beforeProviderStart,
      onAccepted,
    });
    await Promise.resolve();

    await session.abort();
    releasePreparation();

    await expect(sending).resolves.toEqual({
      accepted: false,
      reason: 'cancelled-before-dispatch',
    });
    expect(handle.validateSendOptions).not.toHaveBeenCalled();
    expect(beforeProviderStart).not.toHaveBeenCalled();
    expect(onAccepted).not.toHaveBeenCalled();
    expect(handle.send).not.toHaveBeenCalled();
  });

  it('does not run reservation preparation when the external signal is already aborted', async () => {
    const handle = createHandle({ id: 'thread-pre-cancelled' });
    handle.send = vi.fn(handle.send);
    const session = new Session({
      id: 'reserved-pre-cancelled',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const afterTurnReserved = vi.fn();
    const controller = new AbortController();
    controller.abort();

    await expect(
      session.send('first', { signal: controller.signal, afterTurnReserved }),
    ).resolves.toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
    expect(afterTurnReserved).not.toHaveBeenCalled();
    expect(handle.send).not.toHaveBeenCalled();
  });

  it('does not run reservation state preparation when another turn is active', async () => {
    let releaseSend!: () => void;
    const sendBarrier = new Promise<void>((resolve) => {
      releaseSend = resolve;
    });
    const handle = createHandle({ id: 'thread-reserved-busy' });
    handle.send = vi.fn(async () => sendBarrier);
    const session = new Session({
      id: 'reserved-busy',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first');
    await vi.waitFor(() => expect(handle.send).toHaveBeenCalledOnce());
    const afterTurnReserved = vi.fn();

    await expect(session.send('second', { afterTurnReserved })).rejects.toMatchObject({
      code: 'SESSION_RUNNING',
    });
    expect(afterTurnReserved).not.toHaveBeenCalled();

    releaseSend();
    await expect(firstSend).resolves.toEqual({ accepted: true });
  });

  it('awaits beforeProviderStart before accepted persistence and provider dispatch', async () => {
    const order: string[] = [];
    let releaseBarrier!: () => void;
    const barrier = new Promise<void>((resolve) => {
      releaseBarrier = resolve;
    });
    const handle = createHandle({ id: 'thread-before-provider-order' });
    handle.send = vi.fn(async () => {
      order.push('provider');
    });
    const session = new Session({
      id: 'before-provider-start-order',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const sending = session.send('first', {
      beforeProviderStart: async () => {
        order.push('barrier-start');
        await barrier;
        order.push('barrier-end');
      },
      onAccepted: () => {
        order.push('accepted');
      },
    });
    await vi.waitFor(() => expect(order).toEqual(['barrier-start']));
    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });

    releaseBarrier();
    await expect(sending).resolves.toEqual({ accepted: true });
    expect(order).toEqual(['barrier-start', 'barrier-end', 'accepted', 'provider']);
  });

  it('awaits the host turn lifecycle barrier and releases an undispatched generation', async () => {
    const order: string[] = [];
    const handle = createHandle({ id: 'thread-host-turn-lifecycle' });
    handle.send = vi.fn(async () => {
      order.push('provider');
    });
    const session = new Session({
      id: 'host-turn-lifecycle',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    session.setTurnLifecycleObserver({
      beforeProviderStart: async (turnGeneration) => {
        order.push(`host:${turnGeneration}`);
      },
      onUndispatched: async (turnGeneration) => {
        order.push(`undispatched:${turnGeneration}`);
      },
      onTerminal: vi.fn(),
    });

    await expect(
      session.send('first', {
        beforeProviderStart: () => {
          order.push('caller');
        },
        onAccepted: () => {
          order.push('accepted');
          throw new Error('persist failed');
        },
      }),
    ).rejects.toThrow('persist failed');

    expect(order).toEqual(['host:1', 'caller', 'accepted', 'undispatched:1']);
    expect(handle.send).not.toHaveBeenCalled();
  });

  it('reports the exact observed generation before terminal event listeners', async () => {
    const events = createAsyncQueue<AgentEvent>();
    const handle = createHandle({ id: 'thread-host-turn-terminal' });
    handle.events = () => events;
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'host-turn-terminal',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const order: string[] = [];
    let observerEvent: AgentEvent | null = null;
    let listenerEvent: AgentEvent | null = null;
    session.setTurnLifecycleObserver({
      beforeProviderStart: vi.fn(),
      onUndispatched: vi.fn(),
      onTerminal: ({ turnGeneration, event, isCurrentGeneration }) => {
        observerEvent = event;
        order.push(`terminal:${turnGeneration}:${isCurrentGeneration}`);
      },
    });
    const terminalObserved = new Promise<void>((resolve) => {
      const unsubscribe = session.onEvent((event) => {
        listenerEvent = event;
        order.push('listener');
        unsubscribe();
        resolve();
      });
    });

    await session.send('first');
    events.push({ type: 'done', data: {}, source: 'codex' });
    await terminalObserved;

    expect(order).toEqual(['terminal:1:true', 'listener']);
    expect(listenerEvent).toBe(observerEvent);
    events.end();
  });

  it('does not end the foreground lifecycle for a background terminal event', async () => {
    const events = createAsyncQueue<AgentEvent>();
    const handle = createHandle({ id: 'thread-host-turn-background-terminal' });
    handle.events = () => events;
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'host-turn-background-terminal',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const onTerminal = vi.fn();
    session.setTurnLifecycleObserver({
      beforeProviderStart: vi.fn(),
      onUndispatched: vi.fn(),
      onTerminal,
    });
    const backgroundObserved = new Promise<void>((resolve) => {
      const unsubscribe = session.onEvent((event) => {
        if (event.turnScope !== 'background') return;
        unsubscribe();
        resolve();
      });
    });

    await session.send('first');
    events.push({ type: 'done', data: {}, source: 'codex', turnScope: 'background' });
    await backgroundObserved;

    expect(onTerminal).not.toHaveBeenCalled();
    events.end();
  });

  it('does not persist acceptance when cancelled during the pre-provider barrier', async () => {
    let releaseBarrier!: () => void;
    const barrier = new Promise<void>((resolve) => {
      releaseBarrier = resolve;
    });
    const handle = createHandle({ id: 'thread-before-provider-cancelled' });
    handle.send = vi.fn(async () => undefined);
    handle.abort = vi.fn(async () => undefined);
    const session = new Session({
      id: 'before-provider-cancelled',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const onAccepted = vi.fn();
    const sending = session.send('first', {
      beforeProviderStart: () => barrier,
      onAccepted,
    });
    await Promise.resolve();

    await session.abort();
    releaseBarrier();

    await expect(sending).resolves.toEqual({
      accepted: false,
      reason: 'cancelled-before-dispatch',
    });
    expect(onAccepted).not.toHaveBeenCalled();
    expect(handle.send).not.toHaveBeenCalled();
  });

  it('runs onDispatching after acceptance and immediately before vendor send', async () => {
    const calls: string[] = [];
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => {
      calls.push('vendor');
    });
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    await expect(session.send('first', {
      onAccepted: () => {
        calls.push('accepted');
      },
      onDispatching: () => {
        calls.push('dispatching');
      },
    })).resolves.toEqual({ accepted: true });

    expect(calls).toEqual(['accepted', 'dispatching', 'vendor']);
  });

  it('keeps the reservation while onAccepted is awaiting', async () => {
    let releaseAccepted!: () => void;
    const acceptedReady = new Promise<void>((resolve) => {
      releaseAccepted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first', { onAccepted: () => acceptedReady });
    await Promise.resolve();

    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });
    expect(handle.send).not.toHaveBeenCalled();

    releaseAccepted();
    await firstSend;
    expect(handle.send).toHaveBeenCalledTimes(1);
  });

  it('does not release an accepting reservation from an older terminal event', async () => {
    let releaseAccepted!: () => void;
    const acceptedReady = new Promise<void>((resolve) => {
      releaseAccepted = resolve;
    });
    const events = createAsyncQueue<AgentEvent>();
    const handle = createHandle({ id: 'thread-1' });
    handle.events = () => events;
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalEventObserved = new Promise<void>((resolve) => {
      const unsubscribe = session.onEvent(() => {
        unsubscribe();
        resolve();
      });
    });

    const firstSend = session.send('first', { onAccepted: () => acceptedReady });
    await Promise.resolve();
    events.push({ type: 'status', data: { isRunning: false }, source: 'codex' });
    await terminalEventObserved;

    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });
    expect(handle.send).not.toHaveBeenCalled();

    releaseAccepted();
    await firstSend;
    expect(handle.send).toHaveBeenCalledTimes(1);
    events.end();
  });

  it('does not start handle.send when abort happens while onAccepted is awaiting', async () => {
    let releaseAccepted!: () => void;
    const acceptedReady = new Promise<void>((resolve) => {
      releaseAccepted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.abort = vi.fn(async () => undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first', { onAccepted: () => acceptedReady });
    await Promise.resolve();

    await session.abort();
    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });

    releaseAccepted();
    await expect(firstSend).resolves.toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
    expect(handle.send).not.toHaveBeenCalled();

    await session.send('second');
    expect(handle.send).toHaveBeenCalledTimes(1);
  });

  it('emits a terminal error and closes the session after the event iterator crashes', async () => {
    const crash = new Error('events crashed');
    let crashIterator!: () => void;
    const crashReady = new Promise<void>((resolve) => {
      crashIterator = resolve;
    });
    let releaseClose!: () => void;
    const closeReady = new Promise<void>((resolve) => {
      releaseClose = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.close = vi.fn(async () => closeReady);
    const crashingEvents: AsyncIterable<never> = {
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            await crashReady;
            throw crash;
          },
        };
      },
    };
    handle.events = () => crashingEvents;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const order: string[] = [];
    const terminalEvents: AgentEvent[] = [];
    session.onEvent((event) => {
      if (event.type === 'error') {
        terminalEvents.push(event);
        order.push('error');
      }
    });
    let closedObserved = false;
    const statusChanged = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') {
          closedObserved = true;
          order.push('closed');
          resolve();
        }
      });
    });

    await session.send('first');
    crashIterator();
    await Promise.resolve();
    await Promise.resolve();

    expect(terminalEvents).toContainEqual(expect.objectContaining({
      type: 'error',
      data: expect.objectContaining({
        reason: 'session_event_loop_crashed',
        isTerminal: true,
      }),
    }));
    expect(order).toEqual(['error']);
    expect(closedObserved).toBe(false);
    expect(handle.close).toHaveBeenCalledTimes(1);
    expect(session.getStatus()).toBe('active');
    await expect(session.send('second')).rejects.toThrow('is closing');

    releaseClose();
    await statusChanged;
    expect(order).toEqual(['error', 'closed']);
    expect(session.getStatus()).toBe('closed');
    await expect(session.send('third')).rejects.toThrow('is closed');
    expect(handle.send).toHaveBeenCalledTimes(1);
    expect(handle.close).toHaveBeenCalledTimes(1);
  });

  it('does not publish closed when an iterator crash cannot close the handle', async () => {
    const handle = createHandle({ id: 'thread-crash-close-failed' });
    handle.close = vi.fn(async () => {
      throw new Error('transport close failed');
    });
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            throw new Error('events crashed');
          },
        };
      },
    });
    const session = new Session({
      id: 'session-crash-close-failed',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalErrors: AgentEvent[] = [];
    session.onEvent((event) => {
      if (event.type === 'error') terminalErrors.push(event);
    });
    const statusChanged = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'error') resolve();
      });
    });

    await statusChanged;

    expect(terminalErrors).toContainEqual(expect.objectContaining({
      type: 'error',
      data: expect.objectContaining({
        reason: 'session_event_loop_crashed',
        isTerminal: true,
      }),
    }));
    expect(session.getStatus()).toBe('error');
    expect(handle.close).toHaveBeenCalledTimes(1);
  });

  it('emits a terminal error before closing when the event iterator ends during an active turn', async () => {
    let releaseEnd!: () => void;
    const endReady = new Promise<void>((resolve) => {
      releaseEnd = resolve;
    });
    let running = false;
    const handle = createHandle({ id: 'thread-natural-end-active-turn' });
    handle.send = vi.fn(async () => {
      running = true;
    });
    handle.isTurnRunning = () => running;
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            await endReady;
            return { done: true, value: undefined as never };
          },
        };
      },
    });
    const session = new Session({
      id: 'session-natural-end-active-turn',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const order: string[] = [];
    const terminalErrors: AgentEvent[] = [];
    session.onEvent((event) => {
      if (event.type === 'error') {
        terminalErrors.push(event);
        order.push('error');
      }
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') {
          order.push('closed');
          resolve();
        }
      });
    });

    await session.send('first');
    releaseEnd();
    await closed;

    expect(terminalErrors).toContainEqual(expect.objectContaining({
      type: 'error',
      data: expect.objectContaining({
        reason: 'session_event_loop_crashed',
        isTerminal: true,
      }),
    }));
    expect(order).toEqual(['error', 'closed']);
    expect(session.getStatus()).toBe('closed');
  });

  it('clears the turn stall watchdog when the event iterator ends naturally', async () => {
    vi.useFakeTimers();
    try {
      let releaseEnd!: () => void;
      const endReady = new Promise<void>((resolve) => {
        releaseEnd = resolve;
      });
      let running = false;
      const handle = createHandle({ id: 'thread-natural-end' });
      handle.send = vi.fn(async () => {
        running = true;
      });
      handle.isTurnRunning = () => running;
      handle.events = () => ({
        [Symbol.asyncIterator]() {
          let ended = false;
          return {
            async next(): Promise<IteratorResult<AgentEvent>> {
              if (!ended) {
                ended = true;
                await endReady;
                return { done: false, value: { type: 'done', data: {}, source: 'codex' } };
              }
              return { done: true, value: undefined as never };
            },
          };
        },
      });
      const session = new Session({
        id: 'session-natural-end',
        agentKind: 'codex',
        workDir: '/repo',
        handle,
        capabilities: createAgent(async () => handle).capabilities,
        logger: createLogger(),
        turnStallMs: 1_000,
      });
      const closed = new Promise<void>((resolve) => {
        session.onStatusChange((status) => {
          if (status === 'closed') resolve();
        });
      });

      await session.send('first');
      const terminalErrors: AgentEvent[] = [];
      session.onEvent((event) => {
        if (event.type === 'error') terminalErrors.push(event);
      });
      expect(vi.getTimerCount()).toBeGreaterThan(0);

      running = false;
      releaseEnd();
      await closed;
      expect(vi.getTimerCount()).toBe(0);
      expect(terminalErrors).toEqual([]);
      expect(session.wasClosedByRuntime()).toBe(true);
    } finally {
      vi.useRealTimers();
    }
  });

  it('cancels an in-flight send when the event iterator ends naturally', async () => {
    let releaseEnd!: () => void;
    const endReady = new Promise<void>((resolve) => {
      releaseEnd = resolve;
    });
    let sendEntered!: () => void;
    const sendReady = new Promise<void>((resolve) => {
      sendEntered = resolve;
    });
    const handle = createHandle({ id: 'thread-natural-end-pending-send' });
    handle.send = vi.fn(async (_message, opts) => {
      sendEntered();
      await new Promise<void>((resolve) => {
        if (opts?.signal?.aborted) {
          resolve();
          return;
        }
        opts?.signal?.addEventListener('abort', () => resolve(), { once: true });
      });
    });
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            await endReady;
            return { done: true, value: undefined as never };
          },
        };
      },
    });
    const session = new Session({
      id: 'session-natural-end-pending-send',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });
    const terminalErrors: AgentEvent[] = [];

    session.onEvent((event) => {
      if (event.type === 'error') terminalErrors.push(event);
    });
    const sendPromise = session.send('first');
    await sendReady;
    releaseEnd();
    await closed;

    await expect(sendPromise).rejects.toMatchObject({
      code: 'TURN_DISPATCH_UNCONFIRMED',
    });
    expect(terminalErrors).toContainEqual(expect.objectContaining({
      type: 'error',
      data: expect.objectContaining({
        reason: 'session_event_loop_crashed',
        isTerminal: true,
      }),
    }));
    expect(session.getStatus()).toBe('closed');
  });

  it('lets an explicit close own the closed status when the event iterator ends first', async () => {
    let releaseEnd!: () => void;
    const endReady = new Promise<void>((resolve) => {
      releaseEnd = resolve;
    });
    let releaseClose!: () => void;
    const closeReady = new Promise<void>((resolve) => {
      releaseClose = resolve;
    });
    const handle = createHandle({ id: 'thread-natural-end-during-close' });
    handle.close = vi.fn(async () => closeReady);
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            await endReady;
            return { done: true, value: undefined as never };
          },
        };
      },
    });
    const session = new Session({
      id: 'session-natural-end-during-close',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalErrors: AgentEvent[] = [];
    session.onEvent((event) => {
      if (event.type === 'error') terminalErrors.push(event);
    });

    const closePromise = session.close();
    releaseEnd();
    await Promise.resolve();
    await Promise.resolve();

    expect(session.getStatus()).toBe('active');
    expect(terminalErrors).toEqual([]);

    releaseClose();
    await closePromise;
    expect(session.getStatus()).toBe('closed');
    expect(handle.close).toHaveBeenCalledTimes(1);
    // An external close that began first keeps ownership of the cause.
    expect(session.wasClosedByRuntime()).toBe(false);
  });

  it('does not report direct close() or closeIfIdle() as a runtime self-close', async () => {
    const createIdleSession = (id: string) => {
      const handle = createHandle({ id: `thread-${id}` });
      handle.close = vi.fn(async () => undefined);
      return new Session({
        id,
        agentKind: 'codex',
        workDir: '/repo',
        handle,
        capabilities: createAgent(async () => handle).capabilities,
        logger: createLogger(),
      });
    };
    const direct = createIdleSession('session-direct-close');
    await direct.close();
    expect(direct.getStatus()).toBe('closed');
    expect(direct.wasClosedByRuntime()).toBe(false);

    const idle = createIdleSession('session-close-if-idle');
    await expect(idle.closeIfIdle()).resolves.toBe(true);
    expect(idle.getStatus()).toBe('closed');
    expect(idle.wasClosedByRuntime()).toBe(false);
  });

  it('does not revive a closed session when abort is called after the event iterator crashes', async () => {
    const crash = new Error('events crashed');
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.abort = vi.fn(async () => undefined);
    const crashingEvents: AsyncIterable<never> = {
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            throw crash;
          },
        };
      },
    };
    handle.events = () => crashingEvents;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const statusChanged = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    await expect(session.send('first')).rejects.toMatchObject({
      code: 'TURN_DISPATCH_UNCONFIRMED',
    });
    await statusChanged;
    await session.abort();

    expect(session.getStatus()).toBe('closed');
    await expect(session.send('second')).rejects.toThrow('is closed');
    expect(handle.send).toHaveBeenCalledTimes(1);
  });

  it('does not revive a closed session when the event iterator crashes while abort is awaiting', async () => {
    let releaseAbort!: () => void;
    const abortReady = new Promise<void>((resolve) => {
      releaseAbort = resolve;
    });
    let crashIterator!: () => void;
    const crashReady = new Promise<void>((resolve) => {
      crashIterator = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.abort = vi.fn(async () => {
      await abortReady;
    });
    const crashingEvents: AsyncIterable<never> = {
      [Symbol.asyncIterator]() {
        return {
          async next(): Promise<IteratorResult<never>> {
            await crashReady;
            throw new Error('events crashed during abort');
          },
        };
      },
    };
    handle.events = () => crashingEvents;
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const statusChanged = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    await session.send('first');
    const abortPromise = session.abort();
    crashIterator();
    await statusChanged;
    releaseAbort();
    await abortPromise;

    expect(session.getStatus()).toBe('closed');
    await expect(session.send('second')).rejects.toThrow('is closed');
    expect(handle.send).toHaveBeenCalledTimes(1);
  });

  it('does not duplicate a current terminal error when the iterator crashes while provider send is pending', async () => {
    let markSendEntered!: () => void;
    const sendEntered = new Promise<void>((resolve) => {
      markSendEntered = resolve;
    });
    let releaseSend!: () => void;
    const sendReady = new Promise<void>((resolve) => {
      releaseSend = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => {
      markSendEntered();
      await sendReady;
    });
    handle.isTurnRunning = () => false;
    handle.close = vi.fn(async () => undefined);
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        let first = true;
        return {
          async next(): Promise<IteratorResult<AgentEvent>> {
            if (first) {
              first = false;
              await sendEntered;
              return {
                done: false,
                value: {
                  type: 'error',
                  data: {
                    message: 'terminal error before provider send settled',
                    reason: 'original_terminal',
                    isTerminal: true,
                  },
                  source: 'codex',
                },
              };
            }
            throw new Error('events crashed after terminal error');
          },
        };
      },
    });
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalReasons: Array<string | undefined> = [];
    session.onEvent((event) => {
      if (event.type === 'error') {
        terminalReasons.push((event.data as { reason?: string }).reason);
      }
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    const sendPromise = session.send('first');
    await closed;
    releaseSend();
    await expect(sendPromise).rejects.toMatchObject({
      code: 'TURN_DISPATCH_UNCONFIRMED',
    });

    expect(terminalReasons).toEqual(['original_terminal']);
  });

  it('does not attribute a queued prior-turn error to a newer non-Codex dispatch', async () => {
    let releasePriorError!: () => void;
    const priorErrorReady = new Promise<void>((resolve) => {
      releasePriorError = resolve;
    });
    let releaseCrash!: () => void;
    const crashReady = new Promise<void>((resolve) => {
      releaseCrash = resolve;
    });
    let sendEntered!: () => void;
    const sendReady = new Promise<void>((resolve) => {
      sendEntered = resolve;
    });
    let running = false;
    const handle = createHandle({ id: 'thread-queued-prior-error', agentKind: 'claude-code' });
    handle.isTurnRunning = () => running;
    handle.send = vi.fn(async (message, opts) => {
      if (message.content === 'first') {
        running = false;
        return;
      }
      sendEntered();
      await new Promise<void>((resolve) => {
        if (opts?.signal?.aborted) {
          resolve();
          return;
        }
        opts?.signal?.addEventListener('abort', () => resolve(), { once: true });
      });
    });
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        let first = true;
        return {
          async next(): Promise<IteratorResult<AgentEvent>> {
            if (first) {
              first = false;
              await priorErrorReady;
              return {
                done: false,
                value: {
                  type: 'error',
                  data: {
                    message: 'queued prior-turn terminal error',
                    reason: 'prior_terminal',
                    isTerminal: true,
                  },
                  source: 'claude-code',
                },
              };
            }
            await crashReady;
            throw new Error('events crashed during newer dispatch');
          },
        };
      },
    });
    const session = new Session({
      id: 'session-queued-prior-error',
      agentKind: 'claude-code',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle, 'claude-code').capabilities,
      logger: createLogger(),
    });
    const terminalReasons: Array<string | undefined> = [];
    session.onEvent((event) => {
      if (event.type === 'error') {
        terminalReasons.push((event.data as { reason?: string }).reason);
      }
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    await session.send('first');
    const secondSend = session.send('second');
    await sendReady;
    releasePriorError();
    await Promise.resolve();
    releaseCrash();
    await closed;

    await expect(secondSend).rejects.toMatchObject({
      code: 'TURN_DISPATCH_UNCONFIRMED',
    });
    expect(terminalReasons).toEqual(['prior_terminal', 'session_event_loop_crashed']);
  });

  it('reports a crash after a queued prior-turn terminal event when a newer turn is running', async () => {
    let releasePriorDone!: () => void;
    const priorDoneReady = new Promise<void>((resolve) => {
      releasePriorDone = resolve;
    });
    let releaseCrash!: () => void;
    const crashReady = new Promise<void>((resolve) => {
      releaseCrash = resolve;
    });
    let running = false;
    const handle = createHandle({ id: 'thread-1' });
    handle.isTurnRunning = () => running;
    handle.send = vi.fn(async (message) => {
      running = message.content === 'second';
    });
    handle.close = vi.fn(async () => undefined);
    handle.events = () => ({
      [Symbol.asyncIterator]() {
        let first = true;
        return {
          async next(): Promise<IteratorResult<AgentEvent>> {
            if (first) {
              first = false;
              await priorDoneReady;
              return { done: false, value: { type: 'done', data: {}, source: 'codex' } };
            }
            await crashReady;
            throw new Error('events crashed during newer turn');
          },
        };
      },
    });
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const terminalErrors: AgentEvent[] = [];
    session.onEvent((event) => {
      if (event.type === 'error') terminalErrors.push(event);
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    await session.send('first');
    running = false;
    await session.send('second');
    releasePriorDone();
    await Promise.resolve();
    releaseCrash();
    await closed;

    expect(terminalErrors).toContainEqual(expect.objectContaining({
      type: 'error',
      data: expect.objectContaining({
        reason: 'session_event_loop_crashed',
        isTerminal: true,
      }),
    }));
  });

  it('does not call handle.send when close happens during onAccepted', async () => {
    let releaseAccepted!: () => void;
    const acceptedReady = new Promise<void>((resolve) => {
      releaseAccepted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const firstSend = session.send('first', { onAccepted: () => acceptedReady });
    await Promise.resolve();
    await session.close();
    releaseAccepted();

    await expect(firstSend).rejects.toThrow('is closed');
    expect(handle.send).not.toHaveBeenCalled();
    expect(session.isTurnRunning()).toBe(false);
  });

  it('keeps the session open when closeIfIdle loses to an accepting send', async () => {
    let releaseAccepted!: () => void;
    const acceptedReady = new Promise<void>((resolve) => {
      releaseAccepted = resolve;
    });
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.close = vi.fn(async () => undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const send = session.send('first', { onAccepted: () => acceptedReady });
    await Promise.resolve();

    await expect(session.closeIfIdle()).resolves.toBe(false);
    expect(handle.close).not.toHaveBeenCalled();

    releaseAccepted();
    await expect(send).resolves.toEqual({ accepted: true });
  });

  it('rejects a send that starts after closeIfIdle reserves the session close', async () => {
    let releaseClose!: () => void;
    const handle = createHandle({ id: 'thread-1' });
    handle.send = vi.fn(async () => undefined);
    handle.close = vi.fn(() => new Promise<void>((resolve) => {
      releaseClose = resolve;
    }));
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });

    const close = session.closeIfIdle();

    await expect(session.send('late send')).rejects.toThrow('is closing');
    expect(handle.send).not.toHaveBeenCalled();

    releaseClose();
    await expect(close).resolves.toBe(true);
  });

  it('releases the failed send reservation but fences reuse until terminal drain closes', async () => {
    const handle = createHandle({ id: 'thread-1' });
    const firstError = new Error('boom');
    handle.close = vi.fn(async () => undefined);
    handle.send = vi.fn()
      .mockRejectedValueOnce(firstError)
      .mockResolvedValueOnce(undefined);
    const session = new Session({
      id: 'session-1',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: createAgent(async () => handle).capabilities,
      logger: createLogger(),
    });
    const closed = new Promise<void>((resolve) => {
      session.onStatusChange((status) => {
        if (status === 'closed') resolve();
      });
    });

    await expect(session.send('first')).rejects.toBe(firstError);
    expect(session.isTurnRunning()).toBe(false);
    await expect(session.send('second')).rejects.toMatchObject({ code: 'SESSION_RUNNING' });
    expect(handle.send).toHaveBeenCalledTimes(1);

    await closed;
    expect(session.getStatus()).toBe('closed');
    expect(handle.close).toHaveBeenCalledTimes(1);
  });
});

describe('Session permission mode leases', () => {
  it('serializes live changes and skips a stale conditional restore', async () => {
    const handle = createHandle({ id: 'permission-thread' });
    const applied: PermissionMode[] = [];
    handle.setPermissionMode = vi.fn(async (mode: PermissionMode) => {
      applied.push(mode);
    });
    const baseCapabilities = createAgent(async () => handle).capabilities;
    const session = new Session({
      id: 'permission-session',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: {
        ...baseCapabilities,
        permissionModes: [
          { id: 'ask', displayName: 'Ask' },
          { id: 'auto', displayName: 'Auto' },
          { id: 'bypassPermissions', displayName: 'Full access' },
        ],
        setPermissionModeMidSession: { supported: true },
      },
      logger: createLogger(),
      permissionMode: 'bypassPermissions',
    });

    const temporary = await session.setPermissionModeTracked('ask');
    const userChange = session.setPermissionMode('auto');
    const restored = session.setPermissionModeIfUnchanged(temporary, 'bypassPermissions');

    await expect(userChange).resolves.toBeUndefined();
    await expect(restored).resolves.toBe(false);
    expect(applied).toEqual(['ask', 'auto']);
    expect(session.permissionModeState).toEqual({ mode: 'auto', generation: 2 });
  });

  it('waits for an in-flight permission transition before reserving the next turn', async () => {
    const handle = createHandle({ id: 'permission-transition-thread' });
    handle.send = vi.fn(async () => undefined);
    let releasePermission!: () => void;
    handle.setPermissionMode = vi.fn(
      () =>
        new Promise<void>((resolve) => {
          releasePermission = resolve;
        }),
    );
    const baseCapabilities = createAgent(async () => handle).capabilities;
    const session = new Session({
      id: 'permission-transition-session',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: {
        ...baseCapabilities,
        permissionModes: [
          { id: 'ask', displayName: 'Ask' },
          { id: 'bypassPermissions', displayName: 'Full access' },
        ],
        setPermissionModeMidSession: { supported: true },
      },
      logger: createLogger(),
      permissionMode: 'bypassPermissions',
    });

    const permissionChange = session.setPermissionModeTracked('ask');
    expect(session.stablePermissionModeState).toBeNull();
    const nextTurn = session.send('after permission restore');
    await vi.waitFor(() => expect(handle.setPermissionMode).toHaveBeenCalledOnce());

    expect(handle.send).not.toHaveBeenCalled();
    releasePermission();
    await expect(permissionChange).resolves.toMatchObject({ mode: 'ask' });
    expect(session.stablePermissionModeState).toEqual({ mode: 'ask', generation: 1 });
    await expect(nextTurn).resolves.toEqual({ accepted: true });
    expect(handle.send).toHaveBeenCalledOnce();
  });

  // Regression: an IM turn lease must not postpone any owner permission choice.
  // Exercise the public Session API while retaining the lease that fences new sends.
  it.each(['ask', 'auto', 'bypassPermissions'] as const)('applies %s immediately during a host turn lease without admitting another turn', async (mode) => {
    const handle = createHandle({ id: 'permission-host-lease-thread' });
    const applied: PermissionMode[] = [];
    handle.setPermissionMode = vi.fn(async (mode: PermissionMode) => {
      applied.push(mode);
    });
    handle.send = vi.fn(async () => undefined);
    const baseCapabilities = createAgent(async () => handle).capabilities;
    const session = new Session({
      id: 'permission-host-lease-session',
      agentKind: 'codex',
      workDir: '/repo',
      handle,
      capabilities: {
        ...baseCapabilities,
        permissionModes: [
          { id: 'ask', displayName: 'Ask' },
          { id: 'auto', displayName: 'Auto' },
          { id: 'bypassPermissions', displayName: 'Full access' },
        ],
        setPermissionModeMidSession: { supported: true },
        turnPermissionPolicy: {
          supported: { supported: true },
          unsupportedPermissionModes: ['bypassPermissions'],
        },
      },
      logger: createLogger(),
      permissionMode: 'bypassPermissions',
    });

    const releaseLease = session.acquireTurnLease();
    const temporary = await session.setPermissionModeTracked('ask');
    const externalChange = session.setPermissionMode(mode);
    await expect(externalChange).resolves.toBeUndefined();
    expect(applied).toEqual(['ask', mode]);
    expect(session.stablePermissionModeState).toEqual({ mode, generation: 2 });
    await expect(
      session.setPermissionModeIfUnchanged(temporary, 'bypassPermissions'),
    ).resolves.toBe(false);
    expect(applied).toEqual(['ask', mode]);

    const nextTurn = session.send('after leased permission change');
    await Promise.resolve();
    expect(handle.send).not.toHaveBeenCalled();
    releaseLease();
    await expect(nextTurn).resolves.toEqual({ accepted: true });
    expect(applied).toEqual(['ask', mode]);
    expect(handle.send).toHaveBeenCalledOnce();
  });

});

describe('Maker invalid-resume persistence bridge', () => {
  // PR #7684: a visible local app uses createSession, unlike the private bridge.
  // Exercise late invalid-history detection during Session.send: it must not
  // clear the app's saved native id or authorize an automatic replay (unit).
  it.each(['claude-code', 'pi'] as const)('does not recover or replay a visible %s local app session', async (agentKind) => {
    const storage = createStorage();
    const replay = vi.fn();
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      const handle = createHandle({ id: 'sdk-old', agentKind });
      handle.send = vi.fn(async () => {
        if (await opts.onInvalidResumeSession?.('sdk-old')) replay();
        else throw new Error('native history unavailable');
      });
      return handle;
    });
    const maker = new Maker({
      agents: { [agentKind]: createAgent(startSession, agentKind) },
      storage,
      logger: createLogger(),
    });
    const session = await maker.createSession({
      id: 'visible-local-app', agentKind, workingDir: '/repo', model: 'm',
      resumeSessionId: 'sdk-old',
      [LOCAL_AGENT_CLIENT]: { url: 'http://127.0.0.1:1', token: 'invalid-fixture', hostToolsOnly: true },
    });
    try {
      await expect(session.send('app input')).rejects.toThrow('native history unavailable');
      expect(replay).not.toHaveBeenCalled();
      expect((await storage.get(session.id))?.sdkSessionId).toBe('sdk-old');
    } finally {
      await session.close();
    }
  });

  it('injects a compare-and-clear callback for resumed Claude sessions', async () => {
    const storage = createStorage();
    await storage.create({
      id: 'session-1',
      agentKind: 'claude-code',
      workDir: '/repo',
      title: 'Resume me',
      model: 'claude-opus-4-6',
      sdkSessionId: 'sdk-old',
    });
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      expect(await opts.onInvalidResumeSession?.('sdk-old')).toBe(true);
      expect(await opts.onInvalidResumeSession?.('sdk-old')).toBe(false);
      return createHandle({ id: '<pending>', agentKind: 'claude-code' });
    });
    const maker = new Maker({
      agents: { 'claude-code': createAgent(startSession, 'claude-code') },
      storage,
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'session-1',
      agentKind: 'claude-code',
      workingDir: '/repo',
      model: 'claude-opus-4-6',
      resumeSessionId: 'sdk-old',
    });
    expect((await storage.get('session-1'))?.sdkSessionId).toBeUndefined();
  });

  it('injects a compare-and-clear callback for fresh (non-resume) Claude sessions too', async () => {
    // 全新会话(无 resumeSessionId)也可能把首个 turn 崩溃前落库的 fresh sdk id 变成幽灵 id,
    // 需要同一把 CAS 才能清掉。之前该回调只对 resume 会话装配,全新会话会漏。
    const storage = createStorage();
    let captured: CreateSessionOptions['onInvalidResumeSession'];
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      captured = opts.onInvalidResumeSession;
      return createHandle({ id: 'sdk-fresh', agentKind: 'claude-code' });
    });
    const maker = new Maker({
      agents: { 'claude-code': createAgent(startSession, 'claude-code') },
      storage,
      logger: createLogger(),
    });
    await maker.createSession({
      id: 'session-fresh',
      agentKind: 'claude-code',
      workingDir: '/repo',
      model: 'claude-opus-4-6',
      // 无 resumeSessionId —— 全新会话
    });

    expect(captured).toBeDefined();
    // fresh id 已落库;CAS 能把它清掉(index.ts 的 fresh-session self-reference 恢复会调它)。
    expect((await storage.get('session-fresh'))?.sdkSessionId).toBe('sdk-fresh');
    expect(await captured?.('sdk-fresh')).toBe(true);
    expect((await storage.get('session-fresh'))?.sdkSessionId).toBeUndefined();
    // CAS 不匹配(已清)时再次调用返回 false,不误覆盖。
    expect(await captured?.('sdk-fresh')).toBe(false);
  });

  it('clears after in-flight writes and ignores stale session_id events that arrive after recovery', async () => {
    const baseStorage = createStorage();
    await baseStorage.create({
      id: 'session-1',
      agentKind: 'claude-code',
      workDir: '/repo',
      title: 'Resume me',
      model: 'claude-opus-4-6',
      sdkSessionId: 'sdk-old',
    });

    let releaseOldWrite!: () => void;
    let markOldWriteStarted!: () => void;
    const oldWriteStarted = new Promise<void>((resolve) => {
      markOldWriteStarted = resolve;
    });
    const oldWriteGate = new Promise<void>((resolve) => {
      releaseOldWrite = resolve;
    });
    let shouldBlockOldWrite = true;
    const persistedSdkSessionIds: string[] = [];
    const compareAndClear = vi.fn((id: string, expectedSdkSessionId: string) =>
      baseStorage.compareAndClearSdkSessionId(id, expectedSdkSessionId),
    );
    const storage: SessionStorage = {
      ...baseStorage,
      async update(id, patch) {
        if (typeof patch.sdkSessionId === 'string') {
          persistedSdkSessionIds.push(patch.sdkSessionId);
          if (patch.sdkSessionId === 'sdk-old' && shouldBlockOldWrite) {
            shouldBlockOldWrite = false;
            markOldWriteStarted();
            await oldWriteGate;
          }
        }
        return baseStorage.update(id, patch);
      },
      compareAndClearSdkSessionId: compareAndClear,
    };

    const oldEvents = createAsyncQueue<AgentEvent>();
    const freshEvents = createAsyncQueue<AgentEvent>();
    const oldHandle = createHandle({ id: '<pending>', agentKind: 'claude-code' });
    oldHandle.events = () => oldEvents;
    oldHandle.close = vi.fn(async () => oldEvents.end());
    const freshHandle = createHandle({ id: '<pending>', agentKind: 'claude-code' });
    freshHandle.events = () => freshEvents;
    freshHandle.close = vi.fn(async () => freshEvents.end());

    let startCount = 0;
    const startSession = vi.fn(async (opts: CreateSessionOptions) => {
      startCount += 1;
      if (startCount === 1) return oldHandle;
      expect(await opts.onInvalidResumeSession?.('sdk-old')).toBe(true);
      return freshHandle;
    });
    const maker = new Maker({
      agents: { 'claude-code': createAgent(startSession, 'claude-code') },
      storage,
      logger: createLogger(),
    });

    await maker.createSession({
      id: 'session-1',
      agentKind: 'claude-code',
      workingDir: '/repo',
      model: 'claude-opus-4-6',
      resumeSessionId: 'sdk-old',
    });
    oldEvents.push({ type: 'session_id', data: 'sdk-old', source: 'claude-code' });
    await oldWriteStarted;
    await maker.closeSession('session-1');

    const recoveredSessionPromise = maker.createSession({
      id: 'session-1',
      agentKind: 'claude-code',
      workingDir: '/repo',
      model: 'claude-opus-4-6',
      resumeSessionId: 'sdk-old',
    });
    await vi.waitFor(() => expect(startSession).toHaveBeenCalledTimes(2));
    expect(compareAndClear).not.toHaveBeenCalled();

    releaseOldWrite();
    await recoveredSessionPromise;
    expect(compareAndClear).toHaveBeenCalledTimes(1);
    expect((await storage.get('session-1'))?.sdkSessionId).toBeUndefined();

    // CAS 后晚到的旧 query 事件必须跳过;fresh query 的新 id 仍按原路径回填。
    freshEvents.push({ type: 'session_id', data: 'sdk-old', source: 'claude-code' });
    freshEvents.push({ type: 'session_id', data: 'sdk-fresh', source: 'claude-code' });
    await vi.waitFor(async () =>
      expect((await storage.get('session-1'))?.sdkSessionId).toBe('sdk-fresh'),
    );
    expect(persistedSdkSessionIds).toEqual(['sdk-old', 'sdk-fresh']);
    await maker.closeSession('session-1');
  });
});

// F6-A, unit: cancellation must fence real Maker dedup/publication, not only
// Desktop's outer promise. Deferred native/storage boundaries are the inputs.
describe('cancelled creation ownership', () => {
  it.each(['prepare', 'native', 'storage', 'succeeded'] as const)(
    'cleans a cancelled %s attempt before starting its replacement', async stage => {
      const gate = createDeferred();
      const entered = createDeferred();
      const storage = createStorage();
      const oldHandle = createHandle({ id: 'old-native' });
      const newHandle = createHandle({ id: 'new-native' });
      const closed = vi.spyOn(oldHandle, 'close');
      let starts = 0;
      const pause = async () => { entered.resolve(); await gate.promise; };
      const write = storage.create.bind(storage);
      if (stage === 'storage') storage.create = async input => {
        const row = await write(input);
        if (starts === 1) await pause();
        return row;
      };
      let prepared = 0;
      const maker = new Maker({
        agents: { codex: createAgent(async () => {
          starts++;
          if (stage === 'native' && starts === 1) await pause();
          return starts === 1 ? oldHandle : newHandle;
        }) }, storage, logger: createLogger(),
        lifecycleHooks: {
          prepareStartOptions: async () => { if (stage === 'prepare' && prepared++ === 0) await pause(); },
          onStartSucceeded: async () => { if (stage === 'succeeded' && starts === 1) await pause(); },
        },
      });
      const created = vi.fn();
      maker.on(e => { if (e.type === 'session:created') created(e.session); });
      const opts: CreateSessionOptions = { id: 'cancelled-task', agentKind: 'codex', workingDir: '/repo', model: 'm' };
      const signal = new AbortController();
      const old = maker.createSession(opts, signal.signal).catch(e => e);
      await entered.promise;
      signal.abort(new Error('cancelled attempt'));
      const replacement = maker.createSession(opts);
      gate.resolve();
      expect(String(await old)).toContain('cancelled attempt');
      const current = await replacement;
      expect(current.getStatus()).toBe('active');
      expect(maker.getSession(opts.id!)).toBe(current);
      expect(created).toHaveBeenCalledTimes(1);
      expect(starts).toBe(stage === 'prepare' ? 1 : 2);
      expect(closed).toHaveBeenCalledTimes(stage === 'prepare' ? 0 : 1);
      if (stage === 'storage' || stage === 'succeeded') {
        expect(await storage.get(opts.id!)).toMatchObject({ sdkSessionId: 'new-native' });
      }
      await maker.shutdown();
    },
  );

  it('bounds replacement waits without losing the old cleanup barrier or another task', async () => {
    vi.useFakeTimers();
    const gate = createDeferred();
    const oldHandle = createHandle({ id: 'old-native' });
    const closed = vi.spyOn(oldHandle, 'close');
    let starts = 0;
    const maker = new Maker({ agents: { codex: createAgent(async () => {
      if (++starts === 1) { await gate.promise; return oldHandle; }
      return createHandle({ id: 'native-' + starts });
    }) }, storage: createStorage(), logger: createLogger() });
    const opts: CreateSessionOptions = { id: 'cancelled-task', agentKind: 'codex', workingDir: '/repo', model: 'm' };
    const cancel = new AbortController();
    const old = maker.createSession(opts, cancel.signal).catch(e => e);
    cancel.abort(new Error('cancelled attempt'));
    try {
      const waiting = maker.createSession(opts).catch(e => e);
      await vi.advanceTimersByTimeAsync(1000);
      expect(String(await waiting)).toContain('cleanup is still pending; retry');
      expect(starts).toBe(1);
      expect(vi.getTimerCount()).toBe(0);
      const sibling = await maker.createSession({ ...opts, id: 'sibling' });
      expect(sibling.getStatus()).toBe('active');
      const nextCancel = new AbortController();
      const nextWait = maker.createSession(opts, nextCancel.signal).catch(e => e);
      const abortReason = new Error('replacement cancelled');
      nextCancel.abort(abortReason);
      const aborted = await nextWait;
      expect(aborted).toBe(abortReason);
      expect(String(aborted)).toContain('replacement cancelled');
      expect(vi.getTimerCount()).toBe(0);
      gate.resolve();
      expect(String(await old)).toContain('cancelled attempt');
      expect(closed).toHaveBeenCalledTimes(1);
      const replacement = await maker.createSession(opts);
      expect(replacement.getStatus()).toBe('active');
      expect(maker.getSession('sibling')).toBe(sibling);
      await maker.shutdown();
    } finally { gate.resolve(); vi.useRealTimers(); }
  });

  it('does not begin an already cancelled creation, including anonymous starts', async () => {
    const start = vi.fn(async () => createHandle({ id: 'native' }));
    const maker = new Maker({ agents: { codex: createAgent(start) }, storage: createStorage(), logger: createLogger() });
    const abort = new AbortController(); abort.abort(new Error('cancelled attempt'));
    await expect(maker.createSession({ agentKind: 'codex', workingDir: '/repo', model: 'm' }, abort.signal)).rejects.toThrow('cancelled attempt');
    expect(start).not.toHaveBeenCalled();
    const normal = await maker.createSession({ agentKind: 'codex', workingDir: '/repo', model: 'm' });
    expect(normal.getStatus()).toBe('active');
    await maker.shutdown();
  });
});

// F6-A handoff: Maker may have published before Desktop's final role await.
it('does not reuse a published session while cancelled creation cleanup is pending', async () => {
  const gate = createDeferred();
  const firstHandle = createHandle({ id: 'first-native' });
  const close = vi.spyOn(firstHandle, 'close').mockImplementation(() => gate.promise);
  const start = vi.fn().mockResolvedValueOnce(firstHandle).mockResolvedValueOnce(createHandle({ id: 'second-native' }));
  const maker = new Maker({ agents: { codex: createAgent(start) }, storage: createStorage(), logger: createLogger() });
  const opts: CreateSessionOptions = { id: 'cancelled-role-task', agentKind: 'codex', workingDir: '/repo', model: 'm' };
  const first = await maker.createSession(opts);
  const closing = maker.closeSessionIfCurrent(first);
  const replacement = maker.createSession(opts);
  expect(start).toHaveBeenCalledTimes(1);
  gate.resolve(); await closing;
  const second = await replacement;
  expect(second).not.toBe(first);
  expect(second.getStatus()).toBe('active');
  expect(maker.getSession(opts.id!)).toBe(second);
  expect(close).toHaveBeenCalledTimes(1);
  await maker.shutdown();
});

// F6-C, unit: rejected cleanup (not only timeout) must remain distinguishable
// from a failed native startup; otherwise hosts may relocate route/history.
it.each(['unpublished', 'published'] as const)(
  'classifies rejected %s cleanup without losing ownership or its cause', async publication => {
    const gate = createDeferred();
    const cleanupError = new Error('termination unconfirmed');
    const oldHandle = createHandle({ id: 'old-native' });
    let cleanupAllowed = false;
    const close = vi.spyOn(oldHandle, 'close').mockImplementation(async () => {
      if (!cleanupAllowed) throw cleanupError;
    });
    let starts = 0;
    const storage = createStorage();
    const maker = new Maker({ agents: { codex: createAgent(async () => {
      if (++starts === 1) { await gate.promise; return oldHandle; }
      return createHandle({ id: 'replacement-native' });
    }) }, storage, logger: createLogger() });
    const options: CreateSessionOptions = { id: 'cleanup-owner', agentKind: 'codex', workingDir: '/repo', model: 'm' };
    const abort = new AbortController();
    const starting = maker.createSession(options, abort.signal);
    const settled = starting.catch(error => error);
    if (publication === 'unpublished') abort.abort(new Error('cancelled startup'));
    gate.resolve();
    if (publication === 'published') {
      const session = await starting;
      await expect(maker.closeSessionIfCurrent(session)).rejects.toBe(cleanupError);
    } else {
      expect(String(await settled)).toContain('cancelled startup');
    }
    const beforeRetry = await storage.get(options.id!);
    const failed = await maker.createSession(options).catch(error => error);
    expect(failed).toBeInstanceOf(SessionCreationCleanupPendingError);
    expect(failed.cause).toBe(cleanupError);
    expect(starts).toBe(1);
    expect(close).toHaveBeenCalledTimes(2);
    expect(await storage.get(options.id!)).toEqual(beforeRetry);
    cleanupAllowed = true;
    const replacement = await maker.createSession(options);
    expect(starts).toBe(2);
    expect(replacement.getStatus()).toBe('active');
    expect(maker.getSession(options.id!)).toBe(replacement);
    await maker.shutdown();
  },
);