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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
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)