Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

282 KB
Raw Blame
import type {
  ChatDraftPutResult,
  ChatDraftTakeResult,
  ChatInterruptResult,
  ChatPromptResult, EmptyPromptResult, TextDeliveryResult } from './text-delivery'
import type { ChatScreenRead } from './agents/claude-screen'
import type { PushWebhookMinted, PushWebhookResult, PushWebhookTokenInfo } from './push-webhook'
import type { IdentitySeedEntry } from './agent-identity-seed'
import type { AgentStatusSnapshotEntry } from './agent-status-snapshot'
import type { WhiteboardFile, WhiteboardSaveResult } from './whiteboard'
import type { PrWaitHold } from './pr-wait'
import type { SessionBackend } from './session-backend'
import type { AgentIntegrationsSettings } from './agent-integrations'
import type { NodeSize, SizableNodeKind } from './default-node-size'
// Types shared across the main, preload, and renderer processes.

import { TABBAR_HEIGHT_PX } from './window-chrome-metrics'
import { DEFAULT_MARKDOWN_FONT_FAMILY, DEFAULT_MARKDOWN_FONT_SIZE } from './markdown-font'
import { DEFAULT_WORKTREE_PATH_TEMPLATE } from './worktree'
import type { CloneProgress } from './clone-url'
import type { KeybindingOverrides, TerminalShortcutPolicy } from './keybindings'
import type { NormalizedAgentEvent } from './agents/normalize'
import type { PaneOwner } from './agents/pane-owner-predicate'
import type { AnswerPermissionPayload, ChatQuestion } from './agents/permission-answer'
import type { HostChatQuery, HostChatReply } from './mobile-chat'
import type { AgentId, AgentPermissionMode, BuiltinAgentId, PromptInjectionMode } from './agents/config'
import type { ControlConfirmWaivers } from './control-confirm'
import type { AgentMessageDeliverRequest, AgentMessageReply } from './agents/agent-messaging'
import type { BoardCommentDeliverRequest } from './board-comment'
import type { ChatTranscriptPageRequest } from './chat-page'
import type { BrowserLeasePush } from './browser-indicator'
import type { GroupWorktree } from './worktree'
import type { ClientId, DinoSnapshot, PeerDiff, PeerIdentity, PeerState } from './presence'
import type { WhisperModelInfo } from './speech'
import type { ProjectKanbanGitHub } from './github-issues'
import type { KanbanPullAutoMove, KanbanPullLinks } from './kanban-pull-links'
import type { BoardDispatch } from './board-dispatch'
import type { CodexAccount } from './codex-account'
import type { ClaimResult, ProjectLimitState } from './project-limit'
import type { NotchAlign } from './notch-hud'
import type { ProjectIcon, ProjectIconPickResult } from './project-icon'
import type { AlertSoundKind, AlertSoundSaveResult, CustomAlertSounds } from './alert-sound'
import type { CanvasLayout, LayoutViewports } from './canvas-layout'
import type { ShareTeamApi } from './share-team'
import type {
  ModelDiscoveryResult,
  ModelGatewayCredentialStatus,
  ModelGatewaySettings
} from './agents/model-gateway'

/**
 * The default provider behavior for a FRESH agent spawn — the three-way successor to the old
 * `vanillaLaunchDefault` boolean. Read by `pty-manager`'s spawn-site strip gate and by the
 * renderer's new-node creation (`addAgentNode`):
 *  - `'gateway'`        — inject the model gateway env; the agent uses the CLI's OWN default model
 *                         (no `--model`). Today's behavior for a gateway node with no per-node model.
 *  - `'gateway-model'`  — inject the gateway env AND launch with the configured default gateway
 *                         model (`settings.modelGatewayDefaultModel`), so a new canvas session
 *                         opens on a chosen model without a per-node "Switch model" click.
 *  - `'subscription'`   — strip the gateway + inherited provider env so the agent runs against its
 *                         OWN default provider (Claude's subscription, Copilot's GitHub routing).
 *                         The former `vanillaLaunchDefault: true`. Wins even when a default model is
 *                         set (vanilla = no gateway at all, so the gateway model is moot).
 *
 * `vanillaLaunchDefault` is kept for one release as a migration MIRROR (an older build still honors
 * the choice); `agentLaunchMode === 'subscription'` ⇒ `vanillaLaunchDefault = true`, else `false`.
 */
export type AgentLaunchMode = 'gateway' | 'gateway-model' | 'subscription'

/** Profile-switch replacement intent. The trusted core validates and re-resolves it before teardown. */
export interface PtyRecycleTarget {
  profileId: string
  cwd: string
}

/**
 * A shell-independent request to start or resume an agent.
 *
 * The renderer deliberately does not turn this into a command line: the trusted core validates
 * the semantic fields, resolves the current machine-local agent configuration, and encodes the
 * launch for the concrete shell that owns the live session. In particular, `auto` is not a shell
 * dialect until immediately before a Windows profile is spawned.
 */
export type AgentLaunchIntent =
  | {
      kind: 'agent'
      action: 'start'
      agentId: AgentId
      /** Initial prompt for a new conversation. The core rejects control-bearing values. */
      prompt?: string
      /** Already version/policy-gated starting mode. The core re-validates it at execution. */
      permissionMode?: AgentPermissionMode
      /** Optional provider id minted for this first launch; never reused as a resume id. */
      newSessionId?: string
    }
  | {
      kind: 'agent'
      action: 'resume'
      agentId: AgentId
      /** Existing provider id. Required for resume and runtime-validated by the trusted core. */
      sessionId: string
      /** Starting mode for the reconstructed CLI, where the selected agent supports it. */
      permissionMode?: AgentPermissionMode
    }

/**
 * One locally-authorized launch held behind canvas dependencies.
 *
 * `shell-command` is the explicit `open-terminal --cmd` compatibility path. It is opaque shell
 * source, not something the app can safely parse back into argv. The whole PendingLaunch is
 * machine-local and must be stripped from shared project files, exports, and inbound mutations.
 */
export type TerminalLaunchIntent =
  | AgentLaunchIntent
  | { kind: 'shell-command'; command: string }

export type LaunchIntentFailureReason =
  | 'invalid-intent'
  | 'agent-unavailable'
  | 'unsupported-shell'
  | 'session-unavailable'
  | 'delivery-failed'

/** Opaque execution outcome. It must never contain a rendered command, executable, or argv. */
export type LaunchIntentExecutionResult =
  | { ok: true }
  | { ok: false; reason: LaunchIntentFailureReason; message: string }

/**
 * `pty:execute-launch` request (`PtyApi.executeLaunch`). `launchId` is a fresh UUID v4 per
 * delivery attempt — the session host's exactly-once ledger key. `promptFile` is the
 * canvas-control `--prompt-file` path: the core reads it (the file is on the core's machine) and
 * fills `intent.prompt`, so no shell ever has to expand `$(cat …)`. Only legal on a `start`
 * intent that carries no `prompt` of its own.
 */
export interface LaunchIntentRequest {
  launchId: string
  intent: AgentLaunchIntent
  promptFile?: string
}

/**
 * A semantic launch held beside a terminal node's legacy typed line (`data.launchIntent`). Bound
 * to the EXACT `command` it was assembled with: a writer delivering any other line (a manual Run
 * now of an edited command, a resume) never uses it. Live node data only — never serialized.
 */
export interface HeldLaunchIntent {
  command: string
  intent: AgentLaunchIntent
  promptFile?: string
}

export interface PtyCreateOptions {
  shell?: string
  /** Arguments for `shell` when it is run as the session program (e.g. ssh args). */
  shellArgs?: string[]
  cwd?: string
  cols: number
  rows: number
  /**
   * Stable key (the node id) used to derive a persistent tmux session name so the
   * terminal reattaches to the same session across remounts and app restarts.
   */
  persistKey?: string
  /**
   * The machine-local id (`IndexEntryV3.id`) of the project this node belongs to, as the renderer
   * knows it at the create call. Recorded in the runtime pane-ownership ledger on a GENUINE FRESH
   * spawn (`agents/pane-ownership.ts`) so agent messaging can prove which project actually spawned
   * a pane rather than trusting the git-shared, forgeable `project.json`. Optional: absent ⇒ the
   * pane is left unproven and messaging to it fails closed (never derived from the file id).
   */
  ownerProjectId?: string
  /**
   * Whether the node was on screen when the renderer asked for this session. Used ONLY to order
   * the per-ControlMaster remote spawn queue (`remote-ssh/pty-spawn-gate.ts`): a project switch
   * mounts every node in one tick, and without it the terminals the user is looking at queued
   * behind the ones they are not. `false` = queue behind on-screen spawns; absent (older clients,
   * relay, headless) = on-screen, i.e. the previous plain FIFO.
   */
  onScreen?: boolean
  /**
   * Which agent runs in this session (claude/codex/gemini/custom). Drives the hook env
   * injected at spawn. Defaults to 'claude' for backward compat; the renderer passes a
   * real value in a later phase.
   */
  agentId?: AgentId
  /** Per-node model override. Applied through the node's base harness on launch/cold restore. */
  agentModel?: string
  /**
   * One-shot: spawn (or re-spawn after a recycle) with gateway + inherited provider env stripped
   * so the agent runs against its OWN default provider (Claude's subscription, Copilot's GitHub
   * routing) instead of the configured gateway/inherited override. The strip set is per-agent
   * (`vanillaEnvStripPattern`); `CLAUDE_CONFIG_DIR` is deliberately kept (account isolation
   * survives). Cleared after the spawn resolves so a later ordinary Restart re-applies the gateway.
   */
  clearEnv?: boolean
  /** Managed Claude account: inject CLAUDE_CONFIG_DIR for this account into the session env. */
  accountId?: string
  /**
   * Which VIEW of the session this is, WITHIN one connection. A second view in the same renderer
   * (the kanban card modal) passes its own id so it co-attaches as an independently-detachable
   * subscriber rather than a no-op join; absent ⇒ the PRIMARY view (the canvas node) and bit-for-bit
   * the pre-viewer behavior. Invisible to peers — viewers collapse to the ClientId everywhere a
   * subscriber maps to a person.
   */
  viewerId?: string
  /** When set, this PTY runs on a remote host over the project's ssh ControlMaster, in remote tmux.
   * `remoteHome` is the connection's resolved `$HOME`, used to build an ABSOLUTE remote
   * `CLAUDE_CONFIG_DIR` for a managed remote account (tmux `-e` values are not shell-expanded). */
  sshRemote?: { controlPath: string; conn: import('./ssh').SshConnection; remoteCwd: string; hookEndpointPath?: string; tmuxConfPath?: string; remoteHome?: string }
  /**
   * This node BELONGS to a remote host: never spawn it locally.
   *
   * `sshRemote` says "here is the master to run over"; this says "and if there isn't one, spawn
   * NOTHING". Without it, a create with no `sshRemote` falls straight through to the local
   * tmux/plain-shell branches — which is how an SSH project's terminal, opened while the
   * ControlMaster was down (no network, laptop asleep, host unreachable), quietly became a LOCAL
   * shell in the local `$HOME`: same node id, same `SSH user@host` header chip, the remote
   * session's own scrollback snapshot replayed into it, and — for an agent node — a cold-restore
   * `claude --resume <remote session id>` running on the WRONG MACHINE, under the local account.
   * The refusal (`PtyCreateResult.unavailable`) is the honest answer: the node shows a
   * "not connected" overlay and re-spawns when the master is back.
   */
  requireRemote?: boolean
  /**
   * "If this create turns out to be a COLD start, I want the persisted scrollback back." Set by a
   * caller that would otherwise replay the snapshot into its own emulator (i.e. not a node being
   * opened for the first time with an `initialCommand`).
   *
   * It exists because the emulator is the wrong place for it on a tmux-backed session: tmux puts
   * the client on the alternate screen at attach, hiding anything written before it. With this
   * set, core writes the snapshot into the new PANE instead and answers
   * `PtyCreateResult.scrollbackSeeded`. Ignored on a warm attach, a co-attach join, an SSH-project
   * node and the non-tmux backends — there the caller's own replay still applies.
   */
  restoreScrollback?: boolean
  /**
   * The ONE way a terminal may run on THIS machine while it sits on an SSH project's canvas: the
   * local-account login node Settings → Accounts drops onto whatever canvas is active. Core refuses
   * every other local spawn whose `ownerProjectId` is an SSH project (`PtyManager.setSshProjectCheck`,
   * issue #1186) — the node fields that route a node remotely come from a shared file, and a node
   * that lacks them must never become a local shell. Set only from an in-memory, never-persisted
   * renderer mark (`renderer/lib/localOnSshCanvas.ts`), never from node data.
   */
  localOnSshCanvas?: boolean
  /**
   * Hosted-relay VIEWERS may watch a terminal but never start one: refuse a create that would spawn
   * a NEW session (`unavailable: 'join-only'`), while a co-attach join or a warm tmux reattach still
   * proceeds. Set only by the relay access policy (src/core/relay/access-policy.ts).
   */
  joinOnly?: boolean
  /**
   * The opposite of `joinOnly`: this create may only SPAWN a brand-new session. A co-attach join, a
   * reattach to a live tmux / session-host / Zellij session under this node's name, and a create
   * whose existence probe cannot answer are all refused (`unavailable: 'new-only'`), so the caller's
   * `fresh: true` means "this create made the session". Set only by the relay scoped-guest policy
   * (src/core/relay/scoped-guest-policy.ts) for a node id the guest introduced itself: naming a node
   * id must never be a way to take over a session somebody else is running under it.
   */
  newOnly?: boolean
  /**
   * `false`: this view never constrains the shared pty's size (a viewer's small window must not
   * shrink everyone's terminal). It is still a subscriber and is told the authoritative size.
   */
  sizeVote?: false
}

/** A tmux pane's cursor, as tmux reports it: 0-based column/row within the pane, plus whether the
 *  application currently wants it shown (`#{cursor_flag}`). */
export interface PaneCursor {
  x: number
  y: number
  visible: boolean
}

/** Outcome of typing keys into a node's pane by id (`PtyApi.sendPaneKeys`). Never a rejection. */
export type PaneKeysResult =
  | { ok: true }
  | { ok: false; reason: 'not-connected' | 'unsupported-backend' | 'no-ssh' | 'failed' }

/**
 * Result of creating a PTY session. `fresh` distinguishes a tmux session that had to be
 * created anew (cold start — e.g. after a machine reboot killed the tmux server) from a
 * reattach to a still-running session (warm — e.g. an app restart). The renderer uses it to
 * replay the persisted scrollback and re-launch a resumable agent only on a cold start.
 */
export interface PtyCreateResult {
  sessionId: string
  fresh: boolean
  /**
   * `fresh` is FALSE, but the freshness read never completed — so "a session already exists" was a
   * fold, not an answer (`RemoteSessionIndex`: only tmux's own exit 1 is evidence of absence, and
   * every other outcome answers "exists" because typing `claude --resume …` into a live agent pane
   * is the worse failure). SSH nodes only; a local `has-session` does not have this failure mode.
   *
   * Under a mount burst that overruns the host's `MaxSessions`, that fold is wrong often enough to
   * matter: `tmux new-session -A` then CREATES an empty session, `fresh:false` skips cold restore,
   * and the node sits at a bare shell with the user's conversation stranded on disk. MEASURED on
   * the reporting host: of 107 sessions created in one switch, 66 ended at a bare shell — against
   * 4 of 22 in a smaller burst minutes earlier, i.e. load-dependent, i.e. a race.
   *
   * The renderer re-asks ONCE after the attach has landed (tmux's own `#{session_created}` settles
   * it; see `PtyApi.sessionAge`) and runs the cold-restore relaunch if the session turns out to be
   * one we just made. Absent = the verdict was read, or this is not a remote node ⇒ nothing to
   * re-ask.
   */
  freshUnverified?: boolean
  /** Set when the node's `accountId` had no config dir at spawn, so the session fell back to the
   *  system account. The renderer flags the account chip (folder-missing warning) when true. */
  accountFallback?: boolean
  /**
   * WARM reattach only (local tmux): the reattached session's live working directory no longer
   * exists — the folder was deleted (or deleted and re-created, which is a DIFFERENT inode, so the
   * shell inside keeps printing `getcwd: cannot access parent directories`; issue #464). `tmux
   * new-session -A` ignores the cwd we pass on a reattach, so this is the only moment the fact is
   * knowable cheaply. The renderer shows a dismissible banner with an explicit
   * recycle-and-respawn action — NOTHING is typed into the pane and nothing restarts on its own
   * (the pane may be mid-work, and text into a pane is injection).
   *
   * Absent = fine or unknowable (fresh spawn, plain shell, SSH-remote session, probe failed, or a
   * core older than this field over the relay) — the banner never shows on a guess.
   */
  staleCwd?: boolean
  /**
   * The CURRENT SCREEN of a session this create JOINED (co-attach), captured from tmux — write it
   * into the fresh xterm before the live stream starts.
   *
   * Only a co-attaching client ever gets it, and only when the join left the pty's grid unchanged.
   * A joiner is `fresh:false`, so it skips the cold-restore scrollback replay; the only other thing
   * that could paint its empty terminal is a tmux redraw, and tmux only redraws on SIGWINCH — i.e.
   * when the joiner is strictly SMALLER and actually resizes the pty. Equal (the expected case: the
   * node's persisted geometry and the font settings are the same on both clients) or larger resizes
   * nothing, so without this the second viewer would sit on a blank-but-live terminal until the next
   * byte of output. When the join DOES resize, this is deliberately absent: tmux paints it, and
   * painting twice would splice two points in time.
   *
   * Guaranteed non-empty when present (an empty/failed capture is omitted, exactly like `pty:resync`
   * — a plain-shell session has no tmux to capture and simply gets nothing).
   */
  screen?: string
  /**
   * Where the CURSOR sits in the session that `screen` was captured from, in 0-based pane
   * coordinates, with tmux's cursor-visibility flag.
   *
   * The THIRD thing `capture-pane` does not carry, after the mouse modes below. Its output is the
   * pane's TEXT, so painting it leaves the emulator's cursor wherever the last character landed —
   * the end of the last non-blank row. That was visible as: refresh a terminal running an agent
   * CLI, and the block cursor sits at the end of the status line instead of in the input prompt,
   * until the first keystroke makes the app repaint and place it (reported 2026-08-05).
   *
   * Absent when tmux could not be asked, which the renderer treats as "leave the cursor alone" —
   * the pre-fix behaviour, and better than guessing a position.
   *
   * The coordinates are absolute in the pane, and the paint preserves that frame: the capture
   * starts at pane row 0, the renderer writes it into a terminal that is at least as tall (a
   * SMALLER joiner resizes the pty, and a resizing join gets no `screen` at all), and tmux trims
   * trailing blank rows — so nothing scrolls and pane row N is emulator row N.
   */
  cursor?: PaneCursor
  /**
   * This create JOINED a live TMUX-backed session (co-attach), so the fresh xterm must be told
   * tmux's mouse-tracking is on. tmux emits the mouse-enable DECSET sequences (`?1000h ?1002h
   * ?1006h`) to a client ONLY at its own attach — a mid-stream subscriber (the kanban card modal,
   * a second window) never sees them, and neither `screen` (`capture-pane` carries no private
   * modes) nor a SIGWINCH redraw re-emits them. Without them xterm treats the wheel as local
   * scrollback (empty on the alternate screen), so the joiner cannot scroll tmux's history until a
   * keystroke makes the app re-request mouse. The renderer writes `CO_ATTACH_MOUSE_SEQ` when this
   * is set. Since our tmux is always `mouse on` (local and remote), enabling these unconditionally
   * on a tmux-backed join matches tmux's own invariant client state; the enable is idempotent.
   * Set on BOTH join branches (screen-painted and resized) — the resize does not deliver them.
   * Absent for a plain-shell join (no tmux ⇒ no tmux mouse), for a session-host (Windows) join —
   * same gate as `coAttachAltScreen`: no tmux runs `mouse on` there, and enabled tracking would
   * hand the wheel and drags to the shell — and for the solo spawn path.
   */
  coAttachMouse?: boolean
  /**
   * A TMUX-BACKED joiner must switch its fresh xterm to the ALTERNATE buffer before painting.
   * tmux emits `\e[?1049h` to a client only at that client's own attach; a joiner (a renderer
   * reload re-joins the same still-alive tmux client, and the kanban card modal is always a
   * joiner) never sees it, so its xterm stayed on the NORMAL buffer: up to 10k lines of tmux's
   * scrolled output piled up there and every output frame forced a layout (xterm's viewport
   * resync) — measured 16.1% vs 7.3% total CPU for one terminal streaming 20 lines/s.
   * Absent for plain-shell and session-host sessions: there the pty IS the shell and its
   * normal-buffer scrollback is the only history it has. Known limitation: a REMOTE SSH session on
   * a host WITHOUT tmux (`tmuxOrExplain`'s plain login-shell fallback) is still recorded tmuxBacked,
   * so it gets this (and `coAttachMouse`, and `tmuxClient`) too; detecting that is a follow-up.
   */
  coAttachAltScreen?: boolean
  /**
   * This session's client is a real TMUX client (local or remote; never a session-host session or a
   * plain shell) — set on EVERY create, the solo spawn as well as a join. A `pty:resync` repaint
   * (`repaintResync`) calls `term.reset()`, which drops the emulator back to the NORMAL buffer and
   * clears mouse tracking; tmux does not re-send either (it emitted them once, at attach), so the
   * renderer re-applies `CO_ATTACH_ALT_SCREEN_SEQ` + `CO_ATTACH_MOUSE_SEQ` after the reset when
   * this is set. Same condition as `coAttachAltScreen`, asked of every session rather than only a
   * joiner. Absent = unknown (an older core or relay peer) ⇒ the renderer re-applies nothing, the
   * pre-field behavior.
   */
  tmuxClient?: boolean
  /**
   * This session is TMUX-BACKED (local or remote) — it survives losing this client, so killing our
   * pty client only detaches us and everything running in the session keeps going.
   *
   * False = the plain-shell fallback (no tmux installed, tmux switched off, or a node with no
   * persistKey): the pty IS the shell, and killing it kills the shell and every process under it —
   * an agent CLI mid-task included. The renderer needs the difference because several of its
   * levers dispose a terminal purely as a CACHE (the park window, the park LRU cap, the
   * memory-pressure drop), a call that is only cheap when tmux is underneath. See
   * `renderer/terminal/park-budget.ts` (`canDisposePark`) and issue #126.
   *
   * Absent = unknown (a core older than this field, over the relay): the renderer must then assume
   * the historical behavior (persistent), never protect on a guess.
   */
  persistent?: boolean
  /**
   * This session is owned by the session-host backend (Windows, or POSIX with no tmux), not tmux.
   * Set only on a SPAWN answer; absent everywhere else (tmux, plain shell, a join, an older core).
   *
   * The renderer's launch writer reads it for one decision: a FRESH session-host shell is trusted
   * without a pane probe, because that backend's probe is a process-tree walk that cannot tell a
   * shell from its prompt's helpers (a `git`/`starship` child reads as "not a shell") — issue
   * #916. A fresh tmux pane keeps its probe: tmux's answer is exact, and it still covers the rare
   * `new-session -A` race where another client created the session first.
   */
  sessionHost?: boolean
  /**
   * REFUSED: this node's session was permanently destroyed by ANOTHER client, so nothing was
   * spawned (`sessionId` is empty) — the terminal shows the "closed by <name>" state instead.
   *
   * This is the tombstone (PtyManager): `pty:closed` only reaches a session's SUBSCRIBERS, and a
   * co-viewer whose project is inactive or closed is not one. Without this, the create it issues
   * when it later opens that project would happily spawn a brand-new `nt-<id>` and resurrect a
   * terminal its owner deliberately deleted. The client that DID the destroy is exempt (its ⌘Z
   * must still restore the node), so the single-user delete→undo path is unchanged.
   */
  closed?: { by: number | null }
  /**
   * REFUSED: `requireRemote` was set and no remote spawn was possible (no live ControlMaster, or
   * no `ssh` executable), so nothing was spawned (`sessionId` is empty) — see
   * `PtyCreateOptions.requireRemote` for what used to happen instead. The renderer shows the
   * "not connected" overlay and re-spawns the node once the project's master is back.
   *
   * `'ssh'` is only ever set for a create that would have SPAWNED: a co-attach to a live session
   * for this node id on the requested remote still joins, so a second view of a healthy remote
   * terminal is unaffected.
   *
   * `'held-elsewhere'`: a `requireRemote` create found a live session for this node id held by this
   * process, but NOT on the requested remote — it is local, or its endpoint (host, user, port)
   * differs from the create's `sshRemote`. The join is refused and nothing was started; the held
   * session is left untouched. A create with no `sshRemote` (master down) still joins a held
   * remote session. Not a lost connection: retrying would refuse again.
   *
   * `'codex-account'` is the S6 fail-closed twin: a LOCAL Codex node that explicitly selected a
   * managed account whose home is missing refuses rather than spawning against the system login
   * (§5 property 4). Remote managed Codex accounts refuse unknown/unsafe ids or unresolved/unsafe homes.
   * System SSH Codex may attach before remote home discovery. Nothing spawned on refusal.
   *
   * `'join-only'`: `PtyCreateOptions.joinOnly` was set (a hosted-relay viewer) and no running
   * session could be confirmed to join or reattach to — either it is gone, or its existence could
   * not be checked — so nothing was started. Not a lost connection.
   *
   * `'new-only'`: `PtyCreateOptions.newOnly` was set (a relay guest's create for a node it
   * introduced) and a session already exists under this node's name, or its existence could not be
   * checked. Nothing was joined or started, and the existing session was left untouched.
   */
  unavailable?: 'ssh' | 'codex-account' | 'join-only' | 'held-elsewhere' | 'new-only'
  /**
   * Core already put the persisted scrollback (and the "session restored" separator) into the new
   * tmux pane — see `PtyCreateOptions.restoreScrollback`. The caller must NOT replay the snapshot
   * into its emulator: tmux paints it and owns it as history. Only ever set with `fresh: true`.
   */
  scrollbackSeeded?: boolean
}

/** Payload of `pty:recycled` — see IPC.ptyRecycled and `recycleAction` in the renderer. */
export interface RecycledInfo {
  /** A replacement session is registered for the node: restart onto it. False = the escape-hatch
   *  timeout fired with no replacement (the recycler died mid-move) → do NOT respawn. */
  ready: boolean
}

// 'subagent' and 'loop' are render-only (ephemeral hook-driven viz) and never persisted.
// 'trigger' is a first-class PERSISTED kind (issue #493) — the canvas-owned schedule node; its
// spec rides `CanvasNodeState.trigger` and is sanitized on every load path (@shared/trigger).
export type NodeKind = 'terminal' | 'sticky' | 'group' | 'editor' | 'diff' | 'video' | 'web' | 'browser' | 'files' | 'subagent' | 'loop' | 'dino' | 'trigger' | 'simulator' | 'whiteboard'

/** Persisted state of a single canvas node (terminal, sticky note, group frame, or editor). */
/**
 * A launch a terminal node OWES once every station in `after` has gone idle — what the
 * canvas-control `--after` flag arms instead of running the command on open. This is the
 * difference between a fan-out and a graph: a downstream station starts when the upstream
 * ones have produced something for it to read, without an orchestrator sitting in a poll loop.
 *
 * Persisted, because the wait can outlive an app restart — and note that agent state is NOT
 * (it is rebuilt from live hook events), so after a restart an armed node has no way to learn
 * that its deps already finished. That is why the node carries a manual "run now" escape:
 * a stalled station must never be a dead end.
 */
export interface PendingLaunch {
  /** false proves no input attempt; true/absent require explicit recovery after reload. */
  attempted?: boolean
  /** An attempted/uncertain delivery requires explicit Run now; never replay on hooks. */
  manualOnly?: boolean
  /**
   * Node ids to wait for. Only nodes running a hook-reporting agent may appear here — a plain
   * terminal never reports `done`, so waiting on one would stall forever (refused at creation).
   * A dep that no longer exists counts as satisfied: a deleted node can never report.
   */
  after: string[]
  /** Delivered to the node's shell once the wait is over (agent CLI + prompt, or a plain command). */
  command: string
  /**
   * Which core process owns delivery. Absent is the historical renderer-owned path. Server
   * Edition headless opens stamp `server`, so a connected browser can render the armed state and
   * dependency edges without racing the server to type the command into the same pane. The
   * desktop's headless start (#925) stamps `core` on its manualOnly write-ahead claim.
   */
  executor?: 'server' | 'core'
  /**
   * Server-owned dependencies whose first real turn has not been observed yet. A freshly spawned
   * agent can briefly report `done` while its argv prompt is still booting; that idle blip must not
   * release a downstream launch. The server removes an id only after a verified `working` event,
   * then requires the ordinary later `done`. Persisted so a server restart cannot forget the gate.
   * Desktop-owned launches leave this absent; renderer parity is a separate follow-up.
   */
  awaitWorking?: string[]
  /**
   * Also wait for this worktree GROUP's project setup script to finish (`waitForSetup`). Set when
   * the node is opened into a frame whose checkout is still being prepared — running a command in a
   * half-installed worktree is the failure this gate exists to prevent. It names a group id, never
   * a command: nothing here is ever executed, it only selects a run to ask about.
   *
   * A group with no run on record counts as done (`launchesToFire`), so a persisted arming that
   * outlives the run's event stream — an app restart — releases rather than strands the node.
   */
  awaitSetupGroup?: string
  /**
   * Also wait on GitHub pull requests of the project's board repository (`--after-pr`, see
   * @shared/pr-wait). ANDed with `after` and the setup gate. Validated at both serializer seams
   * (`normalizePendingLaunch`): a malformed value becomes a hold that never fires on its own.
   * A build older than this one does not know the field and releases the node on `after` alone.
   */
  afterPr?: PrWaitHold
  /**
   * Also wait for these stations to REPORT SUCCESS (`--after-success`, see @shared/station-outcome):
   * each id is in `after` too, so this adds "and it said it succeeded" to "its turn is over". ANDed
   * with every other gate. Validated at both serializer seams (`normalizePendingLaunch`): a malformed
   * value becomes a hold that never fires on its own. A build older than this one does not know the
   * field and releases the node on the turn ending alone.
   */
  afterSuccess?: import('./station-outcome').SuccessWaitHold
  /**
   * The file `command` reads its prompt from (`"$(cat '<path>')"`): a `--prompt-file`, or a long
   * `--prompt` spilled to a file (#706). A held launch may be delivered weeks after it was armed, so
   * the delivery loop checks this file still exists before it types the command, and holds the node
   * for ▶ with the reason when it does not — an agent started with no brief is the failure the
   * open-time existence check exists to catch. Absent for a prompt that rides the command inline.
   */
  promptFile?: string
}

export interface CanvasNodeState {
  id: string
  kind: NodeKind
  position: { x: number; y: number }
  size: { width: number; height: number }
  title: string
  /**
   * Agent nodes only: while true (the default), the node title auto-tracks the agent's own
   * session name. Set false once the user renames the node by hand, so we stop overwriting it
   * and instead push the user's name back to the agent via `/rename`. Persisted.
   */
  titleAuto?: boolean
  color: string
  group: string | null
  /** Labels for organizing/filtering terminals. */
  tags?: string[]
  /** When true the node body is hidden (header-only). */
  collapsed?: boolean
  /** Agent nodes only: when true, this node's subagent/loop fan-out cards are hidden. */
  hideFanout?: boolean
  /** Terminal nodes: the ⌘M view (chat / markdown) is open. Persisted, so leaving a project and
   *  coming back (or a reload) reopens the node the way the user left it instead of on the raw
   *  terminal. Absent = closed. */
  mdMode?: boolean
  /**
   * A user-chosen icon shown wherever this node is listed (canvas header, kanban card, sessions
   * sidebar): one emoji/character, or an image file. Absent = the node draws exactly as it did
   * before the feature. Validate with `normalizeNodeIcon` at the point of use — this value comes
   * from a git-shared, hand-editable project file. See @shared/node-icon.
   */
  icon?: import('./node-icon').NodeIcon
  /** Parent group node id, if this node belongs to a group frame. */
  parentId?: string
  // terminal-only
  /** This terminal's own font size (issue #915), set with ⌘+ / ⌘− when
   *  `settings.terminalFontZoomKeys` is on; absent = follow the global `fontSize`. Hand-editable,
   *  so every reader goes through `normalizeTerminalFontSize` (renderer/terminal/terminal-font-zoom). */
  terminalFontSize?: number
  shell?: string
  cwd?: string
  /** Which agent runs in this terminal node (claude/codex/gemini/custom). */
  agentId?: AgentId
  /** Model selected for this agent node through the shared model gateway. */
  agentModel?: string
  /**
   * Agent nodes started on a GitHub issue ("Start with agent" on an issue card, or
   * `open-agent --issue`): WHICH issue this session works on. It drives the binding chips (the
   * issue card's run chips, the node header's `#N`) and the issue card's run history — never a
   * launch line: the launch prompt was composed once, at creation, from a validated reference.
   * Git-shared, so hostile input: `normalizeIssueRef` runs at both serializer seams. See
   * @shared/github-issue-ref.
   */
  issueRef?: import('./github-issue-ref').IssueRef
  /**
   * The node id of the agent that OPENED this node through a canvas-control open verb
   * (`open-agent`/`open-claude`/`open-terminal`, `spawn-team`, `verify`) — recorded where that verb
   * draws its lineage rope. It is what lets the app tell the right agent when this station stops
   * (@shared/station-notice): a rope alone cannot, because an `--after` station is roped to the
   * stations it waited on as well, with the same id shape. Git-shared, so hostile input: validated
   * with `isSafeNodeId` at both serializer seams, and honoured only while the opener's rope to this
   * node still exists and the opener is a canvas-capable agent node in the same project.
   */
  openedBy?: string
  /**
   * One-shot "Restart on subscription" flag: when set, the next `transport.create` strips gateway +
   * inherited provider env (per `vanillaEnvStripPattern`) so the agent resumes against its own
   * default provider. Set by the clear-env recycle action, cleared after the spawn resolves so an
   * ordinary Restart re-applies the gateway. See `PtyCreateOptions.clearEnv`.
   */
  clearEnv?: boolean
  /** Set while this node is armed but not yet launched — see PendingLaunch. */
  pendingLaunch?: PendingLaunch
  /**
   * Claude-only: managed account this node runs on (CLAUDE_CONFIG_DIR injection).
   * Resolved once at node creation (explicit pick → project default → system default)
   * and immutable for the node's lifetime. Undefined = system default (~/.claude).
   */
  accountId?: string
  /**
   * Agents in `SESSION_ID_CAPABLE` (claude): the session id nodeterm minted and launched this
   * node's CLI with (`--session-id`). Persisted so a cold restore can resume even when no hook
   * ever delivered an id — the SSH reverse tunnel is the only path that carries one, and a node
   * whose tunnel was down came back as a blank conversation with its transcript intact on disk.
   * The hook-fed id still wins when known: `/clear` and `--fork-session` mint a new one in-CLI.
   */
  agentSessionId?: string
  /** When set, the terminal runs `ssh` to this host on the local PTY; persisted (auto-reconnects). */
  ssh?: import('./ssh').SshConnection
  /** When true (SSH-project terminals), the node runs in REMOTE tmux on `ssh` rather than `ssh`-on-local-PTY. */
  sshRemoteTmux?: boolean
  /** editor-only: when true (SSH-project editors), reads/writes go to the project's remote fs via `sshFs`. */
  sshFs?: boolean
  /**
   * Run nodes only (a terminal node that runs a `.vscode/launch.json` configuration): folder,
   * configuration, device, reload-on-save. Git-shared and hand-editable — read through
   * `normalizeRunConfig` (@shared/run-config) on every load AND save.
   */
  runConfig?: import('./run-config').RunNodeConfig
  /** Run nodes: a simulator shown inside the node. Read through `normalizeInlineSimulatorConfig`. */
  runSimulator?: import('./simulator').InlineSimulatorConfig
  /** simulator-only: which iOS simulator the node shows. Read through `normalizeSimulatorConfig`. */
  simulator?: import('./simulator').SimulatorNodeConfig
  // sticky-only
  text?: string
  /**
   * sticky-only: last canvas-control `sticky` write — when, and the title of the agent node that
   * wrote it. The stamp means "an agent synced this", not "last touched": a hand edit clears both,
   * so a stale stamp can never vouch for text the user has since rewritten.
   */
  textUpdatedAt?: number
  textUpdatedBy?: string
  /**
   * whiteboard-only: the board this node shows until it saves its own — set on a duplicate or a
   * reopen (which get a NEW id) so the copy needs no file copy and no board file is ever deleted.
   * A node id, never a path: the core resolves it inside this project (core/whiteboards.ts).
   */
  whiteboardSource?: string
  /** whiteboard-only: epoch ms of the last editing session that changed the board. Written once
   *  per session (never per stroke) — what a linked agent's "the board changed" keys on. */
  boardRev?: number
  // dino-only: best score reached in the T-Rex Runner game.
  highScore?: number
  // editor / diff
  filePath?: string
  /**
   * editor/diff-only: true once `filePath` was confirmed gone (e.g. its worktree was removed —
   * see `displacedByWorktree` in `./worktree.ts`). There is nothing to re-point the node at, so
   * it shows a persistent notice instead of silently opening blank / failing a `git show`.
   */
  fileMissing?: boolean
  /** web-only: when set, the web node loads this live URL (else it loads `filePath` as local html). */
  url?: string
  /**
   * browser-only: the Electron session partition for an AGENT-opened browser node
   * (`persist:nt-agent-browser-<projectId>`), set once at creation and never mutated. Absent for a
   * USER-opened node (default session, no migration). Persisted so the jar survives reopen; carried
   * through untouched on Server Edition / mobile, where a browser node renders with no <webview>.
   */
  partition?: string
  /** browser-only: popped out of a run node's browser panel — that run node's id. */
  dockTo?: string
  /** Run nodes: the browser panel inside the node. Read through `normalizeRunBrowserConfig`. */
  runBrowser?: import('./run-preview').RunBrowserConfig
  /** diff-only: true = staged diff (HEAD vs index), false = unstaged (index vs working). */
  diffStaged?: boolean
  /** diff-only: when set, the diff shows parent (<oid>^) vs commit (<oid>) for a file from history. */
  commitOid?: string
  /** group-only: when bound, the git worktree this group works in. */
  worktree?: GroupWorktree
  /**
   * trigger-only: the schedule + payload + target this node represents (issue #493). Git-shared
   * CONTENT — deliberately, the team shares the definition — which is exactly why it is treated
   * as hostile on every load path (`sanitizeNodeTriggers` in core/workspace-files) and why the
   * definition alone never fires: execution additionally requires this machine's arm record
   * (`core/trigger-arm-store.ts`), bound to the spec's exact content. See @shared/trigger.
   */
  trigger?: import('./trigger').TriggerSpec
  /**
   * Set while the node is maximized to fill the viewport (issue #399): the rect to give back on
   * the toggle's second click — the node's ROOT-space (absolute canvas) position plus its size.
   * Absent = not maximized. Persisted so the restore survives a reload. Root-space on purpose:
   * maximizing a grouped node re-fits (and thereby moves) its frame, so a parent-relative rect
   * would restore a few px off — and root-space also survives the frame being ungrouped meanwhile.
   */
  premaxRect?: { x: number; y: number; width: number; height: number }
}

/**
 * One entry in `Project.closedSessions` — everything needed to recreate a fresh node in the same
 * spot a deleted one used to occupy. `node` is the exact shape a live node is already persisted
 * as (`CanvasNodeState`); `absolutePosition` is captured at delete time because `node.position`
 * is relative-to-parent when `node.parentId` is set, and that parent group may not exist by the
 * time this entry is reopened.
 */
export interface ClosedSessionEntry {
  id: string
  closedAt: number
  node: CanvasNodeState
  absolutePosition: { x: number; y: number }
  /**
   * The agent session this node was running when it was closed — a POINTER to the transcript the
   * agent CLI already owns, never a copy of its text (issue #531). It is the one fact that dies
   * with the node and cannot be recovered afterwards: the live id is held only in the transient
   * `agentStatus` store, whose entry is dropped on delete, while the transcript `.jsonl` itself
   * stays on disk under the agent's own root. Without it a closed station's work cannot be read
   * back at all, which is what made "close the node once its branch is merged" quietly destructive.
   *
   * Captured at close from the hook-fed live id, falling back to `node.agentSessionId` (the id
   * nodeterm minted at creation) — the two agree whenever both exist, and each covers a case the
   * other misses (a RESUMED session has no minted id; a node that never emitted a hook event has
   * no live one).
   *
   * MACHINE-LOCAL by construction: `closedSessions` rides `IndexEntryV3`, never the git-shared
   * `.nodeterm/project.json` (see `Project.closedSessions`), so a session id — a `$HOME`-anchored
   * fact about one person's machine — is never shipped to everyone who clones the repo.
   */
  sessionId?: string
}

/**
 * How many closed-session entries one project keeps (newest-first; the rest are dropped).
 *
 * ONE definition, because the cap must hold at every point an entry list is produced OR admitted:
 * the store mutator that records a delete (`recordClosedSessions`), and every load path that
 * admits `IndexEntryV3.closedSessions` (a ref'd project's machine-local history) or an inline
 * project's embedded one. Enforcing it only where WE append is not enforcement at all —
 * workspace.json is hand-editable input too, so an inflated list can arrive from outside (a
 * pre-cap build's file, a hand edit) and would render unbounded rows and be written back in full.
 */
export const CLOSED_SESSIONS_CAP = 20

/**
 * A snapshot of one canvas's nodes in the form sent over the remote mirror wire.
 * Reuses the persisted node shape (`CanvasNodeState`) so host and client agree on layout.
 */
export interface CanvasState {
  nodes: CanvasNodeState[]
}

/**
 * A minimal change to a canvas: replace-or-append a node by id, or drop one by id — and, on the team
 * canvas-sync path, the same for one persisted edge (`edge-*`) or one board item (`kb-*`, see
 * `KanbanOp` below and @shared/kanban-ops).
 * Used for the client's optimistic edits and host-side diffing (see `applyMutation`/`diffToMutations`).
 *
 * `src` and `seq` exist ONLY on the team canvas-sync path (`canvas:mut`), and they are what makes
 * two people editing one node CONVERGE instead of splitting brain (see src/shared/canvas-order.ts):
 *  - `src` is stamped by the sending client's publisher — a random per-Canvas tag, so a client can
 *    recognize its OWN mutation coming back (the reflector echoes to everyone, sender included:
 *    that echo is the ACK that tells the sender where its edit landed in the total order).
 *  - `seq` is stamped by the reflector (src/core/canvas-sync.ts) and is the TOTAL ORDER. It is
 *    server-authoritative: a client-supplied `seq` is overwritten at ingest, never trusted.
 *  - `seen` is the sender's CAUSAL stamp: the highest `seq` it had applied at the moment it cast.
 *    It answers the one question `seq` alone cannot — "did this client already know about the
 *    delete?" — which is what lets a delete beat a concurrent drag frame instead of being
 *    resurrected by it (canvas-order's rule 4). Client-supplied; the reflector clamps it below the
 *    order it is being given, which is hygiene and changes no verdict (see `stampMutation`). A
 *    mutation without it is judged exactly as before, so an unstamped peer degrades rather than
 *    breaks.
 *  - `origin: 'core'` is ALSO reflector-authoritative: a client-supplied one is deleted at ingest.
 *    The core adds it only on a copy that came from an OWNER client (or the core itself) and goes to
 *    an owner client, and it is the ONE thing that lets a receiver take the node's machine-local
 *    `pendingLaunch` as sent (@shared/node-exec `mutationTrustsLaunch`). It means something only on
 *    a node `upsert`; every other op may carry it (the reflector vouches per recipient, not per op)
 *    and ignores it.
 * The legacy relay host's canvas mirror (`canvas:state` / `canvas:mutate`: src/main/remote/
 * host-service.ts and canvas-sync.ts, which stayed there when the relay transport moved to
 * src/core/relay) uses the same vocabulary and simply omits these stamps.
 */
export type CanvasMutation =
  | { op: 'upsert'; node: CanvasNodeState; src?: string; seq?: number; seen?: number; origin?: 'core' }
  | { op: 'remove'; id: string; src?: string; seq?: number; seen?: number; origin?: 'core' }
  | {
      op: 'edge-upsert'
      kind: CanvasEdgeKind
      edge: BridgeLink
      src?: string
      seq?: number
      seen?: number
      origin?: 'core'
    }
  | {
      op: 'edge-remove'
      kind: CanvasEdgeKind
      id: string
      src?: string
      seq?: number
      seen?: number
      origin?: 'core'
    }
  | (KanbanOp & MutationStamp)

/** The node and edge half of `CanvasMutation` — all a canvas SCENE diff (`diffToMutations`) ever
 *  produces. Their order keys are project-independent (node and edge ids are globally unique), so
 *  the ordering API accepts them without a project id; any value that MAY be a board op must name
 *  its project (see `mutationKey`). */
export type SceneMutation = Exclude<CanvasMutation, { op: `kb-${string}` }>

/** Stamp fields every canvas mutation may carry (see canvas-order): the sender tag, the reflector's
 *  total order, the sender's causal position, and the core's per-recipient vouching (`origin`).
 *  Documented on `CanvasMutation` above. */
export interface MutationStamp {
  src?: string
  seq?: number
  seen?: number
  origin?: 'core'
}

/**
 * The board half of the `canvas:mut` vocabulary (@shared/kanban-ops): one op per board ITEM, so two
 * people editing one board converge item by item instead of last-writer-wins on the whole `kanban`
 * block. Keys live in one `k:` space (`kanbanOpKey`); only a column / label / view REMOVAL is a
 * rule-4 deletion — `kb-card-remove` and `kb-meta-remove` set a card's placement / metadata to
 * "none", an ordinary last-writer-wins value (`isKanbanDeletion`). `github` and `pullLinks` are
 * outside the vocabulary and never cast.
 */
export type KanbanOp =
  | { op: 'kb-column'; column: KanbanColumn }
  | { op: 'kb-column-remove'; id: string }
  | { op: 'kb-column-order'; ids: string[] }
  | { op: 'kb-card'; assignment: KanbanAssignment }
  | { op: 'kb-card-remove'; nodeId: string }
  | { op: 'kb-meta'; meta: KanbanCardMeta }
  | { op: 'kb-meta-remove'; nodeId: string }
  | { op: 'kb-label'; label: KanbanLabel }
  | { op: 'kb-label-remove'; id: string }
  | { op: 'kb-label-order'; ids: string[] }
  | { op: 'kb-view'; view: KanbanSavedView }
  | { op: 'kb-view-remove'; id: string }

/**
 * Which persisted edge list a mutation addresses — `bridges` (context links, which an agent can
 * actually READ through) or `ropes` (display-only "spawned by" lineage). They are two arrays on
 * the project with two different meanings, so the kind travels with the mutation; the ORDER,
 * however, is keyed on the edge id alone (canvas-order's `e:<id>`), because one id is one edge and
 * two clients must never end up holding it as both a bridge and a rope. The apply agrees
 * (`applyEdgeMutationToScene`: an upsert takes the id out of the other list, a remove drops it from
 * both), and so does the diff (an id that moved lists casts its upsert and no remove).
 */
export type CanvasEdgeKind = 'bridge' | 'rope'

/** Canvas pan/zoom state. */
export interface Viewport {
  x: number
  y: number
  zoom: number
}

/** A persistent "bridge" link between two Claude nodes (lets their sessions message each other). */
export interface BridgeLink {
  id: string
  source: string
  target: string
  /**
   * Context links only (issue #852): the ONE endpoint allowed to read the other. Absent = both
   * read each other, which is every link persisted before the field existed. A value naming
   * neither endpoint authorizes nobody (fail closed) — see `linkReadPairs` in canvas-link.ts.
   */
  reader?: string
}

/** Where a column sits in a card's lifecycle (see @shared/kanban-category). A closed set; an
 *  unknown value read from a hand-edited or newer file reads as ABSENT (`columnCategory`), and is
 *  left in the file untouched so a newer build's value survives an older build's save. */
export type KanbanColumnCategory = 'unstarted' | 'started' | 'done' | 'closed'

/** One kanban board column. Column order = array order in ProjectKanban.columns. */
export interface KanbanColumn {
  id: string
  title: string
  color: string
  /** Optional lifecycle category. Absent = uncategorized (the pre-category board, and any column
   *  the user never categorized). Read it through `columnCategory`, never directly. */
  category?: KanbanColumnCategory
}

/** Assignment of one session node to a board column. A session with no assignment sits
 *  in the virtual Ungrouped column (never persisted). Order within a column = `rank` (a
 *  fractional-index string, @shared/kanban-rank), and for an entry without a valid one, its
 *  position in ProjectKanban.assignments (@shared/kanban-order `columnOrder`). Every write keeps
 *  the ARRAY in rank order too, so a build that ignores `rank` shows the same column. */
export interface KanbanAssignment {
  nodeId: string
  columnId: string
  /** Optional position key within the column. Absent / invalid ⇒ derived from array order. */
  rank?: string
}

/** Per-project kanban board (docs/superpowers/specs/2026-07-18-kanban-view-design.md).
 *  Absent = never edited: the renderer shows a default 3-column board and writes
 *  nothing until the first change. Cards are the project's session nodes — the board
 *  stores only their column assignments. */
/** Trello-style per-card metadata. Lives beside the assignments (not on the node) so it rides
 *  the same git/mirror machinery; absent entries mean "no metadata". Assignee identity is the
 *  presence identity — the same {name, color} the board log attributes comments to. */
export type KanbanPriority = 'low' | 'medium' | 'high' | 'urgent'

export interface KanbanCardMeta {
  nodeId: string
  assignees?: BoardLogAuthor[]
  /** Due timestamp (ms). Absent = no due date. */
  dueAt?: number
  /** Absent = no priority. */
  priority?: KanbanPriority
  /** Ids of the board labels applied to this card (see ProjectKanban.labels). Absent/empty = none;
   *  ids that no longer resolve to a label are dropped by readers (dangling-safe). */
  labels?: string[]
}

/** The Notion label palette. A closed set so the chip colors and the picker can't desync; an
 *  unknown value read from a hand-edited file falls back to 'default'. */
export type KanbanLabelColor =
  | 'default'
  | 'gray'
  | 'brown'
  | 'orange'
  | 'yellow'
  | 'green'
  | 'blue'
  | 'purple'
  | 'pink'
  | 'red'

/** A board-level label (Notion-style): defined once per board, applied to any number of cards by
 *  id (KanbanCardMeta.labels). Order in ProjectKanban.labels is the palette's display order. */
export interface KanbanLabel {
  id: string
  name: string
  color: KanbanLabelColor
}

/** A saved board view's filters (@shared/kanban-views). SHARED content: a view is how a team
 *  looks at its board. Deliberately NOT here: the live-state status chips (never persisted
 *  anywhere) and display preferences like showing closed columns (per user, localStorage). */
export interface KanbanViewQuery {
  /** The source filter; absent = all. */
  source?: 'all' | 'github' | 'pulls' | 'sessions'
  /** Label filter keys (`local:<labelId>` | `github:<folded name>`); OR within the list. */
  labels?: string[]
  /** Assignee names (the presence identity's name); a card needs one of them. */
  assignees?: string[]
  /** Column ids to SHOW (`ungrouped` names the virtual column); absent/empty = every column. */
  columns?: string[]
}

export interface KanbanSavedView {
  id: string
  name: string
  query: KanbanViewQuery
}

export interface ProjectKanban {
  columns: KanbanColumn[]
  assignments: KanbanAssignment[]
  /** Saved views — named filter sets shared with everyone on the board. Tolerated as absent or
   *  malformed (sanitizeViews); the ACTIVE view is per user (localStorage), never here. */
  views?: KanbanSavedView[]
  /** Optional card metadata; tolerated as absent/malformed by every reader (lib normalizes). */
  meta?: KanbanCardMeta[]
  /** Board-level label palette (Notion-style). Cards reference these by id in `meta[].labels`;
   *  tolerated as absent/malformed by every reader. */
  labels?: KanbanLabel[]
  /** Shared, non-secret GitHub issue label mapping. Local approval and credentials live elsewhere. */
  github?: ProjectKanbanGitHub
  /** Card ↔ pull request link tombstones and per-card auto-move opt-outs (@shared/kanban-pull-links).
   *  Hostile input: read only through `readPullLinks`. */
  pullLinks?: KanbanPullLinks
}

/** Who produced a board-log entry (a teammate on a shared board, or this user). */
export interface BoardLogAuthor {
  name: string
  color: string
}

/** A structural board change worth recording. `type` is closed; the optional fields carry
 *  the human-readable names resolved at event time (the virtual column is named 'Ungrouped'). */
export interface BoardLogEvent {
  type:
    | 'card-created'
    | 'card-moved'
    | 'column-added'
    | 'column-renamed'
    | 'column-deleted'
    | 'member-assigned'
    | 'member-unassigned'
    | 'due-set'
    | 'due-cleared'
    | 'priority-set'
    | 'priority-cleared'
    /** An agent-to-agent message delivery. `from`/`to` are NODE IDS (not column names) and `title`
     *  is the delivery's outcome kind — a trace that cannot answer "did it land?" answers the only
     *  question anyone asks it with silence. Written by `agent-message-trace.recordDelivery`. */
    | 'agent-message'
    /** An agent read a site's cookies through `browser --cookies` — a data-exfiltration surface the
     *  owner allowed but that MUST be loudly traced (PR 9 Task 9.2/9.3). `from` = the owner agent
     *  node's title, `to` = the domain read, `title` = the browser node's title; `nodeId` = the owner
     *  agent node so it files under that agent's card. Written BEFORE the read (fail-closed): a cookie
     *  read that happened but was not recorded is the one outcome this trace exists to prevent. */
    | 'agent-read-cookies'
    /** An agent session was started on a GitHub issue. Filed under the issue CARD's board-log
     *  identity (`issueLogId`), not the node's, so the issue keeps its run history after the
     *  session's node is gone. `run` names the session; `title` is the node title at the time. */
    | 'run-started'
    /** That session's node was closed. `run.end` is the last agent state observed at that
     *  moment — a turn ending (`done`) is NOT a run ending, which is why this is written only when
     *  the node goes. */
    | 'run-ended'
    /** A station an agent opened stopped, and that agent was told (src/core/agents/
     *  station-notice.ts). Filed under the RECIPIENT's card — the orchestrator's — because that is
     *  who has to act on it. `from` = the station's node id, `to` = the reason (a
     *  `StationFailureReason`, @shared/station-notice), `title` = the station's title as the notice
     *  carried it (one line, capped). Never any station output. */
    | 'station-failed'
    /** A station reported its TASK outcome (`report-outcome`, @shared/station-outcome). Filed under
     *  the STATION's own card. `from` = the station's node id, `to` = the outcome (`succeeded` /
     *  `failed`), `title` = its note (one line, capped). Written by the app, never a gate: the
     *  outcome a `--after-success` wait reads lives in core's transient store, not in this file. */
    | 'station-reported'
  from?: string
  to?: string
  /** Column title for column-added/deleted; card title for card-created; outcome for agent-message;
   *  for card-moved, the reason when the board moved the card itself ("PR #12 merged"). */
  title?: string
  /** agent-message only: the `notPermitted` reason when that is the outcome. From a shared file like
   *  every field here, so a reader treats it as an untrusted string. */
  reason?: string
  /** run-started / run-ended only. No cost or token figure: nodeterm has no cumulative number for
   *  a session, and a context-window reading is not one. */
  run?: {
    nodeId: string
    agentId?: string
    sessionId?: string
    end?: 'done' | 'working' | 'waiting' | 'blocked' | 'errored' | 'dropped' | 'unknown'
  }
}

/** One line of the append-only board history (`.nodeterm/board-log.jsonl`). A `comment`
 *  carries `text`; an `event` carries `event`. Serialized one-per-line as JSON. */
export interface BoardLogEntry {
  id: string
  ts: number
  author: BoardLogAuthor
  nodeId?: string
  kind: 'comment' | 'event'
  text?: string
  event?: BoardLogEvent
}

/** Max chars kept for a comment's `text`. On an SSH project the whole JSON line becomes one
 *  shell arg (`printf '%s\n' '<line>'` over the ControlMaster); an unbounded paste blows past
 *  ARG_MAX → the append fails → the optimistic entry silently vanishes on reload. Locally it
 *  just bloats the append-only file. Shared so core (disk) and the renderer (optimistic UI)
 *  clamp identically. */
export const BOARD_LOG_TEXT_MAX = 16_384

/** Read options for the board log: cap the newest N entries (default 500 in the store) or `all`. */
export interface BoardLogReadOpts {
  cap?: number
  all?: boolean
}

/** Result of a board-log read. `unsupported` is set (with `entries: []`) when the project has no
 *  reachable log — an inline/no-cwd canvas, a disconnected SSH project, or an SSH project on the
 *  Server Edition (v1 has no remote board log there). */
export interface BoardLogReadResult {
  entries: BoardLogEntry[]
  unsupported?: boolean
}

/** The board-log surface on `window.nodeTerminal`. Project-routed: the main/server side resolves
 *  the project to a local cwd, a desktop SSH connection, or unsupported. `append` is
 *  fire-and-forget-safe (resolves `false` on any failure, never throws). */
/** One captured debug-log line (issue #78). `seq` is monotonic across the process lifetime so
 *  subscribers can dedupe batches against the snapshot they filled from. */
export interface LogRecord {
  seq: number
  /** Epoch ms. */
  ts: number
  level: 'debug' | 'info' | 'warn' | 'error'
  /** The `[subsystem]` prefix convention the codebase logs with; '' when absent. */
  tag: string
  msg: string
}

export interface LogApi {
  /** The whole ring, oldest-first — the panel's initial fill. */
  snapshot(): Promise<LogRecord[]>
  /** Empty the ring (the panel's Clear button). */
  clear(): void
  /** Subscribe to batched pushes; returns an unsubscribe. Batches may overlap the snapshot
   *  around the subscribe edge — dedupe by `seq`. */
  onBatch(cb: (batch: LogRecord[]) => void): () => void
}

export interface BoardLogApi {
  /** Append one entry. Resolves `false` on any failure (unsupported project, fs/exec error). */
  append(projectId: string, entry: BoardLogEntry): Promise<boolean>
  /** Read the log newest-first (see BoardLogReadResult). */
  read(projectId: string, opts?: BoardLogReadOpts): Promise<BoardLogReadResult>
  /** Subscribe to change pushes for one project; returns an unsubscribe. */
  onChanged(projectId: string, cb: () => void): () => void
}

/** One recorded "deliberate landing" on a node — the breadcrumb trail's unit. Frozen at record
 *  time (nodeId only, no live pointer): a deleted node is filtered at render, a renamed one shows
 *  its current title (read live), but the `note` stays a snapshot of what was happening then. */
export interface NavStop {
  nodeId: string
  at: number
  note: string
}

/** MACHINE-LOCAL: this SSH project was handed over to a hosted team on its host ("Share with
 *  team"). From that moment the server core is the only writer of its project.json, so this
 *  desktop never mirrors, reconciles or polls it again. `hostId` absent = the handover started
 *  and did not finish (the same guard applies until the user reopens it). */
export interface HandedOffTo { hostId?: string; projectId?: string; at: number }

/** A project is one canvas/page: its own nodes, viewport, and default working dir. */
export interface Project {
  id: string
  name: string
  color: string
  /** Optional icon shown beside `name` (tab, start screen). Git-shared like `name`/`color` — see
   *  `sanitizeProjectIcon` (@shared/project-icon) for the hostile-input rules a stored value must
   *  pass on load. */
  icon?: ProjectIcon
  /** Default working directory for new terminals created in this project. */
  cwd?: string
  /**
   * MACHINE-LOCAL: this folder project's canvas lives in app data (`userData/inline-projects/<id>.json`),
   * not in `<cwd>/.nodeterm/project.json`, and nothing is written into the folder (issue #1145).
   * Only meaningful beside a local `cwd`; never written to any shared file. See the
   * folder-data-ref kind in core/workspace-files.ts (`IndexEntryV3.dataFile`).
   */
  storeInAppData?: boolean
  /** When set, this is an SSH project: its terminals run on `server` in `remoteCwd` (remote tmux). */
  ssh?: { server: import('./ssh').SshConnection; remoteCwd: string }
  viewport: Viewport
  nodes: CanvasNodeState[]
  /** Default managed Claude account for new Claude/chat nodes in this project. */
  defaultAccountId?: string
  /** Permission mode for new Claude TERMINAL (CLI) sessions in this project. SDK chat nodes are
   *  not covered — the chat driver still runs in `default`. Unset = use the global setting. */
  defaultPermissionMode?: AgentPermissionMode
  /**
   * Per-project capability switch: agents may drive browser nodes THEY opened in this project.
   * GIT-SHARED (rides .nodeterm/project.json) and therefore hostile input — the raw bit is read
   * ONLY through `projectCapabilityFlagInFile` (@shared/project-capabilities, strict `=== true`,
   * own-property), and it is NEVER a grant by itself: grants go through
   * `projectCapabilityGrantedFor` (@shared/project-capability-consent), which also requires this
   * machine's recorded 'kept' answer below.
   */
  agentBrowserControl?: boolean
  /** Per-project capability switch: agents may message other agent nodes in this project. Same
   *  rules as `agentBrowserControl` above — git-shared hostile input, strict `=== true` read,
   *  never a grant without this machine's recorded 'kept' (`projectCapabilityGrantedFor`). */
  agentMessaging?: boolean
  /** Per-project capability switch: agents may file a GitHub issue in THIS project's repository
   *  when they hit a nodeterm gap. Same rules as the two above — git-shared hostile input, strict
   *  `=== true` read, never a grant without this machine's recorded 'kept'
   *  (`projectCapabilityGrantedFor`). Unlike them, what it grants is PUBLICATION: the text leaves
   *  the machine, so the copy in `PROJECT_CAPABILITY_COPY` says so in as many words. */
  agentIssueReporting?: boolean
  /**
   * MACHINE-LOCAL record of what this machine's user ANSWERED for each capability switch —
   * 'kept' or 'declined', not a bare bit, because a declined switch whose hostile `true`
   * re-arrives via git must be refused and re-noticed, never silently granted (PR #213 C1).
   * Persisted on `IndexEntryV3.capabilityAck`, NEVER written into the shared project file
   * (workspace-files.test.ts / capability-notice tests pin that the file bytes are unchanged).
   */
  capabilityAck?: import('./project-capability-consent').CapabilityAckMap
  /** Best dino-game score in this project — new dino nodes seed from it, so the record survives closing the node. */
  dinoHighScore?: number
  /** Kanban task board — shared via .nodeterm/project.json like nodes. */
  kanban?: ProjectKanban
  /** Bridge links between Claude nodes (optional; absent in pre-bridge files). */
  bridges?: BridgeLink[]
  /**
   * Visual "spawned by" ropes (control-capable agent → node it opened via the `nodeterm` CLI,
   * or browser popup → its opener). Display-only — never context links — but persisted so the
   * lineage survives restarts; deletable like any selected edge.
   */
  ropes?: BridgeLink[]
  /** Camera navigation history — deliberate node landings, newest last. MACHINE-LOCAL: rides
   *  `IndexEntryV3.breadcrumbs`, never emitted into the shared project file (a repo must not carry
   *  one person's wandering camera history). */
  breadcrumbs?: NavStop[]
  /**
   * Named geometry snapshots for this canvas - see @shared/canvas-layout for what a layout may
   * carry and why it may carry nothing else.
   *
   * CONTENT, git-shared via `.nodeterm/project.json` like `kanban`: node geometry is already
   * shared content in that file and a restore writes exactly those fields, so the snapshot belongs
   * beside them. The camera precedent (`viewport`, `breadcrumbs`) deliberately does NOT reach
   * here - those are camera facts, and nobody else's canvas moves when I pan.
   */
  layouts?: CanvasLayout[]
  /** This machine's camera per layout, keyed by layout id. MACHINE-LOCAL: rides
   *  `IndexEntryV3.layoutViewports`, never the shared file - same rule as `breadcrumbs`. */
  layoutViewports?: LayoutViewports
  /**
   * Closed projects are hidden from the tab bar but kept on disk with all their nodes (and their
   * tmux sessions left running) so they can be reopened from the start screen's "Recently closed"
   * list. Absent/false = an open tab. A closed project never becomes `activeProjectId`.
   */
  closed?: boolean
  /** Set alongside `closed: true` — when this project was closed, for sorting "recently closed"
   *  history newest-first. Machine-local (see `IndexEntryV3.closedAt`) — never written into the
   *  shared project file, same rule as `closed` itself. Absent on a project closed before this
   *  field existed; such entries sort last. */
  closedAt?: number
  /** See `HandedOffTo`. Index-only; never written to the shared project.json. */
  handedOffTo?: HandedOffTo
  /**
   * Sessions (terminal/agent/sticky/…) deleted from this project, most-recent-first, capped at
   * 20. MACHINE-LOCAL, same rule as `closedAt`/`breadcrumbs` — see `IndexEntryV3.closedSessions`,
   * never written into the shared project file (a delete's full node-state blob — title, cwd,
   * position — would otherwise churn a committed, teammate-visible document on every one). Whose
   * trash can holds what is a per-machine fact, not shared content. A fresh id per entry;
   * recreating a node from one always mints a new node id/session, never reuses the original
   * (see `recreateNodeFromSnapshot`).
   */
  closedSessions?: ClosedSessionEntry[]
  /**
   * Set at load time when the project's .nodeterm/project.json could not be read
   * (folder missing, server unreachable, corrupt file). Runtime-only — never persisted.
   * Unavailable projects show a greyed tab and cannot be activated.
   */
  unavailable?: boolean
  /**
   * This tab is a LIVE relay connection to another machine's project — not a workspace on
   * THIS disk. Runtime-only, never persisted: set by `openRelayTab` (see relay-tab.ts) and
   * excluded from both `toWorkspace()` and the on-disk index (see the `splitWorkspace` skip in
   * core/workspace-files.ts). A relay tab is a connection bookmark, never a workspace on the
   * peer's disk, so it must never land in this client's workspace.json.
   */
  remote?: boolean
  /**
   * Relay tabs only: the host's SSH endpoint as DISPLAY strings (the tab's `SSH user@host` chip).
   * A relay tab never carries `ssh` — it would make this machine dial the host's server with this
   * machine's credentials (see renderer/session/relay-ssh.ts). Runtime-only like `remote`.
   */
  relaySsh?: { user: string; host: string; remoteCwd: string }
}

/** The full workspace written to / read from disk. */
export interface Workspace {
  version: 2
  activeProjectId: string
  projects: Project[]
}

/** Old single-canvas format (v1), kept only for migration on load. */
export interface WorkspaceV1 {
  version: 1
  viewport: Viewport
  nodes: CanvasNodeState[]
}

export const DEFAULT_PROJECT_ID = 'project-1'

// No projects on a fresh start → the renderer shows the welcome / start screen.
export const EMPTY_WORKSPACE: Workspace = {
  version: 2,
  activeProjectId: '',
  projects: []
}

// ---- Contract for the API exposed to the renderer via preload ----

/** Local core backend discovery, not a runtime health check or a promise about existing sessions. */
export interface TmuxStatus {
  /** tmux discovery only; retained for older callers and install polling. */
  available: boolean
  /** Absent on older peers; null when discovery could not be read. */
  persistence?: {
    enabled: boolean
    backend: 'tmux' | 'zellij' | 'session-host' | null
  } | null
  /**
   * The optional Zellij backend (@shared/session-backend): whether a `zellij` binary was found and
   * whether this machine's setting selects it for NEW local terminals. Absent on older peers and on
   * Windows (no Zellij backend there). `selected && !available` means new terminals fall back to
   * tmux — the Settings row says so rather than letting the choice look applied.
   */
  zellij?: { available: boolean; selected: boolean; socketTooLong?: boolean }
  /** One-shot install command for a terminal node; null = no known installer (text-only banner). */
  installCommand: string | null
  /** Button caption for installCommand (e.g. "Install Homebrew + tmux" when brew must come first). */
  installLabel: string | null
  /** `process.platform` of the core that owns the sessions/filesystem. `null` means the read
   *  failed; callers must not substitute the browser's platform for a server or relay core. */
  platform: string | null
}

/**
 * How close THIS MACHINE is to `kern.tty.ptmx_max`, the system-wide pty-device ceiling that took
 * the whole app down in the 2026-08-11 field report (every spawn failing with a bare
 * `posix_spawnp failed.`). See core/pty-pressure.ts for the bands.
 */
export type PtyPressureLevel = 'none' | 'elevated' | 'critical'

/** A pty-pressure reading, as broadcast on `IPC.ptyPressure`. `null` = could not be measured. */
export interface PtyPressure {
  level: PtyPressureLevel
  /** `/dev/ttys*` entries in existence right now. */
  usage: number | null
  /** `kern.tty.ptmx_max`. */
  ceiling: number | null
}

/** Outcome of the banner's "Fix automatically…" button (macOS only) — see main/ptmx-limit.ts. */
export type PtyLimitFixResult =
  | { ok: true; ceiling: number }
  /** `canceled` = the user dismissed macOS's own admin-password dialog. Not an error to retry.
   *  `busy` = a password dialog from another window/reload is already up. Both are SILENT for the
   *  renderer: nothing failed, so neither may raise an error toast. */
  | { ok: false; error: string; canceled?: boolean; busy?: boolean }

export interface PtyApi {
  /** Starts a new PTY session; returns its sessionId and whether the session was freshly
   *  created (cold start) vs reattached to a still-running tmux session (warm). */
  create(options: PtyCreateOptions): Promise<PtyCreateResult>
  /** Sends user input to the PTY. */
  write(sessionId: string, data: string): void
  /** Updates the PTY when the terminal is resized. The pty runs at the SMALLEST subscriber's grid,
   *  so this is a REPORT, not a command — the effective size comes back over `onSize`.
   *  `cols`/`rows` null means "subscribed, but not viewing" (a parked terminal): the client leaves
   *  the size set entirely, so a parked small window can't shrink everyone else's terminal.
   *  `viewerId` (optional, trailing) scopes the size vote to one VIEW within the connection (the
   *  kanban card modal); absent ⇒ the PRIMARY view. */
  resize(sessionId: string, cols: number | null, rows: number | null, viewerId?: string): void
  /** Flow control: pause (false) or resume (true) reading the PTY when xterm is backed up.
   *  `viewerId` (optional, trailing) scopes the pause to one VIEW (a client's second xterm is
   *  edge-latched independently); absent ⇒ the PRIMARY view. */
  setFlow(sessionId: string, resume: boolean, viewerId?: string): void
  /** Detaches/terminates ONE view of the PTY (the underlying tmux session survives). `viewerId`
   *  (optional, trailing) names the view to detach — closing the kanban modal leaves the canvas
   *  node attached; absent ⇒ the PRIMARY view. */
  kill(sessionId: string, viewerId?: string): void
  /** Permanently ends the persistent session for a node (kills its tmux session) because the node
   *  is being DELETED. Co-viewers get `onClosed` and must not respawn it.
   *
   *  `everySocket` (optional, trailing) widens a kill for a session we hold NOTHING for to every
   *  local tmux socket the name could be on. Opt-in for one caller — the session-memory panel's
   *  speculative kill of a row it swept off either socket. An ordinary node-× must not set it: it
   *  takes the same unheld branch after an app restart, and the legacy `nodeterm-rmt` holds sessions
   *  a pre-unification build on another machine SSHed in to spawn. */
  destroy(persistKey: string, opts?: { everySocket?: boolean }): void
  /** Ends a node's persistent session so the SAME node id respawns in a new cwd ("move into
   *  worktree"). Same tmux kill as `destroy`, opposite intent: the node stays on the canvas, so
   *  co-viewers get `onRecycled` (restart + re-attach), never the permanent closed state. */
  recycle(persistKey: string): void
  /** Suggest a terminal title from its recent output via the configured AI agent. `accountId` is
   *  the node's managed Claude account (trailing + optional: absent = system `~/.claude`), so the
   *  naming request runs under the same login the node itself does. */
  generateName(persistKey: string, cwd: string, accountId?: string): Promise<GitResult>
  /** Suggest a group title from its member terminals' recent output via the configured AI agent. */
  generateGroupName(memberKeys: string[], cwd: string): Promise<GitResult>
  /** Capture a terminal session's output as text. `full` grabs the entire scrollback. */
  capture(persistKey: string, full?: boolean): Promise<string>
  /**
   * Seconds since this node's tmux session was created, measured on the machine that holds it, or
   * `null` when that cannot be told (no session, no tmux, an unreadable host, a garbled answer).
   *
   * The late cold-start check behind `PtyCreateResult.freshUnverified`: `#{session_created}`
   * survives a `new-session -A` attach, so a session created within seconds of our own attach is
   * one we just made — i.e. the node was cold after all. `null` is never an age; the caller acts
   * only on a small number.
   */
  sessionAge(persistKey: string): Promise<number | null>
  /**
   * Has the host behind `sshRemote.controlPath` POSITIVELY listed this node's remote tmux session?
   *
   * The early-attach gate: a remote terminal may run over a ControlMaster whose connect-time setup
   * has not finished only when its session already exists (`new-session -A` then merely attaches,
   * and the remote tmux `-f` config and the `-e` hook/account env are read at session CREATION
   * only). Absent AND unreadable both answer `false` — the node then waits for the full connect,
   * because creating a session without that env silently costs it its agent-status badges.
   *
   * Desktop-only, like SSH projects; the Server Edition bridge answers `false` (never attach
   * early), which is the pre-feature behavior.
   */
  remoteSessionConfirmed(
    persistKey: string,
    sshRemote: { controlPath: string; conn: import('./ssh').SshConnection }
  ): Promise<boolean>
  /** Read the persisted scrollback snapshot for a node (for cold-restart replay). '' if none. */
  readScrollback(persistKey: string): Promise<string>
  /** Send literal text into a session, by default followed by Enter (e.g. a slash command).
   *  `opts.enter: false` writes the text without submitting it (dictation's Insert). Returns
   *  false if unavailable; `pasted-not-submitted` means input was accepted but Enter was not
   *  confirmed written. Surface it without automatically resending. True is not an app receipt. */
  sendText(persistKey: string, text: string, opts?: { enter?: boolean }): Promise<TextDeliveryResult>
  /** Submit a prompt from the ⌘M chat view. For an agent whose screen can be read
   *  (`readsScreenDialogs`), refused BEFORE anything is written when the agent's own dialog owns the
   *  keyboard (`ChatPromptBlocked`) — such dialogs fire no hook. Otherwise the `sendText` contract. */
  sendChatPrompt(persistKey: string, text: string, agentId: string): Promise<ChatPromptResult>
  /** Type `text` + Enter ONLY into an empty composer of an agent whose composer can be read
   *  (issue #1144 — the app's own link notes). Refused, with the reason, before anything is written
   *  when the composer holds a draft, a dialog owns the keyboard, or emptiness cannot be proven. */
  sendToEmptyPrompt(persistKey: string, text: string, agentId: string): Promise<EmptyPromptResult>
  /** One read of an agent's screen for the ⌘M chat view's poll: who owns the keyboard, and the
   *  prompt the agent suggests next (claude: `readClaudeSuggestion`). An agent with no measured
   *  reader, or a pane that could not be read, answers `{ screen: { kind: 'unknown' }, suggestion: null }`. */
  readChatScreen(persistKey: string, agentId: string): Promise<ChatScreenRead>
  /** Esc from the ⌘M chat view: interrupt a running turn, for an agent whose interrupt is measured
   *  (claude). Refused before writing when the agent's own dialog owns the keyboard. `sentText` (the
   *  chat view's last send) lets core take it back out of the agent's input box when the Esc landed
   *  before the reply started; it comes back as `restored`. Never rejects on the desktop. */
  interruptChat(persistKey: string, agentId: string, sentText?: string): Promise<ChatInterruptResult>
  /** ⌘M chat → terminal: type the chat draft into the agent's EMPTY input box, unsent. Never
   *  rejects on the desktop. */
  putChatDraft(persistKey: string, agentId: string, text: string): Promise<ChatDraftPutResult>
  /** Terminal → ⌘M chat: take a draft that can be read back exactly out of the agent's input box
   *  (it is cleared there). Never rejects on the desktop. */
  takeChatDraft(persistKey: string, agentId: string): Promise<ChatDraftTakeResult>
  /** Is tmux available on this host (else the silent plain-shell fallback), plus a suggested
   *  install command for the "tmux not found" banner. */
  tmuxStatus(): Promise<TmuxStatus>
  /** The command currently in the foreground of a node's tmux pane (e.g. 'claude', 'zsh'), by
   *  node persistKey. null when it is unknown — no session, no tmux, or the query failed — which
   *  callers must read as "not observed", never as evidence of a particular command. */
  paneCommand(persistKey: string, opts?: { resolveUnmounted?: boolean }): Promise<string | null>
  /** The live working directory of a node's pane (`#{pane_current_path}`). null when unknown —
   *  no session, no tmux, the session-host backend, a failed query, or a surface that does not
   *  serve it (relay tabs) — and never a rejection. Used as the second cwd for file links. */
  paneCwd(persistKey: string): Promise<string | null>
  /** Type raw keys into a node's tmux pane by node id; no mounted terminal needed. Never rejects. */
  sendPaneKeys(nodeId: string, data: string): Promise<PaneKeysResult>
  /**
   * Desktop only (#925). Spawn-or-attach a node's session with no viewer and deliver `command`
   * through the echo-verified writer, then release the synthetic client (the tmux session keeps
   * running). Refused as `not-persistent` without tmux or the session-host. The Server Edition
   * starts nodes through its own factory, so the browser build rejects with E_UNSUPPORTED.
   */
  launchHeadless(req: {
    ptyOptions: PtyCreateOptions
    command: string
  }): Promise<import('./headless-launch').HeadlessLaunchResult>
  /** Kernel truth about a node's pane — its root pid, tty, tmux pane id and the full argv of its
   *  foreground process group — so a caller can ask WHO owns the pane rather than what tmux calls
   *  it. `null` is "could not read", never evidence that the pane is free (see `isAgentPane`'s
   *  three-valued verdict, which is what consumers should decide on). */
  paneOwner(persistKey: string, opts?: { resolveUnmounted?: boolean }): Promise<PaneOwner | null>
  /**
   * Execute a semantic agent launch in a node's live LOCAL Windows session-host pane: the core
   * encodes it for the pane's own shell (pwsh / Windows PowerShell / cmd) and the host types it
   * exactly once. Every other session (tmux, SSH, Zellij, plain shell, POSIX core, Git Bash/WSL)
   * answers `unsupported-shell`, and the caller keeps its legacy typed line. Optional: surfaces
   * that cannot serve it (relay tabs, test fakes) simply omit it — the caller's answer is the same.
   */
  executeLaunch?(persistKey: string, request: LaunchIntentRequest): Promise<LaunchIntentExecutionResult>
  /** Terminate the foreground process group in a node's pane. Returns false when the pane/process
   *  cannot be safely identified; it never kills the pane's login shell. When `expectedAgentId` is
   *  given, the kill happens only if that harness actually owns the foreground group (argv-verified)
   *  — so a stale menu can never SIGTERM vim or a build the user started in the pane. On Windows
   *  (session host / direct ConPTY) the identity gate is mandatory and the kill is the proven agent's
   *  process tree, never the shell; `'unsupported'` = the running session host predates that verb. */
  terminateForeground(persistKey: string, expectedAgentId?: string): Promise<boolean | 'unsupported'>
  /** The agent session's display name (`/rename` name, else auto name) read from the agent's own
   *  session store, resolved strictly by sessionId; null if unknown. Keeps a node title in sync with
   *  the `/resume` name (e.g. after resume) without cross-contaminating same-folder sessions.
   *  `accountId` scopes the lookup to a managed Claude account's transcript root (default `~/.claude`).
   *  `agentId` picks the reader — grok's name lives in its session metadata, not a claude transcript;
   *  omitted (every pre-grok caller) means the claude transcript reader. */
  readSessionName(sessionId: string, accountId?: string, agentId?: string): Promise<string | null>
  /** Listens for PTY output. Returns an unsubscribe function. */
  onData(sessionId: string, listener: (data: string) => void): () => void
  /** Fires when the PTY process exits. Returns an unsubscribe function. */
  onExit(sessionId: string, listener: (exitCode: number) => void): () => void
  /** The authoritative size of a co-attached session: min(cols) × min(rows) over all subscribers
   *  ("smallest subscriber wins"). Broadcast whenever the subscriber set or any reported size
   *  changes; the terminal renders at this size instead of its own fit. Returns an unsubscribe. */
  onSize(sessionId: string, listener: (size: { cols: number; rows: number }) => void): () => void
  /** Another client permanently destroyed this node while we were co-viewing it: the session is
   *  gone for good (do not respawn — show a "closed by <peer>" state). `by` is the destroying
   *  client's ClientId, or null when the destroy was not attributed to a client (a local desktop
   *  destroy); resolve it to a name via the presence store. Returns an unsubscribe. */
  onClosed(sessionId: string, listener: (info: { by: ClientId | null }) => void): () => void
  /** Another client RECYCLED this node (moved it into a worktree): this session id is dead. With
   *  `ready:true` a replacement is already live under the same node id — restart the terminal (the
   *  re-create co-attaches to it) instead of showing the closed state: nothing was deleted. With
   *  `ready:false` no replacement ever came (the recycler died mid-move): do NOT respawn — the
   *  terminal ends and offers a manual reopen. Returns an unsubscribe. */
  onRecycled(sessionId: string, listener: (info: RecycledInfo) => void): () => void
  /** We fell too far behind and the server dropped our queued output; this is the session's
   *  CURRENT screen captured from tmux. Reset the emulator and repaint from it.
   *  CONTRACT: the payload is guaranteed NON-EMPTY (a failed capture is retried, never sent). The
   *  listener must STILL ignore an empty/falsy payload — never reset on one: a wrongly cleared
   *  screen is unrecoverable, a skipped repaint is not. Returns an unsubscribe. */
  onResync(sessionId: string, listener: (screen: string) => void): () => void
}

export type WorkspaceMigrationKind = 'v2' | 'exec'

export interface WorkspaceSaveOptions {
  localOnly?: boolean
}

export interface WorkspaceApi {
  load(): Promise<Workspace>
  /** `localOnly`: return once this machine's disk holds the save, WITHOUT the SSH mirror
   *  round trips (the mirror is owed and rides the next ordinary save). For a write-ahead barrier
   *  that must be durable here but must not wait on a remote host — see WorkspaceStore.save. */
  save(workspace: Workspace, opts?: WorkspaceSaveOptions): Promise<void>
  /**
   * Ask the core to claim one held launch (node id + command) before any viewer types it
   * (issue #1173): `claimed` = this viewer delivers it, `elsewhere` = another viewer of the same
   * project already claimed it, type nothing. A manual Run now is never refused. Optional: a
   * client without it (an older core, a test double) keeps the per-viewer barrier alone.
   */
  claimLaunch?(nodeId: string, command: string, manual: boolean): Promise<'claimed' | 'elsewhere'>
  /** Reads <folder>/.nodeterm/project.json and returns the assembled Project (cwd resolved), or null. */
  probeFolder(folder: string): Promise<Project | null>
  /** Whether <folder>/.nodeterm/project.json is `present`, definitely `absent`, or `unreadable`
   *  (any non-ENOENT error). Never guesses absence from a failed read — see issue #385. */
  projectFileState(folder: string): Promise<'present' | 'absent' | 'unreadable'>
  /** "Store in app data", second half (issue #1145): once the move's save has landed, carry the
   *  folder's settings into app data and remove its `.nodeterm` files (git-tracked ones only with
   *  `removeTracked`). See `WorkspaceStore.releaseFolderFiles`. */
  releaseFolderFiles(projectId: string, removeTracked: boolean): Promise<import('./project-storage').ReleaseFolderFilesResult>
  /** "Store in folder", first half (issue #1145): refuse a folder that already holds a canvas or
   *  settings, else carry this project's settings in. See `WorkspaceStore.prepareFolderStorage`. */
  prepareFolderStorage(projectId: string): Promise<import('./project-storage').PrepareFolderStorageResult>
  /** Where the store has this project's canvas right now (issue #1145): asked after a move's save,
   *  which can land while the folder write in it did not. See `WorkspaceStore.projectStorage`. */
  projectStorage(projectId: string): Promise<import('./project-storage').ProjectStorageKind>
  /** Fired once after an on-disk migration: `v2` = a v2→v3 migration wrote .nodeterm/ dirs into the
   *  project folders; `exec` = the custom shell / advanced ssh args of already-open projects moved
   *  out of the shared project file into this machine's own workspace index (@shared/node-exec). */
  onMigrated(cb: (kind: WorkspaceMigrationKind) => void): () => void
  /** Fired once per run when a load found the workspace index unreadable and preserved it as
   *  `workspace.json.corrupt-<ts>` (the payload). The projects themselves are untouched — their
   *  canvases live in each <cwd>/.nodeterm/project.json — so the note tells the user to re-add them. */
  onCorruptRecovered(cb: (backupFile: string) => void): () => void
  /** Fired when a project file changed on disk outside the app (git pull, sync, teammate). */
  onExternalChange(cb: (project: Project) => void): () => void
  /** Fired when THIS core wrote the project itself (Server Edition headless canvas control: an agent
   *  opened, renamed, moved, closed…). Not an outside edit — the renderer merges it, never asks. */
  onServerChange(cb: (project: Project) => void): () => void
  /**
   * Main asks for pending canvas edits to be written NOW — before a quit or a restart-to-update
   * (`src/main/renderer-flush.ts`). The callback's settling is the answer; main waits at most ~1 s
   * either way. Desktop only: the Server Edition has no main process to quit, so its bridge never
   * fires it. Returns unsubscribe.
   */
  onFlushRequest(cb: () => Promise<unknown> | void): () => void
}

export interface ProjectSettingsApi {
  /** `{shared, local, conflict?}` for a known project id, or null for an unknown one. */
  read(projectId: string): Promise<import('./project-settings').ProjectSettingsSnapshot | null>
  /** Whole-document write of the git-shared `.nodeterm/settings.json`. See
   *  `WorkspaceStore.writeProjectSettings` for the false-vs-true contract. */
  writeShared(projectId: string, doc: import('./project-settings').ProjectSettingsDoc): Promise<boolean>
  /** This machine's own overlay; `local: undefined` clears it. */
  updateLocal(
    projectId: string,
    local: import('./project-settings').ProjectLocalSettings | undefined
  ): Promise<boolean>
  /** Resolved settings + per-family trust verdict for one project — `null` for an unknown id. The
   *  renderer cache (`renderer/state/projectLaunchInfo.ts`) warms this on activate and never awaits
   *  it inline; a caller wanting the raw handshake calls this directly instead. */
  launchInfo(projectId: string): Promise<import('./project-settings').ProjectLaunchInfo | null>
  /** main → renderer: a family's trust verdict changed for `projectId` (a consent dialog answered,
   *  an approval revoked). Nobody broadcasts this yet — Task 2 records approvals and emits it. */
  onTrustChanged(cb: (p: { projectId: string }) => void): () => void
}

export interface ProjectSetupApi {
  /** Launch a project's setup/archive script behind the trust gate (`project-setup-service.ts`).
   *  `worktreePath`, when given, is the ONLY path-shaped hint this call carries — main derives
   *  `rootPath`/`ssh` from its own workspace index by `projectId` and independently validates
   *  `worktreePath` against that project's actual git worktrees; nothing path-shaped sent here is
   *  trusted as-is (Task 1 review finding). */
  run(
    projectId: string,
    kind: import('./project-settings').ProjectSetupKind,
    worktreePath?: string
  ): Promise<import('./project-settings').ProjectSetupRunResult>
  /** Aborts a live run, or one still waiting at its consent dialog. `false` = nothing by that
   *  runKey exists (already finished, or never did). */
  cancel(runKey: string): Promise<boolean>
  /** Renderer's answer to a `onConsentRequest` prompt. A stale/unknown requestId is a silent no-op. */
  consent(requestId: string, answer: import('./project-settings').ProjectSetupConsentAnswer): Promise<void>
  /**
   * Ask for this project's `agents`/`shell` family to be trusted, prompting the human if it is not
   * yet — the call a launcher makes before consuming a shared-sourced `launchCmd`/`env`/`shell`.
   * `true` only when the family is trusted at that project's location (nothing shared to gate, an
   * existing grant, or a fresh approval); skip, expiry, an unknown project and a refused (relay
   * guest) call are all `false`. Concurrent asks for one location share ONE dialog. On approval,
   * `projectSettings.onTrustChanged` fires for the project, so a cached launch-info verdict is
   * re-read rather than trusted from before the answer.
   */
  requestTrust(projectId: string, family: 'agents' | 'shell'): Promise<boolean>
  /** main → renderer: raise the trust dialog before a shared-sourced script runs, or before a
   *  shared-sourced launch setting is consumed — tagged by family (`ProjectConsentRequest`). */
  onConsentRequest(cb: (req: import('./project-settings').ProjectConsentRequest) => void): () => void
  /** main → renderer: close a prompt nobody answered before the renderer did. */
  onConsentDismiss(cb: (p: { requestId: string }) => void): () => void
  /** Per-project run progress (`ProjectSetupEvent`), mirroring `boardLog.onChanged`'s ref-counted
   *  subscribe/unsubscribe shape. */
  onEvent(projectId: string, cb: (ev: import('./project-settings').ProjectSetupEvent) => void): () => void
}

export interface WorktreeApi {
  /**
   * Symlink a project's configured `sharedPaths` (git-ignored dirs like `node_modules`) from its
   * repo root into a freshly-created git worktree, so a setup `npm install` there sees the links.
   *
   * The renderer passes ONLY `(projectId, worktreePath)` — never the path list: main reads the list
   * itself out of the project's settings by `projectId`, derives the repo root from its own
   * workspace index, and validates `worktreePath` is that project's rootPath or one of its actual
   * git worktrees. An unknown project, an unvalidated path, or an SSH project (local-only this PR)
   * all resolve `[]`. Never rejects — a per-entry `SharedPathResult[]` reports what happened.
   */
  materializeShared(
    projectId: string,
    worktreePath: string
  ): Promise<import('./worktree').SharedPathResult[]>
}

export interface DialogApi {
  /** Opens a native folder picker; returns the chosen path or null if cancelled. */
  selectFolder(): Promise<string | null>
  /** Opens a native file picker; returns the chosen path or null if cancelled. */
  selectFile(): Promise<string | null>
}

export interface ClipboardWriteOptions {
  /**
   * Never raise a failure toast. For writes the user did not explicitly ask for as a copy — today
   * only copy-on-select (issue #759), which writes on every completed drag, where a toast per drag
   * would be unusable. The write still tries every route; only the banner is withheld. The desktop
   * preload's write is fire-and-forget IPC with no failure surface at all, so it ignores this.
   */
  quiet?: boolean
}

export interface ClipboardApi {
  writeText(text: string, opts?: ClipboardWriteOptions): void
  /** Copy local files so Finder and other file-aware macOS apps can paste them. */
  writeFiles(paths: string[]): Promise<boolean>
}

export interface ShellApi {
  /** Reveal a path in the OS file manager (Finder). */
  reveal(path: string): void
  /** Open a path with the OS default application. */
  openPath(path: string): void
  /** Open an http(s) URL in the OS default browser. */
  openExternal(url: string): void
  /** Open a file dialog for a project-icon image; main re-encodes the pick to a bounded PNG data
   *  URL (or an error), or returns null when cancelled. See `pickProjectIcon` (main). */
  pickProjectIcon(): Promise<ProjectIconPickResult>
}

export interface DirEntry {
  name: string
  dir: boolean
  /** True when the entry is matched by .gitignore (shown dimmed). */
  ignored?: boolean
}

export interface FsApi {
  /** List a directory (folders first, then files; alphabetical). */
  list(dirPath: string): Promise<DirEntry[]>
  /** Read a file's text contents (empty string on error). */
  read(filePath: string): Promise<string>
  /** Read a file as base64 (for images and other binary previews; '' on error). */
  readBinary(filePath: string): Promise<string>
  /** Write text to a file; resolves true on success. */
  write(filePath: string, content: string): Promise<boolean>
  /** Create a directory (recursive). Resolves true on success. */
  mkdir(dirPath: string): Promise<boolean>
  /** True when the path exists (file or directory). */
  exists(path: string): Promise<boolean>
}

export interface FilesApi {
  /** Fuzzy-open file index for a project root: root-relative `/`-paths ([] on failure). */
  quickOpen(cwd: string): Promise<string[]>
  /**
   * Mint a one-shot, short-TTL ticket for downloading `path` over HTTP, and resolve the URL to
   * navigate to. Resolves **null** where the shell has no HTTP surface to redeem it on (Electron
   * desktop, relay) — callers treat null as "downloading is not offered here" and hide the
   * affordance rather than erroring.
   */
  downloadTicket(path: string): Promise<DownloadTicket | null>
  /**
   * Persist raw bytes (base64) as a file on the machine the terminals run on, and resolve its
   * ABSOLUTE path — what a clipboard paste of an image has instead of a path, and what a browser
   * client's dropped file has instead of a usable one. Resolves null when it could not be written
   * (too large, unwritable); callers drop that file the way a failed drop does.
   */
  saveUpload(name: string, dataBase64: string): Promise<string | null>
  /**
   * Persist raw bytes (base64) as a CANVAS image and resolve its ABSOLUTE path. Unlike
   * `saveUpload` the file is durable: a canvas image node is persisted in `project.json`, so its
   * file cannot live in a staging area that is swept after a week. The directory is derived from
   * `projectId` on the receiving side — the caller never names a path — and is the project's own
   * git-shared `.nodeterm/images/` when it has a local cwd, else a durable app-local folder.
   * Resolves null when it could not be written; callers drop that file like a failed drop.
   */
  saveCanvasImage(projectId: string, name: string, dataBase64: string): Promise<string | null>
  /**
   * Save a whiteboard node's scene (Excalidraw JSON) and the picture it shows at rest. The core
   * derives the file from (projectId, nodeId) — beside project.json, or its own data dir. Resolves
   * `{ok: true, path, rev}`, a conflict when the board on disk is no longer `expectedRev` (nothing
   * written), or null when it could not be written. A core on an older build answers the bare path
   * string and ignores `expectedRev`. See core/whiteboards.ts.
   */
  saveWhiteboard(
    projectId: string,
    nodeId: string,
    scene: string,
    thumbnailBase64?: string,
    expectedRev?: string | null
  ): Promise<WhiteboardSaveResult | string | null>
  /** Read a whiteboard back; `sourceId` is the board a copied node falls back to until it saves.
   *  `withScene: false` reads only the picture and revision (a board at rest). */
  readWhiteboard(projectId: string, nodeId: string, sourceId?: string, withScene?: boolean): Promise<WhiteboardFile | null>
  /**
   * Store a custom sound for an agent alert (issue #289). The core validates kind, extension,
   * size and magic bytes, then writes a FIXED per-kind file under its own data dir — the picked
   * file's path is never sent, only its bytes and base name. Resolves `{ ok: false, error }` for a
   * refusal; never rejects on a bad file.
   */
  saveAlertSound(kind: AlertSoundKind, name: string, dataBase64: string): Promise<AlertSoundSaveResult>
  /** The stored custom sound for `kind` as base64, or null when there is none (or it is unreadable). */
  readAlertSound(kind: AlertSoundKind): Promise<string | null>
  /** Delete the custom sound for `kind` (Reset to default). */
  clearAlertSound(kind: AlertSoundKind): Promise<boolean>
}

export interface MediaApi {
  /** Allow an absolute local path to be served, and return its nt-media:// URL. */
  allow(absPath: string): Promise<string>
  /**
   * Allow a file that lives on an SSH project's HOST: main pulls it into a local cache over the
   * project's ControlMaster (skipped when the cached copy's size still matches the remote), then
   * allowlists the cached copy. Resolves the playable nt-media:// URL, or a reason it couldn't
   * (not connected, transfer failed). Desktop only — the browser bridge rejects it.
   */
  allowSsh(projectId: string, remotePath: string): Promise<{ ok: true; url: string } | { ok: false; error: string }>
  /** Persist raw HTML to <userData>/agent-web/<id>.html, allowlist it, return its absolute path. */
  writeHtml(html: string): Promise<string>
}

export interface BrowserApi {
  /** Map a browser node's <webview> guest to its node id (for new-window capture). */
  register(webContentsId: number, nodeId: string): void
  unregister(webContentsId: number): void
  /** Fires when a browser guest requested a new window; the renderer opens another browser node. */
  onBrowserNewWindow(listener: (e: { url: string; sourceNodeId: string }) => void): () => void
  /** Push: the current set of browser nodes an agent is driving (chip / rope / kill row). `stopped`
   *  ids drop from the chip immediately, skipping the anti-flicker linger. */
  onLeaseChanged(listener: (push: BrowserLeasePush) => void): () => void
  /** Stop agent control of ONE browser node — the chip button and the node context menu. Detaches
   *  the debugger + drops the lease in main; a later drive from that owner is refused by name. */
  stop(nodeId: string): void
  /** Stop agent control of EVERY driven node — the Settings kill row's Stop-all. */
  stopAll(): void
  /** Stop agent control of every node in a project — the project's browser-control switch going off. */
  stopProject(projectId: string): void
}

/** A user-defined agent (BYO CLI). With no `baseAgent` it is in no capability list, so it gets
 * only spawn + terminal-title + process status (no hooks/branch/loop/bridge). With a `baseAgent`
 * it inherits that builtin harness's capabilities (hooks, resume, permission modes, canvas
 * control) and prompt convention — the use case being a harness-compatible CLI pointed at your
 * own inference proxy, where you want to KEEP nodeterm's integration while redirecting the calls. */
export interface CustomAgent {
  /** Stable id of the form 'custom:<uuid>'. Used as the node's agentId. */
  id: string
  label: string
  /** Base launch command. Blank when `baseAgent` is set means "use the base harness's command"
   * (so a claude-compatible proxy needs zero launch config). */
  launchCmd: string
  /** Prompt convention. Optional: inherited from `baseAgent` when set, else defaults to 'argv'. */
  promptInjectionMode?: PromptInjectionMode
  /** Optional builtin harness to inherit capabilities + prompt convention from. */
  baseAgent?: BuiltinAgentId
  /** Env vars injected at spawn, merged LAST so they win over hook/account env (required for the
   *  proxy case — your ANTHROPIC_AUTH_TOKEN must beat any account env). Values support
   *  `${env:VAR}` / `${env:VAR:fallback}` expansion at spawn time against the live OS env. */
  env?: Record<string, string>
  /** Extra argv inserted after `launchCmd`, before the prompt/flags. Free-text, shell-split.
   *  Supports `${env:…}` expansion. Blank = none. */
  args?: string
  /** Node color. Falls back to `baseAgent`'s color (or the default grey). */
  color?: string
}

/**
 * A managed Claude account. Its credentials/config live in a private config dir
 * ({userData}/claude-accounts/<id>, or `~/.nodeterm/claude-accounts/<id>` on `host` for
 * remote accounts) injected as CLAUDE_CONFIG_DIR at spawn. The claude CLI owns login,
 * credential storage, and token refresh inside that dir — we never write credentials.
 */
export interface ClaudeAccount {
  id: string
  /** Display label; defaults to the captured email. */
  label: string
  email?: string
  /** Set only for remote (SSH) accounts: the ssh host this account's config dir lives on. */
  host?: string
  /** True until `claude /login` completes in the account dir and the email is captured. */
  pending?: boolean
  /** Optional default node color for nodes opened under this account (Settings → Accounts);
   *  unset = the agent's own brand color. Read through `accountNodeColor`, which re-validates it
   *  as a string — this file is hand-editable and nothing checks it field-by-field on load. */
  color?: string
  /**
   * LINKED account: an ABSOLUTE local path to a pre-existing Claude config dir the user already
   * owns (e.g. `~/.claude-2` driven by their own `CLAUDE_CONFIG_DIR` shell setup). Set only by
   * `claudeAccounts.link`; never combined with `host`. A linked account has no managed dir under
   * `{userData}/claude-accounts/` — `claudeConfigDirFor` resolves it to this path — and REMOVING
   * it only forgets the record: the directory is the user's and is never deleted. Hand-editable
   * (settings.json), so it is re-validated at every point of use (absolute, normalized).
   */
  configDir?: string
  /**
   * Share the machine's system skills (`~/.claude/skills`) with this account (issue #643).
   * OFF/absent = the isolation Claude Code's own `join(CLAUDE_CONFIG_DIR, 'skills')` gives, which
   * is the default and often the point. ON = each system skill is LINKED into the account's own
   * `skills/` individually — the account's directory stays real, nodeterm's own skills keep their
   * names, and turning it off removes only the links (`core/claude-skill-share.ts`).
   * Reconciled at launch and whenever the switch is flipped; LOCAL accounts only — a remote (SSH)
   * account's skills live on its host and are out of scope for v1.
   */
  shareSystemSkills?: boolean
  createdAt: number
}

/**
 * Which Claude account a RUNNING session was observed to use — derived by the hook server from
 * the `transcript_path` its hooks report (`<configDir>/projects/<slug>/<session>.jsonl`), never
 * from anything the node was created with. A LABEL, exactly like `NormalizedAgentEvent.verified`:
 * it tells the UI which identity a pane is on (a hand-launched `claude` in a plain terminal, an
 * account switched by the user's own shell), it never grants anything.
 *  - `accountId === null` ⇒ the system default (`<home>/.claude`).
 *  - `accountId` set + `known` ⇒ a managed or linked `ClaudeAccount` from settings.
 *  - `known === false` ⇒ a config dir nodeterm has no record of (`accountId` is null); the UI
 *    labels it by its path and offers to link it. No filesystem read is ever made for such a dir.
 */
export interface ObservedClaudeAccount {
  /** The config dir as the hook reported it (normalized string; may be a REMOTE path for SSH nodes). */
  configDir: string
  accountId: string | null
  known: boolean
  /**
   * The observation came from a session whose FILESYSTEM IS ON ANOTHER MACHINE (an SSH-project
   * pane), so every LOCAL affordance — offering the dir for linking, matching it against a local
   * account's `configDir` — must refuse it. `~/.claude-2` on a host and `~/.claude-2` here are
   * different directories that spell the same string, and the same username on both machines is
   * the common case, not the exotic one.
   *
   * It is NOT set by the classifier: `classifyClaudeConfigDir` is deliberately host-agnostic (its
   * managed-remote and basename-`.claude` rules exist precisely to name a REMOTE dir) and core
   * holds only the payload, which says nothing about which machine posted it. The RENDERER is the
   * only layer that knows a node's project and `data.ssh`, so the flag is attached there, once, at
   * the point the label enters the store.
   *
   * Optional and trailing: an observation without it is a local one, which is what every
   * observation was before the field existed.
   */
  remote?: boolean
}

export interface SpeechSettings {
  engine: 'whisper' | 'cloud'
  /** WhisperModelInfo id — meaningful while engine === 'whisper'. */
  model: string
  /** BCP-47-ish hint or 'auto'. */
  language: string
  /** Press-to-talk / hold-to-talk shortcut, canonical form e.g. "Cmd+Alt+D" (keyed = toggle) or
   *  "Cmd+Alt" (v3, modifier-only = hold-to-talk — the new DEFAULT); see `shared/shortcut.ts`
   *  (`isHoldChord` derives the mode from the string, not a separate setting). "Cmd" is
   *  platform-abstracted: metaKey on mac, ctrlKey elsewhere. Drives the Canvas listener, the
   *  Dock mic tooltip, and the ShortcutsPanel row. */
  shortcut: string
}

/** xterm cursor shapes, mirrored here so `Settings` doesn't depend on the xterm typings (which
 *  are renderer-only — `src/shared` is imported by main and the server shell too). */
export type TerminalCursorStyle = 'block' | 'bar' | 'underline'
export type TerminalCursorInactiveStyle = TerminalCursorStyle | 'outline' | 'none'

/** The primary modifiers of a forwarded desktop ⌘/Ctrl+0 (issue #915): the renderer applies the
 *  per-platform terminal-font-reset predicate to them. Optional on the listener because the Server
 *  Edition stub never fires and an absent value must read as "not a font reset". */
export interface ZoomActualSizeModifiers {
  meta: boolean
  control: boolean
}

/** `settings.runInBackgroundOnClose` — see the field's doc. */
export type BackgroundOnCloseSetting = 'auto' | 'on' | 'off'

/** User-configurable application settings (settings.json). */
export interface Settings {
  fontSize: number
  fontFamily: string
  /** Characters that end a word during xterm double-click selection. */
  terminalWordSeparator: string
  cursorBlink: boolean
  /** Appearance of the APP chrome (tab bar, panels, node headers, menus). `auto` (the default)
   *  takes it from the terminal colour theme, so picking a light terminal theme doesn't leave a
   *  black window framing it; `dark`/`light` pin it. `liquid-glass` follows the terminal theme like
   *  `auto` AND turns the Liquid Glass appearance on: every canvas node and the app chrome go
   *  translucent + blurred over the wallpaper, and terminal windows drop their per-node accent
   *  colour; tint opacities keep the primary text at WCAG 4.5:1 over any backdrop
   *  (renderer/lib/glassContrast.ts). See renderer/lib/appTheme.ts. */
  appTheme: 'auto' | 'dark' | 'light' | 'liquid-glass'
  /** Scale factor for the whole application UI (1 = 100%; issue #299, 4K readability). Applied as
   *  PAGE ZOOM (`webFrame.setZoomFactor`) on desktop, so menus, node headers, dialogs — and
   *  terminal glyphs — all scale together: the terminal font-size setting stays in CSS px, so its
   *  effective size is fontSize × uiScale (the Settings row says so). Hand-editable; every reader
   *  resolves it through `resolveUiScale` (shared/ui-scale.ts), which clamps to [0.5, 2] and maps
   *  garbage to 1. Server Edition: intentionally inert — the browser owns page zoom (Cmd/Ctrl+±). */
  uiScale: number
  /** Reflect the active session in the NATIVE window title ("<node> — <project> — node-terminal"),
   *  so window-title-based time trackers (ActivityWatch et al.) can tell sessions apart — the same
   *  thing iTerm2 / Windows Terminal do per tab (issue #414). Opt-in and OFF by default: the title
   *  is OS-visible surface area (window switchers, screen sharing), so an update must not start
   *  broadcasting session names for users who never asked. Renderer-only (`document.title` —
   *  Electron mirrors page-title changes onto the BrowserWindow, and the Server Edition gets the
   *  browser tab title through the identical write), so there is no bridge member to stub. */
  windowTitleActiveSession: boolean
  /** Terminal colour scheme — an id from `renderer/terminal/themes.ts`. Resolution is tolerant
   *  (settings.json is hand-editable): an unknown id falls back to the default theme, whose
   *  colours reproduce the pre-feature hardcoded `#1e1e1e`/`#e6e6e6` exactly. */
  terminalTheme: string
  /** Desktop wallpaper behind the canvas (Liquid Glass appearance). Opt-in; `none` draws the
   *  canvas exactly as before. Hand-editable: read through `normalizeWallpaper` (shared/wallpaper). */
  desktopWallpaper: import('./wallpaper').DesktopWallpaper
  /** The most recent imported wallpaper image's cache path, kept after switching to a preset so the
   *  "Your image" tile stays and the cache prune keeps its file (`recentWallpaperImage`). */
  recentWallpaperImage: string | null
  /** Weight for normal text. xterm's own default is `normal` (400). */
  fontWeight: number
  /** Weight for BOLD text. xterm's own default is `bold` (700). Lowering it is how you keep bold
   *  legible in a thin font that renders 700 as a smear. */
  fontWeightBold: number
  /** Render bold text in the palette's BRIGHT colours (xterm's default, and the historical
   *  terminal convention). Off keeps bold purely a weight, so colour still means what the program
   *  said it meant. */
  drawBoldTextInBrightColors: boolean
  /** Minimum foreground/background contrast ratio, 1–21. 1 (xterm's default) disables the
   *  adjustment entirely; 4.5 is WCAG AA, 7 is AAA, 21 forces black or white. Costs per-cell work
   *  in the renderer, so it stays off unless asked for. */
  terminalMinContrast: number
  /** Cursor shape. */
  cursorStyle: TerminalCursorStyle
  /** Cursor shape while the terminal does NOT have focus. `outline` (xterm's own default) is what
   *  tells you at a glance which of a canvas full of terminals is taking your keystrokes. */
  cursorInactiveStyle: TerminalCursorInactiveStyle
  /** Line height as a multiple of the font size (1 = xterm's default, i.e. no extra leading). */
  terminalLineHeight: number
  /** Extra horizontal space between cells, in CSS pixels (0 = xterm's default). */
  terminalLetterSpacing: number
  /** Empty string = use the system default shell. */
  defaultShell: string
  gridSize: number
  /** Drag-time snap: while ON, dragging a node rounds its position to the grid. A live editor in
   *  BehaviorSection; the canvas reads it for the React Flow `snapToGrid` prop. Distinct from
   *  `autoAlignGrid` (a one-shot arrange-all), which is a mode, not a drag constraint. */
  snapToGrid: boolean
  /** Snap-to-grid MODE (like a desktop "Auto arrange"): while ON, every node is snapped to the
   *  grid at the moment the mode is turned on (the existing one-shot `alignToGrid` run over all
   *  node ids). Toggled from the native View menu (with a checkmark) and Settings → Behavior.
   *  Distinct from `snapToGrid` (drag-time snap) — turning this on arranges once; it does not
   *  constrain future drags. v1: arrange-all-on-enable only. */
  autoAlignGrid: boolean
  /** Height of the top project tab bar in CSS px (Settings → Appearance). Hand-editable; every
   *  reader — the renderer's `--tabbar-h` and main's traffic-light `y` — goes through
   *  `resolveTabBarHeight` (`@shared/window-chrome-metrics`), which clamps to 28–64 and answers
   *  the default for anything that is not a finite number. Machine-local: it is one person's
   *  chrome, not a canvas fact. */
  tabBarHeight: number
  /** How solid sticky notes / group frames are behind their colour tint, 0–100 (Settings →
   *  Appearance, issue #1113). 0 = see-through, the original look. Hand-editable; read through
   *  `resolveCanvasBacking` (@shared/canvas-backing). Machine-local. */
  stickyNoteBacking: number
  groupFrameBacking: number
  /** Font of the rendered-Markdown reading views — the ⌘M output and chat views and the editor's
   *  Markdown preview (Settings → Appearance). A CSS font stack. Hand-editable; read through
   *  `resolveMarkdownFontFamily` (@shared/markdown-font). Code inside Markdown follows the
   *  terminal `fontFamily` instead. Machine-local, like the terminal font. */
  markdownFontFamily: string
  /** Body size (CSS px) of the same views; headings scale from it, code is 0.92 of it. Read
   *  through `resolveMarkdownFontSize`, which clamps to 8–28 and answers 13 for garbage. */
  markdownFontSize: number
  /** Default size (px) for NEW terminal/agent nodes on the canvas. Existing nodes keep
   *  whatever size they were saved with; other node kinds keep their own defaults. */
  defaultNodeWidth: number
  defaultNodeHeight: number
  /** Default size (px) for NEW nodes of every other kind the add menus create, keyed by kind; a
   *  kind with no entry opens at its built-in size. Read through `defaultNodeSize` (renderer) /
   *  `resolveDefaultNodeSize` (@shared/default-node-size), which clamp hand edits. Machine-local. */
  defaultNodeSizes: Partial<Record<SizableNodeKind, NodeSize>>
  /** Sessions sidebar: the DEFAULT for a project row the user never toggled — on (historical)
   *  keeps the active project expanded and collapses the others, off leaves everything expanded.
   *  Explicit toggles live in `sidebarCollapsedItems` and always win. */
  sidebarAutoCollapse: boolean
  /** Persisted disclosure choices for the sessions tree, keyed `project:<id>` and
   *  `project:<id>:group:<groupId>` (true = collapsed). Pruned on every write against the live
   *  tree, so a deleted frame or project cannot grow settings.json forever. */
  sidebarCollapsedItems: Record<string, boolean>
  /** Sessions sidebar top-level grouping. 'project' (the default, the historical behavior) groups
   *  sessions under their project; 'status' flattens across projects and regroups by live agent
   *  status so sessions needing attention float to the top. Remote/relay sessions have no live
   *  status in the sidebar and show as idle in either mode. */
  sidebarGrouping: 'project' | 'status'
  /** Fallback view for projects the user hasn't explicitly toggled (canvas or the kanban board).
   *  Personal machine-local preference; per-project explicit choices override it. */
  defaultProjectView: 'canvas' | 'kanban'
  /** Global swimlane kanban overview (Omni-Kanban): when enabled, the kanban board shows all
   *  open projects as stacked swimlanes instead of per-project tabs. Toggle in Settings →
   *  Behavior. Default OFF — no silent behavior change for existing users; `globalKanban`
   *  (the view flag) is only honored when this is true. */
  omniKanbanEnabled: boolean
  /** When enabled, Cmd+Shift+B (view.kanbanToggle) opens the global Omni board instead of the
   *  per-project board. The dedicated global shortcut (view.globalKanbanToggle) always opens
   *  Omni regardless of this setting. Opt-in, per user — default OFF. */
  omniKanbanAsDefault: boolean
  /** New-worktree path template, resolved relative to the repository root. Supports `$repoName`
   *  (`$reponame` and `$defaultFolderName` aliases) plus `$branch`; both `$x` and `${x}` forms.
   *  A missing branch token is appended automatically. */
  worktreePathTemplate: string
  /** Issue #1145. Where a folder project created from now on keeps its canvas: `'folder'` (the
   *  default — `<cwd>/.nodeterm/project.json`, git-shareable) or `'appData'` (nothing written into
   *  the folder; see `Project.storeInAppData`). A folder that already has a project.json is adopted
   *  as it is, in its folder, whatever this says. Existing projects move from the tab menu. */
  newProjectStorage: import('./project-storage').NewProjectStorage
  /** ms to dwell over a terminal before it takes pointer focus (pan-across guard). */
  panHoverDelay: number
  /** Issue #757. Whether a terminal node's keyboard focus follows the POINTER (the long-standing
   *  behaviour and the default): a `panHoverDelay` dwell takes it and leaving the node gives it
   *  back. Off = click to focus (the Mac model): the pointer decides nothing, a click or a "go to
   *  node" takes the keyboard, and the terminal keeps it until focus really moves elsewhere
   *  (another node, the empty canvas, a field). Machine-local, Settings → Behavior. Decisions live
   *  in `renderer/lib/terminalFocusMode.ts`. */
  terminalFocusFollowsPointer: boolean
  doubleClickFocus: boolean
  /** "Go to node" (sessions sidebar, notification click, ⌘K jump, breadcrumb steps, presence
   *  travel) fits the node in view. Off: the camera keeps the CURRENT zoom and only pans, which is
   *  what a user who has settled on a zoom level wants — a jump that also rescales the whole canvas
   *  costs them the sense of where they were. Either way the node is centred and kept clear of the
   *  floating chrome (renderer/lib/nodeFocus). */
  focusZoomToNode: boolean
  /** Closing the LAST session (terminal/agent) node of a project with its × offers to close the
   *  project too (issue #848). Opt-in — default OFF, because not everyone closes their last
   *  session when they are done with a project. Only the user's × click asks; a restart, an exit,
   *  a hibernated agent (still a node) or a bulk/programmatic close never does
   *  (renderer/lib/lastSessionClose). Declining keeps the project open. */
  offerCloseProjectOnLastSession: boolean
  /** Whether the bottom-left canvas lock survives a restart. OFF by default, and deliberately so:
   *  the lock was transient by design, because a canvas that will not pan on the next launch reads
   *  as "the app is frozen" to whoever opens it, and the lit button is a small thing to spot. Users
   *  who lock on purpose and want it to stay locked opt in here; everyone else opens unlocked
   *  exactly as before. The lock itself is persisted in localStorage (renderer/lib/canvasLock),
   *  never in settings.json or the git-shared project.json: this flag says whether to remember,
   *  the lock is one person's view state. Machine-local on Desktop; in the Server Edition this
   *  setting is the server's while the lock is per browser profile. */
  rememberCanvasLock: boolean
  /** Whether `nodeterm://` links from other apps are handled (docs/superpowers/specs/
   *  2026-10-13-open-link-design.md). OFF by default: a link can come from any web page, script
   *  or app, so taking them is something a person turns on. On, a `nodeterm://open` link shows a
   *  confirm sheet and opens ONE agent or terminal node only after a click; `nodeterm://pair` and
   *  `nodeterm://join` pre-fill the code prompt. Off, a link opens nothing and a notice says where
   *  to turn it on. Machine-local (settings.json); read by main on every link. */
  allowOpenLinks: boolean
  /** Open Markdown files (.md, .markdown, …) in rendered preview instead of the code editor.
   *  Only picks the view an editor node OPENS in — the node's Preview/Edit toggle (and the
   *  markdown-toggle chord) still switches either way. Default ON since the release after
   *  v0.3.3 (maintainer decision on issue #495; a preview is one ⌘M from the editor, so the
   *  rendered view is the better first sight for docs). A one-shot load migration keyed on
   *  `openMarkdownPreviewMigrated` (see mergeSettings) forces this ON once for every existing
   *  file — including one saved by v0.3.3, the one release that defaulted off and whose
   *  full-snapshot saves materialized `false` for users who never touched the toggle. After
   *  the migration the user's own opt-out is permanent. */
  openMarkdownPreview: boolean
  /** One-shot marker for the openMarkdownPreview default flip (#495). Absent = the file
   *  predates the flip → the load migration sets `openMarkdownPreview: true` and stamps this
   *  true; present = the migration already ran (or the install was born after it) and the
   *  stored `openMarkdownPreview` value is the user's own, never touched again. */
  openMarkdownPreviewMigrated: boolean
  /**
   * Let a MIDDLE CLICK inside a terminal paste (Linux in practice — macOS and Windows have no
   * PRIMARY selection and no tmux middle-click habit, so the guard changes nothing visible there).
   *
   * OFF by default, and OFF means the middle button is fully INERT inside a terminal — tmux's own
   * middle-click paste included. That is a consequence of the real mechanism (issue #84, measured
   * on the reporting machine): the paste never happens in the browser. xterm forwards a mouse
   * report for the middle button and something DOWNSTREAM of the pty consumes it — tmux's root
   * `MouseDown2Pane` binding pastes tmux's buffer at a shell prompt, and an agent TUI reads the X
   * PRIMARY selection itself. There is no browser default action to cancel, so the guard swallows
   * the event before xterm can forward it (`guardMiddleClickPaste`), and tmux's paste necessarily
   * goes with it. The default stays off because the paste fires hardest inside agent TUIs: a stray
   * click drops whatever was last selected anywhere on the machine into a live agent prompt.
   */
  terminalMiddleClickPaste: boolean
  /**
   * Copy a completed MOUSE selection that the terminal emulator (xterm) owns to the system
   * clipboard (issue #759). OFF by default: it preserves the explicit-copy behaviour, and silently
   * changing what is on the clipboard is a surprise worth opting into.
   *
   * Scope, stated honestly: it covers only selections xterm makes itself — a drag, double/triple
   * click, or a FORCED selection (Option-drag on macOS, Shift-drag elsewhere) inside an app that
   * tracks the mouse. It cannot copy a selection an app draws itself, and OSC 52 copies (tmux
   * copy-mode, vim `"+y`) reach the clipboard whether this is on or off. Programmatic selections
   * (find-bar hits) never copy. Read live, so a toggle applies to the next drag on every open
   * terminal. Logic: `renderer/terminal/copy-on-select.ts`.
   */
  copyOnSelect: boolean
  /** ⌘+ / ⌘− / ⌘0 (Ctrl off-mac) change the FOCUSED terminal's own font size instead of doing
   *  nothing / zooming the canvas (issue #915). The size is stored per node
   *  (`CanvasNodeState.terminalFontSize`); ⌘0 clears it back to `fontSize`. OFF by default: off-mac
   *  the chord is Ctrl+−, which a focused terminal passes to the shell today (readline undo). With
   *  it off, and whenever no terminal has focus, the keys behave exactly as before. See
   *  renderer/terminal/terminal-font-zoom.ts. */
  terminalFontZoomKeys: boolean
  /**
   * Windows SSH projects: after a key is unlocked with its passphrase, also load it into the
   * Windows OpenSSH agent service, so later connections (and the user's own `ssh`) do not prompt
   * again. OFF by default because that agent STORES the key — DPAPI-encrypted in
   * `HKCU\Software\OpenSSH\Agent\Keys`, surviving service restarts — until it is removed
   * (`ssh-add -d` / `-D`), and it refuses a lifetime constraint (measured on windows-latest,
   * OpenSSH_for_Windows_9.5p2), so there is no "for this session only". A host whose own
   * `~/.ssh/config` says `AddKeysToAgent yes` gets the add without this switch: that user already
   * asked OpenSSH for exactly this. Logic: `core/remote-ssh/native/agent-add.ts`.
   */
  windowsSshAgentAddKeys: boolean
  /** Plain mouse wheel zooms the canvas (no Cmd/Ctrl needed). On macOS a two-finger trackpad
   *  scroll keeps panning independently (see canvas/wheel-gesture.ts), so mouse and trackpad
   *  coexist; elsewhere this still trades away scroll-to-pan, so it stays opt-in. */
  wheelZoom: boolean
  /** How far one plain wheel click zooms, as a multiplier on the canvas zoom step (0.2–2,
   *  default 1 = historical feel). Applies only to the `wheelZoom` path — Cmd/Ctrl+wheel and
   *  pinch keep the fixed step, so tuning a chunky mouse down never slows the trackpad.
   *  Validated at point of use (canvas/wheel-zoom.ts `clampWheelZoomSpeed`). */
  wheelZoomSpeed: number
  /** macOS only: a two-finger trackpad scroll pans the canvas, independently of `wheelZoom`
   *  (see canvas/wheel-gesture.ts). Off restores the pre-router behavior — `wheelZoom` alone
   *  decides. On the desktop the device is identified from the main process's raw input stream
   *  (main/trackpad-gesture.ts), so mouse zoom and trackpad pan coexist; the off-switch is the
   *  remaining recourse for the Server Edition's browser tab, where detection is heuristic and a
   *  precise-pixel MOUSE still reads as a trackpad. */
  trackpadPan: boolean
  /** What a left-drag on EMPTY canvas does. 'select' (default) rubber-band selects, like
   *  Figma's move tool — pan stays on middle-drag / two-finger scroll. 'pan' drags the map
   *  directly (grab cursor), for mouse users who pan constantly; box-select then moves to
   *  Shift+drag (React Flow's selectionKeyCode). */
  canvasDragMode: 'select' | 'pan'
  /**
   * Browser memory saver: release a browser/web node's page after it has been hidden for
   * `BROWSER_DISCARD_MS` (5 min), reloading it from its URL when it is shown again. Each
   * `<webview>` is a whole Chromium renderer process and the canvas caps nothing, so an
   * afternoon of opened pages is otherwise permanently resident. On by default — the cost is a
   * reload (and the lost back/forward stack, which a webview cannot serialize), not lost work.
   */
  browserMemorySaver: boolean
  accent: string
  tmuxEnabled: boolean
  /**
   * Which multiplexer creates a NEW local terminal's persistent session on POSIX: `tmux` (default)
   * or `zellij`. Hand-editable, so every reader goes through `normalizeSessionBackend`
   * (@shared/session-backend) — anything unknown reads as tmux. A node whose session already
   * lives in one backend keeps reattaching there; Windows and SSH projects ignore it.
   */
  sessionBackend: SessionBackend
  /**
   * Reach a released tmux session with a control-mode (`tmux -C`) client instead of respawning its
   * terminal — the shadow clients in pty-manager.ts (`shadowAttach`) and the shared background-write
   * client behind `backgroundWrite`. A control client holds ZERO pty devices, which is the whole
   * point: the machine-wide `kern.tty.ptmx_max` ceiling is what a canvas of idle terminals runs into
   * first (see pty-devices.ts).
   *
   * ON by default, and read at those two entry points only: switching it off means this process
   * spawns no `tmux -C` child at all, and a released session is simply unreachable again — exactly
   * the behavior of the release before it. It is a kill switch for one soak release, not a feature
   * toggle: nothing user-visible depends on it (the mechanism has no production caller yet), so it
   * has no settings row and is flipped in settings.json.
   */
  ptyShadowClients: boolean
  /** GPU (WebGL) terminal rendering. 'off' routes every terminal to xterm's DOM renderer.
   *  'auto' (default) = one WebGL context PER TERMINAL everywhere except macOS, where it is
   *  'shared'. Repeated macOS field reports (whole-window flicker; terminals compositing black
   *  after renderer swaps, with zero JS-visible errors) point at the OS compositor mishandling
   *  many live WebGL canvases — which is why per-terminal WebGL stays a deliberate opt-in ('on')
   *  there, and why the ONE-context renderer is what macOS defaults to instead. Legacy boolean
   *  values are migrated on load: `false` (an explicit escape-hatch choice) → 'off'; `true`
   *  (indistinguishable from the old merged-in default) → 'auto'.
   *
   *  'shared' is the glyphgrid renderer: instead of one WebGL context per terminal (which is what
   *  the ~16-context cap and the whole budget coordinator exist to ration), every terminal on the
   *  canvas paints into ONE canvas-wide context. Promoted out of experimental on 2026-08-05 after
   *  the device checklist + soak; any failure still drops the session back to xterm's DOM
   *  renderer. See `resolveTerminalRenderer` (shared/webgl.ts) for the full history. */
  terminalGpuRendering: 'auto' | 'on' | 'off' | 'shared'
  tmuxScrollback: number
  /** OPT-IN lead-pane width for Claude Code agent teams (issue #119). 0 = off (default): the
   *  generated tmux confs stay byte-identical to their pre-feature output — no `set-hook` at all.
   *  40–90 = emit guarded after-resize-pane / after-split-window hooks (shared/tmux-lead-pane.ts)
   *  that keep the lead pane at this % of the node width when CC's team backend re-applies its
   *  hardcoded 70/30 split. Hand-editable; re-validated at the conf-generation site
   *  (`sanitizeLeadPaneWidth`). Honest side effect while on: a manual 50/50 split in a plain
   *  terminal node is nudged to the target too. */
  tmuxLeadPaneWidth: number
  /** Minutes a terminal may sit fully offscreen before its xterm+PTY client is torn down in
   *  place (tmux keeps the session; re-approach reattaches and redraws). 0 = never. */
  offscreenTerminalMinutes: number
  /** Minutes a terminal stays PARKED after its project is switched away — xterm + PTY client kept
   *  alive off-DOM so switching back is instant and exact (no reattach). 0 = until the app quits.
   *  Default 10. Hand-editable; re-validated at the use site (`parkWindowMs`). Issue #886. */
  terminalParkMinutes: number
  /** Max parked terminals across all projects before the oldest (local first, then remote) are
   *  released early. Default 20. Re-validated at the use site (`parkCap`). Issue #886. */
  terminalParkMax: number
  /** AI commit message agent: a local coding-agent CLI run read-only. */
  commitAgent: 'claude' | 'codex' | 'custom'
  /** For commitAgent='custom': command template; {prompt} placeholder optional (else stdin). */
  commitAgentCommand: string
  /** Extra instructions appended to the commit prompt (e.g. Conventional Commits). */
  commitExtraPrompt: string
  /** Whether the shortcuts overlay has been shown on first launch. */
  seenShortcuts: boolean
  /** Whether the first-run setup tour (onboarding) has been completed or skipped. Existing
   *  installs (seenShortcuts already true) are migrated to true silently — the tour is for
   *  fresh installs; rerunnable via the ⌘K "Setup tour" command. */
  seenOnboarding: boolean
  /** Notify (OS notification) when a Claude Code turn finishes while the app is in the background. */
  notifyOnClaudeDone: boolean
  /** Periodically `git fetch` while the Source Control panel is open, so ahead/behind stays
   *  accurate (remote/SSH projects fetch on the remote). */
  gitAutoFetch: boolean
  /** Whether the one-time notification consent prompt has been shown. */
  notifyConsentAsked: boolean
  /** Play a retro sound effect when a turn finishes / a session needs you (renderer/lib/sfx.ts).
   *  Unlike OS notifications this fires whether or not the window is focused — the point is to
   *  catch a finish while you're looking at ANOTHER node. Throttled per node. */
  soundEffects: boolean
  /** Sound-effect volume, 0..1. */
  soundVolume: number
  /** User-picked replacements for the built-in chimes, per alert kind (issue #289). Holds only a
   *  display name + a stamp — the FILE lives in the core's data dir (`<userData>/sounds/`), never
   *  at the user's original path. Read through `customAlertSoundFor` (hand-editable JSON); an
   *  absent/malformed entry, or a file that is gone or will not decode, plays the built-in chime. */
  customAlertSounds: CustomAlertSounds
  /** User-defined agents (BYO CLI) appended to the Add menus. */
  customAgents: CustomAgent[]
  /** One gateway root + non-secret credential reference used by model-switch-capable harnesses. */
  modelGateway: ModelGatewaySettings
  /** The default gateway model id (from discovery) applied to a fresh canvas agent spawn when
   *  `agentLaunchMode === 'gateway-model'`. A separate field from `modelGateway` (it is NOT a
   *  credential). Absent/empty = no default ⇒ `'gateway-model'` behaves like `'gateway'`. */
  modelGatewayDefaultModel?: string
  /** Per-builtin-agent launch command overrides (Settings → Agents → Launch commands). The value
   *  replaces the bare CLI name everywhere a launch line is built — new sessions, cold-restore
   *  relaunches and in-place restarts, with the usual flags (`--resume`, `--permission-mode`, the
   *  prompt) appended after it — so a wrapper script that picks an account or sets env vars runs
   *  wherever the agent would. Empty/absent = the builtin default, byte-identical to before this
   *  setting existed. Keyed by builtin id only: custom agents already own their `launchCmd`. */
  agentLaunchCommands: Partial<Record<BuiltinAgentId, string>>
  /** Managed Claude accounts (config-dir isolated). See ClaudeAccount. */
  claudeAccounts: ClaudeAccount[]
  /** Managed Codex accounts (CODEX_HOME isolated, machine-scoped by `host`). See CodexAccount.
   *  Renderer-owned in settings.json exactly like `claudeAccounts`; main owns only fs lifecycle. */
  codexAccounts: CodexAccount[]
  /** Custom display label for the SYSTEM Claude account (~/.claude) in pickers/settings.
   *  Empty = unset → fall back to the detected login email, else "System account". */
  systemAccountLabel: string
  /** Agent ids hidden from the Add menus. */
  disabledAgents: AgentId[]
  /** Usage providers hidden from the pill + popover (Settings → Usage toggles). Hiding is a
   *  DISPLAY choice — credentials and fetchers are untouched, so re-enabling is instant. */
  hiddenUsageProviders: string[]
  /** Ids of node right-click menu rows the user has hidden; empty = everything visible. Only ids
   *  in HIDEABLE_MENU_ITEMS (renderer/lib/ui-visibility.ts) can hide — Delete and the other
   *  recovery actions stay put whatever this array says. */
  hiddenNodeMenuItems: string[]
  /** Ids of terminal node header buttons the user has hidden; empty = everything visible. Gated by
   *  HIDEABLE_HEADER_BUTTONS the same way. */
  hiddenHeaderButtons: string[]
  /** Whether project activation offers the "Resume where you left off" card (breadcrumb trail's
   *  once-per-app-run popup). OFF by default — it interrupts every project switch, so it is
   *  opt-in. Cmd+[ / Cmd+] and the Dock buttons walk the trail regardless of this. */
  showResumeCard: boolean
  /** Draw the canvas dot grid (Settings → Appearance). Display only — snapping and align-to-grid
   *  are unchanged. Default ON in every appearance; read through `showCanvasDots`. */
  canvasDots: boolean
  /** Pulse the RUNNING chip on board cards (Settings → Appearance). Off = the same chip, held still.
   *  The node header's mascot is not affected. Default ON; read through `pulseBoardRunning`, so only
   *  a literal false stops it. */
  boardRunningPulse: boolean
  /** The Liquid Glass slider (Settings → Appearance), 0 = Clear … 1 = Tinted. null = the Readable
   *  tick, where text keeps 4.5:1 (renderer/lib/glassContrast.ts `resolveGlassSlider`). */
  glassTint: number | null
  /** Liquid Glass: keep the node blur and refraction live while the canvas pans or zooms (Apple's
   *  behaviour, more GPU). Off = the blur pauses during a camera move and the tint alone stays.
   *  Default ON; only a literal false turns it off (`keepGlassBlurWhileMoving`). */
  glassBlurWhileMoving: boolean
  /** Whether usage percentages render as consumed ("32% used"), remaining ("68% left"), or raw
   *  token counts ("48k/200k tokens" — context-window surfaces only; provider quota surfaces
   *  have no token counts and fall back to 'used' display). 'remaining' is the historical
   *  default; users coming from other tools expect 'used'. */
  usagePercentMode: 'used' | 'remaining' | 'tokens'
  /** Which agent the ⌘⇧C shortcut / quick-add launches. Always a launchable builtin. */
  defaultAgent: AgentId
  /** The permission mode Claude TERMINAL (CLI) sessions START in — passed as `--permission-mode`
   *  at launch; Shift+Tab still cycles modes at runtime. SDK chat nodes are NOT covered (the chat
   *  driver runs in `default`). Overridable per project via Project.defaultPermissionMode.
   *  `auto` is version-gated: CLIs below 2.1.71 reject the value, so it degrades to no flag. */
  claudePermissionMode: AgentPermissionMode
  /**
   *  When on, EVERY fresh agent launch spawns with gateway + inherited provider env stripped, so the
   *  agent runs against its OWN default provider (Claude's subscription, Copilot's GitHub routing)
   *  instead of a configured gateway/inherited override. The per-node one-shot `data.clearEnv`
   *  (cleared after its single recycle) is the per-node action; this is its global counterpart.
   *  Default OFF — opt-in, because it changes which provider every agent node uses. Does NOT strip
   *  `CLAUDE_CONFIG_DIR` (account isolation survives). See `vanillaEnvStripPattern`.
   */
  vanillaLaunchDefault: boolean
  /** The default provider behavior for a fresh agent spawn (the three-way successor to
   *  `vanillaLaunchDefault`). See `AgentLaunchMode`. Default `'gateway'` = today's behavior. */
  agentLaunchMode: AgentLaunchMode
  /** "Eco": exit the agent CLI of a session that has been idle AND offscreen for
   *  `agentHibernationIdleMinutes`, reclaiming its RAM; the conversation is resumed automatically
   *  when the node is viewed again. Default OFF — opt-in, because it stops a real process.
   *  Scheduled/loop agents and sessions with live subagents are never touched
   *  (renderer/terminal/hibernation-policy.ts explains why). */
  agentHibernationEnabled: boolean
  /**
   * Agent messaging for a project whose `.nodeterm/project.json` carries NO `agentMessaging` value
   * (@shared/project-capabilities, CAPABILITY_MACHINE_DEFAULTS). MACHINE-LOCAL on purpose: it is
   * this machine's user deciding for their own unconfigured projects, which is why it may answer
   * without a clone notice — while an explicit `true` in a cloned file still needs one, and an
   * explicit `false` still wins. Read strictly (`=== true`). Never settable from the canvas CLI
   * (@shared/settings-verb forbids it): it is a grant over every project at once.
   */
  agentMessagingDefault: boolean
  /** How long a session must be idle + offscreen before "Eco" hibernates it (minutes). */
  agentHibernationIdleMinutes: number
  /** When Eco hibernates a session, also mark it PAUSED (see `AgentNodeStatus.paused`) so it does
   *  NOT auto-resume the next time the project or app reopens — only an explicit Resume brings it
   *  back. Off by default: ordinary Eco already resumes automatically on the next reveal, and this
   *  opts a hibernated session OUT of that for good, trading convenience for a colder, smaller
   *  footprint across restarts. Independent of manual "Pause session", which always persists this
   *  way regardless of this setting. */
  agentHibernationPersistAcrossRestart: boolean
  /** Send anonymous usage data: the version/OS telemetry ping, and the open-project count on the
   *  /v1/check call (`openProjects`, a number only — never names, paths or hosts). Opt-OUT
   *  (default on): nothing personal, client IP never stored. Turn it off in Settings → Privacy
   *  (or hard-disable with DO_NOT_TRACK / NODETERM_TELEMETRY_DISABLED). Note: a lighter anonymous
   *  install count also rides the /v1/check call and is NOT gated on this toggle — see core/check.ts. */
  telemetryEnabled: boolean
  /** The user's consent to license and free-project-allowance calls to api.nodeterm.dev while
   *  DO_NOT_TRACK / NODETERM_TELEMETRY_DISABLED is set. Default off: under DNT nothing
   *  license-related leaves the machine until the user says so. Covers ONLY the calls behind
   *  `licenseNetworkGate()` (core/license.ts) — never telemetry or the check feed, which stay off
   *  under DNT whatever this says. Read as `=== true` (main installs it via
   *  `setLicenseNetworkConsent`), so a hand-edited non-boolean is no consent. Shown and revocable in
   *  Settings → Privacy only while DNT is set. Never settable by an agent (SETTINGS_VERB_FORBIDDEN). */
  licenseNetworkConsent: boolean
  /** Debug log panel (issue #78): captures the app's own console into an in-memory, redacted
   *  ring and unlocks the log viewer. Default off — a debugging tool, not a daily surface.
   *  Toggle in Settings → Application → Debug. */
  debugLogPanel: boolean
  /** Keep a standing relay host connection so a paired phone can reach this Mac from anywhere
   *  (end-to-end encrypted). Default on — the host only admits SAS-approved, pinned devices, so
   *  an un-paired install just keeps an idle listener. Toggle in Settings → Phone. */
  phoneAccessEnabled: boolean
  /** Send APNs push notifications to relay-paired phones when an agent needs approval, asks a
   *  question, or finishes a turn (spec: apns-push). Default on — it only fires for users who
   *  have paired a phone. Toggle in Settings → Notifications. */
  mobilePushEnabled: boolean
  /** Push when an agent needs you: approval requests + questions. Default on. Sub-gate under
   *  `mobilePushEnabled` (the master switch). Toggle in Settings → Notifications. */
  mobilePushNeedsYou: boolean
  /** Push when an agent finishes a turn (the `done` kind). Default on. Sub-gate under
   *  `mobilePushEnabled` (the master switch). Toggle in Settings → Notifications. */
  mobilePushDone: boolean
  /** Stream live status updates to paired phones as a session's state + activity + context%
   *  change — an iOS Live Activity (Lock Screen / Dynamic Island) or an Android ongoing
   *  notification (spec: interactive-push-live-activities). Default on. The KEY keeps its
   *  iOS-era name because it is persisted in settings.json; the UI calls it "Live updates on
   *  phone". Sub-gate under `mobilePushEnabled` (the master switch). Toggle in Settings →
   *  Notifications. */
  mobileLiveActivities: boolean
  /** Hold phone ALERTS while you're actively at this computer, releasing them when you go idle or
   *  lock the screen (spec: presence-aware-push). Default on. Desktop-only (the Server Edition is
   *  headless, so it always sends); the live-update stream is never held. Sub-gate under
   *  `mobilePushEnabled`. Off ⇒ alerts always send immediately (legacy). Toggle in Settings →
   *  Notifications. */
  mobilePushPresenceAware: boolean
  /** Deterministic hook-reply approvals (spec: docs/hook-reply-approvals.md). When on (default),
   *  Claude terminal sessions launch with `NODETERM_PERM_WAIT_SECS` set: the managed permission
   *  hook holds briefly for a phone/canvas Approve/Deny before falling through to the normal
   *  interactive prompt. Off ⇒ the env var is absent ⇒ exact legacy behavior. Claude-only. */
  hookReplyApprovals: boolean
  /** Remove a subagent's ephemeral canvas card the moment that subagent REPORTS finished, instead
   *  of keeping it until the parent agent's next turn clears it. Default off ⇒ exact legacy
   *  behavior. A card whose subagent is still running is never removed by this, and neither is one
   *  the stale decay marked done because its end never arrived. Settings → Agents. */
  autoHideFinishedSubagentCards: boolean
  /** Hold an idle-sleep power assertion while a LOCAL agent node is working, so long runs
   *  survive an unattended laptop. Released when the last one stops (or goes stale). Cannot
   *  hold through a closed lid. Asked in the setup tour; Settings → Behavior. */
  keepAwakeWhileAgentsWork: boolean
  /** Ask before the app actually quits (⌘/Ctrl+Q, menu Quit, or the Windows/Linux title-bar ×).
   *  The auto-update "Restart to update" flow never asks — that decision was already made.
   *  Settings → Behavior. */
  confirmBeforeQuit: boolean
  /** Windows/Linux "background mode": closing the window hides it to the notification-area tray
   *  instead of quitting, so the phone relay host, hook server, notifications and updater keep
   *  running — the analogue of macOS keeping the app in the Dock. `'auto'` (default) = on for
   *  Windows, off for Linux (whose tray support depends on the desktop environment). Resolved by
   *  `resolveBackgroundOnClose` (src/main/background-mode.ts); ignored on macOS (always hides) and
   *  on the Server Edition (no window). Hand-editable: an unknown value reads as `'auto'`.
   *  Settings → Behavior (Windows/Linux only). */
  runInBackgroundOnClose: BackgroundOnCloseSetting
  /** macOS Notch HUD (docs/notch-hud.md): a transparent always-on-top strip by the notch showing
   *  walking agent mascots while agents work, expanding into a mini session panel. Default on;
   *  macOS + desktop only (ignored on other platforms / Server Edition). */
  notchHud: boolean
  /** Assumed physical notch width in px. macOS exposes no API for it (Electron has no
   *  `auxiliaryTopLeftArea`), so the capsule has to assume one — this is the knob that makes it sit
   *  flush on YOUR Mac. Bigger = the capsule sits further left. */
  notchWidth: number
  /** Which side of the primary display the capsule sits on. `center` (default) hugs the physical
   *  notch; `left` / `right` draw a floating pill at that edge. Re-validated at use
   *  (`sanitizeNotchAlign`, shared/notch-hud.ts): an unknown string means `center`. */
  notchAlign: NotchAlign
  /** Vertical offset of the capsule from its resting place, px, positive = DOWN. Up is bounded by
   *  the display's top edge (the fused notch capsule is already there, so it only moves down —
   *  and moving it detaches it into a pill). Clamped to NOTCH_OFFSET_MIN/MAX; non-finite → 0. */
  notchOffsetY: number
  /** Expand the notch panel on hover (after a short dwell). Off = click the capsule to expand. */
  notchHoverExpand: boolean
  /** Dictation (desktop/server). Written as a whole object by the renderer. */
  speech: SpeechSettings
  /** Keyboard-shortcut overrides by command id (see shared/keybindings.ts). Absent id = the
   *  command's default bindings; `[]` = disabled. Hand-editable; invalid or conflicting
   *  entries are dropped with a console warning at read time (sanitizeKeybindingOverrides).
   *  Optional and deliberately not in DEFAULT_SETTINGS: absent simply means "no overrides". */
  keybindings?: KeybindingOverrides
  /** Who wins while a terminal has keyboard focus: 'app-first' (default) lets allowInTerminal
   *  app commands fire over an xterm; 'terminal-first' reserves every chord but the terminal's
   *  own (find, copy) for the shell/TUI — including ⌘W/⌘M and the zoom/project-jump gestures. */
  terminalShortcutPolicy: TerminalShortcutPolicy
  /** Command ids whose "this chord was captured from your terminal" notice has been shown
   *  (app-first only, once per command). Optional and absent from DEFAULT_SETTINGS: absent
   *  means none seen. Lives in settings, not localStorage, so Server Edition shares it. */
  seenShortcutCaptureNotices?: string[]
  /** Per-node hook identity enforcement (src/core/agents/node-identity-policy.ts).
   *
   *  One of the three optional keys in this interface, and deliberately so: it is a TRI-state, and the two
   *  non-default states are opposite escape hatches. Absent (the default — it is not in
   *  DEFAULT_SETTINGS) follows `NODE_IDENTITY_STRICT_AFTER`, so the rollout has one schedule for
   *  everybody. `true` opts in to strict enforcement before that date. `false` keeps the warning
   *  window open past it and releases the trust-on-first-proof latch, so a user whose upgrade
   *  strands a live session gets their canvas back without downgrading the app. Neither value ever
   *  admits a forged token. */
  hookIdentityStrict?: boolean
  /** Agent-integration consent (issue #744, `@shared/agent-integrations`): which agents nodeterm
   *  may integrate with by writing into their user-owned global config (status hooks, skills),
   *  here and per SSH host. Optional and absent from DEFAULT_SETTINGS: absent = a new install that
   *  has not been asked, which writes NOTHING. Hand-editable, so every reader sanitizes. */
  agentIntegrations?: AgentIntegrationsSettings
  /** Machine-local waivers for the canvas-control destructive confirm dialog
   *  (@shared/control-confirm). Absent — and absent from DEFAULT_SETTINGS — means "always ask",
   *  which is the pre-feature behavior bit for bit.
   *
   *  MACHINE-LOCAL BY CONSTRUCTION, and the reason is the trap this closed: a permission mode
   *  rides `.nodeterm/project.json` and is git-shared, so anything keyed on the mode alone could
   *  be turned off for a user by a repository they cloned. A waiver is a statement about this
   *  machine's trust in its own agents, so it lives here and NEVER in a project file. */
  controlConfirmWaivers?: ControlConfirmWaivers
  /** Machine-local: move a session card to a column once every pull request linked to it has
   *  merged (@shared/kanban-pull-links — why this is here and never in the project file). Absent —
   *  and absent from DEFAULT_SETTINGS — means off everywhere. Read through
   *  `sanitizeKanbanPullAutoMove`: settings.json is hand-editable. */
  kanbanPullAutoMove?: KanbanPullAutoMove
  /** Machine-local board dispatch: which projects start an agent run when this person moves a
   *  GitHub issue card into a chosen column, with which agent and how many at once, plus the kill
   *  switch (@shared/board-dispatch — why this is here and never in the project file). Absent —
   *  and absent from DEFAULT_SETTINGS — means off everywhere. Read through
   *  `sanitizeBoardDispatch`: settings.json is hand-editable. */
  boardDispatch?: BoardDispatch
}

export const DEFAULT_SETTINGS: Settings = {
  fontSize: 13,
  fontFamily: 'Menlo, Monaco, "Courier New", monospace',
  // Keep hyphens, underscores, slashes and dots inside words so identifiers and paths select whole.
  terminalWordSeparator: " ()[]{}',\"",
  cursorBlink: true,
  // Every appearance default below reproduces the pre-feature look bit-for-bit: the default theme
  // carries the old hardcoded background/foreground, and block/outline/1/0 are xterm's own
  // defaults. Picking a theme is opt-in — an update must not repaint anybody's terminals.
  // Follows the terminal theme, whose own default is dark — so an install that never touches
  // either setting keeps the dark chrome it has always had.
  appTheme: 'auto',
  uiScale: 1,
  windowTitleActiveSession: false,
  terminalTheme: 'nodeterm-dark',
  desktopWallpaper: { kind: 'none' },
  recentWallpaperImage: null,
  fontWeight: 400,
  fontWeightBold: 700,
  drawBoldTextInBrightColors: true,
  terminalMinContrast: 1,
  cursorStyle: 'block',
  cursorInactiveStyle: 'outline',
  terminalLineHeight: 1,
  terminalLetterSpacing: 0,
  defaultShell: '',
  gridSize: 24,
  snapToGrid: false,
  autoAlignGrid: false,
  tabBarHeight: TABBAR_HEIGHT_PX,
  stickyNoteBacking: 0,
  groupFrameBacking: 0,
  markdownFontFamily: DEFAULT_MARKDOWN_FONT_FAMILY,
  markdownFontSize: DEFAULT_MARKDOWN_FONT_SIZE,
  defaultNodeWidth: 640,
  defaultNodeHeight: 440,
  defaultNodeSizes: {},
  sidebarAutoCollapse: true,
  sidebarCollapsedItems: {},
  sidebarGrouping: 'project',
  defaultProjectView: 'canvas',
  omniKanbanEnabled: false,
  omniKanbanAsDefault: false,
  worktreePathTemplate: DEFAULT_WORKTREE_PATH_TEMPLATE,
  newProjectStorage: 'folder',
  panHoverDelay: 600,
  terminalFocusFollowsPointer: true,
  doubleClickFocus: true,
  focusZoomToNode: true,
  offerCloseProjectOnLastSession: false,
  rememberCanvasLock: false,
  allowOpenLinks: false,
  openMarkdownPreview: true,
  openMarkdownPreviewMigrated: true,
  terminalMiddleClickPaste: false,
  copyOnSelect: false,
  terminalFontZoomKeys: false,
  windowsSshAgentAddKeys: false,
  wheelZoom: false,
  wheelZoomSpeed: 1,
  trackpadPan: true,
  canvasDragMode: 'select',
  browserMemorySaver: true,
  accent: '#0a84ff',
  tmuxEnabled: true,
  sessionBackend: 'tmux',
  ptyShadowClients: true,
  terminalGpuRendering: 'auto',
  tmuxScrollback: 50000,
  tmuxLeadPaneWidth: 0,
  offscreenTerminalMinutes: 10,
  terminalParkMinutes: 10,
  terminalParkMax: 20,
  commitAgent: 'claude',
  commitAgentCommand: '',
  commitExtraPrompt: '',
  // 'app-first' reproduces today's dispatch bit-for-bit: allowInTerminal app commands keep
  // firing over a focused xterm. Opting into 'terminal-first' is the user's call, never ours.
  terminalShortcutPolicy: 'app-first',
  seenShortcuts: false,
  seenOnboarding: false,
  notifyOnClaudeDone: true,
  gitAutoFetch: true,
  notifyConsentAsked: false,
  soundEffects: true,
  soundVolume: 0.5,
  customAlertSounds: {},
  customAgents: [],
  modelGateway: { baseUrl: '', apiKey: '' },
  // No default gateway model until the user picks one in Settings → Model gateway. Absent ⇒
  // `'gateway-model'` behaves like `'gateway'` (no --model on a fresh spawn).
  modelGatewayDefaultModel: undefined,
  agentLaunchCommands: {},
  claudeAccounts: [],
  codexAccounts: [],
  systemAccountLabel: '',
  // All three builtin agents (Claude/Codex/Gemini) show in the Add menus out of the box.
  // Existing users keep whatever they've saved (their persisted disabledAgents overrides this).
  disabledAgents: [],
  hiddenUsageProviders: [],
  // Nothing hidden out of the box, so existing users see the menu and header they already know.
  hiddenNodeMenuItems: [],
  hiddenHeaderButtons: [],
  // Opt-in: the resume card pops over the canvas on every qualifying project activation, which
  // reads as noise to users who navigate by the trail chords/Dock buttons instead.
  showResumeCard: false,
  canvasDots: true,
  boardRunningPulse: true,
  glassTint: null,
  glassBlurWhileMoving: true,
  usagePercentMode: 'remaining',
  defaultAgent: 'claude',
  // Sessions start in auto mode out of the box. Existing users pick this up on hydrate
  // (settings hydrate merges over DEFAULT_SETTINGS) — a deliberate behavior change.
  claudePermissionMode: 'auto',
  // Opt-in: strips the gateway/inherited provider env on every fresh launch so agents run against
  // their own default provider. Off by default — changes which provider every agent node uses.
  vanillaLaunchDefault: false,
  // The three-way successor to the boolean above. `'gateway'` = inject gateway env, CLI default
  // model (today's behavior). `vanillaLaunchDefault` is now its migration mirror.
  agentLaunchMode: 'gateway',
  // Opt-in: hibernation exits a live CLI, so nobody gets it without asking. The 30-minute floor
  // is deliberately long — shorter windows exit sessions the user is between turns on.
  agentHibernationEnabled: false,
  // OFF until the cross-restart pane-ownership proof lands: messaging refuses every pane that
  // survived an app restart (core/agents/pane-ownership.ts), so "on by default" would be false
  // after every restart and every update. Flipping this is a separate, deliberate change.
  agentMessagingDefault: false,
  agentHibernationIdleMinutes: 30,
  agentHibernationPersistAcrossRestart: false,
  // Opt-out (default on). Existing users pick this up on hydrate ONLY if their settings.json has
  // no telemetryEnabled key yet; anyone who already saved settings keeps their stored value.
  telemetryEnabled: true,
  // Off: under DO_NOT_TRACK no license call runs until the user consents in Settings → Privacy.
  licenseNetworkConsent: false,
  debugLogPanel: false,
  phoneAccessEnabled: true,
  mobilePushEnabled: true,
  mobilePushNeedsYou: true,
  mobilePushDone: true,
  mobileLiveActivities: true,
  mobilePushPresenceAware: true,
  // Deterministic hook-reply approvals default ON (existing users pick it up on hydrate). Only
  // affects Claude terminal sessions; off reproduces the pre-feature launch bit-for-bit.
  hookReplyApprovals: true,
  autoHideFinishedSubagentCards: false,
  // Keep-awake-while-agents-work default ON (existing users pick it up on hydrate — deliberate,
  // same note style as hookReplyApprovals). Held only while a local agent is actually working.
  keepAwakeWhileAgentsWork: true,
  // Confirm-before-quit default ON: sessions survive a quit anyway, but an accidental ⌘Q
  // tears down every window at once; the toggle is one switch away for who finds it noisy.
  confirmBeforeQuit: true,
  // Background mode 'auto' = on for Windows (the tray is always there), off for Linux.
  runInBackgroundOnClose: 'auto',
  // macOS Notch HUD default ON (guarded to darwin at runtime; a no-op elsewhere).
  notchHud: true,
  notchWidth: 168,
  notchAlign: 'center',
  notchOffsetY: 0,
  notchHoverExpand: true,
  // model: '' = the explicit "no dictation" state (SPEECH_MODEL_NONE, issue #143). Dictation is
  // opt-in: nothing is selected — and so nothing downloads and no shortcut records — until the
  // user picks a model in onboarding or Settings → Speech. Existing installs keep whatever their
  // settings.json already says (the merge only fills ABSENT keys), so nobody's working dictation
  // is switched off by an upgrade.
  speech: { engine: 'whisper', model: '', language: 'auto', shortcut: 'Cmd+Alt' },
}

export interface SettingsApi {
  load(): Promise<Settings>
  save(settings: Settings): Promise<void>
}

/** Agent-integration consent status (issue #744). The CHOICE rides `settings.agentIntegrations`;
 *  this only reports what the host's last reconcile did. */
export interface IntegrationsApi {
  status(): Promise<import('./agent-integrations').AgentIntegrationsStatus>
}

/** A downloadable whisper model plus its on-disk status, as returned by `speech.models()`. */
export interface SpeechModelInfo extends WhisperModelInfo {
  downloaded: boolean
  /** Actual on-disk size in MB, present only when `downloaded`. */
  sizeMB?: number
}

export interface SpeechApi {
  /** Transcribe a chunk of mono PCM audio (16kHz Float32 samples) to text.
   *  `language` is a BCP-47-ish hint or 'auto'; defaults to the user's speech settings. */
  transcribe(pcm: Float32Array, language?: string): Promise<{ text: string }>
  /** List the known whisper models with their download/pro status. */
  models(): Promise<SpeechModelInfo[]>
  /** Download a whisper model to disk (progress via `onProgress`). */
  downloadModel(id: string): Promise<void>
  /** Delete a downloaded whisper model. */
  deleteModel(id: string): Promise<void>
  /** Subscribe to model-download progress (`pct` 0-100). Returns unsubscribe. */
  onProgress(cb: (p: { id: string; pct: number }) => void): () => void
  /** Ask for microphone permission. Electron: OS-level (macOS TCC prompt); browser: always
   *  resolves true — the browser's own getUserMedia prompt is not ours to gate. */
  micConsent(): Promise<boolean>
  /** Open the OS microphone-privacy page (Windows `ms-settings:privacy-microphone`, macOS System
   *  Settings). Desktop only — ABSENT in the browser bridge (a browser's mic permission lives in
   *  its own site settings), and the overlay hides its button when absent. Resolves false where
   *  the OS has no such page. */
  openMicSettings?(): Promise<boolean>
}

export interface SshApi {
  list(): Promise<import('./ssh').SshServer[]>
  save(server: import('./ssh').SshServer): Promise<import('./ssh').SshServer[]>
  remove(id: string): Promise<import('./ssh').SshServer[]>
  /** Parse `~/.ssh/config` into importable hosts (empty if none). */
  importCandidates(): Promise<import('./ssh').ParsedSshHost[]>
}

export type SshProjectStatus = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error'

/**
 * A live SSH project's status, pushed from main. `claudeAutoPermissionMode` rides a `connected`
 * event: the remote `claude --version` probe runs AFTER connect (its login shell is slow and must
 * not delay the project's terminals), so the answer arrives on its own event once it lands.
 * Absent = not probed / nothing new ⇒ the renderer keeps omitting the `auto` flag (fail-open).
 */
export interface SshProjectStatusEvent {
  /** Hook-only health update; it does not imply an SSH reconnect or terminal restart. */
  hookTunnelVerified?: boolean
  projectId: string
  status: SshProjectStatus
  error?: string
  /**
   * The ControlMaster socket path, published the MOMENT `ssh -O check` answers — i.e. while the
   * status is still `connecting`, before the connect's remote setup chain (hook tunnel + per-agent
   * hook installs, `$HOME`, the remote tmux.conf write, the Codex runtime staging) has run.
   *
   * ADDITIVE, and deliberately not a new status value: `connected` keeps its exact meaning (the
   * whole chain finished), and everything hanging off it — git routing, the remote claude probe,
   * the tunnel resync, the connection banner — is untouched. This field only lets a terminal whose
   * remote tmux session ALREADY EXISTS stop waiting: `new-session -A` then merely attaches, and
   * the remote `-f` config and the tmux `-e` pairs are read at session CREATION only. A node whose
   * session does not exist (or could not be read) must still wait for `connected`, or it would
   * create a session with no hook env and lose its agent-status badges — see
   * `PtyApi.remoteSessionConfirmed`.
   *
   * Never emitted for an ADOPTED live-orphan master: that one can still be torn down and rebuilt
   * inside the same connect (the stale reverse-forward cure), which would kill a terminal that had
   * already attached over it.
   */
  masterControlPath?: string
  claudeAutoPermissionMode?: boolean
  /** The remote `claude --version` output the probe read, riding the same `connected` event as
   *  `claudeAutoPermissionMode`. `null` = the probe ran but found no claude (distinguishable from
   *  "old CLI" in the tab-menu hint); absent = nothing new. */
  remoteClaudeVersion?: string | null
  /** Does THIS HOST's `codex` accept `--no-daemon` (probed after connect, `codex --help` through
   *  the login shell)? Keyed by `sshHostKey` because it is a fact about the host's binary, not the
   *  project. Only `supported: true` puts the flag on a remote Codex launch — see
   *  shared/agents/codex-daemon.ts. Absent = nothing new. */
  remoteCodexNoDaemon?: RemoteCodexNoDaemon
}

/** A host's answer to "does its `codex` accept `--no-daemon`?" — see `SshProjectStatusEvent`. */
export interface RemoteCodexNoDaemon {
  hostKey: string
  supported: boolean
}

/** main → renderer: this SSH identity file needs its passphrase (the ssh-agent doesn't hold the
 *  key, or the last answer was wrong). `retry` distinguishes "that passphrase didn't work" from
 *  a first ask. */
export interface SshPassphraseRequest {
  requestId: string
  identityFile: string
  retry: boolean
  /** `user@host` the unlock is for, when main could attribute the prompt to a connection. One key
   *  can serve several servers, and the prompt can fire from the watchdog long after any connect
   *  dialog closed. Absent when the asking master could not be identified (adopted orphan). */
  target?: string
}

export interface SshProjectApi {
  /** Open (or reuse) the ControlMaster for an SSH project; resolves once connected. */
  connect(
    projectId: string,
    server: import('./ssh').SshConnection,
    remoteCwd?: string
  ): Promise<{
    controlPath: string
    hookEndpointPath?: string
    tmuxConfPath?: string
    remoteHome?: string
    /** Whether the REMOTE host's claude CLI accepts `--permission-mode auto` (probed on connect). */
    claudeAutoPermissionMode?: boolean
    /** The probed remote `claude --version` output (`null` = probe failed; only on reused conns). */
    remoteClaudeVersion?: string | null
    /** The host's `--no-daemon` answer, when a probe already ran on this connection (reused conns). */
    remoteCodexNoDaemon?: RemoteCodexNoDaemon
  }>
  /** Tear down the master (remote tmux is unaffected). */
  disconnect(projectId: string): Promise<void>
  /**
   * End the given terminal nodes' REMOTE tmux sessions over the project's live master.
   * Authoritative teardown on project delete: works regardless of whether the nodes are
   * mounted, and must be awaited BEFORE disconnect (which kills the master). `nodeIds` are
   * raw node ids; main maps them to `nt-<id>` session names.
   *
   * `everySocket` widens the kill to every tmux socket on the host rather than the `node-terminal`
   * one an SSH project spawns on (shared with a nodeterm running ON the host). Opt-in for ONE
   * caller — the session-memory panel, whose rows are swept off both sockets. Project deletion
   * stays narrow: the legacy `nodeterm-rmt` holds only what an older build left behind.
   */
  killSessions(
    projectId: string,
    nodeIds: string[],
    opts?: { everySocket?: boolean }
  ): Promise<void>
  /** List remote sub-directories of `path` (default ~). */
  listDir(projectId: string, path: string): Promise<{ path: string; dirs: string[] }>
  /** Create a remote directory (mkdir -p). Resolves false when not connected or the mkdir fails. */
  mkdir(projectId: string, path: string): Promise<boolean>
  /**
   * Upload a local file to the remote over the project's ControlMaster, into
   * `<remoteHome>/.nodeterm/uploads/<token>/<fileName>`. Resolves the ABSOLUTE remote path on
   * success, or null on any failure (not connected, unresolved remote home, mkdir/scp failure).
   */
  uploadFile(projectId: string, localPath: string, fileName: string): Promise<string | null>
  /**
   * Pull a remote file (or, with a directory, the whole tree) down to this machine over the
   * project's ControlMaster, into the OS Downloads folder unless `destDir` names another one.
   * The DESTINATION is built in main (`app.getPath('downloads')` + the remote basename, collision-
   * resolved) — the renderer only ever names the remote side, so no renderer string reaches the
   * local write path. Never throws: a failure resolves `{ ok: false, error }`.
   */
  downloadFile(projectId: string, remotePath: string, destDir?: string): Promise<DownloadResult>
  onStatus(cb: (e: SshProjectStatusEvent) => void): () => void
  /** The user's answer to a passphrase prompt (null on cancel). */
  submitPassphrase(requestId: string, value: string | null): Promise<void>
  onPassphraseRequest(cb: (e: SshPassphraseRequest) => void): () => void
  /** Main expired a pending passphrase request; close its dialog if it is still showing. */
  onPassphraseDismiss(cb: (e: { requestId: string }) => void): () => void
}

/** Outcome of a file download (SSH pull). `localPath` is the absolute path actually written —
 *  collision resolution may have renamed it (`notes.md` → `notes (2).md`). */
export type DownloadResult =
  | { ok: true; localPath: string; dir: boolean }
  | { ok: false; error: string }

/** A one-shot HTTP download ticket (Server Edition). `url` is same-origin and carries the token;
 *  the browser does the transfer natively, so nothing streams through the WS bridge. */
export interface DownloadTicket {
  url: string
  /** Filename the download will land under (a directory becomes `<name>.tar.gz`). */
  name: string
}

/**
 * SSH-project Explorer/Editor filesystem API: the same `FsApi` contract scoped to a project,
 * proxied over the project's ControlMaster (renderer → `sshFs:*` IPC → main `SshFs`). The renderer
 * `sshFs(projectId)` helper closes over `projectId` to expose a plain `FsApi`. Fails open
 * ([]/''/false) when the project is not connected.
 */
export interface SshFsApi {
  list(projectId: string, path: string): Promise<DirEntry[]>
  read(projectId: string, path: string): Promise<string>
  readBinary(projectId: string, path: string): Promise<string>
  write(projectId: string, path: string, content: string): Promise<boolean>
  mkdir(projectId: string, path: string): Promise<boolean>
  exists(projectId: string, path: string): Promise<boolean>
  /** ⌘K Quick Open index of the project's remoteCwd: root-relative `/`-paths ([] on failure). */
  quickOpen(projectId: string, cwd: string): Promise<string[]>
}

export interface GitFileChange {
  path: string
  /** Single-letter status: M (modified), A (added), D (deleted), R (renamed), U (untracked). */
  status: string
  added: number
  deleted: number
}

export interface GitStatus {
  hasRepo: boolean
  /** "owner/repo" from the origin remote, else the folder name. */
  repoName: string
  branch: string
  /** Local branch names (for the branch switcher). */
  branches: string[]
  /** Remote-tracking branch names as `<remote>/<branch>` (HEAD pointers excluded), so the
   *  switcher can offer branches that exist only on a remote — a plain `git switch <branch>`
   *  then DWIMs a local tracking branch. Absent in stale caches: read with `?? []`. */
  remoteBranches?: string[]
  ahead: number
  behind: number
  /** The repo has at least one remote — which may well not be named `origin` (a fork can have only
   *  `upstream`). Never read this to decide whether a `git push origin …` can work: use `hasOrigin`. */
  hasRemote: boolean
  /** A remote literally named `origin` exists — i.e. a hardcoded `push origin <ref>` has a target. */
  hasOrigin: boolean
  /** The current branch has an upstream tracking ref (i.e. it has been published). */
  hasUpstream: boolean
  ghAvailable: boolean
  ghAuthed: boolean
  staged: GitFileChange[]
  changes: GitFileChange[]
}

export interface GitResult {
  ok: boolean
  message: string
  /** worktreeRemove() only: the worktree is no longer on disk (registration pruned, or never
   *  registered), so the caller must clear its binding even when `ok` is false. */
  worktreeGone?: boolean
  /** Set by publish() when no usable GitHub credential was found, so the UI can
   *  fall back to an interactive `gh auth login` instead of just showing an error. */
  needsAuth?: boolean
}

export interface GitApi {
  status(cwd: string): Promise<GitStatus>
  init(cwd: string): Promise<GitResult>
  /** Clone a repo into parentDir; returns the cloned folder path in message on success. */
  clone(parentDir: string, url: string): Promise<GitResult>
  /** Abort the in-flight clone, if any (its clone() promise resolves message:'aborted'). */
  cloneAbort(): Promise<void>
  /** Suggested parent dir for clones: ~/projects if it exists, else the home dir. */
  cloneDefaultParent(): Promise<string>
  /** Subscribe to live clone progress; returns unsubscribe. */
  onCloneProgress(listener: (p: CloneProgress) => void): () => void
  /** Commits the staged changes (no implicit add). */
  commit(cwd: string, message: string): Promise<GitResult>
  push(cwd: string): Promise<GitResult>
  pull(cwd: string): Promise<GitResult>
  /** Pull then push. */
  sync(cwd: string): Promise<GitResult>
  publish(cwd: string, name: string, isPrivate: boolean): Promise<GitResult>
  stage(cwd: string, paths: string[]): Promise<GitResult>
  unstage(cwd: string, paths: string[]): Promise<GitResult>
  stageAll(cwd: string): Promise<GitResult>
  unstageAll(cwd: string): Promise<GitResult>
  /** Unified diff for a file. `staged` selects index vs worktree; untracked shows full file. */
  diff(cwd: string, path: string, staged: boolean, untracked: boolean): Promise<string>
  /** Discard a file's changes (or delete it if untracked). */
  discard(cwd: string, path: string, untracked: boolean): Promise<GitResult>
  switchBranch(cwd: string, name: string): Promise<GitResult>
  createBranch(cwd: string, name: string): Promise<GitResult>
  /** File contents at a git ref ('HEAD', or '' for the index/staged blob). */
  showFile(cwd: string, ref: string, path: string): Promise<string>
  /** Generate a commit message from the staged diff via a local AI agent CLI. */
  generateMessage(cwd: string): Promise<GitResult>
  /** Commit history graph for the repo. */
  history(
    cwd: string,
    options?: { limit?: number; baseRef?: string | null }
  ): Promise<import('./git-history').GitHistoryResult>
  /** File-level changes introduced by a commit (oid). */
  commitFiles(cwd: string, oid: string): Promise<GitFileChange[]>
  /** Remote web URL for a commit sha, or null if it can't be derived. */
  remoteCommitUrl(cwd: string, sha: string): Promise<string | null>
  /** Merge a branch into the current branch. */
  merge(cwd: string, ref: string): Promise<GitResult>
  /** Rebase the current branch onto another. */
  rebase(cwd: string, onto: string): Promise<GitResult>
  /** Delete a branch (force = -D, for unmerged). */
  deleteBranch(cwd: string, name: string, force: boolean): Promise<GitResult>
  /** Rename the current branch. */
  renameBranch(cwd: string, newName: string): Promise<GitResult>
  /** Fetch all remotes and prune. */
  fetch(cwd: string): Promise<GitResult>
  /** Push with --force-with-lease. */
  forcePush(cwd: string): Promise<GitResult>
  /** Stash uncommitted changes (incl. untracked). */
  stashPush(cwd: string): Promise<GitResult>
  /** Pop the latest stash. */
  stashPop(cwd: string): Promise<GitResult>
  /** Revert a commit (--no-edit). */
  revert(cwd: string, oid: string): Promise<GitResult>
  /** Create + switch to a new branch at a commit. */
  branchAt(cwd: string, name: string, oid: string): Promise<GitResult>
  /** Checkout a commit (detached HEAD). */
  checkoutCommit(cwd: string, oid: string): Promise<GitResult>
  repoRoot(cwd: string): Promise<string | null>
  /** `{ ok: false, entries: [] }` when git itself could not be read — which is NOT the same fact as
   *  "this repo has no worktrees", and no caller may treat it as one (see worktree-ops). */
  worktreeList(repoPath: string): Promise<import('./worktree').WorktreeListResult>
  worktreeAdd(repoPath: string, wtPath: string, branch: string, baseRef: string, isNew: boolean): Promise<GitResult>
  /** `push`: also publish `baseRef` to origin after a successful merge (only if a remote exists).
   *  Opt-in — a merge must never publish to a shared remote the user was not told about. */
  worktreeMerge(repoPath: string, branch: string, baseRef: string, push?: boolean): Promise<GitResult>
  /** `pruneOnly`: clean up git's registration only — never delete a directory. Used to prune a
   *  stale binding whose worktree was already deleted outside the app. */
  worktreeRemove(repoPath: string, wtPath: string, deleteBranch: boolean, pruneOnly?: boolean): Promise<GitResult>
  /** Scope remote git routing to the active project: pass its id to route git over that SSH
   *  project's master, or null for a local project so all git ops run locally. */
  setActiveRemote(projectId: string | null): Promise<void>
}

export interface UpdateInfo {
  version: string
  notes?: string
  /**
   * The update cannot self-install and must be downloaded manually (Linux .deb/.rpm: no
   * APPIMAGE env, so electron-updater's quitAndInstall would throw). The card shows a
   * download link instead of the download-progress/restart flow. Absent/false = self-installs.
   */
  manual?: boolean
}

export interface UpdatePolicy {
  /** Minimum supported version for the device's channel (or null when no policy). */
  minSupported: string | null
  /** True when the running version is below the minimum supported version. */
  mandatory: boolean
  /** Optional release highlights (markdown) the feed carries for `latestVersion`. */
  notes?: string
  /** The version `notes` describe. Notes are shown only on a card for this exact version. */
  latestVersion?: string
}

/** Restart-to-update was accepted: `preparing` = waiting for the OS updater to stage it (macOS),
 *  `restarting` = the install is starting now. */
export interface UpdateInstalling {
  phase: 'preparing' | 'restarting'
  version: string | null
}

export interface UpdateProgress {
  /** 0–100. */
  percent: number
  transferred: number
  total: number
  bytesPerSecond: number
}

export interface UpdateApi {
  /** A newer version was found and is downloading. Returns unsubscribe. */
  onAvailable(listener: (info: UpdateInfo) => void): () => void
  /** The update finished downloading and is ready to install. Returns unsubscribe. */
  onDownloaded(listener: (info: UpdateInfo) => void): () => void
  /** Download progress ticks while an update downloads. Returns unsubscribe. */
  onProgress(listener: (p: UpdateProgress) => void): () => void
  /** An updater error occurred (drives the card's error state). Returns unsubscribe. */
  onError(listener: (message: string) => void): () => void
  /** No newer version is available (also the dev no-op reply to check()). Returns unsubscribe. */
  onNotAvailable(listener: () => void): () => void
  /**
   * This build has no update channel and can never learn whether a newer version exists
   * (issue #814). Deliberately separate from `onNotAvailable`: "we looked and you are current"
   * and "we cannot look" are different facts with different remedies. Returns unsubscribe.
   */
  onNoChannel(listener: () => void): () => void
  /** Restart-to-update was accepted and is preparing / restarting. Returns unsubscribe. */
  onInstalling(listener: (s: UpdateInstalling) => void): () => void
  /**
   * The update main already staged this run (announced once), or null. A renderer that loads after
   * that one-time `onDownloaded` — ⌘R, a window recreated after a crash — asks on mount.
   */
  getStaged(): Promise<{ version: string; notes: string } | null>
  /** Trigger a manual update check. */
  check(): void
  /** The running app version. */
  getVersion(): Promise<string>
  /** The channel's mandatory-update policy for the running version (from /v1/check). */
  getPolicy(): Promise<UpdatePolicy>
  /** Quit and install the staged update. */
  restart(): void
  /** Prepare-for-update (Windows session host, issue #829): what the running host holds. Never
   *  launches a host. Answers `unsupported` off Windows and in the Server Edition. */
  prepareInspect(): Promise<import('./update-prep').UpdatePrepInspection>
  /** Prepare-for-update: ask the host to end every session and exit, and confirm it did. */
  prepareShutdownHost(): Promise<import('./update-prep').UpdatePrepShutdown>
  /** Prepare-for-update: quit the app (no quit confirmation) once the host is gone. */
  prepareQuit(): void
}

/** A single news/announcement item, fetched from the remote announcements feed. */
export interface Announcement {
  /** Stable unique id; used to remember which items the user has dismissed. */
  id: string
  title: string
  body?: string
  /** Optional "Learn more" link (opened in the system browser). */
  url?: string
  /** Visual emphasis; defaults to 'info'. */
  level?: 'info' | 'success' | 'warning'
}

/** A one-time popup from the same feed (`popups` in the check reply): shown once per install. */
export interface PopupAnnouncement extends Announcement {
  /** The button's label; absent = "Learn more" for a link, "Upgrade to Pro" for the checkout. */
  ctaLabel?: string
  /** 'upgrade' = the button starts the app's own Pro checkout instead of opening `url`. */
  action?: 'upgrade'
  /** The SHA-256 naming its picture, fetched with `AnnouncementsApi.popupImage`. */
  image?: string
}

export interface AnnouncementsApi {
  /** Fetch the announcements feed from the website (returns [] on any failure). */
  fetch(): Promise<Announcement[]>
  /** The feed's one-time popups ([] on any failure, and on the Server Edition, which does not read
   *  the feed). Which of them were already shown is the renderer's record, not the feed's. */
  popups(): Promise<PopupAnnouncement[]>
  /** A popup's picture as a `data:` URL, or null when it cannot be had. */
  popupImage(sha256: string): Promise<string | null>
}

export interface NotifyPayload {
  title: string
  body: string
  /** Node to focus/center when the notification is clicked. */
  nodeId: string
  /** Show even when the window is focused (used to trigger the macOS permission prompt). */
  force?: boolean
}

/** A chunk of a subagent's live transcript, streamed while it works. */
export interface SubagentActivity {
  toolUseId: string
  chunk: string
}

/** One linked node, as the context-link CLI sees it. */
export interface ContextLinkInfo {
  id: string
  title: string
  /** The linked node's working dir — lets the CLI resolve a transcript when the path isn't known yet. */
  cwd?: string
  /** Set when the linked node is a sticky note: its current text. Note entries have no transcript/terminal. */
  note?: string
  /** The linked node's agent CLI ('claude' | 'codex' | 'gemini') — selects the CLI transcript parser. */
  agentId?: string
  /** Latest known provider session id — lets main resolve the transcript via the per-agent locators. */
  sessionId?: string
  /** Managed Claude account of the linked node — scopes the claude locator fallback. */
  accountId?: string
}

/** Map of node id → the nodes it is context-linked to. Sent to main so it can write link files. */
export type ContextLinkMap = Record<string, ContextLinkInfo[]>

export interface ContextLinkApi {
  /** Push the current link map to main; main rewrites the per-node link files. */
  setLinks(map: ContextLinkMap): Promise<void>
  /** Static facts the renderer needs to compose link messages: the CLI shim's absolute path, and
   *  the `process.platform` of the core that wrote it (absent from an older core ⇒ treat as POSIX).
   *  On `win32` a non-claude agent is told to run the `.cmd` launcher beside the shim. */
  info(): Promise<{ shimPath: string; platform?: string }>
}

/** One usage window (5h session or 7d weekly) as shown in the indicator. */
export interface ClaudeUsageWindow {
  /** 0–100; remaining quota. Drives the bar fill (shows "remaining"). */
  leftPercent: number
  /** Unix ms when this window resets, or null if unknown. */
  resetsAt: number | null
}

/**
 * One usage window, normalized across providers. Claude's endpoint hands these over directly
 * as its open-ended `limits[]` array — a per-model quota (Fable's weekly cap, say) is an
 * ordinary entry whose model name rides in `scopeLabel`, so a new model needs no new field.
 * Other providers (Codex's primary/secondary windows, …) are mapped into the same shape.
 *
 * Percentages are portions USED, which is the providers' own convention; the UI inverts for
 * display where it shows "left".
 */
export interface UsageLimit {
  /** Provider-assigned kind: 'session' | 'weekly_all' | 'weekly_scoped' | future values. */
  kind: string
  /** Coarse grouping ('session' | 'weekly'), or null when the provider omits it. */
  group: string | null
  /** 0–100, portion consumed. */
  usedPercent: number
  /**
   * The provider's own severity call ('normal' | 'warning' | 'critical' | …), or **null when
   * the provider does not report one** — which is the common case (only Claude does today).
   * Null means "derive from the percentage locally"; it must NOT be defaulted to 'normal',
   * or every provider without severity would paint a permanently green bar.
   */
  severity: string | null
  resetsAt: number | null
  /**
   * The bucket's real duration in minutes, when the provider reports it (Codex sends
   * `limit_window_seconds`), else null. Providers can and do vary this per plan, so labelling
   * a window "5h" from its `kind` alone can be a lie.
   */
  windowMinutes: number | null
  /** Model display name for a scoped limit (e.g. 'Fable'), else null. */
  scopeLabel: string | null
  /** The provider says this window is the one currently gating the account. */
  isActive: boolean
}

/**
 * One provider's usage snapshot. `ClaudeUsage` below is the Claude-shaped superset kept for the
 * existing pill; new providers use this leaner shape (they have no per-account story yet).
 */
/** Safe billing diagnostics: never include URLs, response bodies, or exception messages. */
export type UsageDiagnostic = {
  view: 'credits' | 'default'
} & ({ reason: 'http'; httpStatus: number } | {
  reason: 'timeout' | 'network' | 'invalid-response'
})

export interface ProviderUsage {
  /** Agent id the limits belong to: 'claude' | 'codex' | … */
  provider: string
  /** Failed billing views, including failures recovered by a successful fallback. */
  diagnostics?: UsageDiagnostic[]
  limits: UsageLimit[]
  /** Signed-in identity, when the provider exposes one cheaply (email / account label). */
  account: string | null
  /**
   * The managed account this row's numbers belong to, when the provider is account-scoped (Codex
   * manages N homes on one machine). `undefined` is the un-owned system row — an account that
   * cannot be proven un-owned is never labelled un-owned. Rows are keyed by this so one account's
   * usage can never collapse into or be attributed to another (S6 §4.3, no mixing / fail-closed).
   */
  accountId?: string
  updatedAt: number
  /**
   * 'unavailable' = not signed in / no subscription to report → hide this provider entirely.
   * 'fetching' = request in flight. 'ok' = limits present. 'error' = the fetch failed — and when
   * `limits` is non-empty alongside it, those are the LAST GOOD numbers the service kept
   * (`holdLastGoodProvider`), still stamped with their own `updatedAt`.
   */
  status: 'unavailable' | 'fetching' | 'ok' | 'error'
  /** The latest read was refused with HTTP 429 (Codex today, issue #1168). Absent = not rate
   *  limited, or not known to be. */
  rateLimited?: boolean
}

/** Host memory snapshot in MB. `null` from any reader means "could not read" — never "zero".
 *  Shared because it crosses the wire for the system-resource pill; core reads it, the renderer
 *  renders it. */
export interface MemInfo {
  availableMb: number
  totalMb: number
  /**
   * Swap, and the kernel's own stall accounting. **Optional on purpose, and their absence is the
   * darwin contract.**
   *
   * `availableMb` alone cannot see a host that has already spent its overflow reserve: a machine
   * with 10.5 GB "available" and 84% of its swap consumed reads as healthy under a 10%-of-RAM
   * watermark, which is exactly the state the 2026-08-03 swap-thrash lockup was in. These fields
   * carry the two host-wide facts that DO see it.
   *
   * Only the Linux reader populates them (`/proc/meminfo` for swap, `/proc/pressure/memory` for
   * PSI — both world-readable, measured on a `hidepid=invisible` host where a non-root uid can read
   * neither another user's processes nor their tmux socket). `parseVmStat` leaves every one of them
   * undefined, so no macOS reading can ever satisfy a swap or PSI term: darwin cannot start firing
   * on a signal that was never measured there.
   *
   * A consumer must treat `undefined` as NO SIGNAL, never as zero — a zero here reads as
   * "swap totally exhausted" / "no stall", and both are claims the reader has not earned.
   */
  /** Total swap in MB; `0` legitimately means "this host has no swap configured". */
  swapTotalMb?: number
  /** Free swap in MB. */
  swapFreeMb?: number
  /** `/proc/pressure/memory` `some avg60` — % of the last minute at least one task stalled on memory. */
  psiSomeAvg60?: number
  /** `/proc/pressure/memory` `full avg60` — % of the last minute EVERY task was stalled. Thrash. */
  psiFullAvg60?: number
  /**
   * What the RAM pill SHOWS beyond used/total. **Display only: never an input to the reaper, the
   * memory-pressure monitor or a reclaim lever**. It is a separate object,
   * rather than more top-level fields, so that rule is structural: `hostUnderMemoryPressure` reads
   * `swapTotalMb`/`swapFreeMb`, and filling THOSE on darwin would fire the reaper's swap term all
   * day on a Mac that can keep most of its swap in use for hours (16% swap free on the measured
   * one). Absent field = not measured, never zero.
   */
  display?: MemDisplay
}

/** See `MemInfo.display`. Every field is optional and independent: one failed read omits one fact. */
export interface MemDisplay {
  /** Swap in use, MB. darwin: `sysctl vm.swapusage`; Linux: `SwapTotal - SwapFree`. */
  swapUsedMb?: number
  /** Swap currently provisioned, MB. On darwin this GROWS on demand (dynamic swap files), so it is
   *  a size, not a ceiling. */
  swapTotalMb?: number
  /** The kernel's own verdict (`kern.memorystatus_vm_pressure_level`: 1/2/4), darwin only — the
   *  colour Activity Monitor's pressure graph shows. Linux has no equivalent level and PSI has no
   *  measured threshold here, so it is never invented there. */
  pressureLevel?: 'normal' | 'warn' | 'critical'
}

/** One nt- session's memory, as the panel renders it. */
export interface SessionMemoryRow {
  /** tmux session name, `nt-<nodeId>`. */
  session: string
  /** The canvas node id — the session name minus the `nt-` prefix. */
  nodeId: string
  panePid: number
  /** The pane's own process. */
  selfMb: number
  /** Everything below it (MCP servers, headless browsers, …). */
  childrenMb: number
  childCount: number
  /** The whole tree: the pane's own process plus everything below it. */
  totalMb: number
  /** The biggest single process in the tree, pane process included. Part of `totalMb`. */
  largestMb: number
  /** Its name, cleaned for display (`processLabel`). Absent when the table carried no name. */
  largestName?: string
  /** `#{pane_current_command}` — the agent/shell label. */
  command: string
}

/**
 * What a sweep's numbers are, because the three measures answer differently for the same process:
 * on a Mac an idle MCP server measured 242 MB of footprint and 4 MB of rss (most of it compressed).
 *  - `footprint`: macOS phys_footprint, Activity Monitor's "Memory" column;
 *  - `rss`: resident memory: Linux, and every SSH host, which is read with `ps` whatever it runs;
 *  - `working-set`: Windows, Task Manager's "Working set" column.
 */
export type SessionMemoryMetric = 'footprint' | 'rss' | 'working-set'

/**
 * `ok: false` means the sweep could not run (no tmux binary, unreadable process table). It is NOT
 * the same as an empty `rows` with `ok: true`, which means "we looked and there are no sessions".
 * Collapsing the two would make the panel report "nothing is using memory" at exactly the moment
 * it failed to measure.
 */
export interface SessionMemoryReport {
  ok: boolean
  rows: SessionMemoryRow[]
  mem: MemInfo | null
  /** The measure `rows` are in. Absent when the sweep read no process table. */
  metric?: SessionMemoryMetric
  /**
   * Live nodeterm sessions on this machine that the sweep could NOT measure — today, Zellij-backed
   * ones (the sweep reads tmux). Absent/0 = none. `null` = could not tell. Local scope only. The
   * panel must never say "no sessions are running" while this is non-zero or unknown.
   */
  unmeasured?: number | null
  /** Which backend the `unmeasured` sessions belong to, for the panel's sentence. Absent = Zellij
   *  (the original and, off Windows, only case); `'session-host'` = a running session host older
   *  than this app, which names its sessions but cannot describe their processes. */
  unmeasuredBackend?: 'session-host'
  /**
   * The Windows session host's OWN cost, which belongs to no session row (CLAUDE.md, Session
   * memory): its process (every session's headless emulator, node-pty's per-session conout worker
   * thread) and its non-shell children (one conhost/OpenConsole per ConPTY — they are the host's
   * children, siblings of the shell, so no row's tree reaches them). Absent = no session host, or it
   * could not be measured: never a fake zero. The tmux leg never sets it.
   */
  host?: SessionHostOverhead
  /**
   * nodeterm's OWN processes (main, renderer(s), GPU, helpers) — the "nodeterm itself" group.
   * Display only, LOCAL scope only. Absent = this shell cannot enumerate its processes (Server
   * Edition, a relay stub, every SSH scope): not available. `ok:false` = it tried and could not
   * measure. Never part of the session total — see AppSelfMemory.
   */
  app?: AppSelfMemory
}

/** Which of nodeterm's own processes a group is (Electron `ProcessMetric.type`, folded). */
export type AppProcessKind = 'main' | 'renderer' | 'gpu' | 'helper'

/** One kind of nodeterm process, summed over every pid of that kind (the HUD is a 2nd renderer). */
export interface AppSelfGroup {
  kind: AppProcessKind
  count: number
  /** Summed memory in MB, in the SAME accounting as the session rows (darwin: phys_footprint from
   *  the panel's own `top` read; Linux: VmRSS; Windows: working set). Absent when any pid of the
   *  group was missing from the table: a partial sum would understate, which is a wrong number. */
  mb?: number
  /** Summed CPU time since each process started, seconds (Electron `cumulativeCPUUsage`). Absent =
   *  not reported. A lifetime total, deliberately not a percentage. */
  cpuSeconds?: number
}

/**
 * The GPU helper's real footprint (1557-1845 MB live, mostly IOSurfaces)
 * was invisible because `ps` RSS says 96-153 MB and nothing attributed it. `ok:false` (no groups)
 * when the process list or the table could not be read, or no pid of ours was in it.
 */
export interface AppSelfMemory {
  ok: boolean
  groups: AppSelfGroup[]
  /** Sum of every group, only when every group was measured. */
  totalMb?: number
}

/** See `SessionMemoryReport.host`. All MB figures are MEASURED working sets, not estimates. */
export interface SessionHostOverhead {
  pid: number
  /** The session-host process itself. */
  selfMb: number
  /** Its non-shell children (conhost / OpenConsole, plus anything under them — including the
   *  pane-probe PowerShell worker while it is warm, which is the host's child and its cost). */
  consoleMb: number
  /** Direct children recognised as a console host — "N consoles" in the panel. */
  consoleCount: number
  totalMb: number
}

/**
 * What the renderer asks for: the machine a project runs ON, never "this machine" implicitly.
 * `remote: true` is the renderer saying it already knows (from `usageScope`) that the active
 * project is an SSH one; the shell's own `isRemoteProject` is a second, independent confirmation,
 * so a project the shell has not (yet) registered as connected still cannot be answered with the
 * local machine's sessions.
 */
export interface SessionMemoryQuery {
  projectId?: string
  remote?: boolean
}

/**
 * Per-session memory for the machine the ACTIVE PROJECT runs on — the same scoping rule the usage
 * indicator follows (`usageScope`), for the same reason: a number is meaningless without the
 * machine it describes.
 *
 * Both members are on-demand only, never polled: a remote answer costs an ssh exec plus a `ps` of
 * somebody else's whole process table. Pass the query through verbatim — `remote` is one of the two
 * independent sources the service uses to decide which host answers.
 */
export interface SessionMemoryApi {
  /** Per-session breakdown for the scoped machine. `ok:false` = the sweep could not run, which is
   *  NOT an empty `rows` with `ok:true` ("we looked, there are none"). */
  read(q?: SessionMemoryQuery): Promise<SessionMemoryReport>
  /** The scoped machine's RAM. `null` = could not read (never "zero"). */
  host(q?: SessionMemoryQuery): Promise<MemInfo | null>
}

/** Best-effort active organization from this account's Claude identity file. */
export interface ClaudeUsageOrganization {
  name: string
  uuid?: string
  type?: string
  rateLimitTier?: string
}

/** Claude Code subscription usage snapshot for the bottom-left indicator. */
export interface ClaudeUsage {
  /**
   * Every limit the plan exposes, including per-model scoped ones. Prefer this over the
   * `session`/`weekly` fields below, which are kept only so older callers keep compiling.
   */
  limits: UsageLimit[]
  session: ClaudeUsageWindow | null
  weekly: ClaudeUsageWindow | null
  /** Signed-in account email, read-only and best-effort (null if unknown). */
  email: string | null
  /** Active organization, absent when its metadata is unavailable. */
  organization?: ClaudeUsageOrganization
  /** Unix ms when this snapshot was produced. */
  updatedAt: number
  /**
   * 'unavailable' = no OAuth subscription token (API-key billing / logged out) → hide pill.
   * 'fetching' = request in flight. 'ok' = windows present. 'error' = fetch failed — and when
   * `limits` is non-empty alongside it, those are the LAST GOOD numbers the service kept
   * (`holdLastGood`), still stamped with their own `updatedAt`.
   */
  status: 'unavailable' | 'fetching' | 'ok' | 'error'
  /**
   * The latest read was refused with HTTP 429. The usage endpoint's request budget is also
   * spent by every Claude CLI using the same login (the CLI reads this endpoint itself), so a
   * host running dozens of sessions can exhaust it without us. Absent = not rate limited (or
   * not known to be).
   */
  rateLimited?: boolean
}

/**
 * One REMOTE (SSH host) Claude or Codex identity's usage, read on that host over the project's
 * ControlMaster. Separate from the local per-account rows because the identity is only
 * meaningful together with the host it lives on — the same email can be logged in on two
 * machines with two different quotas in flight.
 */
interface RemoteAccountUsageBase {
  /** `user@host` of the connection the numbers came from. */
  hostKey: string
  /** Managed remote account id, or null for that provider's system identity on the host. */
  accountId: string | null
  /** Display label: the managed account's label, else the host key. */
  label: string
}

export type RemoteAccountUsage = RemoteAccountUsageBase & (
  | { provider?: 'claude'; usage: ClaudeUsage }
  | { provider: 'codex'; usage: ProviderUsage }
)

/** What the usage indicator wants from the remote hosts right now. */
export interface RemoteUsageQuery {
  /** Read only this `user@host` — the machine the active project runs on. Omitted = every
   *  connected host, which no scoped UI asks for but keeps the channel general. */
  hostKey?: string
  /** Bypass the cache debounce (the ⟳ button). */
  force?: boolean
}

export interface UsageApi {
  /** Returns the latest snapshot (cached if fresh, else a fresh fetch). Optional account id
   *  targets a managed account; omitted = the system account (also the pushed one). */
  fetch(accountId?: string): Promise<ClaudeUsage>
  /** Forces a fresh fetch, bypassing the focus debounce. Optional account id as `fetch`. */
  refresh(accountId?: string): Promise<ClaudeUsage>
  /** Snapshots for every non-Claude provider (codex, …). Fetched on demand, not polled — pass
   *  `force` to bypass the cache debounce. Providers that aren't signed in come back
   *  'unavailable' rather than being omitted, so the caller can tell "off" from "broken". */
  providers(force?: boolean): Promise<ProviderUsage[]>
  /** Usage for the Claude identities on connected SSH hosts, read on those hosts (the credential
   *  never crosses back). On-demand like `providers`, not polled — each row costs an ssh
   *  round-trip, which is also why the caller should name the ONE host it is showing. Empty when
   *  nothing is connected, or on a shell with no SSH projects (Server Edition), so callers need
   *  no capability check. */
  remote(query?: RemoteUsageQuery): Promise<RemoteAccountUsage[]>
  /** Store (or, with an empty string, clear) a provider's browser cookie. Resolves to whether one
   *  is now stored. Write-only by design — nothing reads the value back across this boundary. */
  setProviderCookie(provider: string, cookie: string): Promise<boolean>
  /** Which cookie-based providers have one stored, so the UI shows state without the secret. */
  cookieProviders(): Promise<Record<string, boolean>>
  /** Fires whenever main pushes a new snapshot (poll/refresh). Returns unsubscribe. */
  onUpdate(listener: (usage: ClaudeUsage) => void): () => void
}

/** A Claude session's context-window fill, pushed per sessionId from the transcript tailer. */
export interface ContextWindowUsage {
  /** Remote Codex observations are node-scoped; equal thread ids on different hosts never mix. */
  nodeId?: string
  /** Invalidates this node/session observation after its remote scope changes or disappears. */
  cleared?: true
  /** Missing on older hosts; only session-env is an observed Claude configuration. */
  windowSource?: 'session-env' | 'transcript' | 'estimate'
  sessionId: string
  /** input + cache_read + cache_creation tokens of the latest assistant message. */
  usedTokens: number
  /** Model context window (200k default, 1M for 1m-context models). */
  windowTokens: number
  /** 0–100 fullness. */
  usedPercent: number
  /** Model id from the transcript, or null if not seen yet. */
  model: string | null
  /**
   * Reasoning effort of the latest request, as Claude Code records it on the transcript's assistant
   * record (`low`/`medium`/`high`/`xhigh`/`max` on 2.1.283). Absent = not recorded: another agent,
   * an older host or CLI, or a model that takes no effort. Shown by the ⌘M composer's toolbar.
   */
  effort?: string
  updatedAt: number
}

export interface ContextApi {
  /** Fires whenever a session's context fill changes. Returns unsubscribe. */
  onUpdate(listener: (usage: ContextWindowUsage) => void): () => void
  /**
   * Fires when a Claude session's transcript records Remote Control (`/remote-control`) connecting
   * or disconnecting. Fed by the same transcript tails as `onUpdate`. Returns unsubscribe.
   */
  onRemoteControl(listener: (update: { nodeId: string; sessionId: string; on: boolean }) => void): () => void
  /**
   * Ask the core to start (or refresh) tracking a session's transcript so the meter populates
   * without waiting for a live hook event — e.g. on node mount after an app restart, when
   * the continuing session is idle. `cwd` is a transcript-path fallback only.
   * `accountId` scopes resolution to a managed Claude account's transcript root (default `~/.claude`).
   *
   * `nodeId` and `agentId` are what make this work for anything but a LOCAL CLAUDE node, and both
   * are load-bearing rather than informational (see `core/context-ensure.ts`):
   * - `nodeId` is the only way to learn that this session runs on an SSH project's HOST, whose
   *   transcript no local resolver can see. Without it a remote node's meter stayed blank until
   *   its next turn, every app restart.
   * - `agentId` routes the resolve to THAT agent's own locator and tail. Claude's resolver falls
   *   back to the newest claude transcript for the cwd, so resolving a codex/gemini session through
   *   it would meter a stranger's conversation. Both omitted ⇒ the legacy local-claude behaviour.
   */
  ensure(
    sessionId: string,
    cwd?: string,
    accountId?: string,
    nodeId?: string,
    agentId?: string
  ): void
}

/**
 * Canvas sync: node mutations travel between the attached clients (an Electron renderer, a
 * Server-Edition browser tab) so they converge on one node set — instead of each holding its own
 * canvas until someone's whole-file `workspace.save` overwrites the other's edits.
 */
export interface CanvasApi {
  /**
   * Publish one local node mutation for `projectId` (a project IS a canvas — a mutation is only
   * ever applied to the canvas it was made on). Fire-and-forget; the reflector fans it out to every
   * OTHER attached client and never echoes it back to the sender.
   */
  mutate(projectId: string, mutation: CanvasMutation): void
  /** Fires with each PEER's mutation (project id + mutation). Returns unsubscribe. */
  onMutation(listener: (projectId: string, mutation: CanvasMutation) => void): () => void
}

/**
 * Which of this core's projects a canvas authority governs (the Server Edition hosting a team,
 * docs/hosted-team-relay.md). The authority writes a governed project's content only from the ops it
 * hears, so a client must publish its canvas ops for such a project even when nobody else is
 * attached — the solo gate is overridden for it. The desktop runs no authority and governs nothing.
 */
export interface CanvasAuthorityApi {
  /** true = this core may govern projects, and which ones is known only once `governed()` answers:
   *  until then a client publishes for EVERY project on it (the Server Edition). false = known in
   *  advance, so nothing is assumed (the desktop and a Team Access tab govern nothing; a hosted
   *  relay tab answers from its own bindings). */
  readonly assumeAllUntilAnswered: boolean
  /** The governed project ids right now. Never rejects: "unknown" is the empty list. */
  governed(): Promise<string[]>
  /** Fires with the NEW governed set whenever it changes (a share or unshare). Returns unsubscribe. */
  onChanged(listener: (ids: string[]) => void): () => void
}

/** One searchable line extracted from a Claude session transcript. */
export interface TranscriptLine {
  role: 'user' | 'assistant' | 'tool'
  text: string
}

/** One ordered piece of a chat message: prose, or a tool call with an optional result.
 *  `summary` (present only on live-turn tools folded into history) carries the diff-preview
 *  metadata so committed tool cards keep the same summary/diff-click treatment as live ones. */
export type ChatPart =
  | { kind: 'text'; text: string }
  | {
      kind: 'thinking'
      text: string
      /**
       * How long the model thought, in ms — this record's timestamp minus that of the newest `user`
       * record before it (the prompt, tool_result or meta line the request answered). Present only on
       * the opt-in `thinking` read, only when both stamps exist and the gap is ≥ 0. Measured 2026-11-02
       * on CLI 2.1.275–2.1.316: a thinking record is written when the thinking ENDS, and the record
       * after it is a tool call whose write time scales with its input, so the gap to the NEXT record
       * is not thinking time; nor is the gap to the record right BEFORE it, which is an empty
       * encrypted thinking record of the same message written ~10 ms earlier (1,018 of 1,037).
       * A paged read sees only its own window, so a thinking record with no `user` record before it
       * in that window (the start of an older page) carries no `ms`.
       */
      ms?: number
    }
  | {
      /**
       * An image the user attached to a prompt (a pasted screenshot): `data` is the base64 payload,
       * drawn as `data:<mediaType>;base64,<data>`. Present only on the opt-in `rich` read
       * (`ChatParseOptions.rich`), and only for a base64 source whose `mediaType` is in
       * `CHAT_IMAGE_TYPES` (core/transcript-reader.ts) — never `image/svg+xml`. An image a tool
       * returned (inside a `tool_result`) is tool output and never becomes one.
       */
      kind: 'image'
      mediaType: string
      data: string
    }
  | {
      /**
       * A message from an agent team's teammate (core/chat-teammate.ts): Claude Code records it in the
       * lead's transcript as a user record, but nobody typed it. Present only on the opt-in `rich`
       * read; without it the record is one `Agent message` tool part. `text` = a plain message's
       * markdown body; `idle` = the teammate reporting that its turn ended (then `text` is absent).
       * `color` is the teammate's TUI color name, as recorded (untrusted: map it, never use it as CSS).
       */
      kind: 'teammate'
      from: string
      color?: string
      summary?: string
      unverified?: boolean
      text?: string
      idle?: ChatTeammateIdle
    }
  | {
      /**
       * The user interrupted the turn here (Esc, or Ctrl+C once): one of Claude Code's fixed marker
       * records (`CLAUDE_INTERRUPT_MARKERS`), which it saves as a USER record but which the user did
       * not type. Present only on the opt-in `rich` read; without it the marker stays a user text
       * part, as before. The renderer draws Claude's own TUI line for it.
       */
      kind: 'interrupt'
    }
  | {
      kind: 'tool'
      name: string
      arg: string
      result?: string
      summary?: ChatToolSummary
      /** Markdown worth reading in full (an `ExitPlanMode` plan, an `AskUserQuestion` question and
       *  its options, and on the opt-in `rich` read a `TodoWrite` checklist — `core/chat-tool-body.ts`).
       *  Present = the renderer shows an expanded card instead of the collapsed chip (a superseded
       *  todo list excepted: `lib/chatTodo.ts`). Capped at 64K characters. */
      body?: string
      /** `AskUserQuestion` only: the questions read for the answer controls (`readQuestions`) —
       *  the SAME reader the held request's texts come from, so a surface can match the card to the
       *  held ticket. Absent = unreadable input = the card stays read-only. */
      questions?: ChatQuestion[]
      /** `Edit` / `Write` only, on the opt-in `rich` read (`ChatParseOptions.rich`): the change the
       *  call asked for, read from its INPUT — never from the result — so the renderer can draw it as
       *  a diff. Absent = any other tool, an unreadable input, or a read without `rich`. */
      diff?: ChatToolDiff
      /** The transcript's `tool_use` id. Set only by a PAGED read (`ChatTranscriptResult.olderCursor`
       *  present): a result carried across a page boundary (`unmatchedResults`) is attached by it. */
      id?: string
    }

/** An `idle_notification` from a teammate (`ChatPart` teammate `idle`). Every field is optional:
 *  the notification names only what the teammate reported. */
export interface ChatTeammateIdle {
  reason?: 'available' | 'interrupted' | 'failed'
  /** The teammate's last direct message, one line. */
  summary?: string
  failureReason?: string
  taskId?: string
  /** The teammate's report, markdown, capped. */
  result?: string
}

/**
 * The change an `Edit` / `Write` tool call asked for (`ChatPart` tool `diff`). Edit's
 * `{file_path, old_string, new_string}` maps to `{filePath, oldText, newText}`; Write's
 * `{file_path, content}` to `{filePath, oldText: '', newText: content}`. An empty `newText` on an
 * Edit is a deletion. Each text is capped at a tool body's length (`capText`, core/chat-tool-body.ts:
 * 64K characters, then `TOOL_BODY_TRUNCATED`, with no markdown fence repair — it is file content).
 */
export interface ChatToolDiff {
  filePath: string
  oldText: string
  newText: string
}

/** A structured chat message reconstructed from a Claude session transcript. */
export interface ChatMessage {
  role: 'user' | 'assistant'
  parts: ChatPart[]
  /**
   * Stable identity for list rendering: the absolute byte offset of the transcript line this
   * message came from. Set only by a PAGED claude read — an absolute offset does not change when
   * an older page is prepended or the file grows, so a prepend does not re-key the list. Absent on
   * the legacy read and on grok (whose reader does not page).
   */
  key?: number
  /**
   * When the transcript line was written (epoch ms, from claude's ISO `timestamp`). Set on BOTH
   * read paths; absent when the line states none (grok, older records). The ⌘M thread shows it as a
   * relative time under an assistant turn and a clock time under a user message, and starts a day
   * divider at each local day's first stamped message.
   */
  at?: number
}

/** A `tool_result` whose `tool_use` was not in the same page (it lives in an OLDER one). */
export interface ChatCarriedToolResult {
  /** The `tool_use_id` — matches `ChatPart.id` of a tool part in an older page. */
  id: string
  result: string
}

/** Edit/Write tool summary for diff-preview cards. */
export interface ChatToolSummary {
  filePath?: string
  added?: number
  removed?: number
}

/**
 * Result of a chat transcript read. `found` is the whole point of the wrapper: an empty
 * `messages` means two very different things — the session exists and nobody has said anything
 * yet (`found: true`), or no transcript could be resolved at all (`found: false`, e.g. Claude's
 * 30-day cleanup removed it, or the id belongs to another machine). The ⌘M panel rendered both
 * as "No conversation yet.", which is what made a resolution failure look like an empty session.
 */
export interface ChatTranscriptResult {
  messages: ChatMessage[]
  found: boolean
  /**
   * PAGED reads only (absent on the legacy unpaged read, which is unchanged byte for byte). The
   * byte offset where this window's first complete line starts — pass it back as `page.before` to
   * read the next OLDER window. `null` = this window reached the start of the file, or the reader
   * does not page (grok).
   *
   * `found: false` on a read WITH `page.before` set is a FAILED OLDER-PAGE load (the host blipped,
   * the file became unreadable), NOT a missing transcript: the caller keeps what it rendered and
   * offers a retry. Only the first (tail) read's `found: false` means "no transcript".
   */
  olderCursor?: number | null
  /**
   * PAGED reads only. Tool results in this window whose `tool_use` is NOT in it: the newer page is
   * read first, so its results precede their tools. Hold them and attach each to the tool part with
   * the same `id` when an older page arrives. Always `[]` from a reader that does not page.
   */
  unmatchedResults?: ChatCarriedToolResult[]
  /**
   * PAGED reads only: the newest assistant record's model in the returned window — claude's
   * `message.model` (`<synthetic>` error lines skipped), grok's `model_id`. Absent when the window
   * has none, and on the legacy read.
   */
  model?: string
  /** PAGED reads only: that same record's effort — claude's top-level `effort`, grok's
   *  `reasoning_effort`. Never carried forward from an older record. */
  effort?: string
  /** PAGED reads only, with `found: false`: the transcript could not be READ (a remote host that did
   *  not answer, a growth re-read that failed, a remote node with no reachable master) — as opposed
   *  to "no transcript exists". Absent on every other result. */
  unreadable?: true
}

/**
 * Three answers to "is there a transcript for this session id?", because two are not enough.
 *
 * `absent` is a POSITIVE finding — we read the place it would be and it is not there. `unknown`
 * is "we could not look": an unreadable root, a downed ControlMaster, a surface with no reader,
 * an id we would not put on a command line anyway. The only consumer that acts on a negative is
 * cold restore (it launches the agent bare instead of resuming a dead id), and for it the two
 * must never collapse: dropping a resume on `unknown` would throw away a live conversation
 * because an ssh call blipped.
 */
export type TranscriptPresence = 'present' | 'absent' | 'unknown'

export interface ChatApi {
  /**
   * Reads an agent session transcript as structured chat messages.
   * Resolves the transcript like `ClaudeApi.readTranscript` (sessionId → cwd), then
   * reconstructs ordered bubbles + tool calls. `nodeId` lets an SSH-project node be resolved
   * on its HOST even when no hook event has registered its transcript in this app run.
   *
   * `agentId` picks the reader. Omitted (or `claude`) keeps the historical claude path exactly as
   * it was. It is NOT optional in spirit: without it a grok node falls into claude's resolver, whose
   * cwd fallback returns the newest CLAUDE transcript for that directory — someone else's
   * conversation. `CHAT_CAPABLE` decides who may ask; this decides who answers.
   *
   * `page` (optional, trailing) asks for ONE window instead of the whole 5 MB tail — see
   * `shared/chat-page.ts`. Absent = the legacy read, byte for byte. Present = a result carrying
   * `olderCursor`, per-message `key`s, tool-part `id`s and `unmatchedResults`. An invalid
   * `before` rejects.
   */
  readTranscript(
    sessionId: string | undefined,
    cwd: string | undefined,
    accountId?: string,
    nodeId?: string,
    agentId?: string,
    page?: ChatTranscriptPageRequest
  ): Promise<ChatTranscriptResult>

  /**
   * Is the transcript this session id names still on disk?
   *
   * Resolved STRICTLY by `sessionId` — no cwd fallback, which would answer `present` from another
   * session's newest file. `nodeId` lets an SSH-project node be asked on its HOST. Never rejects:
   * anything it cannot judge is `unknown`.
   *
   * Claude-shaped transcripts only (`readsClaudeTranscript` is the caller-side gate) — every other
   * agent's id misses this resolver by construction, and reporting that as `absent` would drop a
   * perfectly good resume.
   */
  transcriptExists(
    sessionId: string,
    accountId?: string,
    nodeId?: string
  ): Promise<TranscriptPresence>

  /**
   * The ⌘M composer's `/` catalog for a node: its agent's measured built-in slash commands, custom
   * command files and skills (core/chat-catalog.ts). An SSH-project node's files are read on its
   * HOST (`nodeId` — remoteness is the shell's own record, never this call's). A relay tab REJECTS
   * (E_UNSUPPORTED — the peer's files are not this machine's to read, and the relay does not carry
   * the channel); the composer then offers the shared built-in table alone, and every caller must
   * treat any rejection the same way.
   */
  catalog(nodeId: string, agentId: string, accountId?: string, cwd?: string): Promise<import('./chat-catalog').ChatCatalog>
}

/** Optional SSH context for account ops. When `projectId` names a connected SSH project, the
 *  account lives on that host (config dir + login + removal happen over ssh). Omit it for local. */
export interface AccountSshCtx {
  projectId?: string
}
export interface ClaudeAccountsApi {
  /** Mint a new managed account: create its config dir, install the hook, check the CLI version.
   *  With an SSH `ctx` the dir + hook are created on the remote host instead of locally. */
  add(ctx?: AccountSshCtx): Promise<{ id: string; configDir: string; versionSupported: boolean }>
  /** Poll the account's `.claude.json` for a completed login; null on timeout/cancel. With an SSH
   *  `ctx` the poll reads the remote host's copy over ssh. */
  waitLogin(id: string, ctx?: AccountSshCtx): Promise<{ email: string } | null>
  /** Cancel an in-flight `waitLogin` for this account. */
  cancelWaitLogin(id: string): Promise<void>
  /** Delete a managed account's config dir (recursive). With an SSH `ctx`, `rm -rf` on the host.
   *  For a LINKED account (`configDir` set) this only forgets the record — the dir is untouched. */
  remove(id: string, ctx?: AccountSshCtx): Promise<void>
  /**
   * Link a PRE-EXISTING local Claude config dir as an account (see `ClaudeAccount.configDir`).
   * Validates the path (absolute, exists, is a directory, not the system `~/.claude`, not a managed
   * dir, not already linked), reads its `.claude.json` for the signed-in email (null when not logged
   * in yet), and installs the managed status hook into it. Local only — no SSH ctx.
   */
  link(configDir: string): Promise<{ id: string; configDir: string; email: string | null }>
  /**
   * Turn `~/.claude/skills` sharing on or off for one LOCAL account (issue #643) and reconcile the
   * filesystem now. Idempotent in both directions; the renderer owns the settings flag and calls
   * this for the effect. Never throws — the result reports what happened, including `refused`
   * (the account's `skills/` resolves to the system one) and `failed` (an EPERM, a vanished skill).
   */
  setSkillSharing(id: string, enabled: boolean): Promise<ClaudeSkillShareResult>
  /**
   * Copy a conversation's transcript from one LOCAL account's config dir into another's (`undefined`
   * = the system `~/.claude`), so a node switched onto the target account resumes the SAME
   * conversation there with no `/login`. With an SSH `ctx` the same copy runs on that project's host,
   * between REMOTE accounts pinned to it. Called only after the CLI has exited. Never overwrites a
   * diverged copy (`diverged`); never throws — every refusal is a reason.
   */
  copySession(
    sessionId: string,
    sourceAccountId: string | undefined,
    targetAccountId: string | undefined,
    /** An SSH project's node: the copy runs ON THAT HOST, between its remote account dirs. */
    ctx?: AccountSshCtx
  ): Promise<ClaudeSessionCopyResult>
}

/** What `claudeAccounts.copySession` did. `copied: false` = the target already held this exact copy. */
export type ClaudeSessionCopyResult =
  | { ok: true; copied: boolean }
  | {
      ok: false
      reason: 'bad-request' | 'unknown-account' | 'no-transcript' | 'diverged' | 'failed'
    }

/** What one `setSkillSharing` / launch reconcile did. Counts, never an exception. */
export interface ClaudeSkillShareResult {
  linked: number
  unlinked: number
  /** Links of ours present after the call — what the Settings row reports. */
  shared: number
  /** System skills not shared because the account has its own entry by that name. */
  occupied: number
  failed: number
  /**
   * Why nothing was done. `same-directory`: the account's `skills/` resolves to the system one
   * (a hand-made whole-directory link, or a linked account pointed at `~/.claude`) — linking into
   * it would plant links in the user's own folder and let the off-switch delete them from there.
   * `remote-account`: an SSH account, whose skills live on its host (out of scope for v1).
   */
  refused?: 'same-directory' | 'remote-account'
}

/**
 * Machine-scoped managed Codex accounts (S6). LOCAL accounts on this Mac are reachable through
 * PR 5; SSH remote accounts land in PR 6. The account LIST is renderer-owned in `settings.json`
 * (`codexAccounts`), exactly like `claudeAccounts`; main owns only the fs + daemon lifecycle and
 * the switch protocol.
 */
export interface CodexAccountsApi {
  /** Mint a new managed account: create its private CODEX_HOME (0700) and symlink the shared,
   *  non-secret runtime assets in. Returns the new id + its home. With an SSH `ctx` the home is
   *  created ON that connected host (no credential ever travels); throws when it cannot be. */
  add(ctx?: AccountSshCtx): Promise<{ id: string; home: string }>
  /** Poll the account's `auth.json` (a real file, never a symlink) every 2s up to 5min for a
   *  completed device login, then read its email; null on timeout/cancel. With an SSH `ctx` the poll
   *  runs on the host, and a login whose email cannot be read there resolves `{ email: null }`. */
  waitLogin(id: string, ctx?: AccountSshCtx): Promise<{ email: string | null } | null>
  /** Cancel an in-flight `waitLogin` for this account. */
  cancelWaitLogin(id: string): Promise<void>
  /** Read a managed account's already-logged-in identity (email), or null if not logged in. With an
   *  SSH `ctx`, asked of the account's home on that host. */
  identity(id: string, ctx?: AccountSshCtx): Promise<{ email: string | null } | null>
  /** Read a machine's system (`~/.codex`) account identity. No arg ⇒ this Mac. `{ projectId }` ⇒
   *  the connected SSH host behind that project; a host whose system identity cannot be resolved
   *  resolves `null` (fail-closed — a remote machine panel never borrows this Mac's login). */
  systemIdentity(ctx?: { projectId?: string }): Promise<{ email: string | null } | null>
  /** Remove a managed account: stop its daemon and delete its home. Refused while a switch
   *  reservation holds it or a concurrent removal is in flight (Property 10). With an SSH `ctx`,
   *  the home is deleted on that host; throws when it could not be. */
  remove(id: string, ctx?: AccountSshCtx): Promise<void>
  /** Phase 1 of the owner-authorized same-machine switch: plan + reserve the rollout exposure of a
   *  conversation from one account to another under a `rollbackToken` (TTL 60s, owner = caller). */
  switchThread(
    threadId: string,
    cwd: string,
    sourceAccountId?: string,
    targetAccountId?: string
  ): Promise<{ threadId: string; rollbackToken?: string }>
  /** Phase 2: commit the reserved exposure (atomic hardlink into the target account). */
  commitSwitch(rollbackToken: string): Promise<void>
  /** Phase 3a: finish a committed switch, releasing the reservation. */
  finishSwitch(rollbackToken: string): Promise<void>
  /** Phase 3b: roll back a reservation (releases it; a committed link is left for cleanup). */
  rollbackSwitch(rollbackToken: string): Promise<void>
  /**
   * The SSH leg of a running node's account switch: expose the conversation to `targetAccountId`
   * ON the connected host behind `ctx.projectId` (hardlink the rollout into the target home, verify
   * the target discovers it). `hostAccountIds` = every managed account on that host (the catalogs
   * the thread is resolved across). Resolves once the target can resume it; throws otherwise.
   */
  switchThreadRemote(
    threadId: string,
    targetAccountId: string | undefined,
    hostAccountIds: string[],
    ctx: AccountSshCtx
  ): Promise<void>
  /** Source-side leg of moving an idle LOCAL conversation to an SSH account: validate strict source
   *  containment then hand the upload to the remote import path (PR 6). Local rollout untouched. */
  transferThreadToSsh(
    threadId: string,
    cwd: string,
    projectId: string,
    targetAccountId?: string,
    sourceAccountId?: string
  ): Promise<{ threadId: string; imported: boolean }>
}

/** One ranked search hit across all on-disk Claude session transcripts. */
export interface TranscriptHit {
  sessionId: string
  title: string
  snippet: string
  cwd: string
  projectLabel: string
  mtime: number
  /** The managed/linked Claude account whose root holds this transcript; absent = system. */
  accountId?: string
}

export interface TranscriptsApi {
  /** Search all on-disk Claude session transcripts by content. */
  search(query: string): Promise<TranscriptHit[]>
}

/** What the Claude CLI on THIS machine can do. Fed by the `claude --version` probe in
 *  core/claude-cli.ts; every field fails open to the conservative answer when the version
 *  is unknown (missing CLI, timeout, unreadable output). */
export interface ClaudeCliCaps {
  version: string | null
  /** `--permission-mode auto` is only accepted by Claude Code >= 2.1.71. */
  autoPermissionMode: boolean
  /** `"tui": "fullscreen"` in settings.json is only understood by Claude Code >= 2.1.89. Gates
   *  whether nodeterm writes that key (write-if-absent) so sessions render fullscreen in tmux. */
  fullscreenTui: boolean
  /**
   * Whether this CLI accepts `--session-id <uuid>`, which lets nodeterm MINT a node's session id
   * instead of waiting to learn it from a hook. Detected by reading `claude --help`, not by
   * comparing versions: the version this flag first shipped in is not documented anywhere we can
   * check, and a guessed floor is the one mistake that would be fatal here — an unknown flag makes
   * the CLI exit, so a wrong guess kills every claude launch rather than degrading.
   */
  sessionIdFlag: boolean
}

export interface GrokCliCaps {
  /**
   * Whether the local grok CLI accepts `--session-id <uuid>`, so nodeterm can MINT a node's session
   * id instead of waiting to learn it from a hook.
   *
   * Probed from `grok --help` by `core/grok-cli.ts` — grok's OWN probe, never claude's. The two
   * CLIs are installed and upgraded independently, so claude's answer is not even correlated with
   * grok's, and an unknown flag makes grok exit rather than degrade.
   *
   * grok's grammar differs from claude's in three measured ways (1.0.13): the UUID must not already
   * exist under the target session directory, so minting one twice is a LAUNCH ERROR and never a
   * resume; `--session-id` combines with `--resume`/`--continue` only alongside `--fork-session`;
   * and `--resume` accepts a TITLE as well as an id, failing as ambiguous on duplicates.
   */
  sessionIdFlag: boolean
  /**
   * Model ids this CLI lists, from `grok models` — the CLI's own catalogue, so there is no allowlist
   * to maintain and a model shipped tomorrow appears without a code change.
   *
   * Empty when the subcommand fails, is unparseable, or grok is not installed: the UI then offers no
   * model switching, which is the pre-feature behaviour. Never a partial list.
   */
  models: string[]
}

/** Unprobed grok ⇒ omit the flag, offer no models ⇒ today's command line, byte-identical. */
export const UNKNOWN_GROK_CLI_CAPS: GrokCliCaps = { sessionIdFlag: false, models: [] }

export interface CursorCliCaps {
  /** `cursor-agent models`: id + label, the account's own catalogue. [] when it cannot be read. */
  models: { id: string; name?: string }[]
}

/** Unprobed cursor ⇒ no models ⇒ no model switching (the pre-feature behaviour). */
export const UNKNOWN_CURSOR_CLI_CAPS: CursorCliCaps = { models: [] }

export interface CursorApi {
  /** Never rejects; an unprobed or offline CLI resolves to the empty catalogue. */
  cliCaps(): Promise<CursorCliCaps>
}

export interface GrokApi {
  /** Capabilities of the local grok CLI (memoized in the shell; safe to call repeatedly).
   *  Never rejects — an unprobed CLI resolves to the fail-open caps. */
  cliCaps(): Promise<GrokCliCaps>
  /**
   * The session ids grok already has under this cwd.
   *
   * Needed because grok REFUSES a `--session-id` that already exists under the target session
   * directory — that is a launch error, not a resume, so a node handed a taken id never starts. An
   * array rather than a Set: a Set does not survive the IPC/WS-RPC boundary and would arrive empty,
   * which is the one wrong answer this call can give.
   */
  takenSessionIds(cwd: string): Promise<string[]>
}

/** The answer whenever the CLI version can't be determined: no `auto` flag → bare command, and no
 *  fullscreen-tui write (an unknown settings key can warn on old CLIs — silence is safer). */
export const UNKNOWN_CLAUDE_CLI_CAPS: ClaudeCliCaps = {
  version: null,
  autoPermissionMode: false,
  fullscreenTui: false,
  sessionIdFlag: false
}

/**
 * What the LOCAL `codex` binary can do, read from its own `--help` — see `core/codex-cli.ts`.
 *
 * Separate from `CodexIdentityCaps` on purpose, because the two have OPPOSITE Server Edition
 * answers: shared identity is declined there deliberately (a constant `false`), while the
 * approval vocabulary must be probed for real — the server's own machine is the one that runs its
 * Codex sessions. Folding them into one bag would have made the honest answer to one question the
 * silent absence of the other.
 */
export interface CodexCliCaps {
  /** The values this `codex` advertises for `--ask-for-approval`. `null` = not probed, no codex on
   *  PATH, or a help page we could not read — all of which mean "use the baseline vocabulary", not
   *  "this CLI accepts nothing". Measured: 0.146.0–0.148.0 list `untrusted, on-request, never`;
   *  0.149.0+ list `on-request, never`. */
  approvalValues: string[] | null
  /** Does this `codex` accept `--no-daemon`? `null` = unknown (not probed, no codex). Every
   *  nodeterm-launched plain Codex TUI carries the flag when this is `true`: from 0.157.0 a plain
   *  TUI otherwise runs inside ONE shared background app-server per CODEX_HOME that keeps the FIRST
   *  pane's `NODETERM_*` environment, attributing every later node's hooks and tool shells to that
   *  first node (see `codexNoDaemonFrom`). Optional so an older core's answer still type-checks. */
  noDaemon?: boolean | null
}

/** The answer before the probe has run, and for any surface that cannot speak for the CLI that will
 *  actually run the session (a relay tab, an SSH host). */
export const UNKNOWN_CODEX_CLI_CAPS: CodexCliCaps = { approvalValues: null, noDaemon: null }

/** Whether a Codex node launched on this machine right now would get a managed shared identity.
 *  Fed by core/codex-identity-caps.ts; the unknown answer is `false`, i.e. plain `codex`. */
export interface CodexIdentityCaps {
  shared: boolean
  /** Absolute path of the installed launcher, or null when it could not be written. */
  launcherPath: string | null
  /** Does the installed `codex` accept `--remote`? Feature-detected from its own `--help`. The one
   *  precondition that cannot be recovered from at runtime: the launcher execs, and a CLI without
   *  the flag dies on a usage error where no fallback is left. Unknown ⇒ false ⇒ plain codex, and
   *  "not probed" counts as unknown: when `appServer` is false the help spawns are skipped, so this
   *  reads false whatever the CLI's help page would have said. */
  remoteFlag: boolean
  /** Can this INSTALL run a shared app-server at all? `codex app-server daemon start` needs the
   *  standalone runtime the Codex installer manages; an npm (or snap) install has the `--remote`
   *  flag in its help and no such runtime, so it can never serve a shared identity. Unknown ⇒
   *  false ⇒ plain codex. */
  appServer: boolean
  /** Why shared identity is off by DESIGN rather than by probe, when it is. `unsupported-platform`
   *  = a Windows core (phase 1: not wired there yet; every node runs its own codex). Absent on
   *  every other answer — an older core never sends it. */
  unavailableReason?: 'unsupported-platform'
}

/** The answer before the probe has run, and the one the Server Edition gives on purpose. */
export const UNKNOWN_CODEX_IDENTITY_CAPS: CodexIdentityCaps = {
  shared: false,
  launcherPath: null,
  remoteFlag: false,
  appServer: false
}

/** A Codex node's identity mode, as reported by the node's own launcher at spawn time.
 *  `plain` carries the machine-readable reason the managed identity was unavailable. */
export interface CodexIdentityEvent {
  nodeId: string
  mode: 'shared' | 'plain'
  reason?: string
}

/** The Codex-specific surface. Small on purpose: everything else a Codex node needs already goes
 *  through the shared agent/pty APIs. */
export interface CodexApi {
  /** Would a Codex node launched right now get a managed shared identity on this machine?
   *  Never rejects — the unknown answer is `{ shared: false }`, i.e. plain `codex`. */
  identityCaps(): Promise<CodexIdentityCaps>
  /** What the local Codex CLI accepts, so a launch line only carries flag values this binary
   *  actually has. Never rejects — the unknown answer is `UNKNOWN_CODEX_CLI_CAPS`. */
  cliCaps(): Promise<CodexCliCaps>
  /** Fires when a Codex node's launcher reports its identity mode. `plain` is the fallback, and
   *  this event is what stops that fallback being silent. Returns unsubscribe. */
  onIdentity(listener: (e: CodexIdentityEvent) => void): () => void
}

export interface ClaudeApi {
  /** Capabilities of the local Claude CLI (memoized in the shell; safe to call repeatedly).
   *  Never rejects — an unknown version resolves to the fail-open caps. */
  cliCaps(): Promise<ClaudeCliCaps>
  /**
   * Reads a Claude session's full transcript as flat searchable lines ([] if unavailable).
   * Resolves by `sessionId` when known (exact); otherwise falls back to `cwd` (durable —
   * the newest transcript under that project dir, no live hook event required).
   * `accountId` scopes resolution to a managed Claude account's transcript root (default `~/.claude`).
   * `nodeId` (optional) lets an SSH-project node's transcript be located on its HOST when no hook
   * event has registered it in this app run — without it the search silently reads nothing there.
   */
  readTranscript(
    sessionId: string | undefined,
    cwd: string | undefined,
    accountId?: string,
    nodeId?: string
  ): Promise<TranscriptLine[]>
}

export type HandoffResult = { filePath: string } | { error: string }

/** Agent launch/gateway IPC. The renderer has no `process.env`; `${env:VAR}` expansion runs
 *  renderer-side against the `envSnapshot()` cache (src/renderer/lib/agentEnv.ts), so the
 *  Settings preview and the typed launch command share one assembler AND one environment — they
 *  cannot drift by construction. */
export interface AgentApi {
  /** A string-only snapshot of the main process environment (undefined entries omitted), for
   *  expanding `${env:VAR}` tokens in launch commands and the Settings preview. Desktop-window
   *  only: the browser/relay bridges resolve `{}` (a host env dump must never cross to a peer —
   *  the PR #195 leak class), and expansion there degrades to the missing-env refusal. */
  envSnapshot(): Promise<Record<string, string>>
  /** Query the configured gateway's OpenAI-compatible `/v1/models` endpoint. Never rejects. */
  discoverModels(settings: ModelGatewaySettings): Promise<ModelDiscoveryResult>
  /** Literal gateway credentials are write-only in the renderer. */
  gatewayCredentialStatus(): Promise<ModelGatewayCredentialStatus>
  saveGatewayCredential(apiKey: string): Promise<ModelGatewayCredentialStatus>
  clearGatewayCredential(): Promise<ModelGatewayCredentialStatus>
}

export interface HandoffApi {
  /**
   * Render the source agent's full conversation transcript (located by `sessionId`)
   * to a portable Markdown file under `<cwd>/.nodeterm/` and return its absolute path.
   * No summarization — the entire transcript including tool calls and outputs.
   */
  build(
    sessionId: string,
    agentId: string,
    sourceNodeId: string,
    cwd: string | undefined,
    accountId?: string
  ): Promise<HandoffResult>
}

export interface LicenseStatus {
  /** 'pro' when entitled, else null. */
  tier: string | null
  active: boolean
  /** Unix seconds when the entitlement TOKEN expires, or null — the offline grace window (the server
   *  mints 7-day tokens and the app re-mints every 6 h, so this rolls forward forever). It is NOT
   *  when the subscription ends and must never be shown as that; see `termEndsAt` (issue #800). */
  expiresAt: number | null
  /** Unix seconds when the current subscription term ends, as the server stated it beside the token,
   *  or null. Null is a first-class answer — a lifetime entitlement, a license with no expiry, or a
   *  server that does not send the field yet — and renders as no date at all. Display only. */
  termEndsAt: number | null
  /** Seat cap for the relay host (Team Access): premium → the token's seats (absent → 1), free/inactive → 0. */
  seats: number
  /** Last activation/refresh error reason code, or null. */
  error: string | null
}

/**
 * Where the entitlement behind this install came from. A verified entitlement's licenseId is NOT
 * always a keygen license id: a store purchase on a paired phone bridges Pro to the desktop and
 * mints `apple:<txn>` (App Store) or `google:<orderId>` (Google Play), and `free:` exists too. For
 * those the server makes zero keygen calls and answers `key: null, used: 0, seats: 0` — genuinely
 * "device counting does not apply here", which is a different fact from a failed read and from a
 * keygen license with no devices yet.
 */
export type LicenseSource = 'keygen' | 'apple' | 'google' | 'free'

/** What Settings → License shows: the key to copy and how much of the device cap is in use.
 *  A failed read is an ERROR, never "0 devices" — the two are different facts. */
export interface LicenseDetail {
  /** The license key to copy. `null` on a 200 is legitimate (a keygen policy that hides keys, a
   *  license predating the column, a non-keygen source) — it is NOT an error. */
  key: string | null
  /** Devices currently activated. May EXCEED `seats` if a cap was lowered after activation. */
  used: number
  seats: number
  /** The source the server stated, or null when it stated none — every error reply, and the
   *  release route's 200, which answers with counts only. Never inferred locally. */
  source: LicenseSource | null
  /** Null on success; a stable reason code otherwise ('unauthorized' | 'inactive' | 'offline' |
   *  'disabled' | 'too_soon' | 'not_applicable' | 'network'). A failed read is an error, never
   *  "0 devices". */
  error: string | null
  /** Days until another release is allowed — only set with error === 'too_soon'. */
  retryAfterDays?: number
}

export interface LicenseApi {
  /** Open Stripe checkout bound to this device and poll for the entitlement (no key paste).
   * `target` picks the link: 'seats' = the add-seats (quantity) link, else base Pro (default).
   * Returns the current status immediately; the active status arrives via onChange. */
  upgrade(target?: 'pro' | 'seats'): Promise<LicenseStatus>
  /** Activate a license key on this device. Returns the resulting status. */
  activate(key: string): Promise<LicenseStatus>
  /** Release this device's seat and clear the local license. */
  deactivate(): Promise<LicenseStatus>
  /** Current cached status (verifies the stored token offline). */
  getStatus(): Promise<LicenseStatus>
  /** Fires when the license status changes. Returns unsubscribe. */
  onChange(listener: (s: LicenseStatus) => void): () => void
  /** The license key + device usage for this machine's license. Authorized by the stored
   *  entitlement token — never by deviceId. */
  detail(): Promise<LicenseDetail>
  /** Deactivate every device on this license except this one. Throttled server-side to once
   *  per 30 days (error 'too_soon' + retryAfterDays). Answers with COUNTS only: no key and no
   *  source ride a successful release, so callers must merge rather than replace. */
  releaseOthers(): Promise<LicenseDetail>
}

/** The free-tier open-project limit (src/shared/project-limit.ts; core computes the state). Desktop
 *  only: the Server Edition's stub answers `INACTIVE_PROJECT_LIMIT` and claims `disabled`,
 *  and a relay tab keeps the local preload — the allowance is this machine's, never the host's. */
export interface ProjectLimitApi {
  /** The current state. Cheap and offline: it never waits on the network. */
  state(): Promise<ProjectLimitState>
  /** Claim this device's allowance from the server (lazily, at the limit moment). Never rejects
   *  for a network or server failure — that is `ok: false` with the state as it stands. */
  claim(): Promise<ClaimResult>
  /** Fires with the new state whenever it changes. Main sends it to this machine's windows only
   *  (never broadcast to relay peers). Returns unsubscribe. */
  onChange(listener: (s: ProjectLimitState) => void): () => void
}

export type PhoneApprovalResult = {
  status: 'persisted' | 'approved' | 'saved-disconnected' | 'stale' | 'persistence-failed'
}

export interface RemoteHostApi {
  /**
   * Enter host mode: mint a pairing token, connect to the relay as the host, and return the
   * pairing offer string (`nodeterm://pair?code=…`) to hand to a client. Rejects if the device
   * is not entitled to Pro (or in a dev build without NODETERM_RELAY_URL).
   */
  start(): Promise<{ offer: string }>
  /** Leave host mode: close the relay connection (ends served PTYs, drops client access). */
  stop(): Promise<void>
  /**
   * Push the host's current active-project canvas snapshot to main. Main keeps the latest
   * and (re)broadcasts it to a connected client (debounced). Safe to call when not hosting.
   */
  sendCanvasState(state: CanvasState): void
  /**
   * Listen for a client's mutation command that the host renderer must apply to its React
   * Flow (the single writer). Returns an unsubscribe function.
   */
  onApplyMutation(listener: (mutation: CanvasMutation) => void): () => void
  /**
   * Fires when a client finishes the E2EE handshake and is awaiting approval. The host must call
   * `approve()` before any of the client's pty/fs RPCs are served; `sas` is the channel
   * verification code to display. Returns an unsubscribe function.
   */
  onPeerPending(
    listener: (info: { sas: string | null; id: string; pub?: string | null; standing?: boolean }) => void
  ): () => void
  /** The pending prompt expired host-side (120 s) — the dialog must drop or re-arm, else its
   *  Approve is a silent no-op against a dead id (issue #372). */
  onPeerPendingCleared(
    listener: (info: { id: string | null; pub?: string | null }) => void
  ): () => void
  /** Standing phone consent: persist the displayed handshake identity before granting access.
   *  Both fields must match a bounded pending request. Desktop-only; Server rejects explicitly. */
  approvePhone(id: string, pub: string): Promise<PhoneApprovalResult>
  /** Legacy interactive (single-use offer) approval; does not persist a device pin. */
  approve(id: string, pub?: string): void
  /** Reject the pending client → the connection is dropped. Same id/pub matching as approve. */
  reject(id: string, pub?: string): void
  /**
   * Start/stop the standing (phone) relay host so a paired phone can reach this Mac from anywhere.
   * Mirrors `settings.phoneAccessEnabled`.
   */
  setPhoneAccess(enabled: boolean): void
}

/**
 * Payload of `relayHost.onPeerPending`: a client has finished the E2EE handshake over the new
 * relay tunnel and is awaiting the host human's approval. `id` addresses this pending peer for
 * `confirm(id)`; `sas` is the channel verification code both humans compare (null before the key is
 * derived); `peerKeyB64` is the peer's stable box public key to pin on approval.
 */
export interface RelayPeerPending {
  id: string
  sas: string | null
  peerKeyB64: string
  /** Team Access: the invitee email this seat was invited with, if any. DISPLAY label only (never
   *  trust/identity — the SAS is the gate); used to tag the row in the connected-devices list. */
  email?: string
}

/**
 * HOST side of the new E2EE relay tunnel (Stage 4) — the successor to `RemoteHostApi`. A connected
 * peer becomes a first-class CorePlatform client (it exchanges raw rpc frames), so this surface is
 * only the mutual-approval gate plus enter/leave, not a per-verb API. Desktop-only (Electron);
 * the Server Edition browser build degrades every member to `E_UNSUPPORTED`/no-op.
 */
export interface RelayHostApi {
  /**
   * Enter host mode over the relay: connect and return a pairing offer string to hand to a client.
   * Rejects if the device is not entitled (or a dev build without the relay URL). `projectId` is the
   * single project this hosting session shares with the peer; omit for the legacy whole-workspace view.
   */
  start(projectId?: string): Promise<{ offer: string; id: string }>
  /**
   * Team Access: ADD a seat — mint a fresh pairing offer for one more device (no supersede), tagged
   * with the optional invitee `email` (display label only). Rejects `E_SEATS_FULL` when the licensed
   * seat cap is reached, and with the Pro / dev-build errors `start` uses. `projectId` scopes the
   * shared project as in `start`. Resolves with the offer AND the seat's `id` — the settings UI uses
   * it to show the pending row immediately and to `revoke` a seat whose peer never connects.
   */
  invite(opts?: { projectId?: string; email?: string }): Promise<{ offer: string; id: string }>
  /** Leave host mode: close every bridged peer in the pool. */
  stop(): Promise<void>
  /**
   * Which of these projects may NOT be shared, with the reason (a folder that is the disk root, the
   * home directory or an ancestor of either — every file under it would be readable). The invite
   * UI disables those projects; `start`/`invite` refuse them host-side too. Projects absent from the
   * answer may be shared.
   */
  scopeProblems(projectIds: string[]): Promise<Record<string, string>>
  /**
   * Team Access: per-peer revoke — cut ONE bridged peer's live session immediately (by its id) and
   * free its seat. Distinct from `stop()` (which drops all).
   */
  revoke(id: string): void
  /**
   * Fires when a client finishes the handshake and is awaiting approval. The host must `confirm()`
   * before the peer is admitted as a client. Returns an unsubscribe function.
   */
  onPeerPending(listener: (info: RelayPeerPending) => void): () => void
  /** Approve the pending peer (by its pending id) after comparing the SAS → it joins as a client. */
  confirm(id: string): void
  /** Fires when a bridged peer becomes a live client (both humans confirmed). Returns unsubscribe.
   *  `email` is the seat's invite label, if any (Team Access). */
  onOpen(listener: (info: { id: string; email?: string }) => void): () => void
  /** Fires when a bridged peer's connection drops. Returns an unsubscribe function. */
  onClosed(listener: (info: { id: string }) => void): () => void
}

/**
 * CLIENT side of the new E2EE relay tunnel (Stage 4) — the successor to the deleted legacy relay
 * client dialect. The client exchanges raw rpc.ts frames (JSON strings) with the host over the encrypted tunnel rather
 * than a per-verb channel set. Desktop-only (Electron); the Server Edition browser build degrades
 * every member to `E_UNSUPPORTED`/no-op.
 */
export interface RelayClientApi {
  /**
   * Connect to a host by its pairing offer string. Gates on entitlement (rejects otherwise, and in
   * dev builds without the relay URL). Resolves with a `connectionId` to address the methods below.
   */
  connect(offer: string): Promise<string>
  /**
   * Listen for the channel SAS once the handshake completes, so the client human can compare it
   * with the code shown on the host before approving. Returns an unsubscribe function.
   */
  onSas(connectionId: string, listener: (sas: string | null) => void): () => void
  /** Confirm the SAS on this side (the client half of the mutual-approval gate). */
  confirm(connectionId: string): void
  /** Fires once the host approves this connection → the client may begin exchanging frames. */
  onApproved(connectionId: string, listener: () => void): () => void
  /** Cast an outbound rpc frame (a JSON string) at the host over the tunnel. */
  send(connectionId: string, frame: string): void
  /** Listen for an inbound rpc frame (a JSON string) from the host. Returns an unsubscribe. */
  onFrame(connectionId: string, listener: (frame: string) => void): () => void
  /** Fires when the connection's relay socket drops (host/relay gone). `reason` is set only when
   *  the host refused this device over the tunnel first (a hosted team: an owner declined, removed
   *  it, or nobody answered in time). Returns unsubscribe. */
  onClosed(connectionId: string, listener: (reason?: RelayClosedReason) => void): () => void
  /** Close a connection: end the relay socket and drop access to the host. */
  disconnect(connectionId: string): void
}

/** Why a host refused a relay client before closing it (the core relay's `TrustDeniedReason`). */
export type RelayClosedReason = 'denied' | 'removed' | 'expired'

/**
 * The hosted teams this desktop has joined by `nodeterm://join` code. A join code is passed to
 * `relayClient.connect` like a pairing offer; these are the bookmarks that connect leaves behind.
 * Desktop-only: a browser cannot join a relay host, so the Server Edition answers an empty list.
 */
export interface RelayHostedApi {
  /** The bookmarks, never their device tokens. `approved` = both humans approved this device on
   *  that host, so a reconnect needs no SAS comparison on this side. */
  bookmarks(): Promise<Array<{ hostId: string; label: string; approved: boolean; code: string }>>
  /** Forget a bookmark (its device token and its approval). Rejects while a join for that team is
   *  still minting or joining: that join would write the bookmark straight back. */
  removeBookmark(hostId: string): Promise<void>
}

/** A hosted team member's role (the core team store's `TeamRole`). */
export type HostedRole = 'owner' | 'editor' | 'commenter' | 'viewer'

/** A device waiting for an owner to approve it (core hosted-service's `HostedPending`). */
export interface HostedPending {
  pendingId: string
  /** The code both people compare out of band. */
  sas: string
  peerKeyB64: string
  /** Host wall-clock ms the request arrived. */
  since: number
}

/** Why a pending request stopped being pending. `approved` / `denied` may be ANOTHER owner's answer;
 *  `replaced` = the same device asked again (its newer request arrives on its own). */
export type HostedPendingClosedReason = 'approved' | 'denied' | 'expired' | 'replaced' | 'gone'

/** What `relay:hosted:self` answers: this device's role, its label on the team, the host's label. */
export interface HostedSelf {
  role: HostedRole
  label: string
  hostLabel: string
}

/**
 * The hosted team verbs of ONE relay session. Only a relay tab joined by a `nodeterm://join` code has
 * it (`NodeTerminalApi.hosted`); a local session, a Server Edition browser and a Team Access relay
 * tab (desktop to desktop) never do. The host answers every one of these itself and judges the
 * caller's role: `self` is open to any member, the rest are owner-only.
 */
export interface HostedSessionApi {
  self(): Promise<HostedSelf>
  /** The requests still waiting (owner-only). Pulled once on open; the events below are deltas. */
  pending(): Promise<HostedPending[]>
  /** The team's join code, or null when the host has none to hand out. */
  inviteCode(): Promise<string | null>
  /** Admit a waiting device with `role`. False when it is gone or another owner answered first. */
  approve(pendingId: string, role: HostedRole): Promise<boolean>
  /** Refuse a waiting device. False when it is already gone. */
  deny(pendingId: string): Promise<boolean>
  onPeerPending(listener: (p: HostedPending) => void): () => void
  onPendingClosed(listener: (p: { pendingId: string; reason: HostedPendingClosedReason }) => void): () => void
  /** The team's shared projects changed (share or unshare on the host): their whole set. */
  onSharedChanged(listener: (p: { projectIds: string[] }) => void): () => void
}

/** A paired device as exposed to the renderer — the bearer token is never included. */
export interface PairedDevice {
  id: string
  name: string
  /** epoch-ms the device was paired. */
  pairedAt: number
  /** epoch-ms the host agent last saw this device (0 = never). */
  lastSeenAt: number
  /**
   * The phone's OWN device id — what the relay backend keys its device row on, as opposed to
   * `id`, which is ours. Absent for devices paired before this field existed; that is NOT "there
   * is no server row we can name", because a revoke then falls back to `id`, which is the value
   * the mint sent as the row's key whenever the phone supplied no id of its own (see
   * `revokeDevice` in main/pairing-service.ts, including the residual case it cannot name). An id,
   * not a secret, which is why it may cross to the renderer.
   */
  relayDeviceId?: string
}

/**
 * The server leg of a device revoke — three states, because two cannot tell the truth apart.
 * 'ok' = the backend confirmed; 'failed' = we asked and were refused or could not reach it;
 * 'skipped' = we did not ask and that is fine (no entitlement to sign with — a free-tier desktop
 * has no Pro of ours on that phone to reclaim — or no such device to name). Only 'failed' is a
 * warning: reporting 'skipped' as a failure would tell a free user their phone's Pro is stuck.
 *
 * 'ok' is the backend's 204, which is idempotent and reveals nothing about WHICH row it applied
 * to — see the residual-leak note on `revokeDevice` in main/pairing-service.ts before treating it
 * as proof that a particular phone lost Pro.
 */
export type DeviceRevokeServerOutcome = 'ok' | 'failed' | 'skipped'

/**
 * Both legs of a device revoke, reported independently so a half-finished removal can never render
 * as a clean one (the same discipline as remote/revocation.ts's persisted/killed).
 */
export interface DeviceRevokeResult {
  /** The phone's relay trust (every phone relay pin + live relay session), its authorized_keys line
   *  and its agent.json entry were all removed from this machine. */
  local: boolean
  /** Whether the phone's Pro entitlement was taken back on the relay backend. */
  server: DeviceRevokeServerOutcome
}

/** Phone-pairing (nodeterm iOS "scan a QR" flow) bridge. */
export interface PairingApi {
  /** Start the one-shot LAN listener; resolves with the QR payload + an SSH-reachable hint. */
  start(): Promise<{
    payload: string
    sshOpen: boolean
    relayPlan?: 'ok' | 'dev' | 'off'
    /** false = relay-only host (Windows): no SSH key is installed and the QR waits for the relay,
     *  not sshd (`pairingGate`). Absent from an older main process ⇒ treat as true. */
    sshKey?: boolean
    /** Windows only, explanation only: which authorized_keys file sshd reads for this account. */
    windowsKeyFile?: 'administrators' | 'profile' | 'unknown'
  }>
  /** Cancel an in-flight pairing (e.g. when the settings section unmounts). */
  stop(): Promise<void>
  /** Fires once when pairing finishes (ok=true paired, ok=false timeout / relay-only mint failure).
   *  Returns unsubscribe. */
  onDone(
    cb: (result: {
      ok: boolean
      relay?: 'ok' | 'off' | 'failed' | 'dev'
      reason?: 'timeout' | 'relay-failed'
      reached?: boolean
    }) => void
  ): () => void
  /** Live re-probe of 127.0.0.1:22, so the "SSH server is off" warning can clear the moment the
   *  user turns it on (polled by the UI only while the warning is showing). */
  probeSsh(): Promise<boolean>
  /** Open this OS's settings page for its SSH server — Sharing → Remote Login on macOS, Optional
   *  features on Windows (`sshServerCopy().settingsUrl`, the same table the warning's copy comes
   *  from). The deep link is a main-side constant: neither scheme passes shellOpenExternal's
   *  http(s) allowlist. A no-op where that table offers no URL, and the UI shows no button there. */
  openRemoteLoginSettings(): Promise<void>
  /** List paired devices from ~/.nodeterm/agent.json (never includes the token). */
  listDevices(): Promise<PairedDevice[]>
  /**
   * Revoke a device: remove its registry entry, delete its authorized_keys line, and take its Pro
   * entitlement back on the relay backend. Never rejects for a leg that failed — read the result.
   */
  revokeDevice(id: string): Promise<DeviceRevokeResult>
  /** Push webhook (shared/push-webhook.ts): what token is live for this machine — never its value. */
  webhookStatus(): Promise<PushWebhookResult<PushWebhookTokenInfo | null>>
  /** Mint (or rotate) the token. The value in the result is the only copy that will ever exist
   *  outside the user's own storage: the backend keeps only its hash, and this app keeps nothing. */
  webhookMint(): Promise<PushWebhookResult<PushWebhookMinted>>
  webhookRevoke(): Promise<PushWebhookResult<true>>
  /** The API base the examples should name (NODETERM_API_BASE or production). */
  webhookEndpoint(): Promise<string>
}

/** Team presence (docs/team-presence.md). All of it is transient — nothing here is persisted. */
export interface PresenceApi {
  /** Announce {name, color}. Resolves with THIS client's own id (so it never draws its own
   *  cursor) plus the current peer table. */
  hello(identity: PeerIdentity): Promise<{ clientId: ClientId; peers: PeerState[] }>
  /** Publish the local cursor in FLOW coordinates (null when it leaves the canvas). */
  cursor(cursor: { x: number; y: number } | null): void
  /** Publish the node the local user is working in (null = none). */
  focus(nodeId: string | null): void
  /** Publish live cursor-chat text (null closes the bubble). */
  chat(text: string | null): void
  /** Publish the live dino game we are the authority for (null = stopped/idle). Spectators read
   *  the matching peer's `dino` and render `snap` instead of running their own sim. */
  dino(payload: { nodeId: string; snap: DinoSnapshot } | null): void
  /** Publish the project (canvas) we are looking at — peers on other projects are never drawn
   *  on our canvas, and we are never drawn on theirs (null = no project open). */
  project(projectId: string | null): void
  /** Full peer-table snapshot (on join). Returns unsubscribe.
   *  Exactly one subscriber (the presence store, src/renderer/state/presence.ts): the browser
   *  bridge drains its early-event buffer into the FIRST subscriber, so a second one gets nothing.
   *  Components read the store; they never subscribe here. */
  onSync(listener: (peers: PeerState[]) => void): () => void
  /** Single-peer diff (join / update / leave). Returns unsubscribe.
   *  Exactly one subscriber (the presence store) — same reason as onSync. */
  onPeer(listener: (diff: PeerDiff) => void): () => void
}

/** Keyboard-shortcut plumbing the RENDERER cannot do for itself. */
export interface ShortcutsApi {
  /** Tell the shell that a shortcut recorder is armed (`true`) or released (`false`), so the
   *  desktop's `before-input-event` intercepts stand down and the chord being recorded — ⌘W and
   *  ⌘M among them — reaches the recorder instead of closing the user's selected nodes. A claimed
   *  chord never reaches the page, so the recorder's own preventDefault cannot substitute for
   *  this. Fire-and-forget. **The `false` leg is not optional**: the bit is global, so a recorder
   *  that arms and never releases leaves those chords dead app-wide. Server Edition: a documented
   *  no-op (a browser tab has no application menu to steal a chord back from, so nothing
   *  intercepts). */
  setRecording(active: boolean): void
  /** Mirror whether an xterm currently holds keyboard focus, so the desktop's intercepts can stand
   *  down under the `terminal-first` shortcut policy — `before-input-event` fires before any
   *  renderer handler could answer, so main needs the answer in advance. Sent on CHANGE only.
   *  Fire-and-forget, and **not optional**: the mirror is the only thing that makes the policy
   *  reach the three main-intercepted chords. Read fail-safe on the far side (a missing or stale
   *  mirror = not focused = intercepts on), so the failure mode of never sending is the app
   *  behaving as it did before the policy existed. Server Edition: a documented no-op, like
   *  `setRecording` — a browser tab has no application menu to steal a chord back from. */
  setTerminalFocused(focused: boolean): void
}

/**
 * Trigger nodes (issue #493): the card's IPC surface. `arm` binds this machine's consent to the
 * exact spec the user was shown (content-bound — see @shared/trigger); `runNow` chooses only WHEN,
 * never WHAT (the payload is resolved core-side from the node's persisted content). Real on
 * desktop and the Server Edition; the relay stub refuses (another machine's arm store is not ours
 * to write).
 */
export interface TriggersApi {
  arm(projectId: string, nodeId: string, spec: import('./trigger').TriggerSpec): Promise<boolean>
  disarm(projectId: string, nodeId: string): Promise<void>
  status(projectId: string, nodeId: string): Promise<import('./trigger').TriggerNodeStatus>
  runNow(
    projectId: string,
    nodeId: string
  ): Promise<{ outcome: 'fired' | 'missed' | 'failed' | 'queued'; detail?: string }>
}

/** `nodeterm://` links (see main/open-link.ts, @shared/open-link). */
export interface OpenLinkApi {
  /** The renderer is listening: main delivers any link that arrived before (a cold start). */
  ready(): void
  /** An `open` link for the confirm sheet. */
  onRequest(listener: (req: import('./open-link').OpenLinkPrompt) => void): () => void
  /** A `pair` / `join` link: route to the existing pairing / join flow, never auto-accept. */
  onPair(listener: (link: { kind: 'pair' | 'join'; url: string }) => void): () => void
  /** A refused or dropped link, as one sentence for a toast. */
  onNotice(listener: (n: { text: string }) => void): () => void
  /** The human's choice; main re-checks it and answers with the final open. */
  accept(id: string, choice: import('./open-link').OpenLinkChoice): Promise<import('./open-link').OpenLinkAcceptResult>
  /** The sheet was dismissed (or replaced): forget the request. */
  cancel(id: string): void
}

export interface NodeTerminalApi {
  pty: PtyApi
  workspace: WorkspaceApi
  projectSettings: ProjectSettingsApi
  projectSetup: ProjectSetupApi
  worktree: WorktreeApi
  dialog: DialogApi
  settings: SettingsApi
  integrations: IntegrationsApi
  speech: SpeechApi
  ssh: SshApi
  sshProject: SshProjectApi
  sshFs: SshFsApi
  git: GitApi
  clipboard: ClipboardApi
  shell: ShellApi
  fs: FsApi
  media: MediaApi
  browser: BrowserApi
  files: FilesApi
  updates: UpdateApi
  announcements: AnnouncementsApi
  license: LicenseApi
  projectLimit: ProjectLimitApi
  contextLink: ContextLinkApi
  boardLog: BoardLogApi
  logs: LogApi
  githubIssues: import('./github-issues').GitHubIssuesApi
  githubControl: import('./github-issues').GitHubControlApi
  usage: UsageApi
  sessionMemory: SessionMemoryApi
  devPorts: import('./dev-ports').DevPortsApi
  /** "Open recent" — the newest agent conversations in this machine's CLI histories. */
  recentConversations: import('./recent-conversations').RecentConversationsApi
  wallpaper: import('./wallpaper').WallpaperApi
  /** Run node host side (launch.json, devices, launcher, status, stop, signals, reload on save). */
  runConfig: import('./run-config').RunConfigApi
  /** Simulator node host side (macOS desktop): live iOS simulator screen + input. */
  simulator: import('./simulator').SimulatorApi
  triggers: TriggersApi
  context: ContextApi
  canvas: CanvasApi
  /** Which projects publish their canvas ops even when alone (see CanvasAuthorityApi). */
  canvasAuthority: CanvasAuthorityApi
  codex: CodexApi
  claude: ClaudeApi
  grok: GrokApi
  cursor: CursorApi
  /** Custom-agent launch/preview (env-var expansion + command assembly). */
  agent: AgentApi
  chat: ChatApi
  claudeAccounts: ClaudeAccountsApi
  codexAccounts: CodexAccountsApi
  transcripts: TranscriptsApi
  remoteHost: RemoteHostApi
  relayHost: RelayHostApi
  relayClient: RelayClientApi
  relayHosted: RelayHostedApi
  /** "Share with team" for an SSH project. Desktop only (the Server Edition and relay tabs answer
   *  `E_UNSUPPORTED`). */
  shareTeam: ShareTeamApi
  /** The hosted team verbs of THIS session's host — present only on a relay tab joined by a hosted
   *  team's join code; absent everywhere else (local, Server Edition, Team Access relay tabs). */
  hosted?: HostedSessionApi
  handoff: HandoffApi
  pairing: PairingApi
  presence: PresenceApi
  shortcuts: ShortcutsApi
  /** `nodeterm://` links clicked outside the app. Desktop only (the Server Edition has no URL
   *  scheme: its stub never fires and refuses accept). */
  openLink: OpenLinkApi
  /** Fires when the user presses Cmd/Ctrl+M (toggle markdown view). Returns unsubscribe. */
  onMarkdownToggle(listener: () => void): () => void
  /** Fires when the user presses Cmd/Ctrl+W (close selected node). Returns unsubscribe. */
  onCloseNode(listener: () => void): () => void
  /** Fires when the user presses Cmd/Ctrl+0 (zoom the canvas back to 100%). Desktop only: the
   *  key is intercepted in main because Electron's default View menu owns the accelerator. In the
   *  Server Edition the renderer's own keydown handler sees the key and this is a no-op stub. */
  onZoomActualSize(listener: (mods?: ZoomActualSizeModifiers) => void): () => void
  /** Native View menu → Snap to Grid toggle. Returns unsubscribe. */
  onToggleAutoAlign(listener: () => void): () => void
  /** Native View menu → Fit View. Returns unsubscribe. */
  onFitView(listener: () => void): () => void
  /** Native View menu → Toggle Kanban / Canvas view. Returns unsubscribe. */
  onToggleKanban(listener: () => void): () => void
  /** Fires when the native app menu's "Settings…" item (⌘,) is clicked. Returns unsubscribe. */
  onOpenSettings(listener: () => void): () => void
  /** Close the application window (Cmd/Ctrl+W fallback when no node is selected). */
  closeWindow(): void
  /** Bring the app window to the foreground (show + OS focus). Called after a file is DROPPED
   *  into a terminal: on macOS a drag-drop from another app (Finder/browser) does not activate
   *  the destination app, so the drag-source keeps keyboard focus and the user's next keystrokes
   *  land in the WRONG application — `term.focus()` (DOM-only) can't fix that. Desktop raises the
   *  BrowserWindow; the browser bridge does a best-effort `window.focus()`. */
  focusWindow(): void
  /** Set the macOS Dock badge to the unread-message count (0 clears it). */
  setBadgeCount(count: number): void
  /** Apply the UI-scale setting as page zoom for THIS window (desktop: `webFrame.setZoomFactor`).
   *  The preload re-clamps through `resolveUiScale` — the value originates in hand-editable
   *  settings.json, and the boundary must not trust the caller to have done it. Server Edition:
   *  documented no-op — a browser page cannot set its own page zoom, and the browser already owns
   *  the identical mechanism (Cmd/Ctrl+±). */
  setUiZoomFactor(factor: number): void
  /** Absolute filesystem path for a dropped/picked File (for drag-into-terminal). */
  getPathForFile(file: File): string
  /** Absolute writable base dir (Electron userData) for app-managed files like default worktrees. */
  userDataDir(): Promise<string>
  /** Show an OS notification (main suppresses it if the window is focused). 'failed' =
   *  the OS rejected it (e.g. macOS permission denied) — surface it, don't ignore it. */
  notify(payload: NotifyPayload): Promise<'shown' | 'failed' | 'skipped'>
  /** Open the OS notification settings pane (macOS; no-op elsewhere) to re-grant permission. */
  openNotificationSettings(): Promise<void>
  /** Fires when a notification is clicked, asking the renderer to focus a node. Returns unsubscribe. */
  onFocusNode(listener: (nodeId: string) => void): () => void
  /** Fires when the shell's memory-pressure monitor (core/memory-pressure.ts) sees the host — or
   *  this process's own RSS — cross a watermark: the renderer answers by running its reclaim
   *  levers (hidden WebGL contexts, parked terminals). At most one fire a minute, so the levers
   *  need only be idempotent, not cheap. Returns unsubscribe. Server Edition: never fires (the
   *  pressure levers run host-side there; a browser tab's memory belongs to the browser). */
  onMemoryPressure(listener: (severity: 'warning' | 'critical') => void): () => void
  /** Fires when the main window is put away (`'hidden'`: close-to-tray, macOS hide-on-close,
   *  minimize) or brought back (`'shown'`). The renderer answers by treating every terminal as
   *  offscreen while hidden (renderer/terminal/window-backgrounded.ts). Returns unsubscribe.
   *  Server Edition: never fires — a browser tab being hidden is a routine tab switch, not the app
   *  being put away, so the levers stay on their viewport-only behaviour there. */
  onWindowVisibility(listener: (state: 'hidden' | 'shown') => void): () => void
  /** Fires when THIS MACHINE's pty-device pressure band changes (core/pty-pressure.ts): the
   *  renderer raises/lowers the banner that warns before `kern.tty.ptmx_max` stops every new
   *  terminal from opening. Band changes only, re-sent for a held band at most once every five
   *  minutes; `level: 'none'` means the banner should come down. Returns unsubscribe.
   *  Server Edition: never fires — the reaper leg runs host-side only (see src/server/index.ts). */
  onPtyPressure(listener: (reading: PtyPressure) => void): () => void
  /** Fires when a macOS trackpad gesture (two-finger scroll or pinch) opens or closes on the
   *  main window — edge transitions from the main process's raw input stream
   *  (main/trackpad-gesture.ts), a handful per physical gesture. The canvas wheel router uses
   *  this as ground-truth device identity so a precise-pixel mouse (MX Master) can zoom while the
   *  trackpad pans. Returns unsubscribe. Server Edition: never fires — a browser tab has no raw
   *  input stream, and the router keeps its delta-shape heuristics there. */
  onCanvasTrackpadGesture(listener: (active: boolean) => void): () => void
  /** Raise this Mac's pty-device ceiling (`kern.tty.ptmx_max`) now AND across reboots, behind
   *  macOS's own administrator-password dialog. Called ONLY from the banner's explicit
   *  "Fix automatically…" click — never on the app's initiative. macOS only; a dismissed password
   *  dialog resolves `{ ok: false, canceled: true }`, which is not an error to report or retry. */
  raisePtyDeviceLimit(): Promise<PtyLimitFixResult>
  /** Answer a Claude permission request via the deterministic hook-reply channel (spec:
   *  docs/hook-reply-approvals.md). Writes the one-line answer file the held hook is polling
   *  (`~/.nodeterm/pending/<pendingId>.answer`) on the host the agent runs on — the LOCAL fs for a
   *  local project, or the remote host over the project's ControlMaster for an SSH project. Resolves
   *  `true` when the file was written, `false` on any failure (invalid pendingId, unknown node,
   *  unsupported project, fs/exec error).
   *
   *  `decision` is the original contract and still works alone. An optional structured `answer`
   *  (`PermissionAnswer`: approve a plan with a follow-on mode, send plan feedback, answer an
   *  AskUserQuestion) wins over it; core validates it against the held request file on the agent's
   *  host and refuses (`false`) when that request is gone or the answer does not fit it. A plain
   *  `allow` on a held AskUserQuestion is refused too — Claude would drop it. */
  answerPermission(payload: AnswerPermissionPayload): Promise<boolean>
  /** Notify the core that the user READ a finished (done) session on this surface (the unread-clear
   *  funnel calls it when the node's latest state is `done`). The core marks the node's done inbox
   *  event(s) resolved (phone Inbox archives the card) and re-sends an 'end' live-update so the
   *  paired phone dismisses its lingering DONE Live Activity. Fire-and-forget; no-op if the node has
   *  no unresolved done event. */
  ackDone(nodeId: string): void
  /** Fires when the host swept a phone read-ack (`~/.nodeterm/acks/<nodeId>.seen`) for a finished
   *  session: the renderer should drop the node's unread flag WITHOUT re-acking (call
   *  `clearUnread(id, { external: true })`, so it does not loop back into `ackDone`). Arg is the
   *  node id. Returns unsubscribe. See core/ack-sweep.ts. */
  onUnreadClear(listener: (nodeId: string) => void): () => void
  /** Fires on each normalized agent hook event (working/done/waiting/subagent/…). Returns unsubscribe. */
  onAgentStatus(listener: (e: NormalizedAgentEvent) => void): () => void
  /** The core's per-node agent states as they stand now, read off its agent-status mirror (newest
   *  `AGENT_STATUS_SNAPSHOT_MAX`; no `state` for an identity-only or restored entry). A relay tab asks
   *  right after subscribing to `onAgentStatus`, so it does not start blank; a non-editor peer gets
   *  the shared nodes only. Rejects on a core that predates the channel. */
  agentStatusSnapshot(): Promise<AgentStatusSnapshotEntry[]>
  /** Report a node's Eco hibernation flag to the core (the renderer owns the flag; the core only
   *  mirrors it into the agent-status file so the phone can render SLEEPING). Fire-and-forget;
   *  called on every `setHibernated` change and replayed for the persisted set at boot. */
  reportHibernated(nodeId: string, on: boolean): void
  /** Seed the core's agent-status mirror with node identities from this renderer's persisted
   *  agentStatus store (see `@shared/agent-identity-seed`). Fire-and-forget and add-only: the core
   *  fills only nodes it has no session for, and validates every field. A relay tab's api is a
   *  deliberate no-op — its nodes belong to another core, whose own renderer seeds it. */
  seedAgentIdentity(entries: IdentitySeedEntry[]): void
  /** Fires when the core asks this renderer to WAKE a hibernated node NOW (a phone viewer just
   *  attached to its session over the relay). A nudge with `wakeHibernatedNode`'s exact contract:
   *  re-read the flag, no-op when not hibernated or not mounted. Returns unsubscribe.
   *  Desktop-only signal (the relay host lives in the desktop main process); the ws-bridge
   *  subscribes to nothing and returns a no-op unsubscribe. */
  onAgentWake(listener: (nodeId: string) => void): () => void
  /** Fires with the CURRENT set of node ids that have a live relay (phone) viewer attached — the
   *  full set each change, never a delta. Feeds `isNodeWatched` so Eco cannot hibernate a session
   *  someone is watching from a phone. Desktop-only signal, like `onAgentWake`. */
  onRemoteViewers(listener: (nodeIds: string[]) => void): () => void
  /** Fires when the core asks this renderer to reload a terminal node's view in place (bump its
   *  `respawnNonce` — fresh attach to the SAME tmux session) — the phone relay host's
   *  `node.refresh` verb. A nudge with the `onAgentWake` contract: no-op for an unknown,
   *  non-terminal or unmounted node. Desktop-only signal (the relay host lives in the desktop
   *  main process); the ws-bridge subscribes to nothing and returns a no-op unsubscribe. */
  onAgentRefreshNode(listener: (nodeId: string) => void): () => void
  /** Fires when the core asks this renderer to rename a node on a phone's behalf (the relay
   *  host's `node.rename` verb, title already sanitized host-side). The renderer routes it
   *  through the same `renameSession` funnel as the node header. Desktop-only signal, like
   *  `onAgentRefreshNode`. */
  onAgentRenameNode(listener: (payload: { nodeId: string; title: string }) => void): () => void
  /** Fires with live subagent transcript chunks while a subagent runs. Returns unsubscribe. */
  onSubagentActivity(listener: (e: SubagentActivity) => void): () => void
  /** Fires when an agent's `nodeterm` CLI requests a canvas action. Returns unsubscribe. */
  onAgentControl(
    listener: (cmd: {
      requestId: string
      sourceNodeId: string
      verb: string
      args: Record<string, string>
    }) => void
  ): () => void
  /** Reply to an agent control request (resolves the awaiting CLI call in main). */
  sendAgentControlResult(payload: {
    requestId: string
    ok: boolean
    message?: string
    result?: unknown
    error?: string
  }): void
  /** The `browser` verb resolve round-trip (S8 PR 7): main asks the renderer to resolve a source
   *  node's owning project, control-capability and the LIVE per-project capability value. The
   *  renderer answers over `sendBrowserControlResolveResult` and NEVER runs a CDP command. */
  onBrowserControlResolve(
    listener: (req: { requestId: string; sourceNodeId: string; browserNodeId?: string }) => void
  ): () => void
  /** Answer a browser-control resolve. `ok:false` carries a named refusal; `ok:true` carries the
   *  facts main turns into its own (owner + capability + CDP-gate) decision. `sourceTitle`/
   *  `browserTitle` are for the cookie-read trace only (PR 9) — never a security input. */
  sendBrowserControlResolveResult(payload: {
    requestId: string
    ok: boolean
    refusal?: string
    projectId?: string
    projectCwd?: string
    sourceControlCapable?: boolean
    capabilityOn?: boolean
    sourceTitle?: string
    browserTitle?: string
  }): void
  /** The phone Chat verbs' round-trip (main/remote/host-chat.ts): main asks this renderer for a
   *  node's chat status, or to send a phone message through the ⌘M composer's own gate. Desktop
   *  only — the phone relay host lives in the Electron main process; the browser and relay bridges
   *  subscribe to nothing. */
  onHostChatQuery(listener: (q: HostChatQuery) => void): () => void
  /** Answer a `onHostChatQuery` request. */
  sendHostChatReply(reply: HostChatReply): void
  /** Agent messaging (the `send`/`reply` control verbs): run one delivery in main, where the
   *  scope check, the per-project switch, flow control and the pane probes all live. The reply is
   *  already rendered as a control reply — Canvas forwards it verbatim. */
  agentMessage: {
    deliver(req: AgentMessageDeliverRequest): Promise<AgentMessageReply>
    /** Deliver one mentioned session's copy of a board comment the local user just posted, through
     *  the same gates. `result` carries the typed outcome the comment row renders. Desktop only: the
     *  browser and relay bridges answer `notPermitted: unsupported-edition`. */
    deliverBoardComment(req: BoardCommentDeliverRequest): Promise<AgentMessageReply>
  }
  /** Board dispatch (#1051): the renderer REPORTS its in-memory dispatch map to core, replaced
   *  whole on each change, so the read-only `issues` control verb can show it beside an issue
   *  (@shared/board-dispatch-report). Display only. Desktop and Server Edition are real; a relay
   *  tab's board is the host's, so there it is inert. */
  boardDispatch: {
    report(entries: import('./board-dispatch-report').BoardDispatchReportEntry[]): void
  }
  /** Station-failure notices (@shared/station-notice, src/core/agents/station-notice.ts): the
   *  chips on an orchestrator whose stations stopped, and the renderer's DROPPED verdicts, which
   *  are the one trigger fact core cannot measure. Desktop and Server Edition are real; a relay
   *  tab's stations belong to the host's core, so there it is inert. */
  stationNotice: {
    list(): Promise<import('./station-notice').StationNoticeView[]>
    onChanged(cb: (views: import('./station-notice').StationNoticeView[]) => void): () => void
    reportDropped(nodeId: string, dropped: boolean): void
  }
  /** Station task outcomes (`report-outcome`, src/core/station-outcome-store.ts): what each station
   *  reported about its own task (durable across a restart) — what a `--after-success` wait reads. Desktop and
   *  Server Edition are real; a relay tab's stations belong to the host's core, so there it is inert
   *  (and its launch delivery is refused anyway). */
  stationOutcome: {
    list(): Promise<import('./station-outcome').StationOutcomeRecord[]>
    onChanged(cb: (records: import('./station-outcome').StationOutcomeRecord[]) => void): () => void
  }
  /** Stations with unfinished HANDED-OVER work (src/core/station-handover.ts) — what plain
   *  `--after` reads so it never releases on a `done` from before that work arrived. Desktop and
   *  Server Edition are real; a relay tab's stations belong to the host's core, so there it is
   *  inert (and its launch delivery is refused anyway). */
  stationHandover: {
    list(): Promise<import('./station-handover').StationHandoverRecord[]>
    onChanged(cb: (records: import('./station-handover').StationHandoverRecord[]) => void): () => void
  }
}