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.

52.1 KB
Raw Blame
import path from 'path'
import { healPathAsName } from '../shared/project-name'
import { neutralSshProjectNodes, routeSshProjectNodes } from '../shared/ssh-project-nodes'
import type { AgentPermissionMode } from '../shared/agents/config'
import { collisionSeed, derivedProjectId, legacyFileId } from '../shared/project-id'
import {
  applyLocalNodeExec,
  localNodeExec,
  stripSharedNodeExec,
  type LocalNodeExecMap
} from '../shared/node-exec'
import { sanitizeViews } from '../shared/kanban-views'
import { CLOSED_SESSIONS_CAP } from '../shared/types'
import type { BridgeLink, CanvasNodeState, ClosedSessionEntry, HandedOffTo, NavStop, Project, ProjectKanban, Viewport, Workspace } from '../shared/types'
import { projectCapabilityFields, readProjectCapabilities } from '../shared/project-capabilities'
import { loadedAgentBrowserPartition } from '../shared/browser-partition'
import { sanitizeProjectIcon, type ProjectIcon } from '../shared/project-icon'
import { sanitizeTriggerSpec } from '../shared/trigger'
import {
  pruneLayoutViewports,
  sanitizeLayouts,
  type CanvasLayout,
  type LayoutViewports
} from '../shared/canvas-layout'
import { isRecord } from '../shared/is-record'

/**
 * Drop a browser node's persisted `partition` unless it is exactly the jar THIS project (its
 * machine-local id) would mint. `project.json` is hostile input and `partition` is copied straight
 * to `<webview partition>`, so a foreign/cloned/unsafe stored value is jar forgery; it falls back to
 * the un-owned default session. Non-browser nodes and un-partitioned browser nodes are untouched.
 * See `loadedAgentBrowserPartition`. Pure and side-effect free (only clones the nodes it changes).
 */
function sanitizeBrowserPartitions(nodes: CanvasNodeState[], projectId: string): CanvasNodeState[] {
  return nodes.map((n) => {
    if (n.kind !== 'browser' || n.partition === undefined) return n
    const safe = loadedAgentBrowserPartition(n.partition, projectId)
    if (safe === n.partition) return n
    const { partition: _dropped, ...rest } = n
    return safe === undefined ? rest : { ...rest, partition: safe }
  })
}

/**
 * The trigger twin of `sanitizeBrowserPartitions`, applied on every path a node array crosses the
 * shared-file boundary (read AND write): a `trigger` spec is git-shared CONTENT (the team shares
 * the schedule), but the file is hostile input, so only a spec that passes the strict shape rules
 * survives — a malformed shape, an oversized payload, a smuggled extra key, or a spec sitting on a
 * non-trigger node all degrade to an INERT node with no spec, never a crash and never a
 * half-honored value. Note what this deliberately does NOT decide: whether the trigger may FIRE on
 * this machine — that is the machine-local arm store's question (`core/trigger-arm-store.ts`), and
 * a freshly loaded file can never answer it. See @shared/trigger for the trust model.
 */
export function sanitizeNodeTriggers(nodes: CanvasNodeState[]): CanvasNodeState[] {
  return nodes.map((n) => {
    if (n.trigger === undefined) return n
    if (n.kind === 'trigger') {
      const safe = sanitizeTriggerSpec(n.trigger)
      if (safe) return { ...n, trigger: safe }
    }
    const { trigger: _dropped, ...rest } = n
    return rest
  })
}

export const PROJECT_DIR = '.nodeterm'
export const PROJECT_FILE = 'project.json'

/** Where a cwd-less ("inline") project's content lives, under userData: the twin of a folder
 *  project's `<cwd>/.nodeterm/project.json`. One file per project, named by the project id. */
export const INLINE_PROJECT_DIR = 'inline-projects'

/**
 * May this project id name a file in `userData/inline-projects/`?
 *
 * workspace.json is hand-editable (and on Server Edition it sits next to other users' reach), so an
 * id read back out of it is INPUT, not something we wrote. Minted ids are `project-<base36>-<hex>`
 * (`freshProjectId` / `derivedProjectId`), well inside this charset; anything else — a separator, a
 * `..` segment, a leading dot, an empty or absurdly long string — is refused, and its entry simply
 * keeps the pre-file inline shape (content in the index) instead of naming a path we did not mean.
 */
export function isInlineProjectFileId(id: string): boolean {
  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(id) && !id.includes('..')
}

/** The data file for one inline project, relative to userData. */
export function inlineProjectFileRelPath(id: string): string {
  return path.join(INLINE_PROJECT_DIR, `${id}.json`)
}

/**
 * On-disk shape of <cwd>/.nodeterm/project.json — a GIT-SHARED document (users are asked to
 * commit it so the canvas travels with the repo).
 *
 * It carries CONTENT ONLY. Nothing in here may be state two machines opening the same repo would
 * legitimately disagree about, because git copies this file verbatim: `git worktree add`, a branch
 * checkout, `reset --hard` or a `stash pop` re-materialise every field into a second folder. That
 * is how one machine's project `id` came to name two folders — two tabs answering to one id, the
 * active canvas written into both, then flushed into the other folder's file (field corruption,
 * 2026-08). Machine-local state lives in the machine-local index instead (`IndexEntryV3`).
 *
 * No `cwd` field — the containing folder IS the cwd (that's what makes the folder relocatable).
 * Node cwds inside the root are stored relative ("./sub").
 */
export interface ProjectFileV1 {
  version: 1
  /** Monotonic save counter; picks a winner when an offline cache and the file diverge (SSH). */
  rev: number
  savedAt: string
  /**
   * LEGACY, and never identity. Written as a machine-INDEPENDENT value (`legacyFileId`) purely so
   * a build older than this one still accepts the file instead of sidelining it to `.corrupt-<ts>`
   * inside the user's repo; ignored on read — the index entry says who this project is. Optional
   * because a newer writer may already have dropped it, and because the SSH branch still puts its
   * entry id here as an opaque lineage marker (see `splitWorkspace` / `reconcileSsh`).
   */
  id?: string
  name: string
  color: string
  /** Sanitized on the way in (`fileToProject`) and only ever emitted when valid (`projectToFile`) —
   *  see `sanitizeProjectIcon`. An off/invalid icon adds no bytes to the committed file. */
  icon?: ProjectIcon
  /**
   * NOT a camera any more — a SUGGESTED one, derived from where the canvas's own nodes sit
   * (`framingViewport`).
   *
   * This user's actual camera is machine-local (a pan is not an edit two people share, yet it
   * dirtied the committed file on every gesture) and rides `IndexEntryV3.viewport`. What is
   * written here is a function of the content, so it is identical on every machine, and it is
   * still written at all because a pre-change build REQUIRES the field — without it that build
   * renders the project with `viewport.zoom` undefined and takes the canvas down.
   *
   * On read it is a fallback only: the index entry wins, and a pre-change file's real camera is
   * inherited once on the way into the index.
   */
  viewport?: Viewport
  nodes: CanvasNodeState[]
  bridges?: BridgeLink[]
  ropes?: BridgeLink[]
  /**
   * LEGACY (read-only), same rule as `viewport`: a managed Claude account id names a credential
   * dir under THIS machine's userData ({userData}/claude-accounts/<id>), so a teammate's copy of
   * the file pointed at an account that does not exist for them. It rides
   * `IndexEntryV3.defaultAccountId` now; still read once for a file this machine has not seen.
   */
  defaultAccountId?: string
  defaultPermissionMode?: AgentPermissionMode
  /**
   * Per-project capability switch (see @shared/project-capabilities): deliberately IN the
   * git-shared file — the team shares the policy — which is exactly why reads are strict
   * (`readProjectCapabilities`, literal `true` only) and why the switch alone grants nothing.
   */
  agentBrowserControl?: boolean
  /** Per-project capability switch (@shared/project-capabilities): agents may message other agent
   *  nodes in this project. Git-shared like `agentBrowserControl`, read with the same strictness. */
  agentMessaging?: boolean
  /** Per-project capability switch (@shared/project-capabilities): agents may file GitHub issues
   *  for product gaps they hit. Git-shared like the two above, read with the same strictness —
   *  and the only one of the three whose effect leaves this machine, so a stranger's `true` here
   *  buys nothing until this machine's user answers its notice. */
  agentIssueReporting?: boolean
  dinoHighScore?: number
  kanban?: ProjectKanban
  /**
   * Named geometry snapshots for this canvas (@shared/canvas-layout). CONTENT, exactly like
   * `kanban`: an arrangement is a fact about the nodes this file already carries, and restoring
   * one writes those same node fields, so a teammate's checkout is entitled to it.
   *
   * Re-sanitized in BOTH directions (`fileToProject` on the way in, `projectToFile` on the way
   * out), see `sanitizeLayouts`. The per-layout CAMERA is not here and never will be: it is
   * machine-local and rides `IndexEntryV3.layoutViewports`, the same rule as `viewport`.
   */
  layouts?: CanvasLayout[]
  // NOTE: closedSessions is deliberately NOT here — see `Project.closedSessions` /
  // `IndexEntryV3.closedSessions`. It is machine-local, like `viewport`/`breadcrumbs`.
}

/**
 * One workspace.json v3 entry — a REF, in one of three kinds. name/color are a cached header so an
 * unavailable ref still renders a labeled grey tab.
 *
 *   kind           | source of truth for the content       | what the index entry carries
 *   ---------------|---------------------------------------|--------------------------------------
 *   folder-ref     | `<cwd>/.nodeterm/project.json` (git)   | `cwd` + header + machine-local half
 *   ssh-ref        | the same file on the host              | `ssh` + header + `cache` (offline)
 *   local-data-ref | `userData/inline-projects/<id>.json`   | `dataFile` + header + `project` (cache)
 *
 * The third kind is the cwd-less canvas ("New project", no folder). It used to have no file at
 * all — the whole `Project` rode `project` inside this index, which is ONE file with
 * last-writer-wins semantics: a second instance sharing this userData could erase a canvas that
 * existed nowhere else (measured in #621). It now has its own atomically written file like the
 * other two, and `project` stays beside it as a cache, so a build older than this one still finds
 * the canvas where it expects it.
 *
 * In all three kinds the file carries CONTENT and the entry carries the machine-local half
 * (id, viewport, defaultAccountId, breadcrumbs, closedSessions, localApprovalId, localExec) — the
 * #510 rule. That uniformity is the point: it is also what makes a future "Set folder…" a MOVE of
 * the data file into `<cwd>/.nodeterm/project.json` rather than a reshaping of the project.
 */
export interface IndexEntryV3 {
  /**
   * THE project id — this machine's, and the only authority for it. It is minted here (a new
   * project, or `probeFolder`'s adoption of a folder) and never read back out of the shared
   * project file, which is what makes two copies of one canvas two independent projects.
   */
  id: string
  /** Stable machine-local trust identity. Never copied into the shared project file. */
  localApprovalId?: string
  name: string
  color: string
  closed?: boolean
  /** Set alongside `closed: true` — see `Project.closedAt`. */
  closedAt?: number
  /** See `HandedOffTo`. Index-only; never written to the shared project.json. Validated on every
   *  load (`sanitizeHandedOffTo`): workspace.json is hand-editable input. */
  handedOffTo?: HandedOffTo
  /** MACHINE-LOCAL camera for a ref'd project (local folder or ssh). Where this user is looking is
   *  not something a repo shares — the file's copy churned the git diff on every pan. */
  viewport?: Viewport
  /** MACHINE-LOCAL default managed Claude account for a ref'd project: the id names a credential
   *  dir in THIS machine's userData, so it is meaningless in anyone else's checkout. */
  defaultAccountId?: string
  /**
   * MACHINE-LOCAL record that this machine's user has acknowledged each capability switch for THIS
   * entry (the one-time clone notice, @shared/project-capability-consent). Never copied into the
   * shared project file — a repo must not be able to carry its own consent — and keyed to the
   * entry, so a second worktree of the same repo (a second entry) notifies again, on purpose.
   */
  capabilityAck?: import('../shared/project-capability-consent').CapabilityAckMap
  /** MACHINE-LOCAL camera navigation history for a ref'd project. Same rule as `viewport`: this
   *  user's "where was I" is not something a repo shares. See NavStop. */
  breadcrumbs?: NavStop[]
  /**
   * MACHINE-LOCAL camera per canvas layout, keyed by layout id (@shared/canvas-layout). The
   * layouts themselves are shared CONTENT in the project file; where THIS user was looking when
   * they saved one is not, same rule as `viewport` and `breadcrumbs` above. Pruned against the
   * live layouts on every load and save (`pruneLayoutViewports`), because workspace.json is
   * forever and a canvas churns through ids.
   */
  layoutViewports?: LayoutViewports
  /**
   * MACHINE-LOCAL closed-session history for a ref'd project (folder or ssh) — see
   * `Project.closedSessions`. Whose trash can holds what deleted nodes is a per-machine fact, not
   * shared content: a delete's full node-state blob would otherwise churn a committed,
   * teammate-visible `.nodeterm/project.json` on every one. Validated/capped/trigger-sanitized on
   * every load (`sanitizeLoadedClosedSessions`) exactly like an inline project's embedded
   * `closedSessions` — this file is hand-editable input too.
   */
  closedSessions?: ClosedSessionEntry[]
  cwd?: string
  ssh?: Project['ssh']
  cache?: ProjectFileV1
  /**
   * This entry is a LOCAL-DATA ref: its content lives in `userData/inline-projects/<id>.json` and
   * THAT FILE is the source of truth. Absent = the pre-file shape, where `project` below IS the
   * content. Never set together with `ssh`.
   *
   * Set together with `cwd` it is a FOLDER-DATA-REF (issue #1145): a folder project whose canvas
   * is kept here instead of in `<cwd>/.nodeterm/project.json` (`Project.storeInAppData`). The
   * folder is the project's working directory only — nothing reads or writes its `.nodeterm/`, and
   * the watcher does not watch it. `project` (the cache) is stored without `cwd`, so a build that
   * predates the kind opens it as a plain inline canvas instead of writing into the folder.
   *
   * A build that predates this field ignores it and reads `project`, which is why the two are
   * written together for one release (the downgrade contract).
   */
  dataFile?: boolean
  /**
   * The cwd-less canvas.
   *
   * Before `dataFile` this WAS the storage. Beside a `dataFile` entry it is a CACHE — the local
   * twin of the ssh `cache` above — doing two jobs: an older build still finds the canvas here,
   * and a data file that is missing or corrupt right now falls back to it instead of opening an
   * empty canvas. The file wins whenever it reads.
   */
  project?: Project
  /** MACHINE-LOCAL per-node exec values (`shell`, `ssh.extraArgs`) for a ref'd project. They are
   *  stripped from the shared project file precisely so a cloned/hostile one cannot run code
   *  (@shared/node-exec), and kept here — in userData, never git-shared — so the user's own custom
   *  shell / advanced ssh args still survive a restart. Inline (`project`) entries need none: they
   *  live in this same machine-local file already. */
  localExec?: LocalNodeExecMap
  /**
   * MACHINE-LOCAL settings overlay for this entry — the half of the project settings that is NOT
   * git-shared (`.nodeterm/settings.json` is the shared half). Same rule as `localExec`: it lives in
   * userData because a shell, a launch command or an env var this user chose for THIS checkout is
   * not something a repo may carry — and, read the other way, a repo may not put values here.
   * Re-sanitized on every load (`sanitizeProjectLocalSettings`): workspace.json is hand-editable,
   * so what comes back out of it is input, not state we wrote.
   */
  localSettings?: import('../shared/project-settings').ProjectLocalSettings
  /** The last shared settings.json seen for an SSH entry — the settings twin of `cache`, used while
   *  the server is unreachable. Never set for a local/inline entry (their shared doc is one disk
   *  read away). Validated on load by re-parsing it, exactly like a file read off the remote host:
   *  what sits in workspace.json is no more trusted than what sits on the server. */
  settingsCache?: import('../shared/project-settings').ProjectSettingsFileV1
  /**
   * The one-time exec migration has run for this entry: its project file has been searched once for
   * the exec values it carried from BEFORE the trust boundary existed (a jump host's `ProxyCommand`
   * put there by `createSshTerminalNode`), and they were hoisted into `localExec` above.
   *
   * Absent = not migrated yet. Set on the first save after the upgrade for every entry whose file we
   * could actually READ — an entry that was unavailable at that moment stays unmarked, so its values
   * are still hoisted when the folder/server comes back. A folder adopted AFTER the upgrade is
   * written with the flag already set, which is what keeps a cloned project.json (hostile) out of
   * the hoist. See `hoistLegacyNodeExec`.
   */
  execMigrated?: boolean
}

/**
 * A folder project's canvas as a folder-data-ref stores it — in its data file and its index cache:
 * the project WITHOUT `cwd` (node cwds stay absolute; an older build reads the cache as a plain
 * inline canvas) and without the runtime-only flags. ONE definition for `splitWorkspace` and for
 * the store's "the move into the folder did not land" path.
 */
export function appDataCanvas(p: Project): Project {
  const { unavailable: _u, cwd: _cwd, storeInAppData: _s, ...inline } = p
  return inline
}

/** A folder project whose canvas lives in app data (issue #1145) — see `IndexEntryV3.dataFile`. */
export function isFolderDataRef(e: Pick<IndexEntryV3, 'cwd' | 'ssh' | 'dataFile'>): boolean {
  return !!(e.dataFile && e.cwd && !e.ssh)
}

/**
 * The folder whose `.nodeterm/project.json` holds this entry's CONTENT, or undefined. Not the same
 * question as "does it have a cwd": a folder-data-ref has a working directory and keeps its canvas
 * in app data, so every reader or writer of the folder FILE asks this, and everything that only
 * needs where terminals run keeps reading `cwd`.
 */
export function folderFileCwd(e: Pick<IndexEntryV3, 'cwd' | 'ssh' | 'dataFile'>): string | undefined {
  return e.cwd && !e.dataFile ? e.cwd : undefined
}

export interface WorkspaceIndexV3 {
  version: 3
  activeProjectId: string
  entries: IndexEntryV3[]
}

const isUnder = (p: string, root: string): boolean => {
  const rel = path.relative(root, p)
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
}

/** Rewrites node cwds under `root` to portable "./…" form; other paths untouched. */
export function toPortableNodes(nodes: CanvasNodeState[], root: string): CanvasNodeState[] {
  return nodes.map((n) => {
    if (!n.cwd || !isUnder(n.cwd, root)) return n
    const rel = path.relative(root, n.cwd)
    return { ...n, cwd: rel === '' ? '.' : `./${rel.split(path.sep).join('/')}` }
  })
}

/** Resolves portable "./…" node cwds against `root`; absolute cwds pass through. */
export function resolveNodes(nodes: CanvasNodeState[], root: string): CanvasNodeState[] {
  return nodes.map((n) => {
    if (!n.cwd || !(n.cwd === '.' || n.cwd.startsWith('./'))) return n
    return { ...n, cwd: n.cwd === '.' ? root : path.join(root, n.cwd.slice(2)) }
  })
}

/**
 * The project as it is written to the SHARED file: content only.
 *
 * Dropped on the way out, because a second machine opening the same repo would legitimately
 * disagree about them: the project `id` (identity — see `IndexEntryV3.id`), the `viewport` (this
 * user's camera) and `defaultAccountId` (a credential dir under this userData). Kept, because a
 * team genuinely shares them: name, color, nodes, bridges/ropes, the kanban board, the permission
 * default, the dino record.
 *
 * The two fields a pre-change build cannot do without are still emitted, as machine-INDEPENDENT
 * stand-ins: `id` (`legacyFileId`, derived from the name — it refuses a file without one) and
 * `viewport` (`framingViewport`, derived from the nodes — it dereferences the field unguarded).
 * Both are functions of content, so every machine writes the same bytes. Override `id` only where
 * the file is NOT a git-copied artifact and something still reads it as a lineage marker (the ssh
 * mirror; see `splitWorkspace`).
 */
export function projectToFile(
  p: Project,
  rev: number,
  savedAt: string,
  id: string = legacyFileId(p.name)
): ProjectFileV1 {
  // The project file is a SHARED document (git, or the remote host). Exec-enabling node fields
  // (`shell`, `ssh.extraArgs`) never leave this machine in it — they ride the machine-local index
  // entry instead (`localNodeExec` / `IndexEntryV3.localExec`). See @shared/node-exec.
  // Trigger specs are additionally normalized on the way OUT too, so a malformed spec that
  // reached the live nodes some other way (a peer mutation, a hand edit) is never written into
  // the shared file as if it were ours.
  const nodes = sanitizeNodeTriggers(
    stripSharedNodeExec(
      p.cwd
        ? toPortableNodes(p.nodes, p.cwd)
        : // The SSH mirror records shared LAYOUT, not where this machine runs a node: the host's own
          // desktop opens the same file as a local project (issue #1186). Re-derived on every load.
          neutralSshProjectNodes(p.nodes, p.ssh)
    )
  )
  const icon = sanitizeProjectIcon(p.icon)
  // The SECOND seam for layouts. Live project data is reachable by a peer canvas mutation and by a
  // hand edit that already got past a read, and whatever we write is what the next machine trusts:
  // the same reason `normalizeNodeIcon` and `sanitizeNodeTriggers` validate on the way OUT as well
  // as IN. Validating one direction only passes every round-trip test while leaving the other one
  // open. See @shared/canvas-layout.
  const layouts = sanitizeLayouts(p.layouts)
  // Same two-seam rule for the board (see `sanitizeKanban`).
  const kanban = p.kanban ? sanitizeKanban(p.kanban) : undefined
  const bridges = p.bridges ? sanitizeLinks(p.bridges) : undefined
  const ropes = p.ropes ? sanitizeLinks(p.ropes) : undefined
  return {
    version: 1,
    rev,
    savedAt,
    id,
    name: p.name,
    color: p.color,
    viewport: framingViewport(nodes),
    nodes,
    ...(icon ? { icon } : {}),
    // The same two-seam rule as the board: what we write is what the next machine trusts.
    ...(bridges ? { bridges } : {}),
    ...(ropes ? { ropes } : {}),
    ...(p.defaultPermissionMode ? { defaultPermissionMode: p.defaultPermissionMode } : {}),
    // Strict-normalised (literal true only, known keys only) and omitted when off — an off
    // capability adds no bytes to the committed file. `capabilityAck` is deliberately NOT here:
    // the acknowledgment is machine-local (IndexEntryV3.capabilityAck) and must never travel.
    ...projectCapabilityFields(p),
    ...(p.dinoHighScore ? { dinoHighScore: p.dinoHighScore } : {}),
    ...(kanban ? { kanban } : {}),
    // `layoutViewports` is deliberately absent: a field of that name in the shared file is a
    // forgery (a repo carrying one person's camera), and `fileToProject` never reads one.
    ...(layouts ? { layouts } : {})
  }
}

/** The kanban shape rule used on every load path (file refs, ssh cache, inline projects):
 *  anything but {columns: [], assignments: []} arrays — including v1 {columns, cards}
 *  boards — is dropped, so a legacy/hand-edited shape degrades to the fresh default
 *  instead of crashing the board render. */
export function validKanban(k: unknown): k is ProjectKanban {
  return (
    !!k &&
    Array.isArray((k as ProjectKanban).columns) &&
    Array.isArray((k as ProjectKanban).assignments)
  )
}

/**
 * A project's `bridges` / `ropes` as they may be ADMITTED. Both come straight out of the git-shared,
 * hand-editable project file, and every reader treats them as `BridgeLink[]`: the canvas restores
 * them with `ropes.map((r) => ropeEdge(r.id, r.source, r.target))`, the server-change merge maps
 * their ids, the headless factory spreads them. A non-list, or one `null` entry, threw on project
 * load. The rule: a non-list is dropped; an entry that is not an object with non-empty string `id`,
 * `source` and `target` is dropped; every other field an entry carries round-trips untouched.
 *
 * Returns the SAME array when nothing needed repair, so a clean file is never rewritten, and
 * `undefined` for a non-list. Used on every seam `sanitizeKanban` is.
 */
export function sanitizeLinks(links: unknown): BridgeLink[] | undefined {
  if (!Array.isArray(links)) return undefined
  const ok = (l: unknown): l is BridgeLink =>
    isRecord(l) &&
    typeof l.id === 'string' && l.id !== '' &&
    typeof l.source === 'string' && l.source !== '' &&
    typeof l.target === 'string' && l.target !== ''
  return links.every(ok) ? (links as BridgeLink[]) : links.filter(ok)
}

/**
 * The board as it may be ADMITTED: `validKanban`'s shape rule plus the per-entry repairs a
 * hand-edited, git-shared file needs before a renderer touches it — a render throw on a bad board
 * boot-loops the app (the board view choice persists in localStorage).
 *
 * Repairs, never inventions:
 *  - a column that is not an object with a string `id` and `title` is dropped (React cannot render
 *    an object title, and `resolveColumnRef` lower-cases it);
 *  - a column's `category` that is not a STRING is dropped. An unknown string is KEPT: it may be a
 *    category a newer build added, and dropping it here would erase that build's data from the
 *    shared file on our next save. Readers treat it as absent (`columnCategory`);
 *  - an assignment that is not an object with string `nodeId` and `columnId` is dropped, so is a
 *    card's SECOND assignment (a clean git merge can leave two; the first is what readers use), and
 *    a non-string `rank` (a rank string readers cannot use is kept, like an unknown category);
 *  - a card's `assignees` that is not a list is dropped, and entries without a string name and
 *    colour are filtered out of one that is (`cardAssignees` is the matching reader);
 *  - `views` go through `sanitizeViews` (a non-list is dropped, bad entries repaired or dropped).
 * Every other field — known or not — round-trips untouched.
 *
 * Returns the SAME object when nothing needed repair, so a clean file is never rewritten, and
 * `undefined` for anything `validKanban` refuses. Used on every seam: `fileToProject` (in),
 * `projectToFile` (out), and the inline-project branch of the store, which bypasses both.
 */
export function sanitizeKanban(k: unknown): ProjectKanban | undefined {
  if (!validKanban(k)) return undefined
  let changed = false
  const columns: ProjectKanban['columns'] = []
  for (const c of k.columns as unknown[]) {
    if (!isRecord(c) || typeof c.id !== 'string' || typeof c.title !== 'string') {
      changed = true
      continue
    }
    if ('category' in c && typeof c.category !== 'string') {
      const { category: _drop, ...rest } = c
      columns.push(rest as unknown as ProjectKanban['columns'][number])
      changed = true
      continue
    }
    columns.push(c as unknown as ProjectKanban['columns'][number])
  }
  const assignments: ProjectKanban['assignments'] = []
  const assigned = new Set<string>()
  for (const a of k.assignments as unknown[]) {
    if (!isRecord(a) || typeof a.nodeId !== 'string' || typeof a.columnId !== 'string') {
      changed = true
      continue
    }
    // A clean git merge can leave one card assigned twice; the first copy is the one every reader
    // (`columnForNode`) has always answered with, so it is the one kept.
    if (assigned.has(a.nodeId)) {
      changed = true
      continue
    }
    assigned.add(a.nodeId)
    // Same rule as `category`: a rank STRING the readers cannot use is kept (they treat it as
    // absent, and the next write into that column re-keys it — @shared/kanban-order); a non-string
    // is dropped.
    if ('rank' in a && typeof a.rank !== 'string') {
      const { rank: _drop, ...rest } = a
      assignments.push(rest as unknown as ProjectKanban['assignments'][number])
      changed = true
      continue
    }
    assignments.push(a as unknown as ProjectKanban['assignments'][number])
  }
  // Card assignees: iterated by the board, the card and the log diff. A non-list is dropped and an
  // entry without a string name + colour filtered (`cardAssignees` is the matching reader).
  let meta: unknown = k.meta
  if (Array.isArray(k.meta)) {
    let metaChanged = false
    const out = (k.meta as unknown[]).map((m) => {
      if (!isRecord(m) || !('assignees' in m)) return m
      const list = m.assignees
      if (!Array.isArray(list)) {
        metaChanged = true
        const { assignees: _drop, ...rest } = m
        return rest
      }
      const valid = list.filter(
        (x) => isRecord(x) && typeof x.name === 'string' && typeof x.color === 'string'
      )
      if (valid.length === list.length) return m
      metaChanged = true
      return { ...m, assignees: valid }
    })
    if (metaChanged) {
      meta = out
      changed = true
    }
  }
  // Saved views: their own tolerant reader (@shared/kanban-views), same identity discipline.
  let views: ProjectKanban['views'] | undefined = k.views
  if ('views' in k) {
    views = sanitizeViews(k.views)
    if (views !== k.views) changed = true
  }
  if (!changed) return k
  const next: ProjectKanban = { ...k, columns, assignments, ...(meta !== undefined ? { meta: meta as ProjectKanban['meta'] } : {}) }
  if (views) next.views = views
  else delete next.views
  return next
}

/** A `{x, y}` point, checked at the boundary because the file is hostile input. */
function validPoint(p: unknown): p is { x: number; y: number } {
  return (
    !!p &&
    typeof p === 'object' &&
    typeof (p as { x: unknown }).x === 'number' &&
    typeof (p as { y: unknown }).y === 'number'
  )
}

/**
 * Tolerant-reader guard for `closedSessions`, same "drop it rather than trust it" rule as
 * `validKanban`: a legacy/hand-edited/hostile file degrades to no history instead of crashing.
 *
 * The POSITION fields are not optional politeness — they are the crash. `recreateNodeFromSnapshot`
 * assigns `node.position = reattach ? snapshot.position : snapshot.absolutePosition` UNGUARDED, so
 * an entry missing either one hands React Flow a node with `position: undefined`, and
 * `adoptUserNodes` dereferences `position.x` — a white-screen renderer crash from a file anyone can
 * commit. `kind` is checked for the sibling failure: a garbage kind reaches `buildBase`'s switch,
 * returns null, and the row silently consumes itself and vanishes (`buildBase` already `return
 * null`s for anything unknown, so a non-empty string is enough here — no NodeKind enum copy).
 */
export function validClosedSessions(x: unknown): x is ClosedSessionEntry[] {
  return (
    Array.isArray(x) &&
    x.every((e) => {
      if (!e || typeof e !== 'object') return false
      const entry = e as ClosedSessionEntry
      if (typeof entry.id !== 'string' || typeof entry.closedAt !== 'number') return false
      if (!validPoint(entry.absolutePosition)) return false
      const node = entry.node as CanvasNodeState | undefined
      if (!node || typeof node !== 'object') return false
      return typeof node.kind === 'string' && node.kind.length > 0 && validPoint(node.position)
    })
  )
}

/**
 * The tolerant reader for closed-session history wherever it is admitted from disk: an
 * `IndexEntryV3.closedSessions` (ref'd project) or an inline `IndexEntryV3.project.closedSessions`
 * — both live in workspace.json, which is hand-editable input exactly like a git-shared
 * `.nodeterm/project.json`. Validates shape (`validClosedSessions`), caps at `CLOSED_SESSIONS_CAP`
 * (newest-first — the cap drops the tail), and re-normalizes each snapshot's trigger spec, same as
 * a live node. No exec-strip / browser-partition treatment here: unlike the shared project file,
 * this data never leaves this machine, so a node's own `shell`/`ssh.extraArgs` survive a reopen
 * intact — there is nothing to re-attach from a separate machine-local map. Returns `undefined`
 * for anything that fails the shape guard or has nothing to admit, never `[]`.
 */
export function sanitizeLoadedClosedSessions(x: unknown): ClosedSessionEntry[] | undefined {
  if (!validClosedSessions(x)) return undefined
  const capped = x.slice(0, CLOSED_SESSIONS_CAP)
  if (!capped.length) return undefined
  return capped.map((e) => {
    // `sessionId` (issue #531) is handed straight to the transcript readers, so it is re-checked
    // as a STRING here rather than trusted from the type — workspace.json is hand-editable, and a
    // number or object would ride the IPC into a resolver that expects to call `.test()` on it.
    // Core's own `SESSION_ID_RE` still gates the value's SHAPE; this only gates its kind.
    const { sessionId, ...rest } = e
    return {
      ...rest,
      ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
      node: sanitizeNodeTriggers([e.node])[0]
    }
  })
}

/** The index is hand-editable: keep only a well-formed record. A record without a finite `at` is
 *  not one at all (the project is an ordinary SSH project again); a malformed or oversized
 *  `hostId`/`projectId` is dropped on its own, which still leaves the guard in place. */
export function sanitizeHandedOffTo(v: unknown): HandedOffTo | undefined {
  if (!v || typeof v !== 'object') return undefined
  const o = v as Record<string, unknown>
  if (typeof o.at !== 'number' || !Number.isFinite(o.at)) return undefined
  const ok = (s: unknown, max: number): s is string => typeof s === 'string' && s.length > 0 && s.length <= max
  return {
    at: o.at,
    ...(ok(o.hostId, 64) ? { hostId: o.hostId } : {}),
    ...(ok(o.projectId, 128) ? { projectId: o.projectId } : {})
  }
}

/**
 * The shared file plus this machine's own half of the project.
 *
 * `base.id` is REQUIRED and never defaulted from the file: identity comes from the index entry
 * (or, for a folder that has none yet, from `probeFolder` minting one). Making it a parameter is
 * the structural version of that rule — there is no code path left that can accidentally adopt a
 * git-shared id.
 */
export function fileToProject(
  f: ProjectFileV1,
  base: {
    /** This machine's id for the project (index entry, or freshly minted on adoption). */
    id: string
    cwd?: string
    ssh?: Project['ssh']
    closed?: boolean
    closedAt?: number
    /** This machine's "Share with team" handover record (index entry only; never from the file). */
    handedOffTo?: HandedOffTo
    /** This machine's camera. Falls back to the file's legacy one (a pre-change file, or a
     *  teammate's) and then to a frame that puts the canvas on screen. */
    viewport?: Viewport
    /** This machine's default managed account; falls back to the file's legacy value. */
    defaultAccountId?: string
    /** This machine's clone-notice acknowledgments for this entry (never from the file). */
    capabilityAck?: import('../shared/project-capability-consent').CapabilityAckMap
    /** This machine's navigation history for this entry (never from the file). */
    breadcrumbs?: NavStop[]
    /** This machine's camera per canvas layout for this entry. Taken from the index entry ONLY: a
     *  field of this name in the shared file is a forgery and is never read. Pruned below against
     *  the layouts the file actually carries. */
    layoutViewports?: LayoutViewports
    /** This machine's closed-session history for this entry (never from the file) — already
     *  validated/capped/trigger-sanitized by the caller (`sanitizeLoadedClosedSessions`). */
    closedSessions?: ClosedSessionEntry[]
    /** This machine's own exec values for these nodes (from the local index entry). A file read
     *  WITHOUT them — an adopted/cloned folder, a probe — gets the safe defaults, never the file's
     *  own `shell`/`ssh.extraArgs`. */
    localExec?: LocalNodeExecMap
  }
): Project {
  const defaultAccountId = base.defaultAccountId ?? f.defaultAccountId
  const icon = sanitizeProjectIcon(f.icon)
  const layouts = sanitizeLayouts(f.layouts)
  // A camera for a layout the file no longer carries names nothing: a teammate deleted the layout
  // (they are shared content, the cameras are not), or a hand edit dropped it. Pruning on the way
  // in as well as out is what stops workspace.json accumulating orphans forever.
  const layoutViewports = pruneLayoutViewports(base.layoutViewports, layouts)
  const kanban = sanitizeKanban(f.kanban)
  const bridges = f.bridges ? sanitizeLinks(f.bridges) : undefined
  const ropes = f.ropes ? sanitizeLinks(f.ropes) : undefined
  return {
    id: base.id,
    // A project whose stored name IS its own path is one this machine (or a teammate's) created
    // before the basename fix, when a Windows cwd yielded the whole path instead of the folder.
    // Heal it on read: a name equal to the cwd carries no information the cwd does not already
    // carry, so re-deriving it cannot lose a name the user chose. Anything else is left ALONE —
    // a deliberate rename that happens to look path-ish stays exactly as typed.
    name: healPathAsName(f.name, base.cwd),
    color: f.color,
    ...(icon ? { icon } : {}),
    viewport: base.viewport ?? f.viewport ?? framingViewport(f.nodes),
    // applyLocalNodeExec DROPS whatever the file carried in the exec fields (it is not ours) and
    // re-attaches only what this machine typed. See @shared/node-exec. `sanitizeBrowserPartitions`
    // is the same "the file is hostile input" treatment for a browser node's session jar: a stored
    // `partition` survives only when it is exactly the one THIS project (base.id, machine-local)
    // would mint — a foreign/cloned/unsafe one drops to un-owned default session. See
    // loadedAgentBrowserPartition; without it a cloned project.json forges another project's jar.
    nodes: sanitizeNodeTriggers(
      sanitizeBrowserPartitions(
        applyLocalNodeExec(
          base.cwd
            ? resolveNodes(f.nodes, base.cwd)
            : // An SSH project's nodes run on ITS host, whatever the shared file says (issue #1186):
              // the host's own desktop, a teammate or git writes nodes into that file without this
              // machine's routing fields. See @shared/ssh-project-nodes.
              routeSshProjectNodes(f.nodes, base.ssh),
          base.localExec
        ),
        base.id
      )
    ),
    // Hostile input like the rest of the file: a non-list or a malformed entry threw on load.
    ...(bridges ? { bridges } : {}),
    ...(ropes ? { ropes } : {}),
    ...(defaultAccountId ? { defaultAccountId } : {}),
    ...(f.defaultPermissionMode ? { defaultPermissionMode: f.defaultPermissionMode } : {}),
    // The file is hostile input: only a literal `true` under a known key survives the read
    // (readProjectCapabilities). `"true"`, 1, {} et al. vanish here, at the boundary.
    ...readProjectCapabilities(f),
    ...(f.dinoHighScore ? { dinoHighScore: f.dinoHighScore } : {}),
    ...(kanban ? { kanban } : {}),
    ...(base.cwd ? { cwd: base.cwd } : {}),
    ...(base.ssh ? { ssh: base.ssh } : {}),
    ...(base.closed ? { closed: true } : {}),
    ...(base.closedAt ? { closedAt: base.closedAt } : {}),
    // Machine-local, from the index entry ONLY: a file field named `handedOffTo` is not this
    // machine's record and is never read.
    ...(base.handedOffTo ? { handedOffTo: base.handedOffTo } : {}),
    // Machine-local, from the index entry ONLY: a file field named `capabilityAck` is a forgery
    // attempt (the shared file cannot carry this machine's consent) and is simply never read.
    ...(base.capabilityAck ? { capabilityAck: base.capabilityAck } : {}),
    // Machine-local, from the index entry ONLY: a file field named `breadcrumbs` is a forgery
    // attempt (the shared file cannot carry this machine's navigation history) and is never read.
    ...(base.breadcrumbs?.length ? { breadcrumbs: base.breadcrumbs } : {}),
    // Machine-local, from the index entry ONLY, same rule as `breadcrumbs`: a file field named
    // `closedSessions` is never read here — the shared file cannot carry this machine's trash can.
    ...(base.closedSessions?.length ? { closedSessions: base.closedSessions } : {}),
    ...(layouts ? { layouts } : {}),
    // Machine-local, from the index entry ONLY, same rule as `breadcrumbs`.
    ...(layoutViewports ? { layoutViewports } : {})
  }
}

/**
 * The camera for a canvas nobody on this machine has ever framed (an adopted folder, a teammate's
 * committed canvas): zoom 1, panned so the top-left node sits just inside the corner.
 *
 * Without it a shared canvas whose nodes live at x=4000 opened onto empty space — the file no
 * longer carries the author's camera, so the default {0,0,1} would have been a blank screen and
 * "commit it to share the canvas" would have been a lie.
 *
 * A plain loop with a finiteness guard per AXIS, not `Math.min(...map())`, because this now runs
 * inside `projectToFile` — i.e. inside every `save()` — where the old shape had two ways to ruin
 * one: a hand-edited/corrupt `position` made `Math.min` return NaN, which `JSON.stringify` writes
 * into the COMMITTED file as `"x": null` (a field that used to be the user's own viewport and
 * could not be poisoned by node data), and spreading a large enough node array blows the call
 * stack, which would now fail the whole save rather than one node.
 */
export function framingViewport(nodes: CanvasNodeState[]): Viewport {
  let minX = Infinity
  let minY = Infinity
  for (const n of nodes) {
    // A child's position is relative to its frame, so it cannot anchor the camera.
    if (n.parentId) continue
    const pos = n.position as { x?: unknown; y?: unknown } | undefined
    if (typeof pos?.x === 'number' && Number.isFinite(pos.x) && pos.x < minX) minX = pos.x
    if (typeof pos?.y === 'number' && Number.isFinite(pos.y) && pos.y < minY) minY = pos.y
  }
  return {
    x: Number.isFinite(minX) ? 80 - minX : 0,
    y: Number.isFinite(minY) ? 80 - minY : 0,
    zoom: 1
  }
}

/**
 * Content equality ignoring the bookkeeping fields — decides whether a save must bump rev +
 * rewrite.
 *
 * The legacy `id` (and a pre-change file's `viewport` / `defaultAccountId`) IS compared, because a
 * file still carrying a machine's project id must be rewritten exactly once — that is the
 * migration that scrubs the identity out of the repo. Both sides agree from then on
 * (`legacyFileId` is derived from the name, so it is the same on every machine), which is what
 * keeps the answer "unchanged" on every later save.
 */
export function sameProjectContent(a: ProjectFileV1, b: ProjectFileV1): boolean {
  const strip = ({ rev: _r, savedAt: _s, ...rest }: ProjectFileV1) => rest
  return JSON.stringify(strip(a)) === JSON.stringify(strip(b))
}

/**
 * Splits an in-memory workspace into the v3 index + the project files to write.
 *
 * `files` is keyed by CWD (folder refs, written into the user's own repo); `dataFiles` is keyed by
 * PROJECT ID (cwd-less canvases, written under `userData/inline-projects`). Both hold a
 * `ProjectFileV1` — one shape, which is what lets a future "Set folder…" MOVE the second into the
 * first instead of converting it.
 */
export function splitWorkspace(
  ws: Workspace,
  revOf: (projectId: string) => number,
  savedAt: string
): {
  index: WorkspaceIndexV3
  files: Map<string, ProjectFileV1>
  dataFiles: Map<string, ProjectFileV1>
} {
  const entries: IndexEntryV3[] = []
  const files = new Map<string, ProjectFileV1>()
  const dataFiles = new Map<string, ProjectFileV1>()
  const seenIds = new Set<string>()
  for (const incoming of ws.projects) {
    // A relay tab is a LIVE connection to another machine's project, not a workspace on this
    // disk — it has no disk representation at all. Drop it entirely (no ref, no inline, no
    // cache) BEFORE the unavailable handling, so it leaks in none of the branches below.
    if (incoming.remote) continue
    // Two entries may never share an id. The index is keyed by it — which folder's project.json a
    // save writes, and every id-keyed lookup that reads the index back (ssh control paths,
    // board-log + approval routing, presence, agent status) resolves only the FIRST match. The
    // load-time repair (WorkspaceStore.repairDuplicateIds) is where a corrupt store is normally
    // healed; this is the last resort for a duplicate that reaches save some other way — a
    // hand-edited index, a runtime collision — and it uses the same deterministic derivation, so
    // both paths agree on the id instead of fighting over it.
    const id = seenIds.has(incoming.id)
      ? derivedProjectId(incoming.id, collisionSeed(incoming), (candidate) => seenIds.has(candidate))
      : incoming.id
    seenIds.add(id)
    const p = id === incoming.id ? incoming : { ...incoming, id }
    const header = {
      id: p.id, name: p.name, color: p.color,
      ...(p.closed ? { closed: true } : {}),
      ...(p.closedAt ? { closedAt: p.closedAt } : {}),
      // On the header so even an unavailable placeholder's entry keeps it: the guard must hold
      // while the server is unreachable too.
      ...(p.handedOffTo ? { handedOffTo: p.handedOffTo } : {})
    }
    // The machine-local half of a REF'd project (a folder or an ssh endpoint), which used to ride
    // the shared file: this user's camera and this machine's default managed account. Deliberately
    // NOT added to the `unavailable` branch below — a placeholder's viewport is the {0,0,1} of an
    // empty stand-in, and writing it would forget where the user actually was; `WorkspaceStore.save`
    // restores both from the previous entry instead, exactly as it does for `cache`/`localExec`.
    // Inline entries need none of this: they store the whole Project verbatim.
    const layoutViews = pruneLayoutViewports(p.layoutViewports, sanitizeLayouts(p.layouts))
    const localState = {
      ...(p.viewport ? { viewport: p.viewport } : {}),
      ...(p.defaultAccountId ? { defaultAccountId: p.defaultAccountId } : {}),
      // The clone-notice acknowledgment rides the machine-local entry, never the shared file
      // (projectToFile does not emit it — pinned by project-capability-consent.test.ts).
      ...(p.capabilityAck ? { capabilityAck: p.capabilityAck } : {}),
      ...(p.breadcrumbs?.length ? { breadcrumbs: p.breadcrumbs } : {}),
      // Same rule: whose trash can holds what is machine-local, capped on the way OUT as well as
      // in (see CLOSED_SESSIONS_CAP) — an in-memory list inflated some other way must not be
      // written back uncapped.
      ...(p.closedSessions?.length
        ? { closedSessions: p.closedSessions.slice(0, CLOSED_SESSIONS_CAP) }
        : {}),
      // The layouts themselves are content and ride the file; only this machine's camera per
      // layout is kept here, pruned against the layouts that will actually be written.
      ...(layoutViews ? { layoutViewports: layoutViews } : {})
    }
    if (p.unavailable) {
      // Placeholder (folder missing / server unreachable at load): its nodes:[] is not real
      // data. Emit a header-only ref preserving the ref shape — NEVER a file and NEVER an ssh
      // cache built from the placeholder, so a later save can't clobber the on-disk source.
      if (p.ssh) entries.push({ ...header, ssh: p.ssh })
      // A folder-data-ref placeholder keeps `dataFile`: without it the next load would read the
      // folder's own `.nodeterm/project.json` — a stale or a teammate's canvas — as this project.
      else if (p.cwd && p.storeInAppData) entries.push({ ...header, cwd: p.cwd, dataFile: true })
      else if (p.cwd) entries.push({ ...header, cwd: p.cwd })
      else {
        const { unavailable: _u, ...inline } = p
        entries.push({ ...header, project: inline })
      }
      continue
    }
    // Exec-enabling node fields are stripped from every project file / ssh cache; the local user's
    // own values are preserved HERE, in the machine-local index (@shared/node-exec).
    const local = localNodeExec(p.nodes)
    const localRef = local ? { localExec: local } : {}
    if (p.ssh) {
      entries.push({
        ...header,
        ...localState,
        ...localRef,
        ssh: p.ssh,
        // The ssh mirror keeps the ENTRY id in its `id` field. That file is not a git-copied
        // artifact — it is one folder on one host — and `reconcileSsh` reads the id as the marker
        // that tells a DIFFERENT lineage (another machine's project, a re-added folder) from our
        // own, which is what stops an empty newborn canvas from clobbering a populated server
        // file. It is no longer identity even there: `fileToProject` is handed `e.id` regardless.
        cache: projectToFile(p, revOf(p.id), savedAt, p.id)
      })
    } else if (p.cwd && p.storeInAppData) {
      // The FOLDER-DATA-REF (issue #1145): a folder project whose canvas lives in
      // `userData/inline-projects/<id>.json`, so nothing is written into the folder. It is stored
      // exactly like a cwd-less canvas — the file and its `project` cache both hold the project
      // WITHOUT `cwd`, so node cwds stay absolute and the inline load/write paths serve it
      // unchanged — and the entry adds the `cwd` back. Two consequences are deliberate:
      //  - It never claims `files` for its cwd, so it can sit beside a folder ref on the same
      //    folder without either being demoted to the second-tab branch below.
      //  - A build that predates the kind reads the cwd-less cache and sees an ordinary inline
      //    canvas: it loses the folder binding but never writes into the folder.
      //  - A hand-edited id we will not turn into a path gets no file — the cache IS the storage,
      //    as for the pre-file inline shape — but it still never falls through to the folder.
      const inline = appDataCanvas(p)
      if (isInlineProjectFileId(p.id)) dataFiles.set(p.id, projectToFile(inline, revOf(p.id), savedAt))
      entries.push({ ...header, ...localState, ...localRef, cwd: p.cwd, dataFile: true, project: inline })
    } else if (p.cwd && !files.has(p.cwd)) {
      files.set(p.cwd, projectToFile(p, revOf(p.id), savedAt))
      entries.push({ ...header, ...localState, ...localRef, cwd: p.cwd })
    } else if (p.cwd) {
      // Another project already claimed this cwd (two tabs on one folder). Keying `files` by cwd
      // would collapse them last-wins, and reload would resurrect BOTH entries from the one file
      // (duplicate ids, first canvas lost). Emit this one INLINE instead — kept verbatim in the
      // index, no file write — so both canvases survive a save→load round trip.
      const { unavailable: _u, ...inline } = p
      entries.push({ ...header, project: inline })
    } else {
      // The cwd-less canvas: a LOCAL-DATA ref (see IndexEntryV3). The file is the source of truth
      // and `project` rides along as the cache — the dual-write that lets an older build open this
      // canvas, and that keeps a half-done migration (file written, index write lost, or the
      // reverse) readable either way round.
      //
      // It is otherwise treated exactly like the other two refs: content in the file, the
      // machine-local half on the entry (`localState`), exec-enabling node fields hoisted into
      // `localExec` and STRIPPED from the file by `projectToFile`. That last part costs nothing
      // today — the file sits in userData, as machine-local as the index it replaces — and it is
      // what makes the file safe to move into a repo the day "Set folder…" moves it.
      const { unavailable: _u, ...inline } = p
      if (!isInlineProjectFileId(p.id)) {
        // A hand-edited id we will not turn into a path: keep the pre-file shape, where the index
        // IS the storage for this one entry.
        entries.push({ ...header, project: inline })
        continue
      }
      dataFiles.set(p.id, projectToFile(p, revOf(p.id), savedAt))
      entries.push({ ...header, ...localState, ...localRef, dataFile: true, project: inline })
    }
  }
  return { index: { version: 3, activeProjectId: ws.activeProjectId, entries }, files, dataFiles }
}

/** Pretty, stable-order JSON for the project file (git-diffable; the index stays compact). */
export function serializeProjectFile(f: ProjectFileV1): string {
  return JSON.stringify(f, null, 2)
}