Codeman/src/types/session.ts

/**
 * @fileoverview Session type definitions.
 *
 * Core domain type — SessionState is the primary entity in the system.
 *
 * Key exports:
 * - SessionState — full session state (status, tokens, respawn, ralph, CLI metadata)
 * - SessionConfig — creation-time config (id, workingDir, createdAt)
 * - SessionOutput — captured stdout/stderr/exitCode
 * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
 * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp' | 'copilot' (which CLI backend)
 * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools')
 * - SessionColor — visual differentiation color
 * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
 * - CodexConfig — Codex (OpenAI CLI)-specific settings (model, reasoningEffort, resumeSessionId, bypass, animations, renderMode)
 * - GeminiConfig — Gemini CLI-specific settings (model, approvalMode, resumeSession)
 * - AntigravityConfig — Antigravity CLI (agy) settings (model, dangerouslySkipPermissions, resumeConversationId)
 * - PiConfig — Pi CLI (pi.dev) settings (model, provider, thinking, resume/continue, project trust)
 * - GrokConfig — Grok Build CLI (xAI `grok`) settings (model, alwaysApprove, resume/continue)
 * - CopilotConfig — GitHub Copilot CLI settings (model, allowAll, resume/continue)
 * - DeepSeekConfig — DeepSeek Harness (`dsh`) settings (profile, permissionMode, resume, status bridge)
 *
 * Cross-domain relationships:
 * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
 * - SessionState.id is referenced by: RalphSessionState.sessionId (ralph),
 *   RunSummary.sessionId (run-summary), ActiveBashTool.sessionId (tools),
 *   TeamConfig.leadSessionId (teams), RespawnCycleMetrics.sessionId (respawn),
 *   TaskState.assignedSessionId (task)
 *
 * Persisted to `~/.codeman/state.json`. Served at `GET /api/sessions` and
 * `GET /api/sessions/:id`.
 */

import type { RespawnConfig } from './respawn.js';
import type { AttachmentDetectedType } from './tools.js';
import type { GitFetchStatus } from '../git-fetch.js';

/** Status of a Claude session */
export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';

/**
 * Claude CLI startup permission mode.
 * - `'dangerously-skip-permissions'`: Bypass all permission prompts (default)
 * - `'auto'`: Anthropic's classifier-guarded low-prompt mode (`--permission-mode auto`)
 * - `'normal'`: Standard mode with permission prompts
 * - `'allowedTools'`: Only allow specific tools (requires allowedTools list)
 */
export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools';

/** Session mode: which CLI backend a session runs */
export type SessionMode =
  | 'claude'
  | 'shell'
  | 'opencode'
  | 'codex'
  | 'gemini'
  | 'antigravity'
  | 'pi'
  | 'grok'
  | 'deepseek'
  | 'omp'
  | 'copilot';

/**
 * Who owns a session's name. `placeholder`: Codeman's own `w<n>-<case>` (or no
 * name at all), still eligible for auto-naming. `auto`: titled after its first
 * prompt (`w<n>-<case>: <title>`), which happens once. `manual`: set by a
 * person; auto-naming never touches it.
 */
export type SessionNameSource = 'placeholder' | 'auto' | 'manual';

/** Options for `Session.write()` / `Session.writeViaMux()`. */
export interface SessionWriteOptions {
  /**
   * The bytes were typed by a person, or sent by an agent on their behalf
   * (browser keystrokes, `POST /api/sessions/:id/input`). Only such input can
   * name a tab; Ralph, respawn, cron and approval writes leave this unset.
   */
  fromUser?: boolean;
}

export type RemoteCommandMode = Extract<
  SessionMode,
  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp' | 'copilot'
>;

/**
 * Advanced SSH connection options shared by RemoteHost and SessionRemote.
 *
 * COD-107 — all fields are optional; every field absent reproduces today's
 * behavior (port-22, default-identity, directly-SSH-able hosts). These describe
 * HOW Codeman reaches the host (identity, proxy, jump host, arbitrary `-o`),
 * letting it connect to e.g. a host fronted by a cloudflared SOCKS5 proxy on a
 * custom port — the same connection `ssh-aa-desktop` makes — without a wrapper.
 */
export interface RemoteSshOptions {
  /**
   * Path to an SSH identity (private key) file — path ONLY, never key bytes.
   * A leading `~`/`$HOME` is expanded to an absolute path at command-build time
   * (ssh does not expand `~` in `-i`).
   */
  identityFile?: string;
  /**
   * SOCKS5 proxy as `host:port` (e.g. `127.0.0.1:1080`). Expands to
   * `-o ProxyCommand=nc -X 5 -x <host:port> %h %p` (the cloudflared/SOCKS5 case).
   */
  socksProxy?: string;
  /** SSH jump host (`[user@]host[:port]`) emitted as `-J <jumpHost>`. */
  jumpHost?: string;
  /** Arbitrary additional `-o KEY=VALUE` options (escape hatch). Each `KEY=VALUE`. */
  extraSshOptions?: string[];
}

export interface RemoteHost extends RemoteSshOptions {
  id: string;
  label: string;
  host: string;
  username: string;
  port?: number;
  commands?: Partial<Record<RemoteCommandMode, string>>;
  /**
   * Optional Wake-on-LAN MAC address(es), comma-separated (e.g.
   * `04:d9:f5:80:c6:58`). Codeman sends the magic packet itself (UDP port 9
   * broadcast), so the common case needs no external script. A SLEEPING host's
   * port-22 probe still fails, which is what triggers the wake — this only
   * controls HOW the host is woken.
   */
  wakeMac?: string;
  /**
   * Optional Wake-on-LAN command that powers this host on from SLEEP (e.g. a
   * wrapper script like `/home/joe/bin/whuff`). TAKES PRECEDENCE over `wakeMac`
   * (an explicit override for hosts that need a router/other-host wake). Absent
   * = no wake support and today's behavior exactly. Executed WITHOUT a shell (a
   * single executable path, never a command line), only from user input or an
   * explicit wake request on a session whose host is unreachable — never from
   * the auto-reconnect/boot-recovery path, which would re-wake a host seconds
   * after each suspend.
   */
  wakeCommand?: string;
}

export interface RemoteCase {
  name: string;
  type: 'remote';
  /** Owning username in multi-user mode; absent = legacy/unassigned (admin-only). */
  owner?: string;
  hostId: string;
  remotePath: string;
}

export interface SessionRemote extends RemoteSshOptions {
  hostId: string;
  label: string;
  host: string;
  username: string;
  port?: number;
  remotePath: string;
  commands?: Partial<Record<RemoteCommandMode, string>>;
  /**
   * COD-105 — whether THIS Codeman created the remote tmux session.
   *
   * - `true` (default for COD-104 launched sessions): we own the remote session;
   *   an explicit "kill" may propagate a remote `tmux kill-session`.
   * - `false` (discovered + attached an existing remote session another Codeman
   *   created): closing the local tab must DETACH only — we must NEVER issue a
   *   remote `kill-session`, or we'd nuke work the remote's own Codeman (or
   *   another instance) still relies on. See `killSession()` gate.
   *
   * Absent is treated as owned (legacy/COD-104 sessions persisted before this
   * field existed were all launched by us).
   */
  owned?: boolean;
  /**
   * COD-105 — for a NON-owned (discovered + attached) session, the EXISTING
   * remote tmux session name to `attach -t` (e.g. `codeman-disco1`). It differs
   * from this Codeman's deterministic `codeman-<id>` name because the remote
   * session was created elsewhere. Only meaningful when `owned === false`.
   */
  remoteSessionName?: string;
  /**
   * Wake-on-LAN command carried over from the host config (see `RemoteHost.wakeCommand`)
   * so the input route can wake a sleeping host without re-reading the host list.
   */
  wakeCommand?: string;
  /** Wake-on-LAN MAC address(es) from the host config (see `RemoteHost.wakeMac`). */
  wakeMac?: string;
}

/**
 * COD-105 — a `codeman-*` tmux session discovered on a remote host's
 * `tmux -L codeman` socket (may have been created by the remote's own Codeman,
 * another instance, or this one). Returned by `listRemoteCodemanSessions`.
 */
export interface RemoteSessionInfo {
  /** tmux session name (always starts `codeman-`). */
  name: string;
  /** Whether at least one client is currently attached to the remote session. */
  attached: boolean;
  /** COD-106 — number of clients attached (tmux `session_attached`); >1 = shared. */
  attachedClients: number;
  /** tmux `session_created` epoch seconds. */
  created: number;
  /** Number of windows in the remote session. */
  windows: number;
}

// ========== Docker cases (COD-Docker) ==========
//
// Docker mode is a LOCATION OVERLAY on cases (never a 6th SessionMode), the exact
// analog of the remote-SSH feature above: instead of a local tmux pane running
// `ssh host` into a durable remote tmux server, a local tmux pane runs
// `docker exec -it` into a durable in-container tmux server. The container is
// scoped to the CASE (not the session), so multiple sessions can `docker exec`
// into the same long-lived container. See `docs/docker-cases-plan.md`.

/** Which CLI backends a Docker case can run (same set as remote). */
export type DockerCommandMode = Extract<
  SessionMode,
  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp' | 'copilot'
>;

/** Container engine. Docker and Podman differ in the uid/userns + host-gateway alias. */
export type DockerEngine = 'docker' | 'podman';

/**
 * Container network mode. `host` and any inbound `-p` publish are deliberately
 * unrepresentable (never in this union, never emitted by the flag builder).
 * - `bridge`: own netns, NAT egress, no inbound (default — every API CLI needs egress)
 * - `none`: fully offline sandbox (breaks API CLIs; reserved for `shell`)
 * - `custom`: a user-defined bridge `codeman-net-<slug>` (future egress-allowlist chokepoint)
 */
export type DockerNetworkMode = 'bridge' | 'none' | 'custom';

/** Per-container resource caps. Advisory under non-delegated rootless (see `capsEnforced`). */
export interface DockerResourceLimits {
  /** e.g. '4g' -> --memory 4g --memory-swap 4g (swap==memory: a real OOM cap) */
  memory?: string;
  /** e.g. '2' -> --cpus 2 */
  cpus?: string;
  /** e.g. 512 -> --pids-limit 512 (fork-bomb guard) */
  pidsLimit?: number;
  /** e.g. '4096:8192' -> --ulimit nofile=4096:8192 */
  nofile?: string;
  /** e.g. '256m' -> --shm-size (only when a tool needs /dev/shm) */
  shmSize?: string;
}

/** A reusable Docker engine/image/network/resource profile (mirror of RemoteHost). */
export interface DockerHost {
  id: string;
  label: string;
  /** Engine; when absent the availability probe resolves it (docker, else podman). */
  engine?: DockerEngine;
  /** Base image ref (built locally by scripts/build-agent-image.mjs, e.g. codeman/agent:base). */
  image: string;
  /** Advanced: remote daemon (-H ssh://user@host or a DOCKER_HOST value). */
  daemonHost?: string;
  /** Advanced: docker `--context` name. */
  context?: string;
  /** Network mode (default 'bridge'). */
  network?: DockerNetworkMode;
  /** Custom bridge name when network === 'custom'. */
  networkName?: string;
  resources?: DockerResourceLimits;
  /** GPU allocation, e.g. 'all' / '1' / 'device=0,1' -> `--gpus <value>` (needs the NVIDIA container toolkit). */
  gpus?: string;
  /** true (default) = convenient: bind-mount host cred dirs RW. false = sealed (blocks full-image export). */
  mountCredentials?: boolean;
  /** true (default) = wire in-container hooks (host-gateway callback + workspace scaffold). */
  hooksEnabled?: boolean;
  /** true (default) = a relaunch resumes the last conversation from the bind-mounted transcript. */
  resumeOnStart?: boolean;
  /** Per-mode command overrides (mirror RemoteHost.commands). */
  commands?: Partial<Record<DockerCommandMode, string>>;
  /** Escape hatch: extra `docker create` args (validated like extraSshOptions). */
  extraCreateArgs?: string[];
  /** Escape hatch: extra `docker exec` args. */
  extraExecArgs?: string[];
}

/** A case linked to a Docker container (mirror of RemoteCase). */
export interface DockerCase {
  name: string;
  type: 'docker';
  /** Owning username in multi-user mode; absent = legacy/unassigned (admin-only). */
  owner?: string;
  hostId: string;
  /** Absolute HOST directory: the bind-mount source AND Session.workingDir (real host bytes). */
  hostWorkspacePath: string;
  /** Container path (default = hostWorkspacePath: mirror -> transcript projHash correlates). */
  containerWorkdir?: string;
  /** Container name (default codeman-case-<slug>). */
  container?: string;
  /**
   * Whether THIS Codeman created the container (mirror of `SessionRemote.owned`).
   *
   * - `true` (default for cases Codeman linked/quick-created): we own the
   *   container; drift may recreate it, case-delete may `docker rm -f` it, and
   *   the launch chain may create + start it.
   * - `false` (ADOPTED: an already-running container the user built and runs
   *   themselves): Codeman must never create, start, stop, restart or remove it.
   *   The launch chain fails closed when the container is missing or not running
   *   instead of touching its lifecycle, drift is not evaluated (there is no
   *   `codeman.confighash` label to compare), and no credential seed is copied
   *   into its HOME. Only the in-container tmux session is ever created or
   *   killed — exactly the `owned:false` remote-SSH contract.
   *
   * Absent is treated as owned (cases persisted before this field existed were
   * all created by us).
   */
  owned?: boolean;
  /**
   * CLIs found INSIDE the container by the adoption preflight. A container case
   * runs its agents in the container, so host CLI availability says nothing about
   * what this case can run — the base image ships every CLI, and an adopted
   * container ships whatever its owner installed. Absent = unknown (owned cases,
   * or a case linked before this field existed), which callers read as "do not
   * gate".
   */
  availableModes?: SessionMode[];
  /** Last captured Claude conversation id, replayed via --resume on a fresh launch. */
  lastClaudeSessionId?: string;
}

/**
 * Flattened Docker execution metadata carried on a live session (mirror of
 * SessionRemote). Round-trips through MuxSession/SessionState/mux-sessions.json.
 */
export interface SessionDocker {
  hostId: string;
  label: string;
  engine: DockerEngine;
  image: string;
  /** Per-CASE container name (shared by all sessions of the case). */
  containerName: string;
  hostWorkspacePath: string;
  containerWorkdir: string;
  network: DockerNetworkMode;
  networkName?: string;
  resources?: DockerResourceLimits;
  /** GPU allocation ('all' / '1' / 'device=0,1'). */
  gpus?: string;
  mountCredentials: boolean;
  hooksEnabled: boolean;
  resumeOnStart: boolean;
  daemonHost?: string;
  context?: string;
  commands?: Partial<Record<DockerCommandMode, string>>;
  extraCreateArgs?: string[];
  extraExecArgs?: string[];
  /** Stable hash of the drift-relevant create args (recreate-on-drift detection). */
  configHash?: string;
  /**
   * Whether the container's exec user is root. Claude Code REFUSES
   * `--dangerously-skip-permissions` as root, and an adopted container's user
   * belongs to its owner, so the flag is omitted rather than letting the pane
   * die with a message only visible inside the container.
   */
  runsAsRoot?: boolean;
  /**
   * Mirror of `DockerCase.owned`, flattened onto the live session so every
   * lifecycle decision (launch chain, drift, stop, remove) can see it without
   * re-reading docker-cases.json. Absent = owned. See `DockerCase.owned`.
   */
  owned?: boolean;
}

/**
 * Valid Claude CLI effort levels (claude >= 2.1.154).
 * `ultracode` = xhigh effort + standing dynamic-workflow orchestration; it is a
 * separate `ultracode` settings key rather than an `effortLevel` value.
 */
export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'] as const;

/** Claude CLI effort level for new sessions (soft default, switchable via /effort in-session) */
export type EffortLevel = (typeof EFFORT_LEVELS)[number];

/** Type guard: is the string a valid EffortLevel? */
export function isEffortLevel(value: string | undefined): value is EffortLevel {
  return value !== undefined && (EFFORT_LEVELS as readonly string[]).includes(value);
}

/**
 * Reasoning effort levels codex accepts as `model_reasoning_effort` (codex-cli 0.154.0).
 * Which of them a given model honours is codex's business; Codeman only keeps the value
 * to a known word, since it lands in the launch argv.
 */
export const CODEX_REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'] as const;

/** Codex reasoning effort for a session, passed as `--config model_reasoning_effort=<level>` */
export type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORTS)[number];

/**
 * Model aliases Claude Code accepts for its advisor tool (a stronger model the session's
 * main model consults at decision points; code.claude.com/docs/en/advisor). Haiku is left
 * out on purpose: it can call an advisor but never act as one.
 */
export const ADVISOR_MODEL_ALIASES = ['fable', 'opus', 'sonnet'] as const;

/** A full model id in one of the advisor-capable families, e.g. `claude-opus-5-5`. */
const ADVISOR_MODEL_ID_PATTERN = /^claude-(?:fable|opus|sonnet)-[a-z0-9]+(?:-[a-z0-9]+)*$/;

/**
 * Type guard: is the value an advisor model Codeman will pass to claude? An alias from
 * ADVISOR_MODEL_ALIASES or a full fable/opus/sonnet model id. ⚠️ This allowlist is also the
 * injection guard: the value is rendered inside the single-quoted `--settings` JSON argument.
 */
export function isAdvisorModel(value: unknown): value is string {
  if (typeof value !== 'string' || value.length > 64) return false;
  return (ADVISOR_MODEL_ALIASES as readonly string[]).includes(value) || ADVISOR_MODEL_ID_PATTERN.test(value);
}

/** OpenCode session configuration */
export interface OpenCodeConfig {
  /** Model identifier (e.g., "anthropic/claude-sonnet-4-5", "openai/gpt-5.2", "ollama/codellama") */
  model?: string;
  /** Whether to auto-allow all tool executions (sets permission.* = allow) */
  autoAllowTools?: boolean;
  /** Session ID to continue from */
  continueSession?: string;
  /** Whether to fork when continuing (branch the conversation) */
  forkSession?: boolean;
  /** Custom inline config JSON (passed via OPENCODE_CONFIG_CONTENT) */
  configContent?: string;
}

/** Codex (OpenAI CLI) browser rendering strategy. Hybrid TUI is the only supported mode. */
export type CodexRenderMode = 'hybrid';

/** Codex (OpenAI CLI) session configuration */
export interface CodexConfig {
  /** Model identifier (e.g., "gpt-5", "o4-mini"). Passed via --model. */
  model?: string;
  /** Reasoning effort for this session. Passed via --config model_reasoning_effort=<level>. */
  reasoningEffort?: CodexReasoningEffort;
  /** Resume a previous codex conversation by session id (passed via --resume) */
  resumeSessionId?: string;
  /** Bypass approval prompts (passes --dangerously-bypass-approvals-and-sandbox) */
  dangerouslyBypassApprovals?: boolean;
  /** Enable Codex's decorative TUI animations. Disable to reduce remote terminal redraws. */
  animations?: boolean;
  /** Browser rendering strategy for Codex sessions. Hybrid TUI is the only supported mode. */
  renderMode?: CodexRenderMode;
}

/** Gemini CLI session configuration */
export interface GeminiConfig {
  /** Model identifier (e.g., "gemini-2.5-pro"). Passed via --model. */
  model?: string;
  /** Gemini approval mode for tool calls. */
  approvalMode?: 'default' | 'auto_edit' | 'yolo' | 'plan';
  /** Resume a previous Gemini session ("latest", index, or session id). */
  resumeSession?: string;
}

/** Antigravity CLI (agy) session configuration */
export interface AntigravityConfig {
  /** Model identifier. Passed via --model. */
  model?: string;
  /** Auto-approve all tool permission requests (passes --dangerously-skip-permissions). Absent = agy's default prompting. */
  dangerouslySkipPermissions?: boolean;
  /** Resume a previous conversation by ID (passed via --conversation). */
  resumeConversationId?: string;
}

/** OMP CLI session configuration */
export interface OmpConfig {
  /** Model identifier (e.g., "crof/glm-5.2"). Passed via --model. */
  model?: string;
  /** Resume a previous conversation (passed via --resume). */
  resumeSessionId?: string;
  /** Continue the most recent session in this directory (passed via --continue). */
  continueSession?: boolean;
}

/**
 * Pi CLI (pi.dev) session configuration.
 *
 * Pi has NO permission prompts and no `--dangerously-skip-permissions` analog,
 * so there is deliberately no bypass field here. The one privilege-shaped knob is
 * `approveProjectTrust`, which controls whether pi loads and EXECUTES repo-local
 * `.pi/` extensions (and installs missing project packages).
 */
export interface PiConfig {
  /** Model pattern or ID. Supports `provider/id` and a `:<thinking>` suffix (e.g. `sonnet:high`). Passed via --model. */
  model?: string;
  /** Provider name (anthropic, openai, google, ...). Passed via --provider. */
  provider?: string;
  /** Reasoning level. Passed via --thinking. */
  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
  /** Continue the most recent session (-c). Skipped when resumeSessionId is set (the two conflict). */
  continueSession?: boolean;
  /** Resume a specific session by ID or partial UUID (--session). Ids only, never paths. */
  resumeSessionId?: string;
  /**
   * Tri-state project trust (repo-local `.pi/` settings/extensions/skills, plus
   * installing missing project packages):
   *   true   -> --approve    (trust for this run; loads and EXECUTES repository TypeScript)
   *   false  -> --no-approve (force-deny; the trust prompt never appears)
   *   absent -> pi's own defaultProjectTrust (ask).
   * Multi-user: MATERIALIZED to false for non-granted owners, because pi's
   * absent-config default is a prompt the session user could answer themselves.
   */
  approveProjectTrust?: boolean;
}

/**
 * Grok Build CLI (xAI `grok`) session configuration.
 *
 * Grok has Claude-style permission modes; the bypass switch is `--always-approve`
 * ("auto-approve all tool executions", the CLI's `bypassPermissions` mode). Deny
 * rules from `~/.grok/config.toml` / project `.grok/config.toml` still apply on
 * top of it. Verified against grok 1.0.5.
 */
export interface GrokConfig {
  /** Model ID (e.g. "grok-4.5", or a custom `[model.<name>]` from config.toml). Passed via --model. */
  model?: string;
  /**
   * Auto-approve all tool executions (passes --always-approve). Absent = grok's
   * own default permission mode (ask). Multi-user: forced off for non-granted
   * owners by the only-if-sent clamp branch, like codex/antigravity — the
   * absent-config spawn already defaults safe.
   */
  alwaysApprove?: boolean;
  /** Continue the most recent session for the working directory (-c). Skipped when resumeSessionId is set. */
  continueSession?: boolean;
  /** Resume a specific session by ID (--resume). Ids only, never titles or paths. */
  resumeSessionId?: string;
}

/**
 * GitHub Copilot CLI (`copilot`) session configuration.
 *
 * Copilot asks before running tools ("Manual Approval") and before touching paths
 * outside the trusted folder. `--yolo` is its allow-all switch (tools, paths and URLs),
 * the one the Run button opts into like the other agent CLIs' bypass switches. Verified
 * against copilot 1.0.94.
 */
export interface CopilotConfig {
  /** Model ID passed via --model (e.g. "claude-sonnet-5.5", or "auto"). */
  model?: string;
  /**
   * Allow every tool, path and URL without asking (passes --yolo). Absent = Copilot's own
   * Manual Approval mode. Multi-user: forced off for non-granted owners by the only-if-sent
   * clamp branch, like codex/antigravity/grok.
   */
  allowAll?: boolean;
  /** Resume the most recent session (--continue). Skipped when resumeSessionId is set. */
  continueSession?: boolean;
  /**
   * Resume a specific session (--resume <value>): an id, id prefix or session name, as ONE plain word
   * starting with a letter or digit (a leading `-` would make the value its own flag).
   */
  resumeSessionId?: string;
}

/**
 * DeepSeek Harness (`dsh`) session configuration.
 *
 * Two things make this config shaped unlike every sibling above it.
 *
 * **1. The agent is a PROFILE, not the binary.** `dsh` is a launcher: it boots
 * `$DSH_HOME/profiles/<name>`, an ordered stack of plugin-bundle patch layers.
 * DeepSeek ships only `web`, `headless` and `base`, so the interactive terminal
 * agent is always a third-party profile the user installed. `profile` is
 * therefore the primary knob, and an absent one resolves to the first
 * pane-capable profile found (see resolveDefaultDeepSeekProfile).
 *
 * **2. Permissions are an ENV VAR, not a flag.** The harness has no
 * `--dangerously-skip-permissions` equivalent; its sandbox and approval rows are
 * config, driven by one documented input, `DSH_PERMISSION_MODE`, with three
 * presets (measured from `dsh --dump-default-config`):
 *
 *   read-only          sandbox read-only,          approval ask
 *   workspace-write    sandbox workspace-write,    approval ask     <- default
 *   danger-full-access sandbox danger-full-access, approval never
 *
 * This is the one place a Codeman env export is the RIGHT mechanism rather than
 * the forbidden one: unlike `CLAUDE_CODE_EFFORT_LEVEL` (which hard-locks
 * in-session `/effort`), `DSH_PERMISSION_MODE` is read with `??` as a boot-time
 * DEFAULT, so it stays a soft default the user can still change in-session. It
 * is exported via `tmux setenv`, never on the spawn command line.
 */
export interface DeepSeekConfig {
  /**
   * Profile under `$DSH_HOME/profiles` to boot (`dsh --profile <name>`). Absent
   * = the first pane-capable profile installed. A `web`/`headless` profile is
   * refused at spawn time: neither can drive an interactive pane.
   */
  profile?: string;
  /**
   * Sandbox + approval preset, exported as `DSH_PERMISSION_MODE`. Absent = the
   * harness's own `workspace-write` default, which still ASKS — which is why the
   * multi-user clamp only needs the only-if-sent branch here, like
   * codex/antigravity/grok rather than pi.
   */
  permissionMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
  /** Resume the most recent session for this workspace (`--resume`). */
  resumeSession?: boolean;
  /** Resume a specific session by ID (`--resume <id>`). Wins over resumeSession. */
  resumeSessionId?: string;
  /**
   * Report idle/working/blocked back to Codeman through the Herdr-compatible
   * status shim (see `deepseek-status-shim.ts`). Default ON: it upgrades this
   * mode from output-stabilization guessing to definitive hook events. Only
   * TUIs that implement the contract report; for one that does not, this is
   * inert rather than harmful.
   */
  statusReporting?: boolean;
}

/**
 * Configuration for creating a new session
 */
export interface SessionConfig {
  /** Unique session identifier */
  id: string;
  /** Working directory for the session */
  workingDir: string;
  /** Timestamp when session was created */
  createdAt: number;
}

/**
 * Available session colors for visual differentiation
 */
export type SessionColor = 'default' | 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink';

export type SessionAttachmentHistorySource = 'detected' | 'external';

/**
 * Session-scoped attachment history entry.
 *
 * `externalPath` is server-private. It may be present in the internal persisted
 * history copy, but API-bound session state must sanitize it before returning
 * to the browser.
 */
export interface SessionAttachmentHistoryItem {
  /** Stable history identity used for dedupe and list rendering */
  id: string;
  /** Codeman session ID this item belongs to */
  sessionId: string;
  /** Display filename */
  fileName: string;
  /** Lowercase extension without a leading dot */
  extension: string;
  /** Viewer category used by the web UI */
  attachmentType: AttachmentDetectedType;
  /** File size in bytes */
  size: number;
  /** Last modified timestamp in milliseconds, if known */
  mtimeMs: number;
  /** Last time this attachment was seen or explicitly published */
  timestamp: number;
  /** How the attachment entered the session */
  source: SessionAttachmentHistorySource;
  /** Workspace-relative path for detected session files */
  relativePath?: string;
  /** Server-private absolute path for explicitly published external files */
  externalPath?: string;
}

/**
 * Current state of a session
 */
/** The public half of a session's custom-model selection (on the wire, in `SessionState`). */
export interface CustomModelSelection {
  endpointId: string;
  modelId: string;
  label?: string;
}

/**
 * Where a session's {@link DisplayModel} came from (src/session-display-model.ts):
 * - `custom-endpoint`: the Custom Model Endpoint Profile's model, which wins.
 * - `statusline`: the CLI reported it (claude's statusLine exporter), follows a switch.
 * - `screen`: read off the CLI's own footer (`capabilities.modelDetect`), follows a switch.
 * - `config`: what the CLI's own config pins for this session
 *   (`capabilities.modelDetect.configResolver`), while its screen names none.
 * - `launch`: what the session was launched with; nothing has reported since.
 */
export type DisplayModelSource = 'custom-endpoint' | 'statusline' | 'screen' | 'config' | 'launch';

/** The model a session runs as far as the server knows, for a session header. */
export interface DisplayModel {
  /** Display text: sanitized (no control characters) and at most 64 characters. */
  model: string;
  source: DisplayModelSource;
}

/**
 * The full custom-model selection a session keeps: the public selection plus the
 * bookkeeping `Session.setCustomModel()` needs to UNDO it later without guessing what
 * it once wrote. Persisted to state.json only as the disk-only `__customModel` field
 * (never broadcast); the injected env VALUES are not in here at all, since they carry
 * the endpoint's API key, and are re-derived from the endpoint store on recovery.
 */
export interface CustomModelBookkeeping extends CustomModelSelection {
  /** Env keys the selection injected into the session's envOverrides / tmux session. */
  envKeys: string[];
  /** Isolated per-session config directory written for a `configDir`-kind CLI. */
  configDir?: string;
  /** Value forced onto the CLI's `model` launch param (pi/omp `custom/<id>`, grok's block name). */
  launchModel?: string;
}

/**
 * The agent inside a LOCAL tmux pane has exited, and the pane survived it.
 *
 * Codeman creates every pane with `remain-on-exit on`, so `/exit` ends the CLI
 * while tmux keeps the pane, the tmux session and the `tmux attach-session`
 * process Codeman records as the session's pid. No PTY exit handler runs, so
 * without this record the session reads as a live idle one (Ark0N/Codeman#446).
 *
 * The field is TRI-STATE, and the third state is the absence of the field:
 * `undefined` means Codeman does not know, and it must never be rendered as
 * "alive". It is absent for a direct-PTY session (no pane exists), for a remote
 * SSH session (the local pane holds the ssh client, whose death means transport
 * drop OR exit) and for a docker case (the local pane holds a `docker exec`
 * into the container's own tmux).
 *
 * `status` and `signal` are independently optional because tmux may know that
 * the pane died without reporting how. Measured on tmux 3.2a: a SIGKILLed pane
 * reports `pane_dead=1` with BOTH `#{pane_dead_status}` and `#{pane_dead_signal}`
 * empty, and `#{pane_dead_signal}` does not exist at all before tmux 3.4. So an
 * absent `status` means "the exit code is unknown", never "the exit code is 0".
 *
 * ⚠ AN ABSENT `status` STAYS ABSENT. Never write `status ?? 0`, and never read
 * "no signal was reported" as "the exit must have been clean". On tmux 3.2a
 * the absent status IS how a signal death presents, so absent-stays-absent is
 * the only thing keeping the clean-exit sweep (`pane-exit-sweep.ts`) away
 * from crashed agents: an agent SIGKILLed by the OOM killer would otherwise
 * read as a user typing `/exit` and be closed. Nothing here fails when
 * somebody adds that `??` — the types allow it and the label still renders.
 * The rule is enforced in `derivePaneExits()` (`tmux-manager.ts`), which omits
 * the key rather than defaulting it, and again in `isCleanPaneExit()`, which
 * accepts only an explicit 0.
 */
export interface PaneExit {
  /**
   * tmux `#{pane_dead_status}` — the command's exit code. Absent when tmux
   * reported none, which means UNKNOWN and never 0. See the ⚠ above before
   * giving this a default anywhere.
   */
  status?: number;
  /** tmux `#{pane_dead_signal}` — the signal that killed the command. Absent when unsignalled or unsupported. */
  signal?: number;
  /**
   * Wall-clock ms when THIS server process first observed the pane dead. It is
   * not when the agent exited, which nothing records, and a restart that finds
   * the pane still dead respawns it rather than re-timing the old exit.
   */
  at: number;
}

/**
 * Normalized prompt-cache state of a session's main conversation, from the statusline's
 * `prompt_cache` object (`parsePromptCache` in usage-telemetry.ts). `warm` is the only
 * field Claude always reports: once the prefix has gone cold it sends `warm:false` with a
 * null `expires_at`.
 */
export interface PromptCacheStatus {
  warm: boolean;
  /** Cache lifetime of the current prefix; Claude Code only ever reports these two. */
  ttl?: '5m' | '1h';
  /** Epoch MILLISECONDS when the cached prefix goes cold (the statusline reports seconds). */
  expiresAt?: number;
  /** Tokens the next request re-writes if the cache has gone cold by then. */
  recacheTokensIfCold?: number;
  /** Requests this session that re-processed content the cache already held. */
  misses?: number;
  /** Cache rebuilds that followed a compaction or a clearing of old tool results. */
  expectedRebuilds?: number;
  /** Cache read tokens as a fraction of all input tokens this session, 0-1. */
  hitRatio?: number;
  /** Claude Code's diagnosis of the last miss, e.g. `ttl_expired_1h` or `tools_changed`. */
  lastMissCauses?: string[];
  /**
   * Epoch MS when Codeman saw the context compacted (`/compact`, Claude Code's own idle
   * compaction, or a clearing of old tool results): the first warm report whose
   * `recacheTokensIfCold` is null after one that carried it. Carried while the null window holds,
   * dropped at the next request. Derived in `Session.setPromptCache`, not reported by the
   * statusline, so it is never set by `parsePromptCache`. Lets the readout say "Context compacted
   * at HH:MM"; it is never an alert.
   */
  compactedAt?: number;
}

/**
 * Whether this launch carries Codeman's statusLine exporter, the only source of
 * `promptCache`, and why not when it does not. Decided once per claude spawn
 * (`TmuxManager`), so a setting flipped later does not change it until the next launch.
 * - `injected`: the exporter is on the launch.
 * - `collection-off`: plan-usage collection (`showPlanUsageLimits`) was off at launch.
 * - `workspace-statusline`: the workspace's own `.claude/settings.local.json` sets a
 *   statusLine (or could not be read), and Codeman never replaces one there.
 * - `remote`: remote and Docker launches never carry the exporter.
 */
export type StatusLineExporter = 'injected' | 'collection-off' | 'workspace-statusline' | 'remote';

/**
 * What the prompt-cache keep-warm (`prompt-cache-keepwarm.ts`) is doing for a session, for
 * the Session Options readout. Ephemeral: published through `toState()` and the
 * `session:keepWarm` event, never restored.
 */
export interface KeepWarmStatus {
  /** Effective opt-in: the session's own flag, else the app-wide default (see `keepWarmOn`). */
  enabled: boolean;
  /**
   * Whether this launch carries `idleCompaction: false` (`MuxSession.idleCompactionOff`). False
   * on a session switched on after launch: Claude Code's own idle compaction may still run
   * until its next launch.
   */
  idleCompactionOff: boolean;
  /** `armed` = waiting for the due time, `waiting` = due but deferred by a guard, `nudged` = sent, waiting for the next cache report. */
  state: 'off' | 'armed' | 'waiting' | 'nudged' | 'stopped';
  /** Next evaluation, epoch ms (armed, waiting, nudged). */
  nextCheckAt?: number;
  /** Why it is waiting or stopped, in words. */
  reason?: string;
  /** Nudges sent this session so far. */
  nudges: number;
  lastNudgeAt?: number;
  /** When the keep-warm window after the last real prompt closes, epoch ms. */
  budgetEndsAt?: number;
}

export interface SessionState {
  /** Unique session identifier */
  id: string;
  /** Process ID of the PTY process, null if not running */
  pid: number | null;
  /** Current session status */
  status: SessionStatus;
  /** Working directory path */
  workingDir: string;
  /**
   * The directory the session's local tmux pane is in NOW (`#{pane_current_path}`),
   * when known. `workingDir` is fixed at create time and never follows a `cd`;
   * this is what a relative path printed in the terminal is relative to.
   *
   * Runtime-only: refreshed from the pane-exit watcher's read and never restored
   * from disk, so a restart starts blank. Absent for remote and docker sessions
   * (their local pane runs the ssh / docker-exec client) and for direct-PTY or
   * rediscovered sessions. NOT a confinement root: the file routes stay confined
   * to `workingDir`, and a path resolved outside it goes through the attachment
   * routes like any other out-of-workspace path.
   */
  paneCwd?: string;
  /** Remote execution metadata, present when this session runs over SSH through local tmux */
  remote?: SessionRemote;
  /** Docker execution metadata, present when this session runs inside a container via local tmux + docker exec */
  docker?: SessionDocker;
  /** Owning username in multi-user mode; undefined in single-user (ignored when the flag is off) */
  owner?: string;
  /**
   * The Codeman session that spawned this one, supplied by the caller at create time
   * (`parentSessionId` body field or the `X-Codeman-Parent-Session` header) and resolved
   * against live sessions before being stored.
   *
   * ⚠️ UI DECORATION ONLY — it draws the lineage lines between tabs. It is never an
   * ownership, permission, or lifecycle signal: a child outlives its parent, and an
   * unresolvable value is dropped rather than failing the spawn. Its one non-visual reader
   * picks a default, nothing more: a session an agent spawned does not inherit the app-wide
   * prompt-cache keep-warm default (`keepWarmOn`), though its own switch still works.
   */
  parentSessionId?: string;
  /** ID of currently assigned task, null if none */
  currentTaskId: string | null;
  /** Timestamp when session was created */
  createdAt: number;
  /** Timestamp of last activity */
  lastActivityAt: number;
  /** Session display name */
  name?: string;
  /** Who owns the name (see `SessionNameSource`); absent on states persisted before auto-naming existed. */
  nameSource?: SessionNameSource;
  /** Session mode */
  mode?: SessionMode;
  /** Auto-clear enabled */
  autoClearEnabled?: boolean;
  /** Auto-clear token threshold */
  autoClearThreshold?: number;
  /** Auto-compact enabled */
  autoCompactEnabled?: boolean;
  /** Auto-compact token threshold */
  autoCompactThreshold?: number;
  /** Auto-compact prompt */
  autoCompactPrompt?: string;
  /** Auto-resume on usage limit enabled */
  autoResumeEnabled?: boolean;
  /** Pending usage-limit auto-resume fire time (epoch ms), if armed */
  autoResumeAt?: number;
  /**
   * Prompt-cache state of the main conversation as Claude Code last reported it on the
   * statusline (v2.1.251+), fed by `POST /api/status-telemetry`. Absent until the first
   * report. Restored on a restart (the Session constructor's `promptCache`) so the readout
   * is not blank until the pane's next render; the readout is time-aware, so a value whose
   * `expiresAt` has passed reads as cold rather than as a stale warm.
   */
  promptCache?: PromptCacheStatus;
  /** Why a cache report will or will not arrive (see `StatusLineExporter`); absent when unknown. */
  statusLineExporter?: StatusLineExporter;
  /** Prompt-cache keep-warm opt-in; absent = follow the app-wide `promptCacheKeepWarm` default. */
  keepWarmEnabled?: boolean;
  /** What the keep-warm is doing right now; ephemeral, never restored. */
  keepWarm?: KeepWarmStatus;
  /**
   * Git fetch on an interval for this session's repositories; absent = follow the app-wide
   * `gitFetchEnabled` default. Restored on a restart, like `keepWarmEnabled`, because the choice is the
   * user's and outlives the run.
   */
  gitFetchEnabled?: boolean;
  /** Seconds between this session's runs; absent = follow the app-wide `gitFetchIntervalSeconds` default. */
  gitFetchIntervalSeconds?: number;
  /**
   * What this session's last fetch did. Written to disk with the rest of the record, but the restore copies
   * only the fields its own config lists and this is not one of them, so it is the panel's truth for the
   * life of the session, not across a restart.
   */
  gitFetch?: GitFetchStatus;
  /** Pinned to the top of the session manager list (COD-139) */
  pinned?: boolean;
  /** When the session was pinned (epoch ms) — orders the pinned group, most-recent-first */
  pinnedAt?: number;
  /** Image watcher enabled for this session */
  imageWatcherEnabled?: boolean;
  /** Total cost in USD */
  totalCost?: number;
  /** Input tokens used */
  inputTokens?: number;
  /** Output tokens used */
  outputTokens?: number;
  /** Whether respawn controller is currently enabled/running */
  respawnEnabled?: boolean;
  /** Respawn controller config (if enabled) */
  respawnConfig?: RespawnConfig & { durationMinutes?: number };
  /** Ralph / Todo tracker enabled */
  ralphEnabled?: boolean;
  /** Ralph auto-enable disabled (user explicitly turned off Ralph) */
  ralphAutoEnableDisabled?: boolean;
  /** Ralph completion phrase (if set) */
  ralphCompletionPhrase?: string;
  /** Parent agent ID if this session is a spawned agent */
  parentAgentId?: string;
  /** Child agent IDs spawned by this session */
  childAgentIds?: string[];
  /** Nice priority enabled */
  niceEnabled?: boolean;
  /** Nice value (-20 to 19) */
  niceValue?: number;
  /** User-assigned color for visual differentiation */
  color?: SessionColor;
  /** Flicker filter enabled (buffers output after screen clears) */
  flickerFilterEnabled?: boolean;
  /**
   * True while the CLI in the pane has a mouse-tracking DECSET on, as observed
   * by the server on its way out of the stream (those sequences are stripped for
   * the strip-full and strip-mux-and-mouse modes under tmux, so the browser can
   * never see them itself). The browser
   * hand-encodes a click report ONLY when this is true; without it, every click
   * sent mouse reports to a CLI that never asked for them.
   */
  cliMouseTracking?: boolean;
  /** Claude Code CLI version (parsed from terminal, e.g., "2.1.27") */
  cliVersion?: string;
  /** Claude model in use (parsed from terminal, e.g., "Opus 4.5") */
  cliModel?: string;
  /** Account type (parsed from terminal, e.g., "Claude Max", "API") */
  cliAccountType?: string;
  /** Latest CLI version available (parsed from version check) */
  cliLatestVersion?: string;
  /** OpenCode-specific configuration (only for mode === 'opencode') */
  openCodeConfig?: OpenCodeConfig;
  /** Codex-specific configuration (only for mode === 'codex') */
  codexConfig?: CodexConfig;
  /** Gemini-specific configuration (only for mode === 'gemini') */
  geminiConfig?: GeminiConfig;
  /** Antigravity-specific configuration (only for mode === 'antigravity') */
  antigravityConfig?: AntigravityConfig;
  /** Pi-specific configuration (only for mode === 'pi') */
  piConfig?: PiConfig;
  /** Grok-specific configuration (only for mode === 'grok') */
  grokConfig?: GrokConfig;
  /** GitHub Copilot CLI configuration (only for mode === 'copilot') */
  copilotConfig?: CopilotConfig;
  /** DeepSeek Harness configuration (only for mode === 'deepseek') */
  deepSeekConfig?: DeepSeekConfig;
  /** OMP-specific configuration (only for mode === 'omp') */
  ompConfig?: OmpConfig;
  /** Claude conversation session ID to resume after reboot (set by restore script) */
  resumeSessionId?: string;
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
  effort?: EffortLevel;
  /** Claude advisor model (`advisorModel` in the launch `--settings`, switchable in-session via /advisor) */
  advisorModel?: string;
  /**
   * The model the session was LAUNCHED with (`--model`): the caller's per-session `model`, or
   * the app-wide default when there was none. Persisted so a recovered session relaunches on
   * the same model rather than whatever the default is by then. Not `cliModel`, which is what
   * the CLI's banner reports. Claude sessions only (`cliTakesSessionModel()`): every other CLI
   * keeps its model in its own config object (`codexConfig.model` and so on), and this is
   * absent for them.
   */
  model?: string;
  /**
   * Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md): the custom
   * OpenAI-compatible endpoint (local or cloud) this session's CLI is currently pointed
   * at, if any. Undefined = the harness's native cloud default. No secrets here — the
   * endpoint's base URL/api key live only in Session._envOverrides, never in this public
   * state. The internal half (which env keys were injected, which config dir was
   * written) is {@link CustomModelBookkeeping}, persisted disk-only like `__envOverrides`.
   */
  customModel?: CustomModelSelection;
  /**
   * The model this session runs, as far as the server knows it, and where that came from
   * (src/session-display-model.ts): the custom endpoint's model, else the newest report
   * from the CLI itself (statusline or its own footer), else the model its config pins,
   * else the launch model. Absent when
   * none is known; a session header then shows the harness alone. Untrusted display text
   * (pane-derived for `screen`): render it as text. Persisted, and a `statusline`/`screen`
   * value is restored after a restart until the next report replaces it.
   */
  displayModel?: DisplayModel;
  /** Sanitized per-session attachment history. */
  attachmentHistory?: SessionAttachmentHistoryItem[];
  /**
   * Wall-clock ms of this pane's last Enter (Session.lastSubmitAt). Persisted
   * because it is the response-viewer's only anchor for re-deriving the pane's
   * live conversation after a Codeman restart: `start()` resets
   * `claudeSessionId` to the launch id even when re-attaching to a mux session
   * whose CLI has since moved on via `/clear`, and the correlation cannot run
   * again until the pane's own Enter is known.
   */
  lastSubmitAt?: number;
  /**
   * Wall-clock ms of the last submit that was NOT the prompt-cache keep-alive
   * (Session.lastRealPromptAt): the keep-warm cap's clock. Persisted so a restart
   * does not reopen the window, which `lastSubmitAt` cannot do since every nudge
   * moves it.
   */
  lastRealPromptAt?: number;
  /**
   * Claude conversations this pane has been on, oldest first, current last.
   * Written ONLY from a first-hand `UserPromptSubmit`/`Stop` hook payload —
   * never from the history correlation — so it cannot record a sibling pane's
   * conversation. Persisted because `/clear` is otherwise unrecoverable: once
   * the pane moves on, the predecessor id exists nowhere else, and the last
   * entry is what re-pins `claudeSessionId` past `start()`'s three resets.
   */
  claudeSessionChain?: string[];
  /**
   * PTY-exit circuit breaker tripped — respawn blocked until an explicit restart
   * (COD-118). Runtime-only: never restored on boot (fresh server = fresh breaker).
   */
  respawnBlocked?: boolean;
  /**
   * The agent in this session's LOCAL tmux pane has exited (Ark0N/Codeman#446).
   * See {@link PaneExit} for the tri-state rule and for which session shapes
   * leave it absent. `status` and `pid` are deliberately untouched by it: the
   * PTY-exit breaker owns `status: 'error'`, and a null `pid` is what makes the
   * browser re-attach and launch a fresh CLI.
   *
   * Persisted so a reboot restore can tell a session whose agent exited from one
   * that was merely idle when the power went. `reboot-restore.ts` reads the
   * persisted record and never builds a `Session`, so the record is the only
   * place that survives the reboot to carry it. Nothing reads it there YET:
   * making the restore refuse such a session is a behavior change, and it
   * belongs with the part of Ark0N/Codeman#446 that closes exited sessions.
   */
  paneExit?: PaneExit;
}

/**
 * Output captured from a session
 */