Class SessionManager

constructor

• new SessionManager(tmux: TmuxManager, config: Config): SessionManager

  Parameters

  • tmux: TmuxManager
  • config: Config

  Returns SessionManager

Static ReadonlyDEFAULT_STALL_THRESHOLD_MS

Static ReadonlyDEFAULT_PERMISSION_STALL_MS

Static ReadonlyDEFAULT_PROMPT_TIMEOUT_MS

Static ReadonlyDEFAULT_PROMPT_MAX_RETRIES

load

• load(): Promise<void>

  Load state from disk.

  Returns Promise<void>

reconcileTmuxCrash

• reconcileTmuxCrash(): Promise<{ recovered: number; orphaned: number }>

  Issue #397: Reconcile after tmux server crash recovery. Called when the monitor detects tmux server came back after a crash. Returns counts for observability.

  Returns Promise<{ recovered: number; orphaned: number }>

save

• save(): Promise<void>

  Save state to disk atomically (write to temp, then rename). #218: Uses a write queue to serialize concurrent saves and prevent corruption.

  Returns Promise<void>

debouncedSave

• debouncedSave(): void

  #357: Debounced save — skips immediate save for offset-only changes. Coalesces rapid successive reads into a single disk write.

  Returns void

sendInitialPrompt

• sendInitialPrompt(
      sessionId: string,
      prompt: string,
      timeoutMs?: number,
      maxRetries?: number,
  ): Promise<{ delivered: boolean; attempts: number }>

  Wait for CC to show its idle prompt in the tmux pane, then send the initial prompt. Uses exponential backoff on retry: first attempt waits timeoutMs, subsequent attempts wait 1.5x the previous timeout.

  Returns delivery result. Logs warnings on each retry for observability.

  Parameters

  • sessionId: string
  • prompt: string
  • OptionaltimeoutMs: number
  • OptionalmaxRetries: number

  Returns Promise<{ delivered: boolean; attempts: number }>

createSession

• createSession(
      opts: {
          workDir: string;
          name?: string;
          prd?: string;
          resumeSessionId?: string;
          claudeCommand?: string;
          env?: Record<string, string>;
          stallThresholdMs?: number;
          permissionStallMs?: number;
          permissionMode?: string;
          autoApprove?: boolean;
          parentId?: string;
      },
  ): Promise<SessionInfo>

  Parameters

  • opts: {
        workDir: string;
        name?: string;
        prd?: string;
        resumeSessionId?: string;
        claudeCommand?: string;
        env?: Record<string, string>;
        stallThresholdMs?: number;
        permissionStallMs?: number;
        permissionMode?: string;
        autoApprove?: boolean;
        parentId?: string;
    }

    • workDir: string

    • Optionalname?: string

    • Optionalprd?: string

    • OptionalresumeSessionId?: string

    • OptionalclaudeCommand?: string

    • Optionalenv?: Record<string, string>

    • OptionalstallThresholdMs?: number

    • OptionalpermissionStallMs?: number

    • OptionalpermissionMode?: string

    • OptionalautoApprove?: boolean

      Deprecated

      Use permissionMode instead. Maps true→bypassPermissions, false→default.

    • OptionalparentId?: string

      Issue #702: Parent session ID for sub-agent hierarchy

  Returns Promise<SessionInfo>

getSession

• getSession(id: string): SessionInfo | null

  Get a session by ID.

  Parameters

  • id: string

  Returns SessionInfo | null

updateStatusFromHook

• updateStatusFromHook(
      id: string,
      hookEvent: string,
      hookTimestamp?: number,
  ): UIState | null

  Issue #169 Phase 3: Update session status from a hook event. Returns the previous status for change detection. Issue #87: Also records hook latency timestamps.

  Parameters

  • id: string
  • hookEvent: string
  • OptionalhookTimestamp: number

  Returns UIState | null

detectWaitingForInput

• detectWaitingForInput(id: string): Promise<boolean>

  Issue #812: Detect if CC is waiting for user input by analyzing the JSONL transcript. Returns true if the last assistant message has text content only (no tool_use).

  Parameters

  • id: string

  Returns Promise<boolean>

addSubagent

• addSubagent(id: string, name: string): void

  Issue #88: Add an active subagent to a session.

  Parameters

  • id: string
  • name: string

  Returns void

removeSubagent

• removeSubagent(id: string, name: string): void

  Issue #88: Remove an active subagent from a session.

  Parameters

  • id: string
  • name: string

  Returns void

updateSessionModel

• updateSessionModel(id: string, model: string): void

  Issue #89 L25: Update the model field on a session from hook payload.

  Parameters

  • id: string
  • model: string

  Returns void

getLatencyMetrics

• getLatencyMetrics(
      id: string,
  ):
      | {
          hook_latency_ms: number
          | null;
          state_change_detection_ms: number | null;
          permission_response_ms: number | null;
      }
      | null

  Issue #87: Get latency metrics for a session.

  Parameters

  • id: string

  Returns
      | {
          hook_latency_ms: number
          | null;
          state_change_detection_ms: number | null;
          permission_response_ms: number | null;
      }
      | null

isWindowAlive

• isWindowAlive(id: string): Promise<boolean>

  Check if a session's tmux window still exists and has a live process. Issue #69: A window can exist with a crashed/zombie CC process (zombie window). After checking window exists, also verify the pane PID is alive. Issue #390: Check stored ccPid first for immediate crash detection. When CC crashes (SIGKILL, OOM), the shell prompt returns in the pane, so the current pane PID is the shell (alive). Checking ccPid catches the crash within seconds instead of waiting for the 5-min stall timer.

  Parameters

  • id: string

  Returns Promise<boolean>

listSessions

• listSessions(): SessionInfo[]

  List all sessions.

  Returns SessionInfo[]

findIdleSessionByWorkDir

• findIdleSessionByWorkDir(workDir: string): Promise<SessionInfo | null>

  Issue #607: Find an idle session for the given workDir. Returns the most recently active idle session, or null if none found. Used to resume existing sessions instead of creating duplicates. Issue #636: Verifies tmux window is still alive before returning. Issue #840/#880: Atomically acquires the session under a mutex to prevent TOCTOU race.

  Parameters

  • workDir: string

  Returns Promise<SessionInfo | null>

releaseSessionClaim

• releaseSessionClaim(id: string): void

  Release a session claim after the reuse path completes (success or failure).

  Parameters

  • id: string

  Returns void

getHealth

• getHealth(
      id: string,
  ): Promise<
      {
          alive: boolean;
          windowExists: boolean;
          claudeRunning: boolean;
          paneCommand: string
          | null;
          status: UIState;
          hasTranscript: boolean;
          lastActivity: number;
          lastActivityAgo: number;
          sessionAge: number;
          details: string;
          actionHints?: Record<
              string,
              { method: string; url: string; description: string },
          >;
      },
  >

  Get health info for a session. Issue #2: Returns comprehensive health status for orchestrators.

  Parameters

  • id: string

  Returns Promise<
      {
          alive: boolean;
          windowExists: boolean;
          claudeRunning: boolean;
          paneCommand: string
          | null;
          status: UIState;
          hasTranscript: boolean;
          lastActivity: number;
          lastActivityAgo: number;
          sessionAge: number;
          details: string;
          actionHints?: Record<
              string,
              { method: string; url: string; description: string },
          >;
      },
  >

sendMessage

• sendMessage(
      id: string,
      text: string,
  ): Promise<{ delivered: boolean; attempts: number }>

  Send a message to a session with delivery verification. Issue #1: Uses capture-pane to verify the prompt was delivered. Returns delivery status for API response.

  Parameters

  • id: string
  • text: string

  Returns Promise<{ delivered: boolean; attempts: number }>

recordPermissionPrompt

• recordPermissionPrompt(id: string): void

  Record that a permission prompt was detected for this session.

  Parameters

  • id: string

  Returns void

approve

• approve(id: string): Promise<void>

  Approve a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys.

  Parameters

  • id: string

  Returns Promise<void>

reject

• reject(id: string): Promise<void>

  Reject a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys.

  Parameters

  • id: string

  Returns Promise<void>

waitForPermissionDecision

• waitForPermissionDecision(
      sessionId: string,
      timeoutMs?: number,
      toolName?: string,
      prompt?: string,
  ): Promise<PermissionDecision>

  Issue #284: Store a pending permission request and return a promise that resolves when the client approves/rejects via the API.

  Parameters

  • sessionId: string

    Aegis session ID

  • timeoutMs: number = 10_000

    Timeout before auto-rejecting (default 10_000ms, matching CC's hook timeout)

  • OptionaltoolName: string

    Optional tool name from the hook payload

  • Optionalprompt: string

    Optional permission prompt text

  Returns Promise<PermissionDecision>

  Promise that resolves with the client's decision

hasPendingPermission

• hasPendingPermission(sessionId: string): boolean

  Check if a session has a pending permission request.

  Parameters

  • sessionId: string

  Returns boolean

getPendingPermissionInfo

• getPendingPermissionInfo(
      sessionId: string,
  ): { toolName?: string; prompt?: string } | null

  Get info about a pending permission (for API responses).

  Parameters

  • sessionId: string

  Returns { toolName?: string; prompt?: string } | null

cleanupPendingPermission

• cleanupPendingPermission(sessionId: string): void

  Clean up any pending permission for a session (e.g. on session delete).

  Parameters

  • sessionId: string

  Returns void

waitForAnswer

• waitForAnswer(
      sessionId: string,
      toolUseId: string,
      question: string,
      timeoutMs?: number,
  ): Promise<string | null>

  Issue #336: Store a pending AskUserQuestion and return a promise that resolves when the external client provides an answer via POST /answer.

  Parameters

  • sessionId: string
  • toolUseId: string
  • question: string
  • timeoutMs: number = 30_000

  Returns Promise<string | null>

submitAnswer

• submitAnswer(sessionId: string, questionId: string, answer: string): boolean

  Issue #336: Submit an answer to a pending question. Returns true if resolved.

  Parameters

  • sessionId: string
  • questionId: string
  • answer: string

  Returns boolean

hasPendingQuestion

• hasPendingQuestion(sessionId: string): boolean

  Issue #336: Check if a session has a pending question.

  Parameters

  • sessionId: string

  Returns boolean

getPendingQuestionInfo

• getPendingQuestionInfo(
      sessionId: string,
  ): { toolUseId: string; question: string; timestamp: number } | null

  Issue #336: Get info about a pending question.

  Parameters

  • sessionId: string

  Returns { toolUseId: string; question: string; timestamp: number } | null

cleanupPendingQuestion

• cleanupPendingQuestion(sessionId: string): void

  Issue #336: Clean up any pending question for a session.

  Parameters

  • sessionId: string

  Returns void

escape

• escape(id: string): Promise<void>

  Send Escape key.

  Parameters

  • id: string

  Returns Promise<void>

interrupt

• interrupt(id: string): Promise<void>

  Send Ctrl+C.

  Parameters

  • id: string

  Returns Promise<void>

readMessages

• readMessages(
      id: string,
  ): Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

  Read new messages from a session.

  Parameters

  • id: string

  Returns Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

readMessagesForMonitor

• readMessagesForMonitor(
      id: string,
  ): Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

  Read new messages for the monitor (separate offset from API reads).

  Parameters

  • id: string

  Returns Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

getSummary

• getSummary(
      id: string,
      maxMessages?: number,
  ): Promise<
      {
          sessionId: string;
          windowName: string;
          status: UIState;
          totalMessages: number;
          messages: { role: string; contentType: string; text: string }[];
          createdAt: number;
          lastActivity: number;
          permissionMode: string;
          prd?: string;
      },
  >

  Issue #35: Get a condensed summary of a session's transcript.

  Parameters

  • id: string
  • maxMessages: number = 20

  Returns Promise<
      {
          sessionId: string;
          windowName: string;
          status: UIState;
          totalMessages: number;
          messages: { role: string; contentType: string; text: string }[];
          createdAt: number;
          lastActivity: number;
          permissionMode: string;
          prd?: string;
      },
  >

readTranscript

• readTranscript(
      id: string,
      page?: number,
      limit?: number,
      roleFilter?: "user" | "assistant" | "system",
  ): Promise<
      {
          messages: ParsedEntry[];
          total: number;
          page: number;
          limit: number;
          hasMore: boolean;
      },
  >

  Paginated transcript read — does NOT advance the session's byteOffset.

  Parameters

  • id: string
  • page: number = 1
  • limit: number = 50
  • OptionalroleFilter: "user" | "assistant" | "system"

  Returns Promise<
      {
          messages: ParsedEntry[];
          total: number;
          page: number;
          limit: number;
          hasMore: boolean;
      },
  >

readTranscriptCursor

• readTranscriptCursor(
      id: string,
      beforeId?: number,
      limit?: number,
      roleFilter?: "user" | "assistant" | "system",
  ): Promise<
      {
          messages: (ParsedEntry & { _cursor_id: number })[];
          has_more: boolean;
          oldest_id: number | null;
          newest_id: number | null;
      },
  >

  Cursor-based transcript read — stable under concurrent appends.

  Uses 1-based sequential entry indices as cursors.

  • beforeId: exclusive upper bound (fetch entries with index < beforeId). If omitted, fetch the newest limit entries.
  • limit: max entries to return (capped at 200).
  • Returns entries in ascending order (oldest first) within the window.

  Parameters

  • id: string
  • OptionalbeforeId: number
  • limit: number = 50
  • OptionalroleFilter: "user" | "assistant" | "system"

  Returns Promise<
      {
          messages: (ParsedEntry & { _cursor_id: number })[];
          has_more: boolean;
          oldest_id: number | null;
          newest_id: number | null;
      },
  >

killSession

• killSession(id: string): Promise<void>

  Kill a session.

  Parameters

  • id: string

  Returns Promise<void>