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.

51.9 KB
Raw Blame
import { create } from 'zustand'
import type { AgentPermissionMode } from '@shared/agents/config'
import type {
  BridgeLink,
  CanvasMutation,
  CanvasNodeState,
  ClosedSessionEntry,
  HandedOffTo,
  NavStop,
  Project,
  ProjectKanban,
  SceneMutation,
  Viewport,
  Workspace
} from '@shared/types'
import { CLOSED_SESSIONS_CAP } from '@shared/types'
import { collisionSeed, derivedProjectId } from '@shared/project-id'
import { capabilityHasMachineDefault, type ProjectCapability } from '@shared/project-capabilities'
import type { ProjectIcon } from '@shared/project-icon'
import { recordCapabilityAck, type CapabilityAnswer } from '@shared/project-capability-consent'
import {
  CANVAS_LAYOUTS_CAP,
  CANVAS_LAYOUT_NAME_MAX,
  pruneLayoutViewports,
  type CanvasLayout
} from '@shared/canvas-layout'
import { clampProjectName } from '@shared/project-name'
import { applyCanvasOp as applyCanvasOpTo, contentOf } from '@shared/canvas-content'
import { diffToMutations, type CanvasScene } from '@shared/canvas-mutations'
import { groupsFirst } from '@shared/node-order'
import { applyOwnCanvasMutation, createProject, reorderGroupWithinParent } from './workspace'
import { registerCodexRelayProjectCheck } from './codexCli'
import { markWorkspaceDirty } from './workspaceDirty'
import { rootPositionWith } from '@shared/root-position'
import { folderName } from '../lib/projectOpen'
import { useSettings } from './settings'
// One order-independent key for an edge's endpoints — the SAME rule `hiddenLinkIds` uses, so a
// rope and the bridge it covers are recognized as one relationship here too.
import { pairKey as bridgePairKey } from '../lib/noteLink'

/**
 * What `saveLayout` did.
 *
 * A union rather than a boolean because the refusals need different sentences: the cap is a state
 * the user has to resolve (delete one first), while an unusable name is a typo. Neither may be
 * swallowed - this store is not the only writer of `layouts` (a git pull delivers them too), so
 * the cap can be reached by work the user never did, and a Save button that quietly does nothing
 * is exactly the failure this return value exists to prevent.
 */
export type SaveLayoutResult = 'saved' | 'cap-reached' | 'invalid-name' | 'unknown-project'

interface ProjectsState {
  projects: Project[]
  activeProjectId: string
  /**
   * Monotonic counter the Canvas project-load effect depends on: bumping it re-runs the load, even
   * for the project that is ALREADY active. Runtime-only (never persisted — see toWorkspace) and
   * never reset, not even by hydrate.
   *
   * Field bug 2026-08-10: an in-place reload used to be faked by setting the active id to '' and
   * back on a microtask. React coalesces both writes into one render, so the effect's dependency
   * never changed and the reload never happened — the store held disk's version while React Flow
   * still showed the old nodes, and the next debounced save wrote those old nodes back over disk.
   */
  reloadNonce: number

  hydrate(ws: Workspace): void
  /** Asks Canvas to reload the active project's canvas from the store (external change adopted,
   *  conflict resolved as "reload"). See `reloadNonce`. */
  requestReload(): void
  getProject(id: string): Project | undefined

  setActive(id: string): void
  /** Adds a new project and returns it (caller commits the current canvas first). */
  addProject(name?: string, cwd?: string, ssh?: Project['ssh']): Project
  /** "Open folder…": a folder maps to one project. Reuses the existing project with that
   *  cwd — reopening it if it was closed, so it shows in the tab bar again — or creates a
   *  new one named after the folder. Activates and returns it (caller commits the current
   *  canvas first). */
  openFolderProject(folder: string): Project
  /** "Connect over SSH…": a server folder maps to one project, same contract as
   *  openFolderProject. Reuses the existing project with the same endpoint (host/user/port) and
   *  remoteCwd — reopening it if it was closed — or creates a new one. Re-adding must NEVER mint
   *  a fresh empty project for a folder that already has one: its first mirror write used to
   *  clobber the server's .nodeterm/project.json. Activates and returns it. */
  openSshProject(label: string, ssh: NonNullable<Project['ssh']>): Project
  /** Registers a probed project (from a folder's .nodeterm file). The probe already minted the id
   *  — the shared file carries none — so this only defends against a collision with an existing
   *  project (node ids untouched). Activates it. */
  adoptProject(project: Project): Project
  /** Replaces one project's data wholesale (external file change). Keeps activeProjectId. */
  replaceProject(project: Project): void
  renameProject(id: string, name: string): void
  /** Sets a project's sidebar/monogram accent color. No-op for an unknown id. */
  setProjectColor(id: string, color: string): void
  /** Sets (or clears, with undefined = fall back to the color monogram) the project's icon. Stored
   *  on `Project.icon` and git-shared via project.json like name/color. No-op for an unknown id. */
  setProjectIcon(id: string, icon: ProjectIcon | undefined): void
  setProjectCwd(id: string, cwd: string): void
  /** Issue #1145: where this folder project's canvas is stored. Only the flag — the move itself
   *  (save, then the core step) is `lib/projectStorageMove`. */
  setProjectStoreInAppData(id: string, on: boolean): void
  /** Grey (or un-grey) a project tab as "unavailable" WITHOUT dropping it — runtime-only, never
   *  persisted (see the toWorkspace tripwire). Set true when a relay tab's socket drops (Stage 4
   *  Task 7) so it stays reconnectable; cleared when it reconnects. */
  setProjectUnavailable(id: string, unavailable: boolean): void
  /** Sets (or clears, with undefined) the project's default Claude account for new nodes. */
  setProjectDefaultAccount(id: string, accountId: string | undefined): void
  /** Sets (or clears, with undefined = fall back to the global setting) the project's default
   *  permission mode for new Claude terminal (CLI) sessions. Chat nodes are not covered. */
  setProjectDefaultPermissionMode(id: string, mode: AgentPermissionMode | undefined): void
  /** Sets (or clears, with undefined) the machine-local mark that this SSH project was handed to a
   *  hosted team (see `HandedOffTo`). Cleared means the field is gone, so the next save drops it
   *  from the index entry. The caller saves. No-op for an unknown id. */
  setHandedOffTo(id: string, value: HandedOffTo | undefined): void
  /**
   * THE strict per-project capability setter (@shared/project-capabilities). `on` writes the
   * literal `true` the validators accept AND records this machine's 'kept' answer — setting a
   * switch yourself is its own consent, so the clone notice never fires on your own decision.
   * `off` deletes the field (an off capability adds no bytes to the shared file) — EXCEPT for a
   * capability with a machine default (CAPABILITY_MACHINE_DEFAULTS), where absence means "use this
   * machine's default" and off must therefore be written as a literal `false`. Either way it records
   * 'declined': if a teammate's (or a hostile) `true` re-arrives via git, the capability is refused
   * and re-noticed rather than silently re-granted (PR #213 C1/M-2). */
  setProjectCapability(id: string, cap: ProjectCapability, on: boolean): void
  /**
   * "Use this machine's default" — only meaningful for a capability with a machine default. Removes
   * the file's value AND this machine's recorded answer for it: a kept `'declined'` would otherwise
   * keep an absent field off (the rule that protects a pre-default "turn it off"), so the choice the
   * user just made would not take effect. If a `true` later re-arrives via git it meets no answer
   * and raises the clone notice, exactly as for a never-configured project. */
  resetProjectCapabilityToDefault(id: string, cap: ProjectCapability): void
  /**
   * Records this machine's ANSWER ('kept' | 'declined') to the one-time clone notice.
   * MACHINE-LOCAL by construction: `Project.capabilityAck` rides `IndexEntryV3.capabilityAck`
   * through splitWorkspace on the next save and is never written into .nodeterm/project.json
   * (workspace-files.test.ts pins the file bytes; capability-notice.test.tsx pins this path). */
  recordProjectCapabilityAck(id: string, cap: ProjectCapability, answer: CapabilityAnswer): void
  /** Raises the project's dino high score (never lowers it). */
  setDinoHighScore(id: string, score: number): void
  /** Replaces the project's kanban board (the UI computes the next board via lib/kanban). */
  setProjectKanban(id: string, kanban: ProjectKanban): void
  /** Replaces the project's breadcrumb (navigation history) list wholesale — the UI computes the
   *  next list via lib/breadcrumbs and hands it over whole, same convention as setProjectKanban. */
  setProjectBreadcrumbs(id: string, breadcrumbs: NavStop[]): void
  /** Writes the serialized canvas (nodes + viewport + bridge links + control ropes) back into a project. */
  commitCanvas(
    id: string,
    nodes: CanvasNodeState[],
    viewport: Viewport,
    bridges?: BridgeLink[],
    ropes?: BridgeLink[]
  ): void
  /**
   * Appends context bridges / control ropes to a project that is loaded but NOT active — the edge
   * counterpart of `applyNodeMutation`, and for the same reason: React Flow holds only the active
   * project's edges, so a cold open (canvas control's `open-*` answered out of the store) has
   * nowhere else to put the opener's rope and the fan-in bridge it owes. Deduped by edge id AND by
   * endpoint pair, since `planBridges` mints `bridge-<source>-<target>` while a rope is
   * `ctrl-<source>-<target>` — two ids, one relationship each. No-op for an unknown project.
   */
  appendCanvasLinks(projectId: string, links: { bridges?: BridgeLink[]; ropes?: BridgeLink[] }): void
  /**
   * Applies ONE canvas mutation — node, edge or board — to a project's serialized content, through
   * the ONE reducer (`applyCanvasOp`, @shared/canvas-content) every client and the Server Edition
   * canvas authority share — the path for a project React Flow does not hold (it only ever holds
   * the active project's nodes). Returns false only if the project is unknown here (nothing
   * applied, nothing created); an op that changes nothing is still `true` but writes NOTHING — no
   * new `projects` array, so no subscriber re-runs — and callers that schedule a save compare the
   * project object before and after to tell the two apart.
   *
   * Only the fields the op changed are written back, so an absent `bridges` / `ropes` / `kanban`
   * stays absent (materializing `"bridges": []` or a lazy default board would dirty a file nobody
   * edited). Side-effect free beyond the store: it marks nothing dirty and publishes nothing.
   */
  applyCanvasOp(projectId: string, mutation: CanvasMutation): boolean
  /**
   * Applies ONE peer canvas mutation to a project's serialized nodes — the path for a project
   * that is loaded but NOT active (React Flow only holds the active project's nodes). Returns
   * false if the project is unknown here (nothing applied, nothing created).
   *
   * This must not be skipped for background projects: their serialized nodes are what the next
   * whole-file `workspace.save` writes, so dropping a peer's `remove` would resurrect the node
   * they deleted on the very next save — the data-loss shape canvas sync exists to fix.
   *
   * Delegates to `applyCanvasOp` (one reducer), so it takes any family.
   */
  applyNodeMutation(projectId: string, mutation: CanvasMutation): boolean
  /**
   * The EDGE counterpart, for the same background-project path. Edges (`bridges` = context links,
   * `ropes` = display-only lineage) ride the same whole-file save as the nodes, so dropping a
   * peer's edge mutation for a project we are not looking at has the identical failure mode: our
   * next save writes a project without their edge, deleting it for everyone.
   *
   * Returns false if the project is unknown here (nothing applied). Delegates to `applyCanvasOp`.
   */
  applyEdgeMutation(projectId: string, mutation: CanvasMutation): boolean
  /**
   * Applies a mutation THIS renderer authored (a cold open, an off-canvas display node, the
   * headless start's outcome patch) to a project that is not on screen. Unlike `applyNodeMutation`
   * nothing is stripped: the node's machine-local `pendingLaunch` is ours to set, and an upsert
   * without one CLEARS it (the peer path carries the old one across instead — @shared/node-exec).
   * Never route a peer's mutation through this.
   */
  applyOwnNodeMutation(projectId: string, mutation: CanvasMutation): boolean
  /** Several of our own node writes as ONE store write, re-sorted parents-first (`groupsFirst`) —
   *  a structural control verb run off screen adds a frame after the children it now holds. */
  applyOwnNodeMutations(projectId: string, mutations: readonly CanvasMutation[]): boolean
  /** Renames a node within a project (source of truth for inactive projects). */
  renameNode(projectId: string, nodeId: string, title: string): void
  /** Recolors a node within a project. */
  recolorNode(projectId: string, nodeId: string, color: string): void
  /**
   * Writes an in-place agent restart's rebind (which agent, which account) into a project's
   * serialized node — for a restart that finished after its project stopped being the active one
   * (the user switched away while the CLI was quitting), when React Flow no longer holds the node.
   * A key that is PRESENT is written, even as `undefined` (= the system account); an absent key is
   * left alone.
   */
  rebindNode(
    projectId: string,
    nodeId: string,
    patch: Pick<CanvasNodeState, 'agentId'> & Partial<Pick<CanvasNodeState, 'accountId'>>
  ): void
  /** Removes a node from a project. */
  removeNode(projectId: string, nodeId: string): void
  /** Duplicates a node within a project (fresh id, offset position). */
  duplicateNode(projectId: string, nodeId: string): void
  /** Moves a node into a group frame (groupId) or out to the top level (null), keeping its
   *  on-canvas position fixed by converting absolute/relative coordinates. */
  moveNodeToGroup(projectId: string, nodeId: string, groupId: string | null): void
  /** Reorders a node to sit immediately before another (sidebar order = array order),
   *  joining the target's container if they differ. */
  reorderNode(projectId: string, draggedId: string, beforeId: string): void
  /** Reorders a group subtree among its siblings without changing its parent. */
  reorderGroup(
    projectId: string,
    draggedId: string,
    parentId: string | null,
    beforeId: string | null
  ): void
  /** Reorders a project to sit immediately before another (tab bar + sidebar order = array
   *  order), or to the end with beforeId = null. Closed projects keep their slots. */
  reorderProject(draggedId: string, beforeId: string | null): void
  /** Removes a project permanently; returns the id that should become active ('' = welcome). */
  deleteProject(id: string): string
  /** Hides a project from the tab bar without destroying it; returns the next active open
   *  project id ('' = welcome screen). The project (and its sessions) is kept for reopening. */
  closeProject(id: string): string
  /** Restores a closed project and makes it active. No-op if the id is unknown. */
  reopenProject(id: string): void
  /** Un-close a project WITHOUT making it active: a closed tab reappears, the camera stays put.
   *  For work that landed while the user was elsewhere (`registerProject`, canvas-control
   *  `--run-now` #925). `reopenProject` is the human path and also activates. */
  unhideProject(id: string): void

  /** Records freshly deleted sessions into the project's history (newest-first, capped at
   *  `CLOSED_SESSIONS_CAP`). No-op if `entries` is empty or the project no longer exists. */
  recordClosedSessions(projectId: string, entries: ClosedSessionEntry[]): void
  /** Removes and returns the matching closed-session entry, or `undefined` if it's already gone
   *  (e.g. discarded from another surface first). */
  consumeClosedSession(projectId: string, entryId: string): ClosedSessionEntry | undefined
  /** Removes a closed-session entry without reopening it. */
  discardClosedSession(projectId: string, entryId: string): void

  /**
   * Saves a layout (replacing by id) together with this machine's camera for it.
   *
   * The two halves land in ONE write because they are meaningless apart: the layout is CONTENT in
   * the git-shared project file, the camera is machine-local index state, and a camera whose
   * layout never landed is orphan bytes in a file that is forever.
   *
   * `now` is the caller's clock rather than a `Date.now()` in here, so the snapshot the caller
   * built and the timestamps stored beside it cannot disagree, and a test can prove `createdAt`
   * survived a replace. The store stamps both timestamps itself: they order the list the user
   * reads, and a caller must not be able to backdate a layout into someone else's slot.
   */
  saveLayout(
    projectId: string,
    layout: CanvasLayout,
    viewport: Viewport,
    now: number
  ): SaveLayoutResult
  /**
   * Renames a layout and bumps its `updatedAt`. No-op for an unknown project or layout id, and
   * for a name that is empty once trimmed.
   *
   * Void where `saveLayout` reports, because every refusal here is one the call site can test for
   * itself before calling - it knows the name it typed and the id it picked, so a return value
   * would tell it nothing it did not already have.
   */
  renameLayout(projectId: string, layoutId: string, name: string, now: number): void
  /** Deletes a layout AND this machine's camera for it. Both halves move together: a camera keyed
   *  to a layout nobody can restore is litter in a file that is forever, the rule
   *  `pruneCollapsedItems` states for `settings.sidebarCollapsedItems`. */
  deleteLayout(projectId: string, layoutId: string): void
  /** Records this machine's camera for a layout without touching the shared half - where I was
   *  looking after a restore is a fact about this screen, and writing it into
   *  `.nodeterm/project.json` would move everyone else's canvas. An unknown layout id is refused
   *  rather than answered with a stub, for the same reason `deleteLayout` prunes. */
  recordLayoutViewport(projectId: string, layoutId: string, viewport: Viewport): void

  /**
   * Registers (or finds) the project for a local directory WITHOUT activating it — the store half
   * of the `open-project` control verb (issue #338, spec §2.1 steps 2–4). The human paths
   * (`openFolderProject`/`adoptProject`/`reopenProject`) all set `activeProjectId`; an agent verb
   * must not travel the user's view (spec P6), so this action NEVER writes it, in any branch.
   *
   * `resolvedCwd` is main's already-validated, `path.resolve`d form (spec P7) — this action only
   * re-applies the trailing-slash normalization so the exact-string dedupe cannot be split by a
   * cosmetic slash. Branches, in order:
   *  - idempotent hit (B1): a project with this cwd is returned as-is; a `closed` one is
   *    un-closed (its tab reappears) without activation. `name`/`color` are NOT applied — an
   *    existing project's identity is never mutated on an agent's say-so.
   *  - adopt: `probed` (the folder's own .nodeterm/project.json, from `probeFolder`) is added,
   *    defending against an id collision exactly as `adoptProject` does (derived id, nodes kept).
   *  - create: the same `createProject` factory `addProject` uses; `name` defaults to the folder
   *    basename, `color` applies on create only.
   */
  registerProject(input: {
    resolvedCwd: string
    name?: string
    color?: string
    probed?: Project
  }): { project: Project; created: boolean; adopted: boolean }

  toWorkspace(): Workspace
}

/**
 * A local folder project CREATED from now on (never one adopted from an existing project.json)
 * keeps its canvas where Settings → Behavior says (issue #1145).
 */
function withNewProjectStorage(project: Project): Project {
  return project.cwd && !project.ssh && useSettings.getState().settings.newProjectStorage === 'appData'
    ? { ...project, storeInAppData: true }
    : project
}

/** A persisted node's position in ROOT space: its own plus every ancestor frame's origin. */
function rootStatePosition(
  node: CanvasNodeState,
  nodes: CanvasNodeState[]
): { x: number; y: number } {
  const byId = new Map(nodes.map((candidate) => [candidate.id, candidate]))
  return rootPositionWith(node, (id) => byId.get(id))
}

function stateIsDescendant(
  nodes: CanvasNodeState[],
  candidateId: string,
  ancestorId: string
): boolean {
  const byId = new Map(nodes.map((node) => [node.id, node]))
  const seen = new Set<string>()
  let current = byId.get(candidateId)
  while (current?.parentId && !seen.has(current.parentId)) {
    if (current.parentId === ancestorId) return true
    seen.add(current.parentId)
    current = byId.get(current.parentId)
  }
  return false
}

/** Returns `node` repositioned for a new parent (groupId, or null for top level), keeping its
 *  root-space position fixed across arbitrary nesting. Unchanged if the target is not a
 *  group. `extent` is omitted — nodeStatesToFlow re-derives it from parentId on load. */
function repositionState(
  node: CanvasNodeState,
  groupId: string | null,
  nodes: CanvasNodeState[]
): CanvasNodeState {
  const abs = rootStatePosition(node, nodes)
  if (groupId === null) return { ...node, parentId: undefined, position: abs }
  const group = nodes.find((n) => n.id === groupId)
  if (!group || group.kind !== 'group') return node
  const groupAbs = rootStatePosition(group, nodes)
  return {
    ...node,
    parentId: group.id,
    position: { x: abs.x - groupAbs.x, y: abs.y - groupAbs.y }
  }
}

/**
 * Defense in depth for the ONE invariant this store cannot survive without: no two projects share
 * an id. Every mutator here (`commitCanvas`, `deleteProject`, `closeProject`, `renameNode`, …)
 * either maps by id — writing one canvas into BOTH projects — or filters by id, hitting both. The
 * tab bar keys its children by id, which is how the bug announced itself: ~1500 React "two children
 * with the same key" warnings.
 *
 * The store in main repairs the persisted index and re-keys the file (see
 * `WorkspaceStore.repairDuplicateIds`); this is the renderer's own guard for anything that reaches
 * hydrate some other way (a relay `projects.list` blob, a downgraded/older host). It uses the SAME
 * derivation, so when both run they agree on the id rather than fighting over it.
 */
function withUniqueIds(projects: Project[]): Project[] {
  const seen = new Set<string>()
  return projects.map((p) => {
    if (!seen.has(p.id)) {
      seen.add(p.id)
      return p
    }
    const id = derivedProjectId(p.id, collisionSeed(p), (c) => seen.has(c))
    seen.add(id)
    return { ...p, id }
  })
}

/** Returns `projects` with one project's nodes transformed; other projects untouched. */
function mapProjectNodes(
  projects: Project[],
  projectId: string,
  fn: (nodes: CanvasNodeState[]) => CanvasNodeState[]
): Project[] {
  return projects.map((p) => (p.id === projectId ? { ...p, nodes: fn(p.nodes) } : p))
}

/**
 * Publishes a board write to the project's peers (spec §11.3). Every board write in the renderer
 * goes through `setProjectKanban` — the board, the card modal, the Omni board, node labels, the
 * GitHub settings section, the canvas-control `assign` verb (fenced by board-writers.guard.test.ts)
 * — so the ONE place a board change is published is here, and no writer needs a call site of its
 * own. `prev` is the board read BEFORE the write (`undefined` = the project's lazy default), `next`
 * the board written.
 *
 * A peer's board op must NEVER come through here: it is applied with `applyCanvasOp` (the store
 * reducer), which does not call the hook — publishing it would re-cast someone else's edit as ours.
 */
export type KanbanPublishHook = (
  projectId: string,
  prev: ProjectKanban | undefined,
  next: ProjectKanban | undefined
) => void
let kanbanPublishHook: KanbanPublishHook | null = null
/** Canvas registers this once per core binding and clears it (`null`) on teardown. */
export function setKanbanPublishHook(hook: KanbanPublishHook | null): void {
  kanbanPublishHook = hook
}

/**
 * Publishes the node and edge writes THIS renderer makes into a project's STORED copy — every own
 * store writer: `applyOwnNodeMutation` and `appendCanvasLinks` (a ⌘⇧T / "Recently closed" reopen
 * into a project that is not on screen, a cold open, an off-canvas display node or link, a headless
 * start's launch patch) and the sessions sidebar's `renameNode` / `recolorNode` / `rebindNode` /
 * `removeNode` / `duplicateNode` / `moveNodeToGroup` / `reorderNode` / `reorderGroup`. The node
 * publisher never sees these writes: it diffs React Flow, and a stored project's nodes enter React
 * Flow only through a load, which it ADOPTS as its baseline rather than casting. On a project a
 * Server Edition canvas authority governs that was data loss, because the save overlay replaces the
 * stored content with what the authority heard as ops (docs/hosted-team-relay.md): a reopened node
 * vanished from disk, and a sidebar close killed the session while the node came back.
 *
 * Called AFTER the write with `ops`, which diffs the project's nodes and edges before and after it
 * (`diffToMutations`, the publisher's own diff, so no writer keeps a list of its own that drifts).
 * LAZY: a hook that casts nothing for this project never pays for the diff. Node order is not in
 * the op vocabulary, so a pure reorder yields no op. Same one-owner rule as the board hook: a peer's
 * op is applied with `applyCanvasOp`, which never calls it, so nothing received is published again.
 */
export type StoredCanvasPublishHook = (projectId: string, ops: () => readonly SceneMutation[]) => void
let storedCanvasPublishHook: StoredCanvasPublishHook | null = null
/** Canvas registers this once per core binding and clears it (`null`) on teardown. */
export function setStoredCanvasPublishHook(hook: StoredCanvasPublishHook | null): void {
  storedCanvasPublishHook = hook
}

const sceneOf = (p: Project): CanvasScene => ({
  nodes: Array.isArray(p.nodes) ? p.nodes : [],
  bridges: p.bridges ?? [],
  ropes: p.ropes ?? []
})

/** Run one own write into a stored project, then hand what it changed to the publish hook. */
function ownWrite(get: () => ProjectsState, projectId: string, write: () => void): void {
  const before = get().getProject(projectId)
  write()
  const hook = storedCanvasPublishHook
  const after = get().getProject(projectId)
  if (!hook || !before || !after || before === after) return
  hook(projectId, () => diffToMutations(sceneOf(before), sceneOf(after)))
}

/** One server folder is one project: the same endpoint (host, user, and port — 22 when unset) and
 *  the same remoteCwd. The server entry's own id and label do not count, so a re-added server entry
 *  still finds its folder's project. `openSshProject` dedupes by this, and so does anything that
 *  must know in advance which project that call will reopen. */
export function sameSshEndpoint(a: NonNullable<Project['ssh']>, b: NonNullable<Project['ssh']>): boolean {
  return (
    a.remoteCwd === b.remoteCwd &&
    a.server.host === b.server.host &&
    a.server.user === b.server.user &&
    (a.server.port ?? 22) === (b.server.port ?? 22)
  )
}

/** The cwd `registerProject` dedupes by: trailing slashes stripped, so `/a/b/` and `/a/b` cannot
 *  mint two tabs for one directory. Root stays '/': stripping it to '' would match every cwd-less
 *  project. Exported so anything predicting registerProject's match uses this rule, not a copy. */
export function registeredCwd(resolvedCwd: string): string {
  return resolvedCwd.length > 1 ? resolvedCwd.replace(/\/+$/, '') : resolvedCwd
}

export const useProjects = create<ProjectsState>((set, get) => ({
  projects: [],
  activeProjectId: '',
  reloadNonce: 0,

  hydrate(ws) {
    set({ projects: withUniqueIds(ws.projects), activeProjectId: ws.activeProjectId })
  },

  requestReload() {
    set((s) => ({ reloadNonce: s.reloadNonce + 1 }))
  },

  getProject(id) {
    return get().projects.find((p) => p.id === id)
  },

  setActive(id) {
    set({ activeProjectId: id })
  },

  addProject(name, cwd, ssh) {
    // Every new project's name — a folder's own name, an SSH label, a relay host's project
    // name — gets the same cap as a rename (issue #940). A blank one keeps createProject's default.
    const clean = name === undefined ? undefined : clampProjectName(name) || undefined
    const project = withNewProjectStorage(createProject(get().projects.length, clean, cwd, ssh))
    set((s) => ({ projects: [...s.projects, project] }))
    return project
  },

  openFolderProject(folder) {
    // Never a relay tab: it carries the HOST's cwd, and the same path can exist on both machines.
    const existing = get().projects.find((p) => p.cwd === folder && !p.remote)
    if (existing) {
      // reopenProject also clears `closed` — an "Open folder" on a previously closed
      // project must bring its tab back, not activate an invisible project.
      get().reopenProject(existing.id)
      return existing
    }
    const name = folderName(folder) || 'Project'
    const project = get().addProject(name, folder)
    set({ activeProjectId: project.id })
    return project
  },

  openSshProject(label, ssh) {
    const existing = get().projects.find((p) => !!p.ssh && sameSshEndpoint(p.ssh, ssh))
    if (existing) {
      get().reopenProject(existing.id)
      return existing
    }
    const project = get().addProject(label, undefined, ssh)
    set({ activeProjectId: project.id })
    return project
  },

  adoptProject(project) {
    const taken = get().projects.some((p) => p.id === project.id)
    // `probeFolder` mints the id (the folder's project.json no longer names one), so a collision
    // here means the id was minted against a store this renderer had not hydrated yet — derive a
    // fresh one. Node ids are deliberately kept (they are tmux session names — see the spec's
    // accepted limitation). Deterministic in (id, folder), not random, so this path and the
    // store's own repair never disagree about what a tab is called.
    const adopted = taken
      ? {
          ...project,
          id: derivedProjectId(project.id, collisionSeed(project), (c) =>
            get().projects.some((p) => p.id === c))
        }
      : project
    set((s) => ({ projects: [...s.projects, adopted], activeProjectId: adopted.id }))
    return adopted
  },

  replaceProject(project) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === project.id ? project : p))
    }))
  },

  renameProject(id, name) {
    // Every rename surface funnels through here, so the cap holds even for input that bypassed a
    // field's maxLength (issue #940). A blank name is not a rename.
    const clean = clampProjectName(name)
    if (!clean) return
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, name: clean } : p))
    }))
  },

  setProjectColor(id, color) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, color } : p))
    }))
  },

  setProjectIcon(id, icon) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, icon } : p))
    }))
  },

  setProjectCwd(id, cwd) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, cwd } : p))
    }))
  },

  setProjectStoreInAppData(id, on) {
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== id) return p
        if (on) return { ...p, storeInAppData: true }
        const { storeInAppData: _drop, ...rest } = p
        return rest
      })
    }))
  },

  setProjectUnavailable(id, unavailable) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, unavailable } : p))
    }))
  },

  setProjectDefaultAccount(id, accountId) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, defaultAccountId: accountId } : p))
    }))
  },

  setProjectDefaultPermissionMode(id, mode) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, defaultPermissionMode: mode } : p))
    }))
  },

  setHandedOffTo(id, value) {
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== id) return p
        if (value) return { ...p, handedOffTo: value }
        const { handedOffTo: _drop, ...rest } = p
        return rest
      })
    }))
  },

  setProjectCapability(id, cap, on) {
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== id) return p
        if (on) return recordCapabilityAck({ ...p, [cap]: true }, cap, 'kept')
        const next = { ...p }
        if (capabilityHasMachineDefault(cap)) next[cap] = false
        else delete next[cap]
        // 'declined', not silence: the deletion lives only in this working copy, so a re-arriving
        // `true` (teammate commit, git checkout) must re-notice instead of meeting a bare ack.
        return recordCapabilityAck(next, cap, 'declined')
      })
    }))
    // The setter owns the persist (issue #318): its call sites — the AgentsSection toggle, the
    // clone notice's decline — schedule no save of their own, so without this the choice was lost
    // on restart unless an unrelated canvas edit happened to dirty the workspace afterwards.
    markWorkspaceDirty()
  },

  resetProjectCapabilityToDefault(id, cap) {
    if (!capabilityHasMachineDefault(cap)) return
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== id) return p
        const next = { ...p }
        delete next[cap]
        if (next.capabilityAck && Object.prototype.hasOwnProperty.call(next.capabilityAck, cap)) {
          const ack = { ...next.capabilityAck }
          delete ack[cap]
          if (Object.keys(ack).length) next.capabilityAck = ack
          else delete next.capabilityAck
        }
        return next
      })
    }))
    markWorkspaceDirty()
  },

  recordProjectCapabilityAck(id, cap, answer) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? recordCapabilityAck(p, cap, answer) : p))
    }))
    // Same persistence gap as setProjectCapability: the notice's 'kept' answer rides
    // IndexEntryV3.capabilityAck on the next save — which must actually be scheduled.
    markWorkspaceDirty()
  },

  setDinoHighScore(id, score) {
    // Raise-only: a stale/lower report (e.g. a second dino node) must never shrink the record.
    set((s) => ({
      projects: s.projects.map((p) =>
        p.id === id && score > (p.dinoHighScore ?? 0) ? { ...p, dinoHighScore: score } : p
      )
    }))
  },

  setProjectKanban(id, kanban) {
    // Read BEFORE the write: the publish hook diffs this against what was written.
    const prev = get().getProject(id)?.kanban
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, kanban } : p))
    }))
    // AFTER the write, so a local repair the publisher applies (ruling R2) lands on `kanban`.
    kanbanPublishHook?.(id, prev, kanban)
  },

  setProjectBreadcrumbs(id, breadcrumbs) {
    set((s) => ({
      projects: s.projects.map((p) => (p.id === id ? { ...p, breadcrumbs } : p))
    }))
  },

  commitCanvas(id, nodes, viewport, bridges, ropes) {
    set((s) => ({
      projects: s.projects.map((p) =>
        p.id === id
          ? { ...p, nodes, viewport, ...(bridges ? { bridges } : {}), ...(ropes ? { ropes } : {}) }
          : p
      )
    }))
  },

  appendCanvasLinks(projectId, links) {
    const add = (existing: BridgeLink[] | undefined, incoming: BridgeLink[] | undefined) => {
      if (!incoming?.length) return existing
      const kept = existing ?? []
      const seenId = new Set(kept.map((e) => e.id))
      const seenPair = new Set(kept.map((e) => bridgePairKey(e.source, e.target)))
      const fresh = incoming.filter((e) => {
        const pair = bridgePairKey(e.source, e.target)
        if (seenId.has(e.id) || seenPair.has(pair)) return false
        seenId.add(e.id)
        seenPair.add(pair)
        return true
      })
      return fresh.length ? [...kept, ...fresh] : existing
    }
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: s.projects.map((p) =>
          p.id === projectId
            ? { ...p, bridges: add(p.bridges, links.bridges), ropes: add(p.ropes, links.ropes) }
            : p
        )
      }))
    )
  },

  applyCanvasOp(projectId, mutation) {
    const p = get().projects.find((x) => x.id === projectId)
    if (!p) return false
    // Compare against the object handed to the reducer: `contentOf` builds a new one per call (and
    // a fresh `[]` for an absent list), so only this reference can say "nothing changed".
    const before = contentOf(p)
    const after = applyCanvasOpTo(before, mutation, projectId)
    if (after === before) return true
    // Write back ONLY what the op changed — an absent list or board must stay absent.
    const patch: Partial<Project> = {}
    if (after.nodes !== before.nodes) patch.nodes = after.nodes
    if (after.bridges !== before.bridges) patch.bridges = after.bridges
    if (after.ropes !== before.ropes) patch.ropes = after.ropes
    if (after.kanban !== before.kanban) patch.kanban = after.kanban
    set((s) => ({
      projects: s.projects.map((x) => (x.id === projectId ? { ...x, ...patch } : x))
    }))
    return true
  },

  applyNodeMutation(projectId, mutation) {
    return get().applyCanvasOp(projectId, mutation)
  },

  applyEdgeMutation(projectId, mutation) {
    return get().applyCanvasOp(projectId, mutation)
  },

  applyOwnNodeMutation(projectId, mutation) {
    if (!get().projects.some((p) => p.id === projectId)) return false
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          applyOwnCanvasMutation(nodes, mutation)
        )
      }))
    )
    return true
  },

  applyOwnNodeMutations(projectId, mutations) {
    if (!get().projects.some((p) => p.id === projectId)) return false
    if (mutations.length === 0) return true
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          groupsFirst(mutations.reduce(applyOwnCanvasMutation, nodes))
        )
      }))
    )
    return true
  },

  renameNode(projectId, nodeId, title) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          // An explicit rename means the user owns the name now: stop auto-tracking the session.
          nodes.map((n) => (n.id === nodeId ? { ...n, title, titleAuto: false } : n))
        )
      }))
    )
  },

  recolorNode(projectId, nodeId, color) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          nodes.map((n) => (n.id === nodeId ? { ...n, color } : n))
        )
      }))
    )
  },

  rebindNode(projectId, nodeId, patch) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          nodes.map((n) => (n.id === nodeId ? { ...n, ...patch } : n))
        )
      }))
    )
  },

  removeNode(projectId, nodeId) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) =>
          nodes.filter((n) => n.id !== nodeId)
        )
      }))
    )
  },

  duplicateNode(projectId, nodeId) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) => {
          const src = nodes.find((n) => n.id === nodeId)
          if (!src) return nodes
          const copy: CanvasNodeState = {
            ...src,
            id: `${src.kind}-${Math.random().toString(36).slice(2, 10)}`,
            title: `${src.title} copy`,
            position: { x: src.position.x + 24, y: src.position.y + 24 }
          }
          return [...nodes, copy]
        })
      }))
    )
  },

  moveNodeToGroup(projectId, nodeId, groupId) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) => {
          const node = nodes.find((n) => n.id === nodeId)
          if (!node) return nodes
          if ((node.parentId ?? null) === groupId) return nodes
          // A frame may be moved into another frame, but never into itself or its own subtree.
          if (groupId === nodeId || (groupId && stateIsDescendant(nodes, groupId, nodeId))) {
            return nodes
          }
          const next = repositionState(node, groupId, nodes)
          if (next === node) return nodes // target group missing / not a group
          return nodes.map((n) => (n.id === nodeId ? next : n))
        })
      }))
    )
  },

  reorderNode(projectId, draggedId, beforeId) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) => {
          if (draggedId === beforeId) return nodes
          const dragged = nodes.find((n) => n.id === draggedId)
          const before = nodes.find((n) => n.id === beforeId)
          if (!dragged || !before || dragged.kind === 'group') return nodes
          const targetParent = before.parentId ?? null
          const moved =
            (dragged.parentId ?? null) === targetParent
              ? dragged
              : repositionState(dragged, targetParent, nodes)
          const without = nodes.filter((n) => n.id !== draggedId)
          const idx = without.findIndex((n) => n.id === beforeId)
          return [...without.slice(0, idx), moved, ...without.slice(idx)]
        })
      }))
    )
  },

  reorderGroup(projectId, draggedId, parentId, beforeId) {
    ownWrite(get, projectId, () =>
      set((s) => ({
        projects: mapProjectNodes(s.projects, projectId, (nodes) => {
          const dragged = nodes.find((node) => node.id === draggedId)
          const before = beforeId ? nodes.find((node) => node.id === beforeId) : undefined
          if (!dragged || dragged.kind !== 'group' || (beforeId && before?.kind !== 'group')) {
            return nodes
          }
          return reorderGroupWithinParent(nodes, draggedId, parentId, beforeId)
        })
      }))
    )
  },

  reorderProject(draggedId, beforeId) {
    set((s) => {
      if (draggedId === beforeId) return s
      const dragged = s.projects.find((p) => p.id === draggedId)
      if (!dragged) return s
      const without = s.projects.filter((p) => p.id !== draggedId)
      const idx = beforeId ? without.findIndex((p) => p.id === beforeId) : -1
      // Unknown/null target → append (the "drop at the end" zone).
      const at = idx === -1 ? without.length : idx
      return { projects: [...without.slice(0, at), dragged, ...without.slice(at)] }
    })
  },

  deleteProject(id) {
    const { projects, activeProjectId } = get()
    const index = projects.findIndex((p) => p.id === id)
    const remaining = projects.filter((p) => p.id !== id)
    let nextActive = activeProjectId
    if (activeProjectId === id) {
      // pick the neighbor that takes this slot, or '' (welcome screen) when none remain
      nextActive = remaining.length ? remaining[Math.min(index, remaining.length - 1)].id : ''
    }
    set({ projects: remaining, activeProjectId: nextActive })
    return nextActive
  },

  closeProject(id) {
    const { projects, activeProjectId } = get()
    const index = projects.findIndex((p) => p.id === id)
    const next = projects.map((p) => (p.id === id ? { ...p, closed: true, closedAt: Date.now() } : p))
    let nextActive = activeProjectId
    if (activeProjectId === id) {
      // Move focus to the nearest still-open project (search outward), or the welcome screen.
      const open = next.filter((p) => !p.closed)
      const byDistance = open
        .map((p) => ({ id: p.id, d: Math.abs(next.findIndex((q) => q.id === p.id) - index) }))
        .sort((a, b) => a.d - b.d)
      nextActive = byDistance.length ? byDistance[0].id : ''
    }
    set({ projects: next, activeProjectId: nextActive })
    return nextActive
  },

  recordClosedSessions(projectId, entries) {
    if (!entries.length) return
    set((s) => ({
      projects: s.projects.map((p) =>
        p.id !== projectId
          ? p
          : {
              ...p,
              closedSessions: [...entries, ...(p.closedSessions ?? [])].slice(
                0,
                CLOSED_SESSIONS_CAP
              )
            }
      )
    }))
  },

  consumeClosedSession(projectId, entryId) {
    let found: ClosedSessionEntry | undefined
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== projectId || !p.closedSessions) return p
        const idx = p.closedSessions.findIndex((e) => e.id === entryId)
        if (idx === -1) return p
        found = p.closedSessions[idx]
        return { ...p, closedSessions: p.closedSessions.filter((e) => e.id !== entryId) }
      })
    }))
    return found
  },

  discardClosedSession(projectId, entryId) {
    set((s) => ({
      projects: s.projects.map((p) =>
        p.id !== projectId || !p.closedSessions
          ? p
          : { ...p, closedSessions: p.closedSessions.filter((e) => e.id !== entryId) }
      )
    }))
  },

  saveLayout(projectId, layout, viewport, now) {
    // The dialog validates too, but the command palette reaches this action directly, so the
    // store is the last gate before a name lands in a git-shared file.
    const name = layout.name.trim().slice(0, CANVAS_LAYOUT_NAME_MAX)
    if (!name) return 'invalid-name'
    const project = get().projects.find((p) => p.id === projectId)
    if (!project) return 'unknown-project'
    const layouts = project.layouts ?? []
    const idx = layouts.findIndex((l) => l.id === layout.id)
    // Replace-by-id never counts against the cap. A genuinely new layout past it is refused rather
    // than evicting the oldest: the list is shared, so the entry dropped to make room could be a
    // teammate's, and losing their work to make one Save succeed is worse than a Save that says no.
    if (idx === -1 && layouts.length >= CANVAS_LAYOUTS_CAP) return 'cap-reached'
    const stored: CanvasLayout = {
      ...layout,
      name,
      // A replace keeps the original creation moment: it is still the layout the user made that
      // day, whatever the caller stamped on the snapshot it has just rebuilt.
      createdAt: idx === -1 ? now : layouts[idx].createdAt,
      updatedAt: now
    }
    const next = idx === -1 ? [...layouts, stored] : layouts.map((l, i) => (i === idx ? stored : l))
    set((s) => ({
      projects: s.projects.map((p) =>
        p.id !== projectId
          ? p
          : {
              ...p,
              layouts: next,
              layoutViewports: { ...(p.layoutViewports ?? {}), [stored.id]: viewport }
            }
      )
    }))
    // Saving a layout touches no node, so no canvas edit will schedule the write for us - the same
    // persistence gap the capability setters close.
    markWorkspaceDirty()
    return 'saved'
  },

  renameLayout(projectId, layoutId, name, now) {
    const clean = name.trim().slice(0, CANVAS_LAYOUT_NAME_MAX)
    if (!clean) return
    let changed = false
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== projectId || !p.layouts?.some((l) => l.id === layoutId)) return p
        changed = true
        return {
          ...p,
          layouts: p.layouts.map((l) =>
            l.id === layoutId ? { ...l, name: clean, updatedAt: now } : l
          )
        }
      })
    }))
    if (changed) markWorkspaceDirty()
  },

  deleteLayout(projectId, layoutId) {
    let changed = false
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== projectId || !p.layouts?.some((l) => l.id === layoutId)) return p
        changed = true
        const layouts = p.layouts.filter((l) => l.id !== layoutId)
        // Both halves move together, and the shared pruner is what decides which cameras survive
        // so the store cannot grow a second opinion about it.
        return {
          ...p,
          layouts: layouts.length ? layouts : undefined,
          layoutViewports: pruneLayoutViewports(p.layoutViewports, layouts)
        }
      })
    }))
    if (changed) markWorkspaceDirty()
  },

  recordLayoutViewport(projectId, layoutId, viewport) {
    let changed = false
    set((s) => ({
      projects: s.projects.map((p) => {
        if (p.id !== projectId || !p.layouts?.some((l) => l.id === layoutId)) return p
        changed = true
        return { ...p, layoutViewports: { ...(p.layoutViewports ?? {}), [layoutId]: viewport } }
      })
    }))
    if (changed) markWorkspaceDirty()
  },

  reopenProject(id) {
    set((s) => {
      if (!s.projects.some((p) => p.id === id)) return s
      return {
        projects: s.projects.map((p) => (p.id === id ? { ...p, closed: false } : p)),
        activeProjectId: id
      }
    })
  },

  unhideProject(id) {
    set((s) => {
      if (!s.projects.some((p) => p.id === id && p.closed)) return s
      return { projects: s.projects.map((p) => (p.id === id ? { ...p, closed: false } : p)) }
    })
  },

  registerProject({ resolvedCwd, name, color, probed }) {
    // The same exact-match rule as `openFolderProject` (a folder maps to one project), with the
    // trailing slash stripped (`registeredCwd`).
    const cwd = registeredCwd(resolvedCwd)
    const existing = get().projects.find((p) => p.cwd === cwd)
    if (existing) {
      if (existing.closed) {
        // Un-close WITHOUT activation — reopenProject also activates, which is the exact
        // mutation the register tests are checked against (spec P6).
        get().unhideProject(existing.id)
      }
      return {
        project: get().projects.find((p) => p.id === existing.id) ?? existing,
        created: false,
        adopted: false
      }
    }
    if (probed) {
      // adoptProject's collision defense verbatim (deterministic in (id, folder)) — but appended
      // WITHOUT the `activeProjectId` write that makes adoptProject a human path.
      const taken = get().projects.some((p) => p.id === probed.id)
      const adopted = taken
        ? {
            ...probed,
            id: derivedProjectId(probed.id, collisionSeed(probed), (c) =>
              get().projects.some((p) => p.id === c))
          }
        : probed
      set((s) => ({ projects: [...s.projects, adopted] }))
      return { project: adopted, created: false, adopted: true }
    }
    const fallbackName = clampProjectName(folderName(cwd)) || 'Project'
    // `name` is the agent's `--name`, free text like a rename: same cap (issue #940).
    const project = {
      ...withNewProjectStorage(createProject(get().projects.length, clampProjectName(name ?? '') || fallbackName, cwd)),
      ...(color ? { color } : {})
    }
    set((s) => ({ projects: [...s.projects, project] }))
    return { project, created: true, adopted: false }
  },

  toWorkspace() {
    const { projects, activeProjectId } = get()
    // A relay tab (`remote`) is a live connection to another machine's project, never a
    // workspace on this disk — exclude it so it can't be written into this client's
    // workspace.json (the disk writer skips it too; see core/workspace-files.ts).
    return { version: 2, activeProjectId, projects: projects.filter((p) => !p.remote) }
  }
}))

/**
 * Add an EMPTY relay tab: a project for a connection whose host shared nothing that could be adopted
 * (a Team Access tab's fallback, a hosted team's placeholder). Marked `remote` like every relay tab,
 * because it IS one: the host's nodes reach it over canvas sync, so it must never be saved into this
 * machine's workspace (`toWorkspace` filters `remote`) nor, once its relay session is gone, resolve
 * to the local session (session.ts `sessionForProject`). Added like any project first, so it takes
 * the store's name cap and does not take the screen.
 */
export function addRelayTab(label: string): Project {
  const store = useProjects.getState()
  const relay = { ...store.addProject(label), remote: true }
  store.replaceProject(relay)
  return relay
}

// Codex launch caps must know a relay tab when they see one: its sessions run on ANOTHER machine's
// codex, which this machine's probe never saw (see `codexApprovalCaps`). Registered here rather
// than imported there, because this store imports workspace.ts, which imports codexCli.ts.
registerCodexRelayProjectCheck((id) => useProjects.getState().getProject(id)?.remote === true)