@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/claude-session-start.ts

@@ -0,0 +1,277 @@
+import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk"
+import {
+  createKannaMcpServer,
+  type KannaMcpDelegationContext,
+  type SetupLoopHandlerResult,
+} from "./kanna-mcp"
+import type { LoopSetupInput } from "./loop-template"
+import { KANNA_MCP_SERVER_NAME } from "../shared/tools"
+import { homedir } from "node:os"
+import type { McpServerConfig } from "../shared/types"
+import { KANNA_SYSTEM_PROMPT_APPEND } from "../shared/kanna-system-prompt"
+import {
+  buildCanUseTool,
+  buildClaudeEnv,
+  LOOP_BLOCKED_NATIVE_TOOLS,
+} from "./claude-spawn-helpers"
+import {
+  buildUserMcpServers,
+  CLAUDE_TOOLSET,
+  SDK_RESTRICTED_FS_NATIVE_TOOLS,
+} from "./claude-session-config"
+import { toSdkEffort } from "./claude-prompt-helpers"
+import { AsyncMessageQueue, toClaudeMessageStream } from "./claude-sdk-queue"
+import { createClaudeHarnessStream } from "./claude-harness-stream"
+import { parseConfiguredContextWindowFromModelId } from "./claude-usage-math"
+import { log } from "../shared/log"
+import type { ClaudeSessionHandle, HarnessToolRequest } from "./harness-types"
+import type { SubagentOrchestrator } from "./subagent-orchestrator"
+import type { TunnelGateway } from "./cloudflare-tunnel/gateway"
+import type { ToolCallbackService } from "./tool-callback"
+import type { ChatPermissionPolicy } from "../shared/permission-policy"
+import type { OrchRunDetail, OrchRunInput } from "../shared/orchestration-types"
+import type { ModelPrice } from "../shared/token-pricing"
+import type { AnyValue } from "../shared/errors"
+
+/**
+ * Injectable collaborators for startClaudeSession.
+ *
+ * Kept as a second parameter (with a production default via
+ * buildStartClaudeSessionDeps) so tests can supply fakes for the modules that
+ * would otherwise pollute Bun's global module registry via mock.module().
+ */
+export type StartClaudeSessionDeps = {
+  readonly buildCanUseTool: typeof buildCanUseTool
+  readonly buildClaudeEnv: typeof buildClaudeEnv
+  readonly loopBlockedNativeTools: readonly string[]
+  /** Structural constructor type so both AsyncMessageQueue and test fakes satisfy it. */
+  readonly AsyncMessageQueueCtor: { new <T>(): { push(value: T): void; close(): void } & AsyncIterable<T> }
+  readonly toClaudeMessageStream: typeof toClaudeMessageStream
+  readonly createClaudeHarnessStream: typeof createClaudeHarnessStream
+  readonly parseConfiguredContextWindowFromModelId: typeof parseConfiguredContextWindowFromModelId
+  readonly buildUserMcpServers: typeof buildUserMcpServers
+  readonly claudeToolset: readonly string[]
+  readonly sdkRestrictedFsNativeTools: readonly string[]
+}
+
+/** Returns the real (production) dep implementations. */
+export function buildStartClaudeSessionDeps(): StartClaudeSessionDeps {
+  return {
+    buildCanUseTool,
+    buildClaudeEnv,
+    loopBlockedNativeTools: LOOP_BLOCKED_NATIVE_TOOLS,
+    AsyncMessageQueueCtor: AsyncMessageQueue,
+    toClaudeMessageStream,
+    createClaudeHarnessStream,
+    parseConfiguredContextWindowFromModelId,
+    buildUserMcpServers,
+    claudeToolset: CLAUDE_TOOLSET,
+    sdkRestrictedFsNativeTools: SDK_RESTRICTED_FS_NATIVE_TOOLS,
+  }
+}
+
+export async function startClaudeSession(args: {
+  projectId: string
+  localPath: string
+  model: string
+  effort?: string
+  planMode: boolean
+  sessionToken: string | null
+  forkSession: boolean
+  oauthToken: string | null
+  /** When set, redirect the SDK to OpenRouter instead of Anthropic. */
+  openrouterApiKey?: string | null
+  additionalDirectories?: string[]
+  chatId?: string
+  tunnelGateway?: TunnelGateway | null
+  onToolRequest: (request: HarnessToolRequest) => Promise<AnyValue>
+  systemPromptAppend?: string
+  systemPromptOverride?: string
+  initialPrompt?: string
+  /** Routes AskUserQuestion/ExitPlanMode through tool-callback when KANNA_MCP_TOOL_CALLBACKS=1. */
+  toolCallback?: ToolCallbackService
+  /** Per-chat permission policy. Defaults to POLICY_DEFAULT if omitted. */
+  chatPolicy?: ChatPermissionPolicy
+  /** Orchestrator for delegate_subagent. Omit to hide the tool. */
+  subagentOrchestrator?: SubagentOrchestrator
+  /** Per-spawn delegation context (depth / ancestor chain / parentUserMessageId resolver). */
+  delegationContext?: KannaMcpDelegationContext
+  /** Enabled user MCP servers, merged into the SDK's mcpServers map. */
+  customMcpServers?: readonly McpServerConfig[]
+  /** Pre-resolved oauth bearer tokens keyed by server id (from ensureFreshMcpToken). */
+  oauthBearers?: ReadonlyMap<string, string>
+  /** Folder-restricted subagent: disallow native FS tools, allowlist mcp__kanna__*, per-run path-deny. */
+  restrictedAllowedPaths?: string[]
+  /** Backs the `setup_loop` MCP tool. Omit to hide the tool. */
+  setupLoop?: (input: LoopSetupInput) => Promise<SetupLoopHandlerResult>
+  /** Backs the `stop_loop` MCP tool. Omit to hide the tool. */
+  stopLoop?: () => Promise<void>
+  /** Live check: true while an autonomous loop is armed — blocks direct-edit native tools. */
+  isLoopArmed?: () => boolean
+  /** Backs the `orch_run` / `orch_run_status` / `orch_cancel_run` MCP tools. Main-chat only. */
+  runOrch?: (input: OrchRunInput) => Promise<{ ok: true; runId: string } | { ok: false; errors: string[] }>
+  cancelOrchRun?: (runId: string) => Promise<void>
+  getOrchRunStatus?: (runId: string) => OrchRunDetail | null
+  /**
+   * Agentic-turn bound passed natively to the SDK query() (Claude Code's
+   * per-agent frontmatter maxTurns analog): the SDK stops gracefully and
+   * keeps the accumulated output. Used by subagent spawns.
+   */
+  maxTurns?: number
+  /** When true, leave the prompt queue open after initialPrompt and expose pushChannelPrompt on the handle. */
+  keepAlive?: boolean
+  /** Per-turn price for computing cost when the provider doesn't report it (OpenRouter). */
+  turnPrice?: ModelPrice | null
+  /** Overrides the configured context window (OpenRouter model contextLength). */
+  contextWindowOverride?: number
+},
+  _deps: StartClaudeSessionDeps = buildStartClaudeSessionDeps(),
+): Promise<ClaudeSessionHandle> {
+  const canUseTool = _deps.buildCanUseTool({
+    localPath: args.localPath,
+    chatId: args.chatId,
+    sessionToken: args.sessionToken,
+    onToolRequest: args.onToolRequest,
+    toolCallback: args.toolCallback,
+    chatPolicy: args.chatPolicy,
+    isLoopArmed: args.isLoopArmed,
+  })
+
+  const promptQueue = new _deps.AsyncMessageQueueCtor<SDKUserMessage>()
+
+  const q = query({
+    prompt: promptQueue,
+    options: {
+      cwd: args.localPath,
+      ...(args.additionalDirectories && args.additionalDirectories.length > 0
+        ? { additionalDirectories: args.additionalDirectories }
+        : {}),
+      model: args.model,
+      effort: toSdkEffort(args.effort),
+      resume: args.sessionToken ?? undefined,
+      forkSession: args.forkSession,
+      permissionMode: args.planMode ? "plan" : "acceptEdits",
+      canUseTool,
+      // Filter-at-spawn (Claude Code's filterToolsForAgent pattern): while a
+      // loop is armed the direct-edit tools are removed from the tool list the
+      // model sees, so it cannot even attempt them. The dynamic canUseTool
+      // deny stays as belt-and-suspenders; an armed-state flip respawns the
+      // session (see loopArmedAtSpawn in startClaudeTurn).
+      ...(args.isLoopArmed?.() ? { disallowedTools: [..._deps.loopBlockedNativeTools] } : {}),
+      // Per-agent turn bound, threaded from Subagent.maxTurns. The SDK emits
+      // a graceful stop at the limit — accumulated output is preserved,
+      // matching Claude Code's max_turns_reached semantics.
+      ...(args.maxTurns !== undefined ? { maxTurns: args.maxTurns } : {}),
+      tools: args.restrictedAllowedPaths && args.restrictedAllowedPaths.length > 0
+        ? _deps.claudeToolset.filter((t) => !new Set<string>(_deps.sdkRestrictedFsNativeTools).has(t))
+        : [..._deps.claudeToolset],
+      mcpServers: {
+        [KANNA_MCP_SERVER_NAME]: createKannaMcpServer({
+          projectId: args.projectId,
+          localPath: args.localPath,
+          chatId: args.chatId,
+          sessionId: args.sessionToken ?? undefined,
+          tunnelGateway: args.tunnelGateway ?? null,
+          toolCallback: args.toolCallback,
+          chatPolicy: args.chatPolicy,
+          subagentOrchestrator: args.subagentOrchestrator,
+          delegationContext: args.delegationContext,
+          restrictedAllowedPaths: args.restrictedAllowedPaths,
+          setupLoop: args.setupLoop,
+          stopLoop: args.stopLoop,
+          runOrch: args.runOrch,
+          cancelOrchRun: args.cancelOrchRun,
+          getOrchRunStatus: args.getOrchRunStatus,
+        }),
+        ..._deps.buildUserMcpServers(args.customMcpServers ?? [], args.oauthBearers),
+      },
+      systemPrompt: args.systemPromptOverride != null
+        ? args.systemPromptOverride
+        : {
+            type: "preset",
+            preset: "claude_code",
+            append: args.systemPromptAppend ?? KANNA_SYSTEM_PROMPT_APPEND,
+          },
+      settingSources: ["user", "project", "local"],
+      pathToClaudeCodeExecutable: process.env.CLAUDE_EXECUTABLE?.replace(/^~(?=\/|$)/, homedir()) || undefined,
+      env: _deps.buildClaudeEnv(process.env, args.oauthToken, args.openrouterApiKey ? { apiKey: args.openrouterApiKey } : null),
+    },
+  })
+
+  // Follow-up turns (sendPrompt + keep-alive pushChannelPrompt) share one
+  // queue-push policy so the two transports cannot drift apart.
+  const enqueueUserPrompt = (content: string) => {
+    promptQueue.push({
+      type: "user",
+      message: { role: "user", content },
+      parent_tool_use_id: null,
+      session_id: args.sessionToken ?? "",
+    })
+  }
+
+  if (args.initialPrompt != null) {
+    promptQueue.push({
+      type: "user",
+      message: {
+        role: "user",
+        content: args.initialPrompt,
+      },
+      parent_tool_use_id: null,
+      session_id: args.sessionToken ?? undefined,
+    })
+    if (!args.keepAlive) {
+      promptQueue.close()
+    }
+  }
+
+  return {
+    provider: "claude",
+    stream: _deps.createClaudeHarnessStream(
+      _deps.toClaudeMessageStream(q),
+      args.contextWindowOverride ?? _deps.parseConfiguredContextWindowFromModelId(args.model),
+      args.turnPrice ? () => args.turnPrice ?? null : undefined,
+    ),
+    getAccountInfo: async () => {
+      try {
+        return await q.accountInfo()
+      } catch {
+        return null
+      }
+    },
+    interrupt: async () => {
+      await q.interrupt()
+    },
+    sendPrompt: async (content: string) => {
+      enqueueUserPrompt(content)
+    },
+    setModel: async (model: string) => {
+      await q.setModel(model)
+    },
+    setPermissionMode: async (planMode: boolean) => {
+      await q.setPermissionMode(planMode ? "plan" : "acceptEdits")
+    },
+    getSupportedCommands: async () => {
+      try {
+        return await q.supportedCommands()
+      } catch (error) {
+        log.warn("[kanna/claude] supportedCommands failed", String(error))
+        return []
+      }
+    },
+    ...(args.keepAlive ? {
+      pushChannelPrompt: async (content: string) => {
+        enqueueUserPrompt(content)
+      },
+    } : {}),
+    close: () => {
+      promptQueue.close()
+      q.close()
+      // Do NOT cancel pending tool-callback records here. close() also fires
+      // on token rotation and idle-session sweep — both of which preserve
+      // the model's logical turn (it will resume / re-emit). Denying
+      // mid-turn used to mask the question prompt as a silent drop. Pending
+      // records are now reaped by the explicit chat.cancel / chat.delete
+      // paths in ws-router.ts and by recoverOnStartup on server boot.
+    },
+  }
+}

package/src/server/claude-session-state-queries.test.ts

@@ -0,0 +1,344 @@
+import { describe, it, expect, mock } from "bun:test"
+import {
+  getActiveStatuses,
+  getWaitStartedAtByChatId,
+  getPendingTool,
+  getDrainingChatIds,
+  getSlashCommandsLoadingChatIds,
+  getClaudeSessionStates,
+  isClaudeSessionIdle,
+  sweepIdleClaudeSessions,
+  type SessionStateQueryDeps,
+} from "./claude-session-state-queries"
+import type { ActiveTurn, ClaudeSessionState, PendingToolRequest } from "./claude-session-state"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSession(overrides?: Partial<ClaudeSessionState>): ClaudeSessionState {
+  return {
+    id: "sess-1",
+    chatId: "chat-1",
+    session: {} as ClaudeSessionState["session"],
+    localPath: "/tmp/test",
+    additionalDirectories: [],
+    model: "claude-opus-4-5",
+    planMode: false,
+    sessionToken: null,
+    accountInfoLoaded: false,
+    nextPromptSeq: 0,
+    pendingPromptSeqs: [],
+    activeTokenId: null,
+    oauthKeyMasked: null,
+    oauthLabel: null,
+    openrouterKeyMasked: null,
+    openrouterModel: null,
+    lastUsedAt: Date.now(),
+    backgroundTaskIds: new Set(),
+    backgroundTaskDeadlineAt: 0,
+    loopArmedAtSpawn: false,
+    ...overrides,
+  } as ClaudeSessionState
+}
+
+function makeActiveTurn(overrides?: Partial<ActiveTurn>): ActiveTurn {
+  return {
+    chatId: "chat-1",
+    provider: "claude",
+    turn: {} as ActiveTurn["turn"],
+    model: "claude-opus-4-5",
+    planMode: false,
+    status: "running",
+    pendingTool: null,
+    postToolFollowUp: null,
+    hasFinalResult: false,
+    cancelRequested: false,
+    cancelRecorded: false,
+    waitStartedAt: null,
+    userMessageId: null,
+    ...overrides,
+  } as ActiveTurn
+}
+
+function makeDeps(overrides?: Partial<SessionStateQueryDeps>): SessionStateQueryDeps {
+  return {
+    activeTurns: new Map(),
+    claudeSessions: new Map(),
+    drainingStreams: new Map(),
+    slashCommandsInFlight: new Set(),
+    isClaudeSdkProvider: mock(() => false),
+    hasPendingBackgroundTask: mock(() => false),
+    resolveClaudeIdleMs: mock(() => 600_000),
+    hasLiveWorkflow: mock(() => false),
+    closeClaudeSession: mock(() => undefined),
+    emitStateChange: mock(() => undefined),
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// getActiveStatuses
+// ---------------------------------------------------------------------------
+
+describe("getActiveStatuses", () => {
+  it("returns empty map when no active turns", () => {
+    const deps = makeDeps()
+    expect(getActiveStatuses(deps).size).toBe(0)
+  })
+
+  it("maps chatId → status for each active turn", () => {
+    const deps = makeDeps({
+      activeTurns: new Map([
+        ["chat-1", makeActiveTurn({ chatId: "chat-1", status: "running" })],
+        ["chat-2", makeActiveTurn({ chatId: "chat-2", status: "waiting_for_user" })],
+      ]),
+    })
+    const result = getActiveStatuses(deps)
+    expect(result.get("chat-1")).toBe("running")
+    expect(result.get("chat-2")).toBe("waiting_for_user")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getWaitStartedAtByChatId
+// ---------------------------------------------------------------------------
+
+describe("getWaitStartedAtByChatId", () => {
+  it("returns empty map when no turns are waiting", () => {
+    const deps = makeDeps({
+      activeTurns: new Map([["chat-1", makeActiveTurn({ waitStartedAt: null })]]),
+    })
+    expect(getWaitStartedAtByChatId(deps).size).toBe(0)
+  })
+
+  it("returns waitStartedAt only for turns with non-null value", () => {
+    const ts = 12345
+    const deps = makeDeps({
+      activeTurns: new Map([
+        ["chat-1", makeActiveTurn({ waitStartedAt: ts })],
+        ["chat-2", makeActiveTurn({ waitStartedAt: null })],
+      ]),
+    })
+    const result = getWaitStartedAtByChatId(deps)
+    expect(result.get("chat-1")).toBe(ts)
+    expect(result.has("chat-2")).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getPendingTool
+// ---------------------------------------------------------------------------
+
+describe("getPendingTool", () => {
+  it("returns null when chatId has no active turn", () => {
+    const deps = makeDeps()
+    expect(getPendingTool(deps, "chat-x")).toBeNull()
+  })
+
+  it("returns null when active turn has no pending tool", () => {
+    const deps = makeDeps({
+      activeTurns: new Map([["chat-1", makeActiveTurn({ pendingTool: null })]]),
+    })
+    expect(getPendingTool(deps, "chat-1")).toBeNull()
+  })
+
+  it("returns PendingToolSnapshot when pending tool is present", () => {
+    const deps = makeDeps({
+      activeTurns: new Map([
+        [
+          "chat-1",
+          makeActiveTurn({
+            pendingTool: {
+              toolUseId: "tool-123",
+              tool: { toolKind: "ask_user_question" } as PendingToolRequest["tool"],
+              resolve: () => undefined,
+            },
+          }),
+        ],
+      ]),
+    })
+    const result = getPendingTool(deps, "chat-1")
+    expect(result).toEqual({ toolUseId: "tool-123", toolKind: "ask_user_question" })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getDrainingChatIds
+// ---------------------------------------------------------------------------
+
+describe("getDrainingChatIds", () => {
+  it("returns empty set when no draining streams", () => {
+    const deps = makeDeps()
+    expect(getDrainingChatIds(deps).size).toBe(0)
+  })
+
+  it("returns chatIds of draining streams", () => {
+    const draining = new Map<string, unknown>([["chat-a", {}], ["chat-b", {}]])
+    const deps = makeDeps({ drainingStreams: draining as SessionStateQueryDeps["drainingStreams"] })
+    const result = getDrainingChatIds(deps)
+    expect(result.has("chat-a")).toBe(true)
+    expect(result.has("chat-b")).toBe(true)
+    expect(result.size).toBe(2)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getSlashCommandsLoadingChatIds
+// ---------------------------------------------------------------------------
+
+describe("getSlashCommandsLoadingChatIds", () => {
+  it("returns empty set when no slash commands in flight", () => {
+    const deps = makeDeps()
+    expect(getSlashCommandsLoadingChatIds(deps).size).toBe(0)
+  })
+
+  it("mirrors the slashCommandsInFlight set", () => {
+    const deps = makeDeps({ slashCommandsInFlight: new Set(["chat-1", "chat-2"]) })
+    const result = getSlashCommandsLoadingChatIds(deps)
+    expect(result.has("chat-1")).toBe(true)
+    expect(result.has("chat-2")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getClaudeSessionStates
+// ---------------------------------------------------------------------------
+
+describe("getClaudeSessionStates", () => {
+  it("returns empty map when no sessions", () => {
+    const deps = makeDeps()
+    expect(getClaudeSessionStates(deps).size).toBe(0)
+  })
+
+  it("returns 'active' for SDK providers", () => {
+    const session = makeSession({ chatId: "chat-1" })
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      activeTurns: new Map([["chat-1", makeActiveTurn({ provider: "claude" })]]),
+      isClaudeSdkProvider: () => true,
+    })
+    expect(getClaudeSessionStates(deps).get("chat-1")).toBe("active")
+  })
+
+  it("returns 'warming' when background task pending", () => {
+    const session = makeSession({ chatId: "chat-1", lastUsedAt: 0 })
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      hasPendingBackgroundTask: () => true,
+      resolveClaudeIdleMs: () => 100,
+    })
+    expect(getClaudeSessionStates(deps).get("chat-1")).toBe("warming")
+  })
+
+  it("returns 'idle' when idle timeout elapsed and no activity", () => {
+    const session = makeSession({ chatId: "chat-1", lastUsedAt: 0 })
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      resolveClaudeIdleMs: () => 1, // 1 ms — already elapsed
+    })
+    expect(getClaudeSessionStates(deps).get("chat-1")).toBe("idle")
+  })
+
+  it("returns 'warming' when recently used and no activity", () => {
+    const session = makeSession({ chatId: "chat-1", lastUsedAt: Date.now() })
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      resolveClaudeIdleMs: () => 600_000,
+    })
+    expect(getClaudeSessionStates(deps).get("chat-1")).toBe("warming")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// isClaudeSessionIdle
+// ---------------------------------------------------------------------------
+
+describe("isClaudeSessionIdle", () => {
+  it("returns false when provider is an SDK provider", () => {
+    const session = makeSession({ lastUsedAt: 0 })
+    const deps = makeDeps({
+      activeTurns: new Map([["chat-1", makeActiveTurn({ provider: "claude" })]]),
+      isClaudeSdkProvider: () => true,
+      resolveClaudeIdleMs: () => 1,
+    })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(false)
+  })
+
+  it("returns false when session has pending prompt seqs", () => {
+    const session = makeSession({ lastUsedAt: 0, pendingPromptSeqs: [1] })
+    const deps = makeDeps({ resolveClaudeIdleMs: () => 1 })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(false)
+  })
+
+  it("returns false when chat has a live workflow", () => {
+    const session = makeSession({ lastUsedAt: 0 })
+    const deps = makeDeps({
+      hasLiveWorkflow: () => true,
+      resolveClaudeIdleMs: () => 1,
+    })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(false)
+  })
+
+  it("returns false when background task is pending", () => {
+    const session = makeSession({ lastUsedAt: 0 })
+    const deps = makeDeps({
+      hasPendingBackgroundTask: () => true,
+      resolveClaudeIdleMs: () => 1,
+    })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(false)
+  })
+
+  it("returns false when idle timeout has not elapsed", () => {
+    const session = makeSession({ lastUsedAt: Date.now() })
+    const deps = makeDeps({ resolveClaudeIdleMs: () => 600_000 })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(false)
+  })
+
+  it("returns true when all idle conditions met", () => {
+    const session = makeSession({ lastUsedAt: 0, pendingPromptSeqs: [] })
+    const deps = makeDeps({ resolveClaudeIdleMs: () => 1 })
+    expect(isClaudeSessionIdle(deps, "chat-1", session, Date.now())).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// sweepIdleClaudeSessions
+// ---------------------------------------------------------------------------
+
+describe("sweepIdleClaudeSessions", () => {
+  it("does nothing when no sessions", () => {
+    const deps = makeDeps()
+    sweepIdleClaudeSessions(deps, Date.now())
+    expect((deps.closeClaudeSession as ReturnType<typeof mock>).mock.calls.length).toBe(0)
+  })
+
+  it("closes and emits state change for idle sessions", () => {
+    const session = makeSession({ chatId: "chat-1", lastUsedAt: 0, pendingPromptSeqs: [] })
+    const closeFn = mock<(chatId: string, session: ClaudeSessionState) => void>(() => undefined)
+    const emitFn = mock<(chatId: string) => void>(() => undefined)
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      resolveClaudeIdleMs: () => 1,
+      closeClaudeSession: closeFn,
+      emitStateChange: emitFn,
+    })
+    sweepIdleClaudeSessions(deps, Date.now())
+    expect(closeFn.mock.calls.length).toBe(1)
+    expect(closeFn.mock.calls[0]?.[0]).toBe("chat-1")
+    expect(emitFn.mock.calls.length).toBe(1)
+    expect(emitFn.mock.calls[0]?.[0]).toBe("chat-1")
+  })
+
+  it("does not close non-idle sessions", () => {
+    const session = makeSession({ chatId: "chat-1", lastUsedAt: Date.now(), pendingPromptSeqs: [] })
+    const closeFn = mock(() => undefined)
+    const deps = makeDeps({
+      claudeSessions: new Map([["chat-1", session]]),
+      resolveClaudeIdleMs: () => 600_000,
+      closeClaudeSession: closeFn,
+    })
+    sweepIdleClaudeSessions(deps, Date.now())
+    expect(closeFn.mock.calls.length).toBe(0)
+  })
+})