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.

183 KB
Raw Blame
import type { SshConnection } from '../shared/ssh'
import { promises as fs } from 'fs'
import { createHash, randomUUID } from 'node:crypto'
import path from 'path'
import { renameAtomic, sweepForeignTempFiles, writeFileAtomic } from './fs-atomic'
import { IPC } from '../shared/ipc'
import { platform } from './platform'
import {
  DEFAULT_PROJECT_ID, EMPTY_WORKSPACE,
  type BridgeLink, type CanvasNodeState, type HandedOffTo, type KanbanColumn, type KanbanLabel, type Project,
  type ProjectKanban, type Workspace, type WorkspaceSaveOptions, type WorkspaceV1
} from '../shared/types'
import { contentOf, type CanvasContent } from '../shared/canvas-content'
import {
  PROJECT_DIR, PROJECT_FILE, appDataCanvas, fileToProject, folderFileCwd, inlineProjectFileRelPath, isFolderDataRef,
  isInlineProjectFileId,
  projectToFile, resolveNodes, sameProjectContent,
  sanitizeLoadedClosedSessions, sanitizeNodeTriggers, serializeProjectFile, splitWorkspace,
  sanitizeHandedOffTo,
  sanitizeKanban,
  sanitizeLinks,
  type IndexEntryV3, type ProjectFileV1, type WorkspaceIndexV3
} from './workspace-files'
import { projectSettingsPath, readProjectSettingsFile, writeProjectSettingsFile } from './project-settings-files'
import { gitTracksFile } from './git-tracked'
import { carryWhiteboards, type WhiteboardLocation } from './whiteboards'
import type { PrepareFolderStorageResult, ProjectStorageKind, ReleaseFolderFilesResult } from '../shared/project-storage'
import {
  parseProjectSettingsFile, sameProjectSettingsContent, sanitizeProjectLocalSettings,
  sanitizeProjectSettingsDoc, serializeProjectSettingsFile,
  type ProjectLocalSettings, type ProjectSettingsDoc, type ProjectSettingsFileV1,
  type ProjectSettingsSnapshot
} from '../shared/project-settings'
import { readProjectCapabilities, type ProjectCapability } from '../shared/project-capabilities'
import type { CapabilityAckMap } from './project-capability-consent'
import { carryLocalNodeExec, hoistLegacyNodeExec, stripSharedNodeExec, type LocalNodeExecMap } from '../shared/node-exec'
import { collisionSeed, derivedProjectId, freshProjectId } from '../shared/project-id'
import {
  pruneLayoutViewports,
  sanitizeLayoutViewports,
  sanitizeLayouts
} from '../shared/canvas-layout'
import { appendProjectNode, removeProjectNode, type RemoteNodeInput } from './project-node-append'
import { editProjectCardLabels, ensureProjectBoard, setProjectCardColumn, type CardLabelEdit } from './project-kanban-write'
import { boardLabels, cardMeta } from '../shared/kanban-labels'
import { localizeAdoptedNode } from '../shared/adopt-cwd'
import { routeSshProjectNode, routeSshProjectNodes } from '../shared/ssh-project-nodes'
import { clampProjectName, folderName } from '../shared/project-name'
import { countOpenProjects } from '../shared/project-limit'
import { SYSTEM_NODE_COLORS } from '../shared/node-colors'
import { codedError } from './relay/admin-error'
import { createLaunchClaimLedger } from './launch-claim-ledger'

/** What `WorkspaceStore.adoptFolder` did: the project now holding the folder, and whether this call
 *  added it (`created: false` = an existing project already held the same real directory). */
export interface AdoptFolderResult {
  projectId: string
  projectName: string
  created: boolean
}

/**
 * The seam a content authority (the Server Edition's canvas authority, `core/canvas-authority.ts`)
 * governs shared projects through. For every project it governs it is the one writer of the CONTENT
 * fields (nodes, bridges, ropes, board items); the renderer's whole-workspace saves and this store's
 * loads still carry everything else, so both are passed through it.
 */
export interface ContentAuthorityHooks {
  /** Rewrite governed projects' content fields just before a save is split and written. */
  overlaySave(ws: Workspace): Promise<Workspace>
  /** Rewrite governed projects' content fields in a load result. */
  overlayLoad(ws: Workspace): Promise<Workspace>
}

/** Checked remote read: `absent` (no file — safe to push our cache) is NOT `error` (connection
 *  down / ssh failure — a failed read is never evidence of absence, so nothing may be pushed). */
export type RemoteReadResult = { status: 'ok'; content: string } | { status: 'absent' } | { status: 'error' }

/** Remote file access for SSH projects (implemented in src/main over SshFs — src/core stays electron-free). */
export interface RemoteWorkspaceIO {
  read(projectId: string, ssh: NonNullable<Project['ssh']>): Promise<RemoteReadResult>
  write(projectId: string, ssh: NonNullable<Project['ssh']>, content: string): Promise<boolean>
  /** `.nodeterm/settings.json` on the same host. Optional: an IO that predates the settings leg (or
   *  a test fake that only cares about project.json) simply leaves the project on its offline cache,
   *  which is exactly the disconnected behaviour. */
  readSettings?(projectId: string, ssh: NonNullable<Project['ssh']>): Promise<RemoteReadResult>
  writeSettings?(projectId: string, ssh: NonNullable<Project['ssh']>, content: string): Promise<boolean>
}

/** cwd -> its project-file path. The path is a pure function of the cwd string, and the hosted
 *  relay's per-frame access check (`projectIdsForNode` → `canvasInputs`) needs it for every index
 *  entry on every frame, where `path.join` was most of the cost. Bounded, oldest out: the key set is
 *  the cwds the index has ever held, which only grows by the user adding folders. */
const projectFilePaths = new Map<string, string>()
const PROJECT_FILE_PATHS_CAP = 1024
const projectFilePath = (cwd: string): string => {
  let file = projectFilePaths.get(cwd)
  if (file === undefined) {
    file = path.join(cwd, PROJECT_DIR, PROJECT_FILE)
    if (projectFilePaths.size >= PROJECT_FILE_PATHS_CAP) projectFilePaths.delete(projectFilePaths.keys().next().value!)
    projectFilePaths.set(cwd, file)
  }
  return file
}

/** The data file of one cwd-less ("inline") project: `userData/inline-projects/<id>.json`. Only
 *  ever called with an id `isInlineProjectFileId` has already accepted — workspace.json is
 *  hand-editable, so an id read back out of it is input and may not reach a path unchecked. */
/** Per-project side files (the board log) of a folder project kept in app data, under userData. */
const PROJECT_SIDE_FILES_DIR = 'project-files'

/**
 * The directory whose `.nodeterm/` holds a local project's own files — settings.json and the board
 * log: the folder of a folder ref, the per-project app-data root of a folder-data-ref (the folder's
 * `.nodeterm/` layout, moved under userData), and none for ssh (routed separately) or a cwd-less
 * canvas.
 */
export const appDataProjectRoot = (projectId: string): string =>
  path.join(platform().userDataDir, PROJECT_SIDE_FILES_DIR, projectId)

function settingsRootFor(e: IndexEntryV3): string | undefined {
  if (e.ssh) return undefined
  if (isFolderDataRef(e)) return isInlineProjectFileId(e.id) ? appDataProjectRoot(e.id) : undefined
  return folderFileCwd(e)
}

const inlineFilePath = (projectId: string): string =>
  path.join(platform().userDataDir, inlineProjectFileRelPath(projectId))

/** How many recent mirror payloads a project remembers for self-write recognition (see
 *  `recentMirrorHashes`). Big enough to cover a burst of throttled writes inside one poll window;
 *  small enough that a server-side revert to genuinely old content still reads as external. */
const RECENT_MIRROR_CAP = 8

/** `projectIdsForNode`'s answer for an id no project holds (shared, frozen: callers only read it). */
const NO_PROJECTS: readonly string[] = Object.freeze([])

const contentHash = (content: string): string => createHash('sha256').update(content).digest('hex')

/**
 * This machine's exec values for one ref'd entry's file, exactly as the load computes them
 * (`WorkspaceStore.execOverlay`) but without its bookkeeping, so a read-only caller can ask: a
 * migrated entry answers with its own `localExec`; an entry still owed the one-time migration also
 * hoists what its file carried from before the trust boundary (@shared/node-exec).
 */
function localExecOverlay(e: IndexEntryV3, f: ProjectFileV1): LocalNodeExecMap | undefined {
  if (e.execMigrated) return e.localExec
  const hoisted = hoistLegacyNodeExec(f.nodes)
  return hoisted ? { ...hoisted, ...e.localExec } : e.localExec
}

/** A project file's `rev` as a number. The file is hand-editable input; a string there would turn
 *  `rev + 1` into string concatenation. */
const fileRev = (f: ProjectFileV1): number =>
  typeof f.rev === 'number' && Number.isFinite(f.rev) ? f.rev : 0

/** The board keys that belong to the FILE, not to the content vocabulary: the GitHub sync config
 *  and the pull-request link overrides are coupled to columns but are never carried by a canvas
 *  mutation, so a content write must not be able to change them. */
const BOARD_CONFIG_KEYS = ['github', 'pullLinks'] as const

/**
 * `board` (the content's) with the file's own `github` / `pullLinks`, field-level: every other key
 * comes from `board`, those two from `file` — present when the file has them, absent when it does
 * not, whatever `board` says. Key order follows `board`, so a board that came out of this file
 * serializes in the file's own order. When the content has no board, the file's board is kept as it
 * is: a content write never deletes a board.
 */
function boardWithFileConfig(
  board: ProjectKanban | undefined,
  file: ProjectKanban | undefined
): ProjectKanban | undefined {
  if (!board) return file
  const own = (file ?? {}) as Record<string, unknown>
  const isConfig = (k: string): boolean => (BOARD_CONFIG_KEYS as readonly string[]).includes(k)
  const out: Record<string, unknown> = {}
  for (const [k, v] of Object.entries(board)) {
    if (!isConfig(k)) out[k] = v
    else if (own[k] !== undefined) out[k] = own[k]
  }
  for (const k of BOARD_CONFIG_KEYS) if (!(k in out) && own[k] !== undefined) out[k] = own[k]
  return out as unknown as ProjectKanban
}

/** An edge list to write: the content's, except that an EMPTY list does not add a key the base did
 *  not carry — "no list" and "an empty list" are the same content, and writing `"bridges": []` into
 *  a file nobody drew a link in is a diff in the user's repository nobody made. */
const edgeList = (next: BridgeLink[], prev: BridgeLink[] | undefined): BridgeLink[] | undefined =>
  next.length || prev !== undefined ? next : undefined

/** `base` with its content fields replaced by `content`: nodes and edge lists whole, the board
 *  field-level (`boardWithFileConfig`). Everything else — name, colour, icon, capabilities, layouts,
 *  the machine-local half — is `base`'s. */
function withContent(base: Project, content: CanvasContent): Project {
  const out: Project = { ...base, nodes: content.nodes }
  const bridges = edgeList(content.bridges, base.bridges)
  const ropes = edgeList(content.ropes, base.ropes)
  const kanban = boardWithFileConfig(content.kanban, base.kanban)
  if (bridges) out.bridges = bridges
  else delete out.bridges
  if (ropes) out.ropes = ropes
  else delete out.ropes
  if (kanban) out.kanban = kanban
  else delete out.kanban
  return out
}

/** A cwd-less canvas's content out of its index cache, admitted with the sanitizers the inline load
 *  branch applies: workspace.json is hand-editable, and the entry's `project` can be the raw copy
 *  (the load sanitizes what it RETURNS, not the entry). Null for a cache with no node list. */
function inlineContent(p: Project): CanvasContent | null {
  if (!Array.isArray(p.nodes)) return null
  return contentOf({
    nodes: sanitizeNodeTriggers(p.nodes),
    bridges: p.bridges ? sanitizeLinks(p.bridges) : undefined,
    ropes: p.ropes ? sanitizeLinks(p.ropes) : undefined,
    kanban: sanitizeKanban(p.kanban)
  })
}

/** What `writeDataFile` did. The save path ignores it; `writeProjectContent` answers with it. */
type DataFileWrite = 'written' | 'unchanged' | 'ahead' | 'refused' | 'failed' | 'skipped'

/** Alias of the shared `ProjectSettingsSnapshot` (moved to `shared/project-settings.ts` so the
 *  renderer's `ProjectSettingsApi` can name the shape without importing core) — the store's
 *  methods keep this name in their signatures. */
export type ProjectSettingsState = ProjectSettingsSnapshot

/** A parsed project file together with the exact bytes it was parsed from. `lastWritten` must
 *  record `raw` — see the field it caches. */
interface ProjectFileRead {
  file: ProjectFileV1
  raw: string
}

/** One index entry paired with the project loadV3 built from it (and, for a local ref, the file it
 *  was built from). The uniqueness pass needs all three: it re-keys the project the renderer sees,
 *  the entry that persists that identity, and the project.json the id was wrongly read from. */
interface LoadedEntry {
  entry: IndexEntryV3
  project: Project
  file?: ProjectFileV1
}

export async function writeAtomic(filePath: string, content: string): Promise<void> {
  // Unique temp per write: writers that bypass each other's queue (a second app instance, the SSH
  // poll's index write) must never share a tmp file — interleaved writes into one shared tmp
  // published spliced JSON under the atomic rename. writeFileAtomic also removes its own temp on
  // failure (project.json temps live in the USER'S repo, where litter is visible) and retries the
  // rename over Windows sharing violations. The error still propagates; per-file callers swallow
  // it by design.
  await writeFileAtomic(filePath, content)
}

/**
 * Whether `real` (already a real path) is the filesystem root, the real home directory, or a folder
 * that contains it. A shared folder is readable by every teammate, Viewers included, and a home
 * holds the ssh keys, the agents' credentials and nodeterm's own hook tokens. An unreadable home is
 * judged by the path as given; an empty one only refuses the root.
 */
async function containsHome(real: string, home: string): Promise<boolean> {
  if (path.parse(real).root === real) return true
  if (!home) return false
  const homeReal = await fs.realpath(home).catch(() => home)
  const rel = path.relative(real, homeReal)
  return rel === '' || (!path.isAbsolute(rel) && rel.split(path.sep)[0] !== '..')
}

/**
 * v3 persistence: workspace.json is an index (refs + inline canvases); each local
 * project's data lives in <cwd>/.nodeterm/project.json (source of truth). The
 * renderer contract is unchanged: load() returns / save() takes an assembled
 * v2-shaped Workspace.
 */
export class WorkspaceStore {
  /** file path -> exact content of the file as we last WROTE or READ it (skip-unchanged + watcher
   *  self-write suppression). Always the RAW bytes, never a re-serialization: a project.json whose
   *  on-disk formatting differs from ours (a teammate's editor, a git checkout) would otherwise
   *  never match isSelfWrite, so every fs event on it read as an external change forever — endless
   *  spurious reloads and conflict bars (field bug 2026-08-10). */
  private lastWritten = new Map<string, string>()
  /** `lastWritten`'s bytes, parsed once. `save()` compares every folder project's candidate against
   *  its last write on EVERY autosave; re-parsing each file each time was pure waste. Keyed by the
   *  raw string, so any `lastWritten.set` elsewhere invalidates it by construction. */
  private lastWrittenParsed = new Map<string, { raw: string; parsed: ProjectFileV1 }>()
  /** `projectIdsForNode`'s node → projects map, and the `canvasInputs` snapshot it was built from. */
  private nodeProjectMemo: { inputs: unknown[]; map: Map<string, readonly string[]> } | null = null
  /** The index bytes we last wrote and the file's size/mtime/inode right after, so an unchanged
   *  index is not rewritten on every autosave — but one another writer changed on disk still is.
   *  The inode is what catches a same-size rewrite on a coarse-mtime filesystem: every writer
   *  publishes by rename, so any rewrite is a new inode. Any other index write of ours clears it, so
   *  it only ever describes the last write `save()` made. */
  private lastIndexWrite: { json: string; size: number; mtimeMs: number; ino: number } | null = null
  /** project id -> rev of the last written/loaded file. */
  private revs = new Map<string, number>()
  /** Entries whose one-time exec migration could NOT run (their project file was unreadable at load).
   *  They stay unmarked on disk, so the hoist is retried when the folder/server comes back. */
  private execUnmigrated = new Set<string>()
  /** A hoist happened this load → show the one-time note (fired with the migration's save, exactly
   *  like the v2→v3 one: a silent change to how the user's own config is stored is not acceptable). */
  private pendingExecNote = false
  /** Raw v2 file content, kept until the first save backs it up (migration). */
  private pendingV2Backup: string | null = null
  /** The corrupt-index recovery note is a one-time-per-run banner: every later load in the same run
   *  sees the same missing index next to the same backup and must stay quiet. */
  private corruptNoteSent = false
  /** ssh project ids whose last mirror write was dropped (connection down). Retried on every
   *  save/connect until a write confirms — guarantees the server file lands regardless of node
   *  type or creation timing. Runtime-only, never persisted. */
  private unmirrored = new Set<string>()
  /** ssh project ids whose remote file has been read-compared at least once this run. Until then a
   *  save may NOT blind-write the mirror: a fresh/re-added project would clobber a populated
   *  server file it has never looked at (the ".nodeterm reset itself" bug). Runtime-only. */
  private reconciled = new Set<string>()
  /** ssh project id -> node ids a save REMOVED from that project's cache and the server has not been
   *  told about yet. The one discriminator between the two ways our cache can lack a node the server
   *  has: "the user deleted it here" (the deletion must travel — never rescue it back) and "we simply
   *  never had it" (the phone appended it while we were looking away — never delete it). Both rescue
   *  sites consult it. An id is retired ONLY by a READ that no longer lists it (`confirmClearedDeletions`)
   *  or by an adopt that overrules our deletions — never by a write ack, which is optimistic for the
   *  throttle's trailing write and cost the 2026-09-06 resurrection bug.
   *  Runtime-only: after a restart an UNMIRRORED clear is indistinguishable from a
   *  node we never had, and the tie is broken toward rescuing (a resurrected node is visible and
   *  deletable again; a deleted session node is gone with no trace of where it went). */
  private clearedNodes = new Map<string, Set<string>>()
  /** ssh project id -> sha256 of the last few project.json payloads THIS store handed to
   *  `remoteIO.write`. The SSH twin of `lastWritten`'s watcher self-write suppression: the 15 s
   *  poll and the connect-time refresh read the very file the mirror writes, so a reconcile can
   *  read the store's OWN bytes back — either a write that just landed, or (because the real IO's
   *  5 s throttle acks a trailing write optimistically) an OLDER own write the trailing one has
   *  not yet replaced. Recognized by exact bytes, they are never an external change: without this
   *  a rev-only decision "adopted" our own mirror and broadcast it, raising the Reload/Keep-mine
   *  conflict bar over a file nobody else touched — and the older-write echo could rescue back a
   *  node the user had just deleted. Several hashes (RECENT_MIRROR_CAP), not one, precisely for
   *  that throttle window. Runtime-only: after a restart the rev comparison is the arbiter, as
   *  before. */
  private recentMirrorHashes = new Map<string, string[]>()
  /** project id -> this machine's settings overlay, already sanitized. The map — not the index
   *  entry — is the live copy: `splitWorkspace` rebuilds entries from the renderer's Workspace,
   *  which has never carried machine-local state, so every save would otherwise drop the overlay
   *  (the same reason `localExec`/`cache` are re-attached below). Absent = no overlay. */
  private localSettingsByProject = new Map<string, ProjectLocalSettings>()
  /** ssh project id -> last shared settings.json seen on that host (offline copy). Only entries that
   *  round-tripped through `parseProjectSettingsFile` are in here. */
  private settingsCacheByProject = new Map<string, ProjectSettingsFileV1>()
  /** ssh project ids whose settings.json was git-conflict-marked on the last read: `writeSshSettings`
   *  refuses while an id is in here instead of picking a side of the merge (the local leg refuses
   *  the same way, straight off the file it re-reads). Cleared as soon as a read finds the file
   *  parsing again — or gone. Runtime-only, and deliberately NOT relied on to be populated: a write
   *  that finds both settings maps cold does its own read first, because "a read established this
   *  flag before any write" is an assumption about panel order, not something this store enforces. */
  private settingsConflictByProject = new Set<string>()
  /** project id -> the shared settings file as last read/written, i.e. the rev source for the NEXT
   *  write. Runtime-only: a write that has not read first starts at rev 1, which is the same thing
   *  a fresh file means. */
  private lastSharedSettings = new Map<string, ProjectSettingsFileV1>()
  /** Last index written/loaded — lets readLocalRef/refresh resolve entries without a full load. */
  private index: WorkspaceIndexV3 | null = null
  /** Optional hook fired after every load()/save() — the watcher re-syncs its watch set (Task 5). */
  onPersist?: () => void
  /**
   * What the most recent `loadInner` found at the index path: `read` (a shape this build builds a
   * workspace from, empty or not), `absent` (no file — a first run), or `unreadable` (the file is
   * there but could not be read, did not parse, or is a shape this build does not recognise, such
   * as a newer build's). It describes the LAST load, so a caller about to write a fresh index can
   * ask whether doing so would replace one it never read
   * (`adoptFolder`, which loads without sidelining and so leaves no backup behind).
   */
  private indexReadState: 'read' | 'absent' | 'unreadable' = 'absent'
  /**
   * Projects `adoptFolder` added that no renderer has loaded yet. A renderer's save is its whole
   * workspace and `saveNow` rebuilds the index from it, so a browser tab opened before a headless
   * adoption would otherwise delete the adopted entry on its next autosave. A renderer can only
   * delete a project it has loaded, so an entry no renderer has seen is never treated as deleted:
   * the renderer save path re-appends it (`withPendingAdoptions`) until an OWNER client's load
   * hands it out (a client that cannot save cannot be the one whose save would drop it).
   */
  private pendingAdoptions = new Set<string>()
  /** Exactly-once claim of renderer-delivered held launches across viewers (#1173). */
  private readonly launchClaims = createLaunchClaimLedger()
  /** The content authority, when this process runs one (Server Edition hosting a team). */
  private contentAuthority: ContentAuthorityHooks | null = null

  constructor(private remoteIO?: RemoteWorkspaceIO) {}

  /** Attach (or, with null, detach) the content authority whose overlays every later save and load
   *  pass through. Set once at boot; the Server Edition sets it after its first index load (the
   *  authority adopts every shared project itself) and clears it on close. */
  setContentAuthority(hooks: ContentAuthorityHooks | null): void {
    this.contentAuthority = hooks
  }

  private get indexPath(): string {
    return path.join(platform().userDataDir, 'workspace.json')
  }

  registerIpc(): void {
    platform().handleWithSender(IPC.workspaceLoad, async (senderId: number) => {
      const workspace = await this.load()
      // The renderer now holds these, so from here on its saves speak for them. Only the ids this
      // load actually returned: an adoption that landed while the load was in flight stays pending.
      // And only for a client that CAN save: a relay peer or a hosted-team guest reaches this same
      // handler but is refused `workspace:save`, so its load proves nothing about the owner's tabs,
      // and clearing on it let the first teammate to join hand a stale owner tab the right to drop
      // the shared project. A platform that cannot tell (a test double) counts every caller.
      if (platform().isOwnerClient?.(senderId) !== false) {
        for (const p of workspace.projects) this.pendingAdoptions.delete(p.id)
      }
      return workspace
    })
    platform().handle(IPC.workspaceSave, (workspace: Workspace, opts?: WorkspaceSaveOptions) =>
      this.saveFromRenderer(workspace, opts?.localOnly === true))
    platform().handleWithSender(IPC.workspaceClaimLaunch,
      (senderId: number, nodeId: unknown, command: unknown, manual: unknown) =>
        this.launchClaims.claim(nodeId as string, command as string, manual === true, senderId))
    platform().handle(IPC.workspaceProbeFolder, (folder: string) => this.probeFolder(folder))
    platform().handle(IPC.workspaceProjectFileState, (cwd: unknown) =>
      typeof cwd === 'string' && cwd ? this.projectFileState(cwd) : 'unreadable')
    // Issue #1145. Host-only for every peer (core/relay/access-policy.ts): both write files.
    platform().handle(IPC.workspaceReleaseFolderFiles, (projectId: unknown, removeTracked: unknown) =>
      typeof projectId === 'string'
        ? this.releaseFolderFiles(projectId, removeTracked === true)
        : { ok: false, reason: 'not-app-data' })
    platform().handle(IPC.workspacePrepareFolderStorage, (projectId: unknown) =>
      typeof projectId === 'string' ? this.prepareFolderStorage(projectId) : { ok: false, reason: 'not-app-data' })
    platform().handle(IPC.workspaceProjectStorage, (projectId: unknown) =>
      typeof projectId === 'string' ? this.projectStorage(projectId) : 'none')
    platform().handle(IPC.projectSettingsRead, (projectId: unknown) =>
      typeof projectId === 'string' ? this.readProjectSettings(projectId) : null)
    platform().handle(IPC.projectSettingsWriteShared, (projectId: unknown, doc: ProjectSettingsDoc) =>
      typeof projectId === 'string' ? this.writeProjectSettings(projectId, doc) : false)
    platform().handle(IPC.projectSettingsUpdateLocal,
      (projectId: unknown, local: ProjectLocalSettings | undefined) =>
        typeof projectId === 'string' ? this.updateLocalProjectSettings(projectId, local) : false)
  }

  /**
   * `sideline` (default true) forwards to readProjectFile: an unparsable/wrong-shape local
   * project.json is renamed to `.corrupt-<ts>` so a later save can't overwrite the only copy —
   * correct for boot/renderer loads. Read-only callers (e.g. the relay `projects.list` blob, which
   * a phone can trigger mid git-merge) pass false so a conflict-marked file is left hand-resolvable.
   */
  async load(opts?: { sideline?: boolean }): Promise<Workspace> {
    let result = await this.loadInner(opts?.sideline ?? true)
    const authority = this.contentAuthority
    if (authority) {
      try {
        result = await authority.overlayLoad(result)
      } catch (err) {
        // Answer the load WITHOUT the overlay rather than throw. `loadInner` has already set
        // `this.index`, so the empty-save guard at the top of `saveNow` (`!this.index`) no longer
        // protects it: a renderer left without the projects this load failed to hand over can still
        // save (a new project, say), and that save rebuilds the index without them and sweeps their
        // inline data files. A stale copy is the safe side — the next save is overlaid again.
        console.warn(`[workspace] content overlay failed on load; serving the stored workspace: ${String(err)}`)
      }
    }
    this.onPersist?.()
    return result
  }

  private async loadInner(sideline: boolean): Promise<Workspace> {
    // Read-only loads (sideline: false — the relay blob path) must not mutate the disk, so the
    // litter sweep rides the same flag as the corrupt-file sideline.
    if (sideline) await sweepForeignTempFiles(this.indexPath)
    let raw: string
    try {
      raw = await fs.readFile(this.indexPath, 'utf-8')
    } catch (err) {
      this.indexReadState = (err as NodeJS.ErrnoException)?.code === 'ENOENT' ? 'absent' : 'unreadable'
      // No index. Usually a first run — but it is also what a crash BETWEEN the sideline rename
      // below and the next index write leaves behind, and that case owes the user the note. Only
      // this branch pays for the readdir, and only for a load that may touch disk anyway.
      if (sideline) this.noteCorruptIndex(await this.newestSidelined())
      return EMPTY_WORKSPACE
    }
    let parsed: unknown
    try {
      parsed = JSON.parse(raw)
    } catch {
      this.indexReadState = 'unreadable'
      // Same rule as a corrupt project.json: sideline the only copy so the boot flow's
      // unconditional save cannot replace it with an empty index. Read-only callers must not
      // mutate the disk (sideline: false).
      if (sideline) {
        const backup = `${path.basename(this.indexPath)}.corrupt-${Date.now()}`
        try {
          await renameAtomic(this.indexPath, path.join(platform().userDataDir, backup))
          // Only AFTER the rename succeeded: the note promises a backup exists.
          this.noteCorruptIndex(backup)
        } catch { /* best effort — never destroy data */ }
      }
      return EMPTY_WORKSPACE
    }
    const anyParsed = parsed as { version?: number; entries?: unknown }
    // Only a v3 index with an entry list of objects is one: `{"version":3}` alone used to reach loadV3
    // and throw (`index.entries is not iterable`); now it falls through, like any unrecognised shape.
    if (anyParsed?.version === 3 && Array.isArray(anyParsed.entries) && anyParsed.entries.every(isObjectEntry)) {
      try {
        const built = await this.loadV3(parsed as WorkspaceIndexV3, sideline)
        this.indexReadState = 'read'
        return built
      } catch (e) {
        this.indexReadState = 'unreadable'
        throw e
      }
    }
    // v1/v2: assemble in memory now; the first save() performs the actual migration.
    const legacy = migrateLegacy(parsed)
    // PARSED, but no index this build recognises (`{}`, `null`, `[]`, a v2 without its projects list,
    // a v3 without entries, a newer build's version): read as unreadable. A readable EMPTY v2/v3
    // index is not this.
    this.indexReadState = legacy === EMPTY_WORKSPACE ? 'unreadable' : 'read'
    if (legacy.projects.length) this.pendingV2Backup = raw
    return legacy
  }

  /** Newest `workspace.json.corrupt-<ts>` sitting in userData, or null. */
  private async newestSidelined(): Promise<string | null> {
    const prefix = `${path.basename(this.indexPath)}.corrupt-`
    let newest: { name: string; ts: number } | null = null
    try {
      for (const name of await fs.readdir(platform().userDataDir)) {
        if (!name.startsWith(prefix)) continue
        const ts = Number(name.slice(prefix.length))
        if (!Number.isFinite(ts)) continue
        if (!newest || ts > newest.ts) newest = { name, ts }
      }
    } catch { /* userData unreadable — nothing to report */ }
    return newest?.name ?? null
  }

  /** One-time note: the index was lost but backed up, and no project data went with it. */
  private noteCorruptIndex(backup: string | null): void {
    if (!backup || this.corruptNoteSent) return
    this.corruptNoteSent = true
    platform().broadcast(IPC.workspaceCorruptRecovered, backup)
  }

  private async loadV3(index: WorkspaceIndexV3, sideline: boolean): Promise<Workspace> {
    for (const entry of index.entries) {
      entry.localApprovalId ||= randomUUID()
      // Same "workspace.json is hand-editable input too" treatment as the inline-project branch
      // below, for a REF'd project's own closed-session history: validate shape, cap, and
      // re-normalize each snapshot's trigger spec. Sanitized ONCE here so every downstream reader
      // of `e.closedSessions` (fileToProject, readLocalRef, the ssh reconcile paths) can trust it.
      entry.closedSessions = sanitizeLoadedClosedSessions(entry.closedSessions)
      // Same rule for this machine's per-layout cameras: workspace.json is hand-editable input,
      // and a non-finite `zoom` reaching `setViewport` blanks the canvas. Pruning against the live
      // layouts happens later, in `fileToProject`, which is the first point that knows what the
      // project file actually carries.
      entry.layoutViewports = sanitizeLayoutViewports(entry.layoutViewports)
      // Same rule for the "Share with team" handover record: it decides whether this desktop may
      // write an SSH project's file at all, so only a well-formed record is honoured.
      entry.handedOffTo = sanitizeHandedOffTo(entry.handedOffTo)
    }
    this.index = index
    const built: LoadedEntry[] = []
    for (const e of index.entries) {
      // A LOCAL-DATA ref reads its own file first; `e.project` below is its cache and answers only
      // when the file is missing or unreadable (and for a pre-file entry, which has no file yet).
      // A FOLDER-DATA-REF (issue #1145) is a local-data ref with a working directory: the file and
      // its cache are stored without `cwd` (see splitWorkspace), so the folder is put back here.
      const folderData = isFolderDataRef(e)
      const inFolder = (project: Project): Project =>
        folderData ? { ...project, cwd: e.cwd, storeInAppData: true } : project
      const fromDataFile = e.dataFile && !e.ssh
        ? await this.loadDataFileEntry(e, sideline)
        : null
      if (fromDataFile) {
        built.push({ ...fromDataFile, project: inFolder(fromDataFile.project) })
      } else if (e.project) {
        // Inline projects are stored verbatim in the index (no fileToProject pass), so apply the
        // same kanban shape guard here — a v1/hand-edited board would otherwise crash the render —
        // and the same trigger shape rule (workspace.json is hand-editable input too).
        // `rest` drops BOTH guarded fields; each is added back below only if it passes its guard.
        const { kanban, closedSessions, layouts, layoutViewports, bridges, ropes, ...rest } = e.project
        const admittedKanban = sanitizeKanban(kanban)
        const base = admittedKanban ? { ...rest, kanban: admittedKanban } : rest
        // The canvas links, like the board: a non-list or a `null` entry threw on project load.
        const admittedBridges = bridges ? sanitizeLinks(bridges) : undefined
        const admittedRopes = ropes ? sanitizeLinks(ropes) : undefined
        // An inline project's embedded layouts are hand-editable input exactly like a git-shared
        // file's, and they never pass through `fileToProject` on this branch, so they are
        // sanitized (and their cameras pruned against them) here instead.
        const admitted = sanitizeLayouts(layouts)
        const views = pruneLayoutViewports(sanitizeLayoutViewports(layoutViewports), admitted)
        // Same treatment for `closedSessions` as the ref'd-project entries above, and for the
        // same reason: a malformed value here reaches `mergeClosedHistory`, which iterates it (a
        // non-array throws and takes the whole sidebar render down) and hands each entry's node
        // to React Flow.
        const history = sanitizeLoadedClosedSessions(closedSessions)
        built.push({
          entry: e,
          project: inFolder({
            ...base,
            nodes: sanitizeNodeTriggers(base.nodes),
            ...(admittedBridges ? { bridges: admittedBridges } : {}),
            ...(admittedRopes ? { ropes: admittedRopes } : {}),
            ...(history ? { closedSessions: history } : {}),
            ...(admitted ? { layouts: admitted } : {}),
            ...(views ? { layoutViewports: views } : {})
          })
        })
      } else if (folderData) {
        // File AND cache gone. Never fall through to the folder branch below: that reads the
        // folder's own `.nodeterm/project.json` — a stale copy or a teammate's canvas — and the
        // next save would adopt it as this project. The grey placeholder keeps the kind instead.
        built.push({ entry: e, project: { ...unavailableProject(e), storeInAppData: true } })
      } else if (e.cwd) {
        if (sideline) await sweepForeignTempFiles(projectFilePath(e.cwd))
        const read = await this.readProjectFile(e.cwd, sideline)
        if (read) {
          const p = read.file
          this.revs.set(e.id, p.rev)
          this.lastWritten.set(projectFilePath(e.cwd), read.raw)
          built.push({
            entry: e,
            file: p,
            project: fileToProject(p, {
              // The ENTRY's id, always. The file's own `id` is a legacy compatibility field that
              // git copies verbatim into every worktree — reading it is what let one machine's
              // project id name two folders.
              id: e.id,
              cwd: e.cwd,
              closed: e.closed,
              closedAt: e.closedAt,
              handedOffTo: e.handedOffTo,
              viewport: e.viewport,
              defaultAccountId: e.defaultAccountId,
              breadcrumbs: e.breadcrumbs,
              closedSessions: e.closedSessions,
              layoutViewports: e.layoutViewports,
              capabilityAck: e.capabilityAck,
              localExec: this.execOverlay(e, p)
            })
          })
        } else {
          this.deferExecMigration(e)
          built.push({ entry: e, project: unavailableProject(e) })
        }
      } else if (e.ssh) {
        if (e.cache) {
          this.revs.set(e.id, e.cache.rev)
          built.push({
            entry: e,
            project: fileToProject(e.cache, {
              id: e.id,
              ssh: e.ssh,
              closed: e.closed,
              closedAt: e.closedAt,
              handedOffTo: e.handedOffTo,
              viewport: e.viewport,
              defaultAccountId: e.defaultAccountId,
              breadcrumbs: e.breadcrumbs,
              closedSessions: e.closedSessions,
              layoutViewports: e.layoutViewports,
              capabilityAck: e.capabilityAck,
              localExec: this.execOverlay(e, e.cache)
            })
          })
        } else {
          this.deferExecMigration(e)
          built.push({ entry: e, project: unavailableProject(e) })
        }
      } else {
        // Nothing this build recognises as content: a data-ref whose file is gone AND whose cache
        // has already been dropped, or an entry written by a NEWER build carrying a ref kind this
        // one has never heard of. It becomes the same labeled grey placeholder an unreadable
        // folder does, because the one thing an entry may never do is silently vanish — the save
        // that follows a silent drop writes it out of the index, and whatever it named is then
        // unreachable for good.
        built.push({ entry: e, project: unavailableProject(e) })
      }
    }
    await this.repairDuplicateIds(built, sideline)
    // AFTER the repair: it re-keys entries in place, and the maps are keyed by project id.
    this.adoptSettingsFromIndex(index)
    const projects = built.map((b) => b.project)
    const active = projects.some((p) => p.id === index.activeProjectId && !p.unavailable)
      ? index.activeProjectId
      : (projects.find((p) => !p.closed && !p.unavailable)?.id ?? '')
    return { version: 2, activeProjectId: active, projects }
  }

  /**
   * The backstop: after every entry is loaded, no two projects may still share an id.
   *
   * The shared file no longer carries an id to copy, so nothing can corrupt a store this way any
   * more — but the stores corrupted BEFORE that are still on disk, and they cannot heal
   * themselves: once two entries were saved under one id (both folders' files carried it at the
   * last save), nothing downstream notices. `splitWorkspace` dedupes by CWD, so both entries
   * survive every save; `commitCanvas` maps by id, so the active canvas is written into BOTH
   * projects and the next save flushes it into the other folder's project.json. That is silent
   * cross-folder data loss on every autosave, so the repair cannot wait for the user to notice —
   * and it must be persisted, or every restart re-inherits the same corrupt index.
   *
   * It repairs the INDEX only. Re-keying the loser's project.json (what this did while the file
   * was the id's home) is now both pointless and wrong: the id in there is a legacy compatibility
   * field nothing reads, and writing to a git-shared file to fix a machine-local mistake is the
   * habit this whole change is removing.
   *
   * First holder keeps the id; the rest are re-keyed by `derivedProjectId`, which is DETERMINISTIC
   * in (id, folder) — a random id would give the two folders new names on every boot, whereas this
   * converges: the second load finds no collision at all.
   *
   * Loud on purpose (one line per repaired project, naming the folder): the user's tabs quietly
   * change identity, and a silent repair of someone's data is worse than a noisy one.
   */
  private async repairDuplicateIds(built: LoadedEntry[], sideline: boolean): Promise<void> {
    const seen = new Set<string>()
    let repaired = false
    for (const b of built) {
      if (!seen.has(b.project.id)) {
        seen.add(b.project.id)
        continue
      }
      const old = b.project.id
      const seed = collisionSeed({
        cwd: b.entry.cwd,
        ssh: b.entry.ssh,
        name: b.project.name
      })
      const next = derivedProjectId(old, seed, (id) => seen.has(id) || built.some((o) => o.project.id === id))
      seen.add(next)
      repaired = true
      console.warn(
        `[workspace] two projects claimed the project id "${old}" — a git-shared ` +
          `.nodeterm/project.json copied into a second folder (worktree/checkout). Re-keyed ` +
          `${b.entry.cwd ?? b.entry.ssh?.remoteCwd ?? `inline canvas "${b.project.name}"`} to "${next}".`
      )
      b.entry.id = next
      b.project = { ...b.project, id: next }
      if (b.entry.project) b.entry.project = { ...b.entry.project, id: next }
      if (b.entry.cache) {
        b.entry.cache = { ...b.entry.cache, id: next }
        this.revs.set(next, b.entry.cache.rev)
      }
      // The rev is tracked per project id, so it has to follow the re-key. The file itself is not
      // touched: it holds this project's CONTENT, and the content did not change.
      if (b.file) this.revs.set(next, b.file.rev)
    }
    // The re-keyed ENTRIES are the half that makes the repair survive a restart — without this the
    // next boot reads the old index and repairs again (harmlessly, but forever).
    if (!repaired || !sideline) return
    try {
      this.lastIndexWrite = null
      await writeAtomic(this.indexPath, JSON.stringify(this.index))
    } catch { /* the next save writes it anyway */ }
  }

  /**
   * The machine-local exec overlay for one ref'd entry — plus the ONE-TIME migration (see
   * `IndexEntryV3.execMigrated` / `hoistLegacyNodeExec`).
   *
   * `ssh.extraArgs` had a producer before the trust boundary existed, so an existing user's jump
   * host / corporate `ProxyCommand` is sitting in the CURRENT project file with no `localExec` to
   * match. Dropping it would break the connection and then, on the next save, erase it from disk and
   * propagate the deletion to every teammate. So for an entry that has not been migrated yet — i.e.
   * one that was ALREADY REFERENCED in this machine's workspace.json at upgrade time, which is the
   * provenance signal available — the file's own values are hoisted into the overlay once.
   * `localExec` (if any) still wins per node.
   */
  private execOverlay(e: IndexEntryV3, f: ProjectFileV1): LocalNodeExecMap | undefined {
    // This entry is readable THIS load, so any earlier deferral (its file was offline when we first
    // loaded) is now resolved. Clear it so the next save() may record execMigrated=true — otherwise
    // the entry stays unmarked forever and the hoist re-runs on every full load, which would also
    // let a project.json swapped in AFTER the deferral get its exec fields hoisted as trusted.
    this.execUnmigrated.delete(e.id)
    const overlay = localExecOverlay(e, f)
    // A hoist happened exactly when the overlay is not the entry's own map (see `localExecOverlay`).
    if (overlay !== e.localExec) this.pendingExecNote = true
    return overlay
  }

  /** The file was unreadable, so the hoist could not run: leave the entry unmarked and retry it on
   *  a later load. Anything dropped must be visible or recoverable — never silently gone. */
  private deferExecMigration(e: IndexEntryV3): void {
    if (!e.execMigrated) this.execUnmigrated.add(e.id)
  }

  /**
   * Loads the settings halves out of a just-read index into the two runtime maps.
   *
   * workspace.json is hand-editable (and, on Server Edition, sits next to other users' reach), so
   * neither field is trusted on the way in: the overlay goes through the same sanitizer a settings
   * file gets, and a cached SHARED file is accepted only if it still parses as one — the parser is
   * reused as the validator so there is exactly one definition of "a valid settings file",
   * wherever the bytes came from.
   */
  private adoptSettingsFromIndex(index: WorkspaceIndexV3): void {
    this.localSettingsByProject.clear()
    this.settingsCacheByProject.clear()
    for (const e of index.entries) {
      const local = sanitizeProjectLocalSettings(e.localSettings)
      if (local && Object.keys(local).length) this.localSettingsByProject.set(e.id, local)
      if (!e.ssh || !e.settingsCache) continue
      const parsed = parseProjectSettingsFile(JSON.stringify(e.settingsCache))
      if (parsed.status === 'ok') this.settingsCacheByProject.set(e.id, parsed.file)
    }
  }

  /** Writes the maps back onto an index about to be persisted — the machine-local half that
   *  `splitWorkspace` cannot know about. Runs on every index write, so an entry the maps no longer
   *  cover loses the field rather than keeping a stale copy of it. */
  private applySettingsToIndex(index: WorkspaceIndexV3): void {
    for (const e of index.entries) {
      const local = this.localSettingsByProject.get(e.id)
      if (local) e.localSettings = local
      else delete e.localSettings
      // Only an ssh entry has anywhere to cache: a local ref's shared file is one disk read away,
      // and an inline canvas has no shared file at all.
      const cached = e.ssh ? this.settingsCacheByProject.get(e.id) : undefined
      if (cached) e.settingsCache = cached
      else delete e.settingsCache
    }
  }

  /**
   * The shared + local settings of one project. `null` means the id names no entry (never "no
   * settings" — an entry with neither file nor overlay answers `{shared: null, local: undefined}`).
   *
   * The shared doc is read from disk on every call rather than cached: `.nodeterm/settings.json` is
   * a git-tracked file a checkout/merge/teammate rewrites behind our back, and a settings read is
   * rare enough (a panel opening, a launch) that a stale answer would cost more than the read does.
   */
  async readProjectSettings(projectId: string): Promise<ProjectSettingsState | null> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e) return null
    const local = this.localSettingsByProject.get(projectId)
    if (e.ssh) return this.readSshSettings(projectId, e.ssh, local)
    // An inline canvas has no folder, so there is no shared document to have. A folder project
    // kept in app data has one, in its app-data root rather than the folder (issue #1145) — read
    // exactly like the folder's, so its values still resolve as 'shared' and keep every consent.
    const root = settingsRootFor(e)
    if (!root) return { shared: null, local }
    const read = await readProjectSettingsFile(root)
    if (read.status === 'ok') {
      // The rev source for the next write — a write that skipped the read would restart at rev 1
      // and lose the counter a remote/offline comparison depends on.
      this.lastSharedSettings.set(projectId, read.file)
      return { shared: read.file, local }
    }
    // conflict: the file exists but is mid-merge; it is left untouched for the user to resolve and
    // reported as such, so a caller shows "resolve this" instead of "this project has no settings".
    if (read.status === 'conflict') return { shared: null, local, conflict: true }
    return { shared: null, local } // absent / invalid (sidelined) / unreadable
  }

  /**
   * The ssh half of `readProjectSettings`: reconcile the host's settings.json against the offline
   * cache, then answer with whichever is authoritative. Same rules the project.json mirror lives by:
   *
   *  - no settings IO / read `error` → serve the cache. A failed read is never evidence of absence,
   *    so nothing is pushed and nothing is dropped; the project stays usable offline.
   *  - `absent` → the host has no file; heal it from the cache (the mirror direction) and serve the
   *    cache. Without a cache there is simply no shared document yet.
   *  - `ok` → the bytes are HOSTILE INPUT (a git-shared file on a machine we do not control) and go
   *    through `parseProjectSettingsFile` alone. The higher rev wins, ties to the host, so a
   *    teammate's push is adopted rather than fought over, while a STRICTLY newer cache (this
   *    machine edited while disconnected) is pushed back instead of being silently overwritten.
   *  - `conflict`/`invalid` → the remote copy cannot be trusted and must not be clobbered; the cache
   *    is served as the last known good, with `conflict` flagged so a caller can say "resolve this"
   *    (and, for a conflict, remembered so a WRITE refuses too — see `settingsConflictByProject`).
   *
   * The cache is read AFTER the round trip, never before: a cache-first write can land while this
   * read is in flight, and comparing the host's answer against a snapshot taken before the await
   * would adopt an older remote doc over an edit the user has already been told was saved.
   */
  private async readSshSettings(
    projectId: string,
    ssh: NonNullable<Project['ssh']>,
    local: ProjectLocalSettings | undefined
  ): Promise<ProjectSettingsState> {
    const res = await this.remoteIO?.readSettings?.(projectId, ssh)
    const cached = this.settingsCacheByProject.get(projectId) ?? null
    if (!res || res.status === 'error') return { shared: cached, local }
    if (res.status === 'absent') {
      // The host has no file to be mid-merge: whatever conflict a previous read saw is gone.
      this.settingsConflictByProject.delete(projectId)
      if (cached) await this.pushSshSettings(projectId, ssh, cached)
      return { shared: cached, local }
    }
    const parsed = parseProjectSettingsFile(res.content)
    if (parsed.status === 'conflict') {
      this.settingsConflictByProject.add(projectId)
      return { shared: cached, local, conflict: true }
    }
    // `invalid` deliberately leaves the flag alone: unparsable is not "resolved", and refusing to
    // write is the conservative side of a file we still cannot read.
    if (parsed.status === 'invalid') return { shared: cached, local }
    this.settingsConflictByProject.delete(projectId) // the host's file parses again — resolved
    const file = parsed.file
    if (cached && file.rev < cached.rev) {
      // Offline edits outrank the host's older copy — push them rather than letting the next read
      // adopt a document the user already replaced here.
      await this.pushSshSettings(projectId, ssh, cached)
      return { shared: cached, local }
    }
    this.lastSharedSettings.set(projectId, file)
    // Only persist when the cache actually moved: a read is the common case, and rewriting
    // workspace.json on every panel open would be a disk write per glance.
    if (!cached || cached.rev !== file.rev || !sameProjectSettingsContent(cached, file)) {
      this.settingsCacheByProject.set(projectId, file)
      await this.persistIndexNow().catch(() => {})
    }
    return { shared: file, local }
  }

  /** Best-effort mirror of one settings document to the host. A failure is not an error anywhere:
   *  the cache is the durable copy and the next read reconciles (heal / push again). */
  private async pushSshSettings(
    projectId: string,
    ssh: NonNullable<Project['ssh']>,
    file: ProjectSettingsFileV1
  ): Promise<boolean> {
    // Handed to a hosted team: the server core owns the host's `.nodeterm/` now. The cache keeps
    // this machine's copy; nothing is pushed over the server's.
    if (this.index?.entries.find((x) => x.id === projectId)?.handedOffTo) return false
    const io = this.remoteIO
    if (!io?.writeSettings) return false
    try {
      return await io.writeSettings(projectId, ssh, serializeProjectSettingsFile(file))
    } catch {
      return false
    }
  }

  /**
   * The ssh half of `writeProjectSettings`, CACHE-FIRST: the rev-bumped document lands in the
   * offline cache and workspace.json BEFORE it is offered to the host, so a connection that dies
   * mid-save loses a round trip, never the user's edit. The remote write is then best-effort —
   * `true` here means "this edit is safely recorded", and an unreachable host is reconciled by the
   * next read (which heals an absent file and pushes a cache that outranks the remote).
   *
   * The doc is sanitized on the way in because this cache is served straight from memory and
   * persisted into workspace.json; running it through the same sanitizer a read applies keeps one
   * definition of "a valid settings file" whichever side the bytes came from.
   *
   * REFUSES a git-conflict-marked host file, exactly like the local leg refuses a conflicted
   * settings.json: a conflicted file is the user's to resolve, and pushing over it would silently
   * pick a side of a merge nobody has looked at. Two mechanisms enforce that, because the ssh leg
   * cannot afford the local leg's read-before-every-write (a round trip per save):
   *  - WARM (this run has a cache or a last-read doc): the runtime flag a read left behind, which
   *    clears itself the moment a read finds the file parsing again — or gone.
   *  - COLD (neither map knows this project, so no read has ever compared): one read here, or the
   *    refusal would be a promise nothing checks — the first save of a session would blind-write
   *    the mirror over a merge. `absent` writes rev 1 as before; a read `error` proceeds
   *    cache-first, since being unable to reach the host is exactly what the cache exists for.
   */
  private async writeSshSettings(
    projectId: string,
    ssh: NonNullable<Project['ssh']>,
    doc: ProjectSettingsDoc
  ): Promise<boolean> {
    if (this.settingsConflictByProject.has(projectId)) return false
    let prev = this.settingsCacheByProject.get(projectId) ?? this.lastSharedSettings.get(projectId) ?? null
    if (!prev && this.remoteIO?.readSettings) {
      // A throwing IO is an unreachable host, not a verdict on the file — same fail-open shape as
      // `pushSshSettings`, and the cache-first write below is what makes that survivable.
      let cold: RemoteReadResult = { status: 'error' }
      try {
        cold = await this.remoteIO.readSettings(projectId, ssh)
      } catch { /* offline: fall through to the cache-first write */ }
      if (cold.status === 'ok') {
        const parsed = parseProjectSettingsFile(cold.content)
        if (parsed.status === 'conflict') {
          this.settingsConflictByProject.add(projectId)
          return false
        }
        // `invalid` is left as prev=null: the host's bytes are unusable as a rev source, and the
        // cache-first write is what gives the user a readable file again.
        if (parsed.status === 'ok') {
          prev = parsed.file
          this.lastSharedSettings.set(projectId, parsed.file)
          this.settingsConflictByProject.delete(projectId)
        }
      }
    }
    // Canonical shape (bookkeeping first, then the sanitized doc) — the same order
    // `parseProjectSettingsFile` produces, so a cache built here compares equal to the identical
    // document read back from the host instead of looking like a change. Sanitizing on the way in
    // keeps one definition of "a valid settings file" whichever side the bytes came from, and drops
    // the stale version/rev/savedAt of a document a caller hands straight back.
    const next: ProjectSettingsFileV1 = {
      version: 1,
      rev: (prev?.rev ?? 0) + 1,
      savedAt: new Date().toISOString(),
      ...sanitizeProjectSettingsDoc(doc)
    }
    this.settingsCacheByProject.set(projectId, next)
    this.lastSharedSettings.set(projectId, next)
    try {
      await this.persistIndexNow()
    } catch {
      return false // the edit is live in this session, but it did not durably land
    }
    await this.pushSshSettings(projectId, ssh, next)
    return true
  }

  /**
   * Whole-document write of the GIT-SHARED settings file. Whole-document on purpose: a per-field
   * patch grammar would have to merge against a file that another writer (a teammate's commit, the
   * user's editor) may have changed since the caller read it, and silently merging into a file the
   * caller never saw is how the shared half stops meaning what the repo says.
   *
   * ALWAYS READS FIRST — not just when this run has never read the file. A remembered rev is not
   * evidence of the file's current STATE: `.nodeterm/settings.json` is git-tracked, so between the
   * panel's read and the user's save a pull/merge can leave conflict markers, and a write off the
   * warm rev would overwrite them (the same file `readProjectSettings` deliberately refuses to
   * parse). Without any read a fresh process is worse still — rev restarts at 1 over a file that was
   * at rev N. Settings are cold (a panel save, not a keystroke), so one read per write is the ruled
   * cost of never writing a file this store has not just looked at.
   *
   * An ssh project takes the cache-first remote leg instead (`writeSshSettings`).
   *
   * False = there is nowhere to write it, or writing would destroy something. On BOTH legs: an
   * unknown id, an inline canvas (no folder), and a git-conflicted shared file — the user's to
   * resolve, left untouched (the local leg sees it in the read-before-write; the ssh leg sees it
   * WARM from a cache or last-read doc this run already has, or — COLD, when neither map knows this
   * project yet — from the one read `writeSshSettings` does itself before its first write, per its
   * own docstring above). Local leg only: an unreadable file (a failed read is never evidence of
   * absence, so it may not be clobbered either) or a failed write. SSH leg only: an index write that
   * did not persist — a failed REMOTE write is not false there, because the cache already holds
   * the edit.
   */
  async writeProjectSettings(projectId: string, doc: ProjectSettingsDoc): Promise<boolean> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e) return false
    if (e.ssh) return this.writeSshSettings(projectId, e.ssh, doc)
    const root = settingsRootFor(e)
    if (!root) return false
    const read = await readProjectSettingsFile(root)
    // absent → nothing to lose, start at rev 1. invalid → the read already sidelined the only
    // copy to `.corrupt-<ts>`, so this write destroys nothing either.
    if (read.status === 'conflict' || read.status === 'error') return false
    let prev: ProjectSettingsFileV1 | null = null
    if (read.status === 'ok') {
      prev = read.file
      this.lastSharedSettings.set(projectId, read.file)
    }
    try {
      const written = await writeProjectSettingsFile(
        root, doc, prev, new Date().toISOString()
      )
      this.lastSharedSettings.set(projectId, written)
      return true
    } catch {
      // Folder gone / read-only checkout: the caller is told the doc did not land, exactly like a
      // failed project.json write leaves the entry stale rather than pretending it saved.
      return false
    }
  }

  /**
   * Replaces this machine's overlay for one project (undefined = clear it) and persists the index
   * NOW, without waiting for a canvas save: a settings edit is often the only thing the user did in
   * that session, and an overlay that lives only in memory until the next node is dragged is an
   * overlay that quietly disappears when the app quits.
   */
  async updateLocalProjectSettings(
    projectId: string,
    local: ProjectLocalSettings | undefined
  ): Promise<boolean> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e) return false
    const clean = local === undefined ? undefined : sanitizeProjectLocalSettings(local)
    if (clean && Object.keys(clean).length) this.localSettingsByProject.set(projectId, clean)
    else this.localSettingsByProject.delete(projectId)
    await this.persistIndexNow()
    return true
  }

  /** Rewrites the CURRENT index with the settings maps applied. On `saveChain` like every other
   *  index write, so it can neither interleave with a save's own rewrite nor invent entries: it
   *  persists exactly what `this.index` already holds (and does nothing before the first load). */
  private persistIndexNow(): Promise<void> {
    const run = this.saveChain.then(() => this.writeIndexNow())
    this.saveChain = run.catch(() => {})
    return run
  }

  /** The index write itself, WITHOUT queueing — for callers that are already running on
   *  `saveChain` (queueing from inside a chain step would wait on the step itself). */
  private async writeIndexNow(): Promise<void> {
    const index = this.index
    if (!index) return
    this.applySettingsToIndex(index)
    this.lastIndexWrite = null
    await writeAtomic(this.indexPath, JSON.stringify(index))
  }

  /**
   * Reads + parses one project file. Only the authoritative loadV3 path passes `sideline: true`,
   * which renames an unparsable/wrong-shape file to `.corrupt-<ts>` so a later save can't overwrite
   * the only copy. Read-only callers (probeFolder — an RPC reachable with arbitrary paths on Server
   * Edition — and the watcher's readLocalRef*) pass false: a probe must never mutate the disk, and a
   * git-conflict-marked project.json mid-merge must be left in place so the user can hand-resolve it.
   */
  private async readProjectFile(cwd: string, sideline: boolean): Promise<ProjectFileRead | null> {
    const file = projectFilePath(cwd)
    let raw: string
    try {
      raw = await fs.readFile(file, 'utf-8')
    } catch {
      return null
    }
    try {
      const parsed = JSON.parse(raw) as ProjectFileV1
      // `raw` travels with the parse so callers can record the BYTES on disk in `lastWritten`.
      // A missing `id` is NOT a wrong shape: the file stopped carrying identity, and the version
      // that still demanded one sidelines every modern file it meets (which is precisely why we
      // keep writing the legacy field for a release — see `legacyFileId`).
      if (parsed?.version === 1 && Array.isArray(parsed.nodes)) return { file: parsed, raw }
      // parses but isn't a ProjectFileV1 — sideline it too, so a later save can't overwrite the only copy.
    } catch { /* not JSON — sideline below */ }
    if (sideline) {
      try {
        await renameAtomic(file, `${file}.corrupt-${Date.now()}`)
      } catch { /* best effort — never destroy data */ }
    }
    return null
  }

  /**
   * The LOCAL-DATA ref's load leg: read `userData/inline-projects/<id>.json` and build the project
   * from it, or answer null so the caller falls back to the index's `project` cache.
   *
   * Identical in shape to the folder-ref leg above — the file carries content, the ENTRY carries
   * this machine's camera / default account / breadcrumbs / trash can / consent / exec overlay —
   * which is the whole point of giving the cwd-less canvas a file: one ref shape everywhere, and a
   * file already in the form that "Set folder…" will move into `<cwd>/.nodeterm/project.json`.
   *
   * The in-memory entry's `project` cache is refreshed from what the file said, because a dozen
   * sync readers (`getNode`, `persistedCanvases`, `capabilityProjectFor`, …) answer out of the
   * loaded index and must not keep serving a copy the file has already superseded.
   */
  private async loadDataFileEntry(e: IndexEntryV3, sideline: boolean): Promise<LoadedEntry | null> {
    if (!isInlineProjectFileId(e.id)) return null
    const file = inlineFilePath(e.id)
    if (sideline) await sweepForeignTempFiles(file)
    const read = await this.readDataFile(e.id, sideline)
    if (!read) return null
    this.revs.set(e.id, read.file.rev)
    this.lastWritten.set(file, read.raw)
    const project = fileToProject(read.file, {
      id: e.id,
      closed: e.closed,
      closedAt: e.closedAt,
      handedOffTo: e.handedOffTo,
      viewport: e.viewport,
      defaultAccountId: e.defaultAccountId,
      breadcrumbs: e.breadcrumbs,
      closedSessions: e.closedSessions,
      layoutViewports: e.layoutViewports,
      capabilityAck: e.capabilityAck,
      localExec: this.execOverlay(e, read.file)
    })
    e.project = project
    return { entry: e, project, file: read.file }
  }

  /** Reads + parses one inline data file. Same rules as `readProjectFile`: a file that is not a
   *  ProjectFileV1 is sidelined to `.corrupt-<ts>` on the authoritative load path so a later save
   *  cannot overwrite the only copy — here the index's `project` cache is the other copy, which is
   *  what makes sidelining cost the user nothing. */
  private async readDataFile(projectId: string, sideline: boolean): Promise<ProjectFileRead | null> {
    const file = inlineFilePath(projectId)
    let raw: string
    try {
      raw = await fs.readFile(file, 'utf-8')
    } catch {
      return null
    }
    try {
      const parsed = JSON.parse(raw) as ProjectFileV1
      if (parsed?.version === 1 && Array.isArray(parsed.nodes)) return { file: parsed, raw }
    } catch { /* not JSON — sideline below */ }
    if (sideline) {
      try {
        await renameAtomic(file, `${file}.corrupt-${Date.now()}`)
      } catch { /* best effort — never destroy data */ }
    }
    return null
  }

  /** True when writing an empty canvas to `file` destroys nothing: the file is absent (fresh
   *  folder) or already an empty-nodes project file. Populated AND unparsable both answer false —
   *  a corrupt file is left for readProjectFile's sideline instead of being overwritten. */
  private async emptyOrAbsentOnDisk(file: string): Promise<boolean> {
    let raw: string
    try {
      raw = await fs.readFile(file, 'utf-8')
    } catch {
      return true
    }
    try {
      const parsed = JSON.parse(raw) as ProjectFileV1
      return parsed?.version === 1 && Array.isArray(parsed.nodes) && parsed.nodes.length === 0
    } catch {
      return false
    }
  }

  /** In-flight save chain: saves run FIFO (same idiom as SpeechService.queue). Overlapping saves
   *  used to interleave their file writes and land their indexes out of call order — the "both
   *  projects went blank after tab switching" wipe. */
  private saveChain: Promise<unknown> = Promise.resolve()

  /**
   * Resolves once every write queued on `saveChain` so far (saves, content writes, reconciles) has
   * finished, landed or failed; never rejects. The Server Edition's close awaits it BEFORE it stops
   * the content authority: a browser save still queued behind a slow write would otherwise run after
   * the authority was detached and write its stale content un-overlaid over the final flush.
   */
  idle(): Promise<void> {
    return this.saveChain.then(() => undefined)
  }

  /**
   * `localOnly` makes the save durable on THIS machine only: every local file and the index (which
   * carries each SSH project's cache) are written, but no SSH project is read, reconciled or
   * mirrored — a changed, already-reconciled entry is marked `unmirrored` instead, so the next
   * ordinary save pushes it. It exists for the launch write-ahead barrier (`commitLaunchAttempt`):
   * that save must be on disk before a command is typed, and waiting on two SSH round trips per
   * save made every new agent node on an SSH project sit on QUEUED for seconds. It still runs on
   * the FIFO chain, so ordering against every other save is unchanged.
   */
  save(workspace: Workspace, opts: WorkspaceSaveOptions = {}): Promise<void> {
    const run = this.saveChain.then(() => this.saveNow(workspace, opts.localOnly === true))
    this.saveChain = run.catch(() => {})
    return run
  }

  /**
   * A RENDERER's whole-workspace save (the `workspace:save` IPC). Exactly `save()`, plus the
   * pending-adoption rule (see `pendingAdoptions`). The merge runs inside the chain step, never
   * before the enqueue: an await ahead of it would let a later save overtake this one.
   */
  private saveFromRenderer(workspace: Workspace, localOnly: boolean): Promise<void> {
    const run = this.saveChain.then(async () =>
      this.saveNow(this.pendingAdoptions.size ? await this.withPendingAdoptions(workspace) : workspace, localOnly))
    this.saveChain = run.catch(() => {})
    return run
  }

  /** `workspace` plus the store's own copy of every pending adoption it does not carry. Runs on
   *  `saveChain`. An entry whose file cannot be read right now is left out, as before this rule. */
  private async withPendingAdoptions(workspace: Workspace): Promise<Workspace> {
    const carried = new Set(workspace.projects.map((p) => p.id))
    const missing: Project[] = []
    for (const id of this.pendingAdoptions) {
      if (carried.has(id)) continue
      const own = await this.readLocalRef(id)
      if (own) missing.push(own)
    }
    return missing.length ? { ...workspace, projects: [...workspace.projects, ...missing] } : workspace
  }

  /** The parse of `lastWritten.get(file)`, cached per raw string (see `lastWrittenParsed`). Throws
   *  exactly where the inline `JSON.parse` it replaces did. */
  private parsedLastWritten(file: string): ProjectFileV1 | null {
    const raw = this.lastWritten.get(file)
    if (!raw) return null
    const hit = this.lastWrittenParsed.get(file)
    if (hit && hit.raw === raw) return hit.parsed
    const parsed = JSON.parse(raw) as ProjectFileV1
    this.lastWrittenParsed.set(file, { raw, parsed })
    return parsed
  }

  /**
   * The current content of a project as this store knows it, WITHOUT queueing on `saveChain`: the
   * content authority calls it from inside `saveNow` (its save overlay), and a queued read would
   * wait on the very save that is waiting on it. null = unknown project, SSH project (its file is
   * on another machine), or a file this store cannot read.
   *
   * A folder project answers from the store's own last write or read of its file (`lastWritten`),
   * else from one read off disk, converted the way a load converts it: portable cwds resolved
   * against the folder and this machine's exec values re-applied. The read is NOT recorded:
   * recording it would make the watcher take an outside edit it has not processed yet for one of
   * our own writes. A cwd-less canvas answers from its index cache, which every save and every
   * `writeProjectContent` keeps in step with its data file.
   */
  async readProjectContent(projectId: string): Promise<CanvasContent | null> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e || e.ssh) return null
    if (folderFileCwd(e) && e.cwd) {
      const file = await this.knownProjectFile(e.cwd)
      if (!file) return null
      return contentOf(fileToProject(file, { id: e.id, cwd: e.cwd, localExec: localExecOverlay(e, file) }))
    }
    return e.project ? inlineContent(e.project) : null
  }

  /** A folder project's file as this store last wrote or read it, else as it is on disk now. */
  private async knownProjectFile(cwd: string): Promise<ProjectFileV1 | null> {
    try {
      const known = this.parsedLastWritten(projectFilePath(cwd))
      if (known && Array.isArray(known.nodes)) return known
    } catch { /* our own record, but never trusted blindly — fall back to the disk */ }
    return (await this.readProjectFile(cwd, false))?.file ?? null
  }

  /**
   * Replace a project's content fields (nodes, bridges, ropes, the board's items) atomically — the
   * content authority's flush. Queued on `saveChain` like every other read-modify-write of a
   * project file, so it can never interleave with a save.
   *
   * The file it writes is byte-identical to the one `save()` writes for the same project, apart
   * from `rev` and `savedAt`: it goes through the same `projectToFile` (portable node cwds, exec
   * fields stripped, triggers / links / board sanitized, the derived `viewport` and legacy `id`),
   * and the project it hands that function is the file's own, read the way a load reads it, with
   * only its content fields replaced. So the file keeps everything else it carried — name, colour,
   * icon, capabilities, layouts — and its board keeps its own `github` and `pullLinks`.
   *
   * It does what a save does to the store's bookkeeping — `lastWritten` (so the watcher reads it
   * as a self-write, never an outside edit), `revs`, a cwd-less canvas's `e.project` cache and the
   * index write that carries it, and `onPersist` — and deliberately broadcasts nothing: every
   * client already has the change from the reflector.
   *
   * Resolves false when nothing could be written: an unknown or SSH project, an unreadable file
   * (never written over — a file mid-merge is left for the user), an I/O error, a cwd-less file
   * whose disk rev is ahead of ours (another instance wrote it), or an empty canvas over a
   * populated file this store has never read. The last two are the save path's own rules.
   *
   * An outside edit the watcher has NOT processed yet (inside its debounce) is not merged: the file
   * is read from disk, so the edit's other fields survive, but its CONTENT is replaced by the
   * authority's, which has not seen the edit; and `lastWritten` then records the bytes written, so
   * the watcher's pending event reads the file as a self-write and the edit is never adopted. A
   * save does exactly the same (it writes the whole project and records it). The rev never goes
   * below the one on disk.
   */
  writeProjectContent(projectId: string, content: CanvasContent): Promise<boolean> {
    const run = this.saveChain.then(() => this.writeProjectContentNow(projectId, content))
    this.saveChain = run.catch(() => {})
    return run
  }

  private async writeProjectContentNow(projectId: string, content: CanvasContent): Promise<boolean> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e || e.ssh) return false
    const savedAt = new Date().toISOString()
    if (folderFileCwd(e) && e.cwd) return this.writeFolderContent(e, e.cwd, content, savedAt)
    if (e.project) return this.writeInlineContent(e, e.project, content, savedAt)
    return false
  }

  /** The folder leg: `<cwd>/.nodeterm/project.json`, under the save's folder-leg rules. */
  private async writeFolderContent(
    e: IndexEntryV3,
    cwd: string,
    content: CanvasContent,
    savedAt: string
  ): Promise<boolean> {
    const file = projectFilePath(cwd)
    const read = await this.readProjectFile(cwd, false)
    if (!read) return false
    const candidate = projectToFile(withContent(fileToProject(read.file, { id: e.id, cwd }), content), 0, savedAt)
    // Unchanged: nothing to write, and no rev to burn.
    if (sameProjectContent(read.file, candidate)) return true
    let known: ProjectFileV1 | null = null
    try {
      known = this.parsedLastWritten(file)
    } catch { /* treated as never read */ }
    // The save's rule: an empty canvas never overwrites a populated file this store has not read.
    if (!known && candidate.nodes.length === 0 && read.file.nodes.length > 0) return false
    const rev = Math.max(this.revs.get(e.id) ?? 0, fileRev(read.file)) + 1
    const out = serializeProjectFile({ ...candidate, rev })
    try {
      await writeAtomic(file, out)
    } catch {
      return false
    }
    this.lastWritten.set(file, out)
    this.revs.set(e.id, rev)
    this.onPersist?.()
    return true
  }

  /** The cwd-less leg: the data file under `writeDataFile`'s rules, then the index cache. A pre-file
   *  canvas (no `dataFile`, or an id we will not turn into a path) is stored IN the index, so for
   *  it the index write is the write.
   *
   *  The index `project` also holds this machine's exec values (`shell`, `ssh.extraArgs`): for a
   *  pre-file canvas it is their ONLY store, and for a data-ref it is the cache a missing data file
   *  falls back to. The content carries none (the authority strips them), so each node keeps the
   *  cached node's values, and whatever the content carried is dropped first: the index is the
   *  trusted store, and nothing but this machine's own save may put an exec value there
   *  (@shared/node-exec). The data file is unaffected either way, since `projectToFile` strips. */
  private async writeInlineContent(
    e: IndexEntryV3,
    cached: Project,
    content: CanvasContent,
    savedAt: string
  ): Promise<boolean> {
    const cachedById = new Map((Array.isArray(cached.nodes) ? cached.nodes : []).map((n) => [n.id, n]))
    const nodes = stripSharedNodeExec(content.nodes).map((n) => carryLocalNodeExec(cachedById.get(n.id), n))
    const updated = withContent(cached, { ...content, nodes })
    const viaFile = e.dataFile === true && isInlineProjectFileId(e.id)
    if (viaFile) {
      const landed = await this.writeDataFile(e.id, projectToFile(updated, 0, savedAt))
      if (landed !== 'written' && landed !== 'unchanged') return false
    }
    e.project = updated
    try {
      await this.writeIndexNow()
    } catch {
      // A data-ref's file already holds the content and wins at load, so a stale cache costs
      // nothing lasting; a pre-file canvas has nowhere else to be.
      if (!viaFile) {
        e.project = cached
        return false
      }
    }
    this.onPersist?.()
    return true
  }

  private async saveNow(workspace: Workspace, localOnly = false): Promise<void> {
    if (!workspace.projects.length && !this.index) {
      // A store that never read the index may not replace a populated one with "no projects":
      // that is the boot-save wipe — load() failed transiently, the renderer hydrated zero
      // projects, and its unconditional boot save would atomically erase every ref. A fresh
      // install has no readable index and falls through.
      try {
        const disk = JSON.parse(await fs.readFile(this.indexPath, 'utf-8')) as
          { entries?: unknown[]; projects?: unknown[] }
        if ((disk.entries?.length ?? 0) > 0 || (disk.projects?.length ?? 0) > 0) return
      } catch { /* absent or unparsable (loadInner sidelines corruption) — an empty write is fresh */ }
    }
    // A governed project's content comes from the content authority, never from this (possibly
    // stale) copy of it. Applied BEFORE the split, so every leg below — the project file, the data
    // file, the index cache — writes the overlaid content. The authority reads the current content
    // through `readProjectContent`, which does not queue on `saveChain`: this code runs ON it.
    // FAILS CLOSED: a rejecting overlay rejects the save before any leg below has written a byte
    // (the project file, the data file and the index are all written after this line). Never catch
    // it and write the workspace as handed: that is the stale copy the overlay exists to overrule.
    if (this.contentAuthority) workspace = await this.contentAuthority.overlaySave(workspace)
    const savedAt = new Date().toISOString()
    const previousIndex = this.index
    const { index, files, dataFiles } = splitWorkspace(workspace, (id) => this.revs.get(id) ?? 0, savedAt)

    for (const entry of index.entries) {
      const previous = this.index?.entries.find((candidate) => candidate.id === entry.id)
      entry.localApprovalId = previous?.localApprovalId || randomUUID()
    }

    // The settings overlay / ssh settings cache ride every index write, like `localExec` and
    // `cache`: `splitWorkspace` builds entries from the renderer's Workspace, which carries no
    // machine-local state, so without this each autosave would erase them from disk.
    this.applySettingsToIndex(index)

    // An unavailable placeholder carries no real data. splitWorkspace already dropped its file
    // and cache; here we restore the machine-local payload (ssh offline cache) from the previous
    // index so the index rewrite doesn't drop a good cache we still can't reach.
    // The one-time exec migration is now recorded, so it never runs again for these entries — which
    // is what keeps a project.json cloned AFTER the upgrade (the hostile case) out of the hoist. An
    // entry whose file we could not read at load stays unmarked, so it is retried.
    for (const e of index.entries) {
      // A pre-file inline canvas keeps its exec values inside its own `project` copy, so it has no
      // overlay to migrate. A LOCAL-DATA ref does: its file is written exec-free and the values
      // ride `localExec`, exactly like a folder ref.
      if (e.project && !e.dataFile) continue
      if (!this.execUnmigrated.has(e.id)) e.execMigrated = true
    }

    const unavailableIds = new Set(workspace.projects.filter((p) => p.unavailable).map((p) => p.id))
    if (unavailableIds.size) {
      for (const e of index.entries) {
        if (!unavailableIds.has(e.id)) continue
        const old = this.index?.entries.find((o) => o.id === e.id)
        if (old?.cache) e.cache = old.cache
        // Same reasoning for the machine-local exec values: the placeholder has no nodes, so
        // splitWorkspace could not carry them — restoring them keeps the user's own custom shell /
        // ssh args for when the ref becomes readable again.
        if (old?.localExec) e.localExec = old.localExec
        // …and for the rest of the machine-local half. A placeholder's viewport is the {0,0,1} of
        // an empty stand-in canvas: persisting it would forget where the user was looking the
        // moment a folder is briefly unmounted.
        if (old?.viewport) e.viewport = old.viewport
        if (old?.defaultAccountId) e.defaultAccountId = old.defaultAccountId
        if (old?.breadcrumbs) e.breadcrumbs = old.breadcrumbs
        // Same rule: a placeholder's project carries no closedSessions (it has no nodes to have
        // deleted), so without this an unavailable window would silently forget the user's trash
        // can the moment splitWorkspace rebuilds the index.
        if (old?.closedSessions) e.closedSessions = old.closedSessions
        // Same rule again: a placeholder carries no layouts, so `splitWorkspace` pruned its
        // cameras away against an empty list. Restoring them keeps the user's per-layout camera
        // for when the ref becomes readable again.
        if (old?.layoutViewports) e.layoutViewports = old.layoutViewports
        // The clone-notice acknowledgment must also survive an unavailable window: forgetting it
        // would re-raise a notice the user already answered the moment the folder remounts.
        if (old?.capabilityAck) e.capabilityAck = old.capabilityAck
        // A data-ref placeholder (its file was unreadable at load) must stay a data-ref. Without
        // this the entry comes back as a PRE-FILE inline entry holding the placeholder's
        // `nodes: []` — the empty canvas becomes the stored truth and the file it named is
        // orphaned. Restore the previous cache, or drop the field entirely so the entry stays a
        // pure ref and renders as the grey tab it is.
        if (old?.dataFile) {
          e.dataFile = true
          if (old.project) e.project = old.project
          else delete e.project
        }
      }
    }

    // Which project each pending file belongs to. `files` is keyed by cwd and the candidate no
    // longer carries an id (that is the point), while `revs` is keyed by PROJECT id — so the two
    // are joined here, through the index entry that owns the folder. At most one ref entry exists
    // per cwd (splitWorkspace's second tab on a folder becomes an inline entry, no cwd at all).
    const projectIdForCwd = new Map(
      index.entries.filter((e) => folderFileCwd(e)).map((e) => [e.cwd!, e.id] as const)
    )
    // What this store remembers of a folder file belongs to the entry that owned that folder in the
    // PREVIOUS index. An entry that takes a folder over from a data file ("Set folder…", a move back
    // from app data, issue #1145) starts without the record: the folder was probed empty right
    // before, so a remembered copy can only describe a file that has since left the folder (a
    // `git rm`, a branch checkout), and comparing against it would skip the write as "unchanged" —
    // after which the sweep below would delete the data file, the only copy left.
    const previousById = new Map((previousIndex?.entries ?? []).map((e) => [e.id, e] as const))
    for (const e of index.entries) {
      const cwd = folderFileCwd(e)
      if (!cwd || !previousById.get(e.id)?.dataFile) continue
      this.lastWritten.delete(projectFilePath(cwd))
      this.lastWrittenParsed.delete(projectFilePath(cwd))
    }
    // The folder files this save actually wrote. The data-file sweep reads this, never `lastWritten`:
    // only a write in this save shows that the folder holds the canvas now.
    const folderFilesWritten = new Set<string>()
    for (const [cwd, candidate] of files) {
      const projectId = projectIdForCwd.get(cwd) ?? cwd
      const file = projectFilePath(cwd)
      const prevParsed = this.parsedLastWritten(file)
      if (prevParsed && sameProjectContent(prevParsed, candidate)) continue
      if (!prevParsed && candidate.nodes.length === 0 && !(await this.emptyOrAbsentOnDisk(file))) {
        // The local twin of the SSH "never blind-write a file we have not read" rule: an empty
        // canvas from a store that never read this file (setProjectFolder, migration, a hydrate
        // race) must not overwrite the populated — or corrupt-but-recoverable — only copy. The
        // disk stays authoritative; the next load returns its truth.
        continue
      }
      const next: ProjectFileV1 = { ...candidate, rev: (this.revs.get(projectId) ?? 0) + 1 }
      const content = serializeProjectFile(next)
      try {
        await fs.mkdir(path.dirname(file), { recursive: true })
        await writeAtomic(file, content)
        this.lastWritten.set(file, content)
        this.revs.set(projectId, next.rev)
        folderFilesWritten.add(file)
      } catch { /* folder gone (unmounted disk): the entry simply stays stale → unavailable next load */ }
    }

    // A folder project moving its canvas from app data INTO its folder (issue #1145) whose folder
    // write did not land — the leg above swallows a failed write, an unchanged skip is impossible
    // here (the record was dropped above) — stays a folder-data-ref for this save: same data file,
    // same cache. Otherwise the index would name a folder file that is not there, a restart would
    // open the project empty and unavailable, and its data file would be referenced by nothing.
    // The renderer still asks for the folder, so the next save retries; `projectStorage` tells the
    // menu the move did not happen. Unavailable placeholders never reach this (the loop further up
    // already kept their `dataFile`, so they have no folder file to ask for).
    for (const e of index.entries) {
      const cwd = folderFileCwd(e)
      if (!cwd || folderFilesWritten.has(projectFilePath(cwd))) continue
      const before = previousById.get(e.id)
      if (!before || !isFolderDataRef(before)) continue
      const p = workspace.projects.find((x) => x.id === e.id)
      if (!p) continue
      const inline = appDataCanvas(p)
      e.dataFile = true
      e.project = inline
      if (isInlineProjectFileId(e.id)) dataFiles.set(e.id, projectToFile(inline, this.revs.get(e.id) ?? 0, savedAt))
    }

    // Inline (cwd-less) canvases: their own file under userData, written before the index and with
    // the same rules the folder leg lives by — skip an unchanged candidate, never let an empty
    // candidate overwrite a populated file this store has not read — plus the one rule only this
    // leg needs (see `writeDataFile`): a second app instance shares this userData, so a file whose
    // rev has moved ahead of ours belongs to that instance and is not overwritten.
    // A folder project that has just moved its canvas INTO app data (issue #1145) may find a file
    // of its own already there — litter from an earlier "Set folder…" or move, same id and same
    // lineage. It is never what this project holds now, and left alone it can win: an empty
    // candidate is refused over a populated file this store never read, and the next load would
    // adopt those stale bytes. So it is cleared before the write, for exactly that transition.
    // Only for an id this store already had as a folder ref: a file under an id we never held is
    // another instance's (see `sweepRemovedDataFiles`).
    const wasFolderRef = new Set(
      (previousIndex?.entries ?? []).filter((e) => folderFileCwd(e)).map((e) => e.id)
    )
    for (const e of index.entries) {
      if (!isFolderDataRef(e) || !wasFolderRef.has(e.id) || !e.cwd) continue
      // From this save on the folder's project.json is not this project's, whether or not the user
      // later keeps a tracked copy of it: forget it, so nothing compares a future write against it.
      this.lastWritten.delete(projectFilePath(e.cwd))
      this.lastWrittenParsed.delete(projectFilePath(e.cwd))
      if (!isInlineProjectFileId(e.id)) continue
      const file = inlineFilePath(e.id)
      await fs.rm(file, { force: true }).catch(() => undefined)
      this.lastWritten.delete(file)
      this.lastWrittenParsed.delete(file)
    }
    for (const [projectId, candidate] of dataFiles) await this.writeDataFile(projectId, candidate)

    // ssh caches: bump rev on change so a later remote write can win; mirror write in Task 8.
    for (const e of index.entries) {
      if (!e.ssh || !e.cache) continue
      if (e.handedOffTo) continue // handed to a hosted team: the server core is the only writer now
      // (`markUnmirrored` may still add a handed-off id; every consumer of that debt refuses it.)
      const prevRev = this.revs.get(e.id) ?? 0
      const previousCache = this.index?.entries.find((old) => old.id === e.id && old.cache)?.cache
      const changedSinceLoad = !(previousCache && sameProjectContent(previousCache, e.cache))
      e.cache.rev = changedSinceLoad ? prevRev + 1 : prevRev
      this.revs.set(e.id, e.cache.rev)
      if (!this.remoteIO) continue
      // Anything this save dropped is a deliberate local deletion — remember it until the server has
      // been told, so the mirror write's re-read below can tell it apart from a node we never had.
      // Without that record the re-read would hand every just-deleted node straight back on the very
      // write that was supposed to remove it, and no node on an ssh project could ever be closed.
      this.recordLocalDeletions(e.id, previousCache?.nodes, e.cache.nodes)
      if (localOnly) {
        // No network. An unreconciled entry is left for the next ordinary save to LOOK first (the
        // never-blind-write rule is untouched); a reconciled one that changed now owes its mirror.
        if (changedSinceLoad && this.reconciled.has(e.id)) this.unmirrored.add(e.id)
        continue
      }
      if (!this.reconciled.has(e.id)) {
        // Never blind-write a remote file we have not read yet: the first mirror of a fresh or
        // re-added project must LOOK first — an existing lineage on the server may win (adopted,
        // broadcast to the renderer) instead of being clobbered by an empty newborn canvas.
        const adopted = await this.reconcileSsh(e)
        if (adopted) platform().broadcast(IPC.workspaceExternalChange, adopted)
        continue
      }
      // Mirror on change, and re-mirror while a previous write is still owed (the first save
      // often races the ControlMaster coming up — its write is dropped fail-open, and without
      // the retry nothing rewrites until the next real content change).
      //
      // The write RE-READS the server first (mirrorSshCache) — it used to be blind, which is the
      // gap that cost users a phone-started session: the phone appends its node to the server file
      // at T0, the user drags a node here at T0+2s, and that ordinary save's mirror write pushed a
      // cache that had never seen the append, deleting it from both sides for good. The ~15s poll
      // only rescued the appends that happened to land outside its own window. The re-read costs one
      // extra round-trip per CHANGED save (an unchanged, already-mirrored save still reads nothing).
      if (changedSinceLoad || this.unmirrored.has(e.id)) await this.mirrorSshCache(e)
    }
    // Tombstones are retired by a server read (`confirmClearedDeletions`), so a project that left
    // the index would keep its set for the rest of the run with nothing left to read it. Bound it.
    if (this.clearedNodes.size) {
      const liveIds = new Set(index.entries.map((e) => e.id))
      for (const id of this.clearedNodes.keys()) if (!liveIds.has(id)) this.clearedNodes.delete(id)
    }

    // Back up the raw v2 file BEFORE the v3 index flip: a crash between the two must never leave a
    // migrated tree (project files already written above) without its pre-migration backup.
    const migrating = this.pendingV2Backup !== null
    if (migrating) {
      try {
        await writeAtomic(path.join(platform().userDataDir, 'workspace.v2.bak'), this.pendingV2Backup!)
      } catch { /* backup is best-effort */ }
      this.pendingV2Backup = null
    }

    // Compact index, atomic — same reasoning as the old single-file store. Skipped when the bytes
    // equal our last write AND the file still has the size/mtime/inode that write left (another
    // instance sharing this userData rewrote it otherwise). A migration always writes: the v3 flip
    // is the point of that save.
    const indexJson = JSON.stringify(index)
    const last = this.lastIndexWrite
    const onDisk = !migrating && last?.json === indexJson
      ? await fs.stat(this.indexPath).catch(() => null)
      : null
    const unchanged =
      !!onDisk &&
      !!last &&
      onDisk.size === last.size &&
      onDisk.mtimeMs === last.mtimeMs &&
      onDisk.ino === last.ino
    if (!unchanged) {
      this.lastIndexWrite = null
      await writeAtomic(this.indexPath, indexJson)
      const st = await fs.stat(this.indexPath).catch(() => null)
      this.lastIndexWrite = st
        ? { json: indexJson, size: st.size, mtimeMs: st.mtimeMs, ino: st.ino }
        : null
    }
    await this.sweepRemovedDataFiles(previousIndex, index, folderFilesWritten)
    this.index = index

    if (migrating) platform().broadcast(IPC.workspaceMigrated, 'v2')
    if (this.pendingExecNote) {
      this.pendingExecNote = false
      platform().broadcast(IPC.workspaceMigrated, 'exec')
    }

    this.onPersist?.()
  }

  /**
   * Writes one cwd-less canvas to `userData/inline-projects/<id>.json`.
   *
   * Three refusals, in order, and each one leaves the disk MORE authoritative than this store:
   *
   *  1. unchanged since we last wrote or read it → no write at all (the common save), so an idle
   *     canvas costs neither a read nor a write;
   *  2. the file on disk carries a rev ABOVE ours → a second app instance sharing this userData
   *     wrote it after we last looked, and a lower rev may not overwrite a higher one. The two
   *     canvases are NOT merged (see the limits in CLAUDE.md): that instance's canvas stands and
   *     the next load here adopts it. What the rule buys is that two instances can no longer
   *     ERASE each other, which is exactly what the single shared index allowed;
   *  3. an empty candidate over a populated file this store has never read → the local twin of the
   *     folder leg's rule, for a renderer that hydrated zero nodes for some transient reason.
   *
   * A failed write is not fatal and is deliberately not retried here: the index still carries this
   * canvas in `project` (the dual-write), so the content is readable either way round — which is
   * also what makes a half-done migration consistent in both directions.
   */
  private async writeDataFile(projectId: string, candidate: ProjectFileV1): Promise<DataFileWrite> {
    if (!isInlineProjectFileId(projectId)) return 'skipped'
    const file = inlineFilePath(projectId)
    const prev = this.lastWritten.get(file)
    let prevParsed: ProjectFileV1 | null = null
    if (prev) {
      try {
        prevParsed = JSON.parse(prev) as ProjectFileV1
      } catch { /* our own cache, but never trusted blindly */ }
    }
    if (prevParsed && sameProjectContent(prevParsed, candidate)) return 'unchanged'
    const ourRev = this.revs.get(projectId) ?? 0
    // Read the file only when we are actually about to write it.
    const onDisk = await this.readDataFile(projectId, false)
    if (onDisk && onDisk.file.rev > ourRev) {
      // Adopt the other writer's bytes as what we know is on disk, so the next save compares
      // against reality instead of re-deciding this every time.
      this.lastWritten.set(file, onDisk.raw)
      this.revs.set(projectId, onDisk.file.rev)
      return 'ahead'
    }
    if (!prevParsed && candidate.nodes.length === 0 && (onDisk?.file.nodes.length ?? 0) > 0) return 'refused'
    const next: ProjectFileV1 = { ...candidate, rev: ourRev + 1 }
    const content = serializeProjectFile(next)
    try {
      await fs.mkdir(path.dirname(file), { recursive: true })
      await writeAtomic(file, content)
      this.lastWritten.set(file, content)
      this.revs.set(projectId, next.rev)
      return 'written'
    } catch {
      // the index's `project` copy still holds this canvas; the next save retries
      return 'failed'
    }
  }

  /**
   * Deletes the data file of a project THIS store had and no longer has — i.e. one the user
   * removed. Nothing else: a file whose id was never in our own loaded index is left alone,
   * because that is precisely a second instance's project, and the whole point of this layer is
   * that one instance's index write can no longer destroy another's canvas. The cost of the
   * asymmetry is a few KB of litter after a re-key or a crash, which is the right side to err on.
   */
  private async sweepRemovedDataFiles(
    previous: WorkspaceIndexV3 | null,
    next: WorkspaceIndexV3,
    folderFilesWritten: ReadonlySet<string>
  ): Promise<void> {
    if (!previous) return
    // Ids whose entry still keeps its content in a data file. An id that is live but no longer a
    // data ref left that storage — "Set folder…" bound it to a folder, or a folder-data-ref moved
    // its canvas back into the folder (issue #1145) — and its file is deleted too: same id, same
    // lineage, and a leftover with a higher rev would win `writeDataFile`'s rev rule (and its stale
    // bytes be adopted) the day the project moved back into app data.
    //
    // Only once the folder holds the canvas, though: the folder leg swallows a failed write (an
    // unmounted or read-only disk), and deleting the data file then would leave the canvas in
    // memory only. So the file goes only when THIS save wrote the folder's file. What the store
    // remembers having written there is not enough: the file may have left the folder since.
    const nextById = new Map(next.entries.map((e) => [e.id, e] as const))
    const keep = (id: string): boolean => {
      const n = nextById.get(id)
      if (!n) return false
      if (n.dataFile) return true
      const cwd = folderFileCwd(n)
      return !cwd || !folderFilesWritten.has(projectFilePath(cwd))
    }
    for (const e of previous.entries) {
      if (!e.dataFile || keep(e.id) || !isInlineProjectFileId(e.id)) continue
      const file = inlineFilePath(e.id)
      await fs.rm(file, { force: true }).catch(() => undefined)
      this.lastWritten.delete(file)
      this.lastWrittenParsed.delete(file)
      // A project that only moved its canvas keeps its rev: it continues in the new location, and
      // resetting it would send the folder's next write out as rev 1 over the rev N just written.
      if (!nextById.has(e.id)) this.revs.delete(e.id)
      // A DELETED folder project kept in app data takes its app-data side files with it (settings,
      // board log: `appDataProjectRoot`), as a folder ref's would go with its folder if the user
      // deleted that. One that only moved back into its folder keeps them: its board log history
      // stays there rather than vanish with a move.
      if (!nextById.has(e.id) && isFolderDataRef(e)) {
        await fs.rm(appDataProjectRoot(e.id), { recursive: true, force: true }).catch(() => undefined)
      }
      // A folder-data-ref that moved back into its folder: its app-data settings were carried into
      // the folder by `prepareFolderStorage`. Removed only once the folder demonstrably has them —
      // a move that skipped the carry must not lose the project's settings.
      const moved = nextById.get(e.id)
      if (moved?.cwd && isFolderDataRef(e) && (await readProjectSettingsFile(moved.cwd)).status === 'ok') {
        await fs.rm(projectSettingsPath(appDataProjectRoot(e.id)), { force: true }).catch(() => undefined)
      }
    }
  }

  /**
   * The ADOPTION path: a folder with no index entry (Open folder…, a fresh clone). It is the one
   * place that must MINT an id — the file used to supply one, which is exactly how a worktree's
   * copy handed a second folder the first's identity.
   *
   * Minting cannot be idempotent (two folders holding the same canvas must become two projects),
   * so re-opening a folder is kept to one project by the CALLER, which looks the folder up by cwd
   * before it probes (`projects.openFolderProject` / `addProjectFromFolder`). Once adopted, the
   * index entry owns the id for good.
   */
  async probeFolder(folder: string): Promise<Project | null> {
    return (await this.probeFolderFile(folder))?.project ?? null
  }

  /** `probeFolder` plus the file's own `rev`, from the SAME read (`adoptFolder` continues it). */
  private async probeFolderFile(folder: string): Promise<{ project: Project; rev: number } | null> {
    const read = await this.readProjectFile(folder, false)
    // No `localExec`: this folder is being ADOPTED (its project.json may have been cloned from
    // anywhere), so its nodes come up with no custom shell and no extra ssh args — the safe
    // defaults. Only values this machine typed itself are ever restored (@shared/node-exec).
    return read ? { project: fileToProject(read.file, { id: freshProjectId(), cwd: folder }), rev: fileRev(read.file) } : null
  }

  /**
   * Is this folder's `.nodeterm/project.json` genuinely gone, merely unreadable, or fine?
   *
   * `readProjectFile` collapses all three into `null`, which is right for its callers (they only
   * need "can I use it") but wrong for recovery: clearing a project's `unavailable` placeholder
   * lets the next save WRITE its empty canvas, so doing that on a file that is present but
   * momentarily unreadable (permissions, a stalled mount) would overwrite the only copy. A failed
   * read is never evidence of absence — so the errno is the answer, and anything that is not a
   * definite ENOENT reports `unreadable`, the side that changes nothing. See issue #385.
   */
  /**
   * The second half of "Store in app data" (issue #1145), run once the move's save has landed:
   * carry the folder's settings.json into the project's app-data root (when it has none of its
   * own), then remove `.nodeterm/project.json` and `settings.json` from the folder, so a later
   * "Open folder…", a worktree or an older build cannot adopt the stale copy as a second project.
   *
   * Refused unless the entry IS a folder-data-ref whose data file this store has written or read —
   * the canvas must demonstrably be in app data before its folder copy goes. A file git tracks (or
   * that could not be checked) is KEPT unless `removeTracked`: deleting it is a change in the
   * user's repo, which the caller asks about first. A settings file that could not be carried over
   * is kept too. Queued on `saveChain`, after any save in flight.
   */
  releaseFolderFiles(projectId: string, removeTracked: boolean): Promise<ReleaseFolderFilesResult> {
    const run = this.saveChain.then(() => this.releaseFolderFilesNow(projectId, removeTracked))
    this.saveChain = run.catch(() => {})
    return run
  }

  private async releaseFolderFilesNow(projectId: string, removeTracked: boolean): Promise<ReleaseFolderFilesResult> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e || !isFolderDataRef(e) || !e.cwd) return { ok: false, reason: 'not-app-data' }
    if (!isInlineProjectFileId(e.id) || !this.lastWritten.has(inlineFilePath(e.id))) {
      return { ok: false, reason: 'not-saved' }
    }
    const cwd = e.cwd
    // Kept or removed, the folder's project.json is no longer this project's record (the move's save
    // already forgot it; this covers a release that runs on its own).
    this.lastWritten.delete(projectFilePath(cwd))
    this.lastWrittenParsed.delete(projectFilePath(cwd))
    const candidates: string[] = []
    if ((await this.projectFileState(cwd)) === 'present') candidates.push(projectFilePath(cwd))

    const folderSettings = await readProjectSettingsFile(cwd)
    if (folderSettings.status === 'ok') {
      // The folder's copy is the current one: this project read its settings from there until the
      // move. An app-data file already present is a leftover (a sweep that did not finish), so it is
      // overwritten rather than allowed to win, with its rev continued.
      const root = appDataProjectRoot(e.id)
      const own = await readProjectSettingsFile(root)
      if (own.status === 'ok' || own.status === 'absent' || own.status === 'invalid') {
        try {
          const written = await writeProjectSettingsFile(
            root, folderSettings.file, own.status === 'ok' ? own.file : null, new Date().toISOString()
          )
          this.lastSharedSettings.set(e.id, written)
          candidates.push(projectSettingsPath(cwd))
        } catch { /* not carried: the folder's copy stays */ }
      }
    }

    const removed: string[] = []
    const kept: string[] = []
    for (const file of candidates) {
      const tracked = await gitTracksFile(cwd, file)
      if (tracked !== false && !removeTracked) {
        kept.push(file)
        continue
      }
      try {
        await fs.rm(file, { force: true })
        removed.push(file)
      } catch {
        kept.push(file)
      }
    }
    // An emptied `.nodeterm/` goes too; one still holding images or a board log stays.
    if (removed.length) await fs.rmdir(path.join(cwd, PROJECT_DIR)).catch(() => undefined)
    return { ok: true, removed, kept }
  }

  /**
   * The first half of "Store in folder" (issue #1145), run before the move's save: refuse when the
   * folder already holds a project.json (the save would overwrite that canvas — the same
   * probe-before-bind rule as "Set folder…") or a settings.json (this project's own would be lost),
   * and an unreadable file is never taken for an absent one. Otherwise carry the project's
   * app-data settings into the folder, so they are there the moment the canvas is, and its
   * whiteboards (`carryWhiteboards`), so a board edited in app data is not hidden by the folder's
   * older copy once the folder is read first again.
   */
  /**
   * Where this store has a project's canvas, answered after any save in flight (queued on
   * `saveChain`). The move into the folder asks it after its save: a save can land while the folder
   * write inside it did not, in which case the project stays in app data and the menu must say so.
   */
  projectStorage(projectId: string): Promise<ProjectStorageKind> {
    const run = this.saveChain.then((): ProjectStorageKind => {
      const e = this.index?.entries.find((x) => x.id === projectId)
      if (!e) return 'none'
      if (isFolderDataRef(e)) return 'appData'
      return folderFileCwd(e) ? 'folder' : 'none'
    })
    this.saveChain = run.catch(() => {})
    return run
  }

  async prepareFolderStorage(projectId: string): Promise<PrepareFolderStorageResult> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e || !isFolderDataRef(e) || !e.cwd) return { ok: false, reason: 'not-app-data' }
    const state = await this.projectFileState(e.cwd)
    if (state === 'present') return { ok: false, reason: 'occupied' }
    if (state === 'unreadable') return { ok: false, reason: 'unreadable' }
    const folderSettings = await readProjectSettingsFile(e.cwd)
    if (folderSettings.status === 'ok' || folderSettings.status === 'conflict') return { ok: false, reason: 'settings-occupied' }
    if (folderSettings.status === 'error') return { ok: false, reason: 'settings-unreadable' }
    if (isInlineProjectFileId(e.id)) {
      const own = await readProjectSettingsFile(appDataProjectRoot(e.id))
      if (own.status === 'ok') {
        try {
          await writeProjectSettingsFile(e.cwd, own.file, null, new Date().toISOString())
        } catch {
          return { ok: false, reason: 'settings-unreadable' }
        }
      }
      await carryWhiteboards(appDataProjectRoot(e.id), e.cwd)
    }
    return { ok: true }
  }

  async projectFileState(cwd: string): Promise<'present' | 'absent' | 'unreadable'> {
    try {
      await fs.stat(projectFilePath(cwd))
      return 'present'
    } catch (err) {
      return (err as NodeJS.ErrnoException)?.code === 'ENOENT' ? 'absent' : 'unreadable'
    }
  }

  /**
   * HEADLESS adoption (`team bootstrap`): add the folder at `cwd` as a project of this core and
   * save it, so the canvas authority can read it before it is shared. One project per REAL path:
   * an entry whose folder resolves to the same directory is reused, never duplicated, because the
   * desktop names the folder by whatever path it holds and a symlink must not mint a second
   * project. A reused project that was closed is reopened. A folder with a project file is adopted
   * with `probeFolder` semantics (fresh project id, node ids kept — they are tmux session names),
   * and its `rev` continues from the file's own. One without becomes an empty project named after
   * the folder.
   *
   * Every refusal is one that keeps the only copy of something: a project file that is present
   * but cannot be read (see `projectFileState`) — whether or not an entry already names the folder
   * (a reused entry whose file did not load is an `unavailable` placeholder with no content, which
   * the authority could not read) — and an index this load could not read, which the save below
   * would replace with one holding only the adopted project (and, when an earlier load this run did
   * read it, `sweepRemovedDataFiles` would then delete every inline project's data file with it).
   * Nothing here sidelines a corrupt file either; it is left in place for the user to fix. The root,
   * the home directory and any folder containing the home are refused with E_BAD_CWD
   * (`containsHome`): every teammate, Viewers included, may read any file under a shared folder.
   *
   * `home` expands the SSH project's `~` paths and drops its SSH-only node flags
   * (`localizeAdoptedNode`), on a reused project too: a browser's "Open folder…" or an older
   * desktop mirror push can have left that entry holding the SSH view. The server runs as the same
   * user the desktop logged in as, so the home is the same. For a project the canvas authority
   * already governs, the save is overlaid with the authority's own content (it owns shared
   * content), so this localizes only a project that is not shared yet.
   *
   * The whole read-modify-write runs ON `saveChain`: a save queued meanwhile would otherwise write
   * an index built before this project existed over the one that adds it. A created project stays
   * in `pendingAdoptions` until a renderer loads it, so a browser tab that loaded before this call
   * cannot drop it with its next autosave.
   */
  adoptFolder(cwd: string, opts: { home: string }): Promise<AdoptFolderResult> {
    const run = this.saveChain.then(() => this.adoptFolderNow(cwd, opts))
    this.saveChain = run.catch(() => {})
    return run
  }

  private async adoptFolderNow(cwd: string, opts: { home: string }): Promise<AdoptFolderResult> {
    if (!path.isAbsolute(cwd)) throw codedError('E_BAD_CWD', `Not an absolute path: ${cwd}`)
    let real: string
    try {
      real = await fs.realpath(cwd)
      if (!(await fs.stat(real)).isDirectory()) throw new Error('not a directory')
    } catch {
      throw codedError('E_BAD_CWD', `Not a directory on this host: ${cwd}`)
    }
    if (await containsHome(real, opts.home)) {
      throw codedError(
        'E_BAD_CWD',
        `Refusing to share ${real}: it is the home directory or contains it, and every teammate, Viewers included, could read every file in it. Share a project folder instead.`
      )
    }
    // `load` does not queue on `saveChain`, so calling it from this chain step cannot deadlock.
    // Read-only (no sideline): adoption must not rename some OTHER project's conflict-marked file.
    const workspace = structuredClone(await this.load({ sideline: false }))
    // Set by the load just above. A load running beside it reads the same file, so it can only
    // report a different state if the file itself changed in between.
    if (this.indexReadState === 'unreadable') {
      throw codedError('E_ADOPT_FAILED', `This server's workspace index could not be read; fix or move ${this.indexPath} first.`)
    }
    for (const p of workspace.projects) {
      if (!p.cwd || p.ssh) continue
      const theirs = await fs.realpath(p.cwd).catch(() => p.cwd as string)
      if (theirs !== real) continue
      if (p.unavailable) {
        throw codedError('E_ADOPT_FAILED', `${projectFilePath(real)} could not be read; fix it before sharing this folder.`)
      }
      const nodes = p.nodes.map((n) => localizeAdoptedNode(n, opts.home))
      const localized = nodes.some((n, i) => n !== p.nodes[i])
      if (localized) p.nodes = nodes
      const reopened = p.closed === true
      if (reopened) {
        p.closed = false
        delete p.closedAt
      }
      if (localized || reopened) await this.saveNow(workspace, false)
      return { projectId: p.id, projectName: p.name, created: false }
    }
    const state = await this.projectFileState(real)
    if (state === 'unreadable') throw codedError('E_ADOPT_FAILED', `Could not read ${projectFilePath(real)}.`)
    let project: Project
    if (state === 'present') {
      const probed = await this.probeFolderFile(real)
      if (!probed) throw codedError('E_ADOPT_FAILED', `${projectFilePath(real)} is not a project file this server can read.`)
      project = { ...probed.project, nodes: probed.project.nodes.map((n) => localizeAdoptedNode(n, opts.home)) }
      // The save numbers the file from `revs` (+1). Without this the fresh id has no entry and the
      // file would go back to rev 1, while every other writer keeps a project file's rev rising.
      this.revs.set(project.id, probed.rev)
    } else {
      project = {
        id: freshProjectId(),
        name: clampProjectName(folderName(real)) || 'Project',
        color: SYSTEM_NODE_COLORS[workspace.projects.length % SYSTEM_NODE_COLORS.length],
        cwd: real,
        viewport: { x: 0, y: 0, zoom: 1 },
        nodes: []
      }
    }
    workspace.projects.push(project)
    if (!workspace.activeProjectId) workspace.activeProjectId = project.id
    await this.saveNow(workspace, false)
    this.pendingAdoptions.add(project.id)
    return { projectId: project.id, projectName: project.name, created: true }
  }

  localRefPaths(): string[] {
    return (this.index?.entries ?? []).filter((e) => folderFileCwd(e)).map((e) => projectFilePath(e.cwd!))
  }

  isSelfWrite(filePath: string, content: string): boolean {
    return this.lastWritten.get(filePath) === content
  }

  async readLocalRef(projectId: string): Promise<Project | null> {
    const e = this.index?.entries.find((x) => x.id === projectId && folderFileCwd(x))
    if (!e?.cwd) return null
    const read = await this.readProjectFile(e.cwd, false)
    if (!read) return null
    // The watcher's re-read after a git checkout is exactly where a foreign file arrives; the
    // project must come back under OUR entry id or `replaceProject` (which matches by id) silently
    // drops it. Same for the camera: a teammate's committed viewport must not yank this user's.
    this.revs.set(e.id, read.file.rev)
    this.lastWritten.set(projectFilePath(e.cwd), read.raw)
    return fileToProject(read.file, {
      id: e.id,
      cwd: e.cwd,
      closed: e.closed,
      closedAt: e.closedAt,
      handedOffTo: e.handedOffTo,
      viewport: e.viewport,
      defaultAccountId: e.defaultAccountId,
      breadcrumbs: e.breadcrumbs,
      closedSessions: e.closedSessions,
      layoutViewports: e.layoutViewports,
      capabilityAck: e.capabilityAck,
      localExec: e.localExec
    })
  }

  /** Maps a watched file path back to its project and re-reads it. */
  async readLocalRefByPath(filePath: string): Promise<Project | null> {
    // `folderFileCwd`, not `cwd`: a folder-data-ref on the same folder as a folder ref must not
    // answer for the ref's file, or the ref misses its outside edit.
    const e = this.index?.entries.find((x) => {
      const cwd = folderFileCwd(x)
      return cwd !== undefined && projectFilePath(cwd) === filePath
    })
    return e ? this.readLocalRef(e.id) : null
  }

  /**
   * Reconciles the server's .nodeterm/project.json with our cached copy (see reconcileSsh):
   * remote won → adopt (returned; caller broadcasts it); otherwise our cache pushed up.
   * Called on connect, and periodically while connected (the POLL — how a session the mobile
   * companion appended to the server file reaches the live canvas). The poll passes
   * `pushIfStanding: false`: when our cache simply stands, a poll must be read-only — only an
   * OWED mirror (a previously dropped write) may still push.
   *
   * Runs ON `saveChain`, like every other read-modify-write of the same state: off the chain a
   * poll could snapshot the pre-save index entry, then complete its slow ssh read AFTER the save's
   * mirror write landed — remote.rev > (stale) cacheRev, and the store "adopted" and broadcast its
   * OWN write as an external change (the spurious Reload/Keep-mine conflict bar). Queued, a
   * reconcile always compares the server file against the same generation of cache/rev state, and
   * its index write cannot interleave with a save's either.
   */
  refreshSshProject(projectId: string, opts?: { pushIfStanding?: boolean }): Promise<Project | null> {
    const run = this.saveChain.then(() => this.refreshSshProjectNow(projectId, opts))
    this.saveChain = run.catch(() => {})
    return run
  }

  private async refreshSshProjectNow(projectId: string, opts?: { pushIfStanding?: boolean }): Promise<Project | null> {
    const e = this.index?.entries.find((x) => x.id === projectId && x.ssh)
    if (!e?.ssh || !this.remoteIO) return null
    const revBefore = e.cache?.rev
    const adopted = await this.reconcileSsh(e, opts?.pushIfStanding ?? true)
    // Persist the index only when the reconcile moved something — a quiet poll must not churn
    // workspace.json every tick.
    if (adopted || e.cache?.rev !== revBefore) {
      this.lastIndexWrite = null
      await writeAtomic(this.indexPath, JSON.stringify(this.index))
    }
    return adopted
  }

  /** The ssh entry ids of the current index: the IDENTITY list ("this project runs on someone
   *  else's machine", connected or not, handed off or not), which the session-memory and dev-ports
   *  scope checks read. */
  sshProjectIds(): string[] {
    return (this.index?.entries ?? []).filter((e) => e.ssh).map((e) => e.id)
  }

  /** The ssh entry ids this desktop still keeps in sync — what the connected-project poll and the
   *  agent-status push iterate. Leaves out a project handed to a hosted team: the server core on its
   *  host owns its file and sessions now, so it is never polled again. */
  pollableSshProjectIds(): string[] {
    return (this.index?.entries ?? []).filter((e) => e.ssh && !e.handedOffTo).map((e) => e.id)
  }

  /**
   * The OPEN ssh entries of the current index, with their endpoints — what the boot-time master
   * pre-warm dials (see core/remote-ssh/ssh-prewarm.ts).
   *
   * Deliberately NOT `sshProjectIds()` plus a lookup: a CLOSED project must never be dialed.
   * `closeProject` is non-destructive — it leaves the host's tmux sessions running and the project
   * on disk — so a closed tab is the user saying "not now", and waking an ssh login (possibly a
   * passphrase prompt) for one is worse than a slow first switch.
   */
  openSshProjects(): { id: string; ssh: NonNullable<Project['ssh']> }[] {
    return (this.index?.entries ?? [])
      .filter((e) => e.ssh && !e.closed)
      .map((e) => ({ id: e.id, ssh: e.ssh as NonNullable<Project['ssh']> }))
  }

  /** How many projects of the loaded index are open (`countOpenProjects`), or undefined before the
   *  index is loaded. The index never holds a relay tab (`splitWorkspace` drops them), and an
   *  unavailable placeholder is an entry like any other — it is still an open tab. Sync. */
  openProjectCount(): number | undefined {
    return this.index ? countOpenProjects(this.index.entries) : undefined
  }

  /** Every project in the loaded index as a `nodeterm://open` link may name it (main/open-link.ts):
   *  id, name, folder, closed, and the two kinds a link never offers (SSH, handed to a hosted team).
   *  Undefined before the index is loaded. Sync, like `localCwdForProject`. */
  linkProjectEntries():
    | { id: string; name: string; cwd?: string; closed?: boolean; ssh?: boolean; handedOff?: boolean }[]
    | undefined {
    if (!this.index) return undefined
    return this.index.entries.map((e) => ({
      id: e.id,
      name: e.name,
      ...(e.cwd ? { cwd: e.cwd } : {}),
      ...(e.closed ? { closed: true } : {}),
      ...(e.ssh ? { ssh: true } : {}),
      ...(e.handedOffTo ? { handedOff: true } : {})
    }))
  }

  /** The local folder cwd of a project by id (index lookup), or undefined for ssh/inline/unknown
   *  projects. Sync (reads the in-memory index). Where the project's terminals RUN — which is
   *  also a relay seat's folder jail. Not where nodeterm may write its own files: see
   *  `sideFilesFolderForProject` and `boardLogRootForProject`. */
  localCwdForProject(projectId: string): string | undefined {
    return this.index?.entries.find((e) => e.id === projectId && e.cwd)?.cwd
  }

  /**
   * The folder whose `.nodeterm/` may hold this project's side files (canvas images), or undefined
   * — the caller's app-data fallback. A folder-data-ref has a cwd and still answers undefined: the
   * whole point of keeping its canvas in app data is that nothing is written into the folder
   * (issue #1145).
   */
  sideFilesFolderForProject(projectId: string): string | undefined {
    const e = this.index?.entries.find((x) => x.id === projectId)
    return e ? folderFileCwd(e) : undefined
  }

  /**
   * Where a project's whiteboards live (core/whiteboards.ts), without the app folder every location
   * falls back to. A folder ref writes `<cwd>/.nodeterm/whiteboards/` and reads, after it, what it
   * drew while its canvas was kept in app data. A folder-data-ref writes the same layout under its
   * app-data root and only READS its folder, where the boards drawn before the move still are
   * (issue #1145: nothing is written into the folder). Not the canvas images' answer
   * (`sideFilesFolderForProject`): the app's shared image folder is keyed by file name, while a board
   * is keyed by node id, which two folders holding the same committed canvas share — in one shared
   * folder, two such projects in app data would read and overwrite each other's boards. SSH and
   * cwd-less projects answer `{}`: the app folder alone.
   */
  whiteboardLocationForProject(projectId: string): Omit<WhiteboardLocation, 'userDataDir'> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e || e.ssh) return {}
    const appData = isInlineProjectFileId(e.id) ? appDataProjectRoot(e.id) : undefined
    if (isFolderDataRef(e)) return appData ? { projectCwd: appData, createRoot: true, readOnlyRoot: e.cwd } : {}
    const cwd = folderFileCwd(e)
    if (!cwd) return {}
    return appData ? { projectCwd: cwd, readOnlyRoot: appData } : { projectCwd: cwd }
  }

  /**
   * The root a project's board log lives under (`<root>/.nodeterm/board-log.jsonl`), or undefined
   * when it has none (ssh — routed separately — and cwd-less canvases). A folder ref's is its
   * folder, beside project.json; a folder-data-ref's is a per-project directory in userData, so the
   * log — and the cookie trace that reads it — keeps working without touching the folder.
   */
  boardLogRootForProject(projectId: string): string | undefined {
    const e = this.index?.entries.find((x) => x.id === projectId)
    return e ? settingsRootFor(e) : undefined
  }

  /** Minimal per-project target info for the setup/archive runner (project-setup-runner-local.ts's
   *  `resolveProjectSetupTarget`) — cwd/ssh/name straight off the loaded index. Sync, like
   *  `localCwdForProject`: this is what closes the Task 1 review finding that a run's rootPath/
   *  ssh/projectName must come from THIS machine's own index, never from whatever the renderer
   *  happened to send. */
  projectTargetInfo(projectId: string): { cwd?: string; ssh?: Project['ssh']; name: string } | null {
    const e = this.index?.entries.find((x) => x.id === projectId)
    return e ? { cwd: e.cwd, ssh: e.ssh, name: e.name } : null
  }

  /** Resolve the shared project together with its machine-local trust identity. The approval id
   *  never enters the shared project object or project.json. */
  async githubProject(projectId: string): Promise<{
    project: Project
    localApprovalId: string
  } | null> {
    const workspace = await this.load({ sideline: false })
    const project = workspace.projects.find((candidate) => candidate.id === projectId)
    const localApprovalId = this.index?.entries.find((entry) => entry.id === projectId)?.localApprovalId
    return project && localApprovalId ? { project, localApprovalId } : null
  }

  /** The local ref cwds of the current index — the workspace half of the phone bridge's fs/git
   *  jail. The phone browses EVERY project over `projects.list`, so jailing to only the active
   *  canvas's node cwds denied any project the desktop didn't happen to have focused. */
  localProjectCwds(): string[] {
    return (this.index?.entries ?? []).filter((e) => e.cwd).map((e) => e.cwd!)
  }

  /** Node ids of an ssh project's cached file — the slice of the agent-status mirror its host
   *  receives (see remote-status-push.ts). Empty when the project isn't an ssh entry. */
  sshProjectNodeIds(projectId: string): Set<string> {
    const e = this.index?.entries.find((x) => x.id === projectId && x.ssh)
    return new Set((e?.cache?.nodes ?? []).map((n) => n.id))
  }

  /** The SSH project id a node belongs to, or undefined for a local/inline node (deterministic
   *  approvals: a match routes the answer-file write to the REMOTE host over that project's
   *  ControlMaster; undefined ⇒ write on the LOCAL fs). Scans the ssh entries' cached node lists;
   *  a not-yet-cached remote node resolves undefined (fail-open to a local write that harmlessly
   *  never matches a remote poll). */
  sshProjectIdForNode(nodeId: string): string | undefined {
    for (const e of this.index?.entries ?? []) {
      if (!e.ssh) continue
      if ((e.cache?.nodes ?? []).some((n) => n.id === nodeId)) return e.id
    }
    return undefined
  }

  /**
   * Resolve a node's human display title (what the canvas header / sessions sidebar shows) from the
   * last-persisted workspace, across all three entry kinds: inline canvases (`e.project.nodes`), ssh
   * caches (`e.cache.nodes`), and local folder refs (the last content we wrote to their
   * `project.json`, held in `lastWritten`). Sync + in-memory (no disk read). Returns undefined when
   * the node isn't found or carries no non-empty title.
   *
   * Chosen as the mobile-push `nodeTitle` source (over the agent-status mirror) because:
   *  - the mirror's `sessionTitle` field is declared but NEVER emitted by any normalizer — recording
   *    it would record nothing;
   *  - the OS-notification title is formatted in the RENDERER and reaches main already-composed
   *    (`app:notify`), so main keeps no nodeId→title map of its own;
   *  - the persisted node title here is the exact canvas/sidebar name and is refreshed on every
   *    debounced save (which commits the ACTIVE project's live nodes first — see Canvas `persist()`),
   *    so it lags a rename only by the save debounce. Freshness caveat: a brand-new node not yet
   *    saved, or a rename inside that debounce window, resolves to undefined and the field is simply
   *    omitted — acceptable for an optional alert-title enrichment.
   */
  /**
   * The persisted node record for a node id (first project that has it), or undefined. The
   * session-name sweep needs more than the title — `accountId` (managed Claude accounts scope the
   * transcript root) and `titleAuto` (a hand-renamed node must not be overwritten). Same scan as
   * `getNodeTitle`, which now delegates here.
   */
  getNode(nodeId: string): CanvasNodeState | undefined {
    return this.findNode(nodeId)?.node
  }

  /**
   * `getNode`, with the node's cwd as the CANVAS sees it: a local ref's project.json stores node
   * cwds portable (`./sub`), and this resolves them against the project root exactly as
   * `fileToProject` / `persistedCanvases` do. For callers that hand the cwd to a resolver keyed on
   * the absolute path (the phone Chat verbs' transcript read). `getNode` keeps the stored form so
   * its existing callers are unchanged. An SSH project's node comes back ROUTED (its host, its
   * remote cwd — `routeSshProjectNode`, issue #1186), since its cache holds the neutral shared form.
   */
  getNodeResolved(nodeId: string): CanvasNodeState | undefined {
    const hit = this.findNode(nodeId)
    if (!hit) return undefined
    if (hit.ssh) return routeSshProjectNode(hit.node, hit.ssh)
    return hit.root ? resolveNodes([hit.node], hit.root)[0] : hit.node
  }

  private findNode(
    nodeId: string
  ): { node: CanvasNodeState; root?: string; ssh?: Project['ssh'] } | undefined {
    for (const e of this.index?.entries ?? []) {
      let nodes: CanvasNodeState[] | undefined
      if (e.project) nodes = e.project.nodes
      else if (e.cache) nodes = e.cache.nodes
      else if (folderFileCwd(e) && e.cwd) {
        const raw = this.lastWritten.get(projectFilePath(e.cwd))
        if (raw) {
          try {
            nodes = (JSON.parse(raw) as ProjectFileV1).nodes
          } catch {
            // Corrupt cached content: skip this entry, keep scanning the others.
          }
        }
      }
      const node = nodes?.find((n) => n.id === nodeId)
      // Only a local ref's nodes come off the shared file in portable form.
      if (node)
        return {
          node,
          root: !e.project && !e.cache && folderFileCwd(e) ? e.cwd : undefined,
          ...(!e.project && e.cache && e.ssh ? { ssh: e.ssh } : {})
        }
    }
    return undefined
  }

  /**
   * Every project that holds this node id, with the node as THAT project recorded it and the
   * project's SSH server when it is an SSH project — the relay host's attach decides where a
   * phone-opened session runs from this (core `relay-attach-plan.ts`), never from the phone's words.
   * All of them, never the first: node ids travel in git-shared project files, so the same canvas
   * opened in a local folder and over SSH holds the same ids. Local-ref cwds come back resolved.
   */
  relayNodePlacements(
    nodeId: string
  ): Array<{ projectId: string; projectServer?: SshConnection; node: CanvasNodeState }> {
    const out: Array<{ projectId: string; projectServer?: SshConnection; node: CanvasNodeState }> = []
    for (const c of this.persistedCanvases()) {
      const node = c.nodes.find((n) => n.id === nodeId)
      if (!node) continue
      const server = this.index?.entries.find((e) => e.id === c.id)?.ssh?.server
      out.push({ projectId: c.id, ...(server ? { projectServer: server } : {}), node })
    }
    return out
  }

  /**
   * EVERY project that holds this node id, in index order ([] = none) — exactly what a
   * `persistedCanvases` scan answers. All of them, never the first: node ids travel in git-shared
   * project files, so one id can sit in two projects, and the hosted team's access policy treats a
   * node as shared only when every project holding it is shared. Memoized, because a hosted-team
   * relay asks it once per access decision for every viewer (each agent:status event,
   * subagent-activity chunk, unread-clear, snapshot element, terminal frame) and a
   * `persistedCanvases()` call re-parses every local project's cached file.
   *
   * The memo is validated against the IDENTITY of every input `persistedCanvases` reads
   * (`canvasInputs`), not a version counter: a counter is only as good as the writers that remember
   * to bump it, and this class changes those inputs from a dozen places — `lastWritten.set`, index
   * reassignment, and in-place entry updates (`e.cache = …`, `e.project = …`, `e.id = …` on a
   * re-key). Every one of them replaces a reference, so a snapshot comparison sees all of them,
   * including writers added later. The snapshot goes down to the node arrays themselves
   * (`e.project.nodes`, `e.cache.nodes`) and the inline project's own id, so a writer that swaps
   * `.nodes` or re-keys `.id` on the SAME entry and project/cache object is seen too. What it cannot
   * see is an array MUTATED in place (a push into `nodes`): the rule this file keeps is that a
   * project's node array is replaced, never mutated.
   */
  projectIdsForNode(nodeId: string): readonly string[] {
    const inputs = this.canvasInputs()
    const memo = this.nodeProjectMemo
    const fresh =
      memo !== null && memo.inputs.length === inputs.length && memo.inputs.every((v, i) => v === inputs[i])
    if (fresh) return memo.map.get(nodeId) ?? NO_PROJECTS
    const map = new Map<string, string[]>()
    for (const c of this.persistedCanvases()) {
      for (const n of c.nodes) {
        const held = map.get(n.id)
        if (!held) map.set(n.id, [c.id])
        else if (!held.includes(c.id)) held.push(c.id)
      }
    }
    for (const held of map.values()) Object.freeze(held)
    this.nodeProjectMemo = { inputs, map }
    return map.get(nodeId) ?? NO_PROJECTS
  }

  /** Every input `persistedCanvases` reads, by identity: the index object, and per entry the entry,
   *  its id, its inline project with that project's id and node array, its ssh cache with its node
   *  array, its cwd and the text last written/read for that cwd's project file. A node array is
   *  compared by reference: it must be replaced, never mutated in place (see `projectIdsForNode`). */
  private canvasInputs(): unknown[] {
    const out: unknown[] = [this.index]
    for (const e of this.index?.entries ?? []) {
      out.push(
        e,
        e.id,
        e.project,
        e.project?.id,
        e.project?.nodes,
        e.cache,
        e.cache?.nodes,
        e.cwd,
        folderFileCwd(e) && e.cwd ? this.lastWritten.get(projectFilePath(e.cwd)) : undefined
      )
    }
    return out
  }

  /**
   * Every node id in every project the index holds — open, closed and SSH alike — or `undefined`
   * when that set cannot be known: the index is not loaded, a local ref's project.json has not been
   * read this run (unavailable folder, corrupt file), or an SSH entry has no offline cache.
   *
   * The agent-status mirror uses it to drop an IDENTITY-ONLY entry (a session id kept past the 6 h
   * state expiry) whose node was deleted while this process was not watching. A wrong "gone" costs
   * the phone that node's session id, so every doubt answers `undefined` — the mirror then bounds
   * the entry by its identity TTL alone. Same three-entry-kind scan as `findNode`.
   * Consequence: ONE permanently unavailable local ref or one never-cached SSH project turns
   * existence pruning off for EVERY project, leaving only the 30-day identity TTL.
   * An index rebuilt from nothing is an answer here: a wrongly pruned identity costs one hook event
   * to restore.
   * Parses through `parsedLastWritten`, so a mirror flush re-parses no unchanged project.json.
   */
  knownNodeIds(): Set<string> | undefined {
    if (!this.index) return undefined
    const ids = new Set<string>()
    for (const e of this.index.entries) {
      let nodes: CanvasNodeState[] | undefined
      if (e.project) nodes = e.project.nodes
      else if (e.cache) nodes = e.cache.nodes
      else if (folderFileCwd(e) && e.cwd) {
        try {
          nodes = this.parsedLastWritten(projectFilePath(e.cwd))?.nodes
        } catch {
          return undefined
        }
      }
      if (!Array.isArray(nodes)) return undefined
      for (const n of nodes) if (n && typeof n.id === 'string') ids.add(n.id)
    }
    return ids
  }

  /**
   * Every persisted canvas as {id, nodes, bridges} — the raw material the Server Edition derives
   * its context-link map from (src/server/context-link.ts). Same three-entry-kind scan as
   * `getNode`, but whole projects rather than one node, because a link edge only means anything
   * alongside the nodes it joins.
   *
   * Sync + in-memory: it reads the loaded index and the last content written to each local ref's
   * project.json, so a project whose file has never been read this run is simply absent (it
   * appears after the next load/save, which is also what re-derives the map).
   */
  // `bridges` and `ropes` go through `sanitizeLinks` on all three legs: the index entry and the
  // last-written file are the raw, hand-editable JSON (not the admitted project), and the
  // context-link map built from this (`buildBackgroundLinkMaps`) iterates every entry — as does the
  // station-failure notice's recipient rule (`stationRecipient`), which reads the ropes.
  persistedCanvases(): Array<{
    id: string
    nodes: CanvasNodeState[]
    bridges?: BridgeLink[]
    ropes?: BridgeLink[]
  }> {
    const out: Array<{
      id: string
      nodes: CanvasNodeState[]
      bridges?: BridgeLink[]
      ropes?: BridgeLink[]
    }> = []
    for (const e of this.index?.entries ?? []) {
      if (e.project) {
        out.push({
          id: e.project.id,
          nodes: e.project.nodes,
          bridges: sanitizeLinks(e.project.bridges),
          ropes: sanitizeLinks(e.project.ropes)
        })
      } else if (e.cache) {
        out.push({
          id: e.id,
          // Routed exactly as `fileToProject` routes them (issue #1186): the cache is the shared
          // file's neutral form, and callers decide where a node runs from what this returns.
          nodes: routeSshProjectNodes(e.cache.nodes, e.ssh),
          bridges: sanitizeLinks(e.cache.bridges),
          ropes: sanitizeLinks(e.cache.ropes)
        })
      } else if (folderFileCwd(e) && e.cwd) {
        const raw = this.lastWritten.get(projectFilePath(e.cwd))
        if (!raw) continue
        try {
          const f = JSON.parse(raw) as ProjectFileV1
          // Node cwds are stored portable ("./sub"); resolve them the way `fileToProject` does, so
          // a caller sees the same absolute paths the desktop's renderer would have handed it.
          // Keyed by the ENTRY id — the map's consumers look projects up by the id the renderer
          // knows, which is never the git-shared file's (it no longer has one).
          out.push({
            id: e.id,
            nodes: resolveNodes(f.nodes, e.cwd),
            bridges: sanitizeLinks(f.bridges),
            ropes: sanitizeLinks(f.ropes)
          })
        } catch {
          // Corrupt cached content: skip this entry, keep scanning the others.
        }
      }
    }
    return out
  }

  /**
   * Does THIS machine hold an undelivered launch (`pendingLaunch`) for `nodeId` in `projectId`?
   * Read from the entry's machine-local exec overlay (`localExec`, where every ref kind keeps it),
   * with the entry's own node copy as a fallback. Same id semantics as `persistedCanvases`. Agent
   * messaging asks it to tell a node that has not STARTED yet from one whose pane is unproven.
   */
  heldLaunch(projectId: string, nodeId: string): boolean {
    for (const e of this.index?.entries ?? []) {
      if ((e.project ? e.project.id : e.id) !== projectId) continue
      if (e.localExec?.[nodeId]?.pendingLaunch) return true
      const nodes = e.project?.nodes ?? e.cache?.nodes ?? []
      return nodes.some((n) => n.id === nodeId && !!n.pendingLaunch)
    }
    return false
  }

  /**
   * Does this project exist on THIS machine, and is it SSH? The `--project` targeting gate
   * (issue #338, src/core/project-grants.ts) asks the core store — never the request — before
   * any targeted open is forwarded. Same three-entry-kind scan and same id semantics as
   * `persistedCanvases` (inline keyed by `e.project.id`, ssh/local refs by `e.id`), because the
   * projectId a grant names there must resolve to the same project here. `undefined` = unknown
   * to this store (deleted, invented, another machine's) — the gate fails closed on it.
   */
  projectMetaFor(projectId: string): { ssh: boolean } | undefined {
    if (!projectId) return undefined
    for (const e of this.index?.entries ?? []) {
      if (e.project) {
        if (e.project.id === projectId) return { ssh: !!e.project.ssh }
        continue
      }
      if (e.id === projectId) return { ssh: !!e.ssh }
    }
    return undefined
  }

  /**
   * The capability view of one project, for `projectCapabilityGrantedFor`: the STRICT capability
   * flags from the shared file (`readProjectCapabilities` — literal `true`, known keys only) plus
   * this machine's recorded answers from the INDEX ENTRY. Same three-entry-kind scan and same id
   * semantics as `persistedCanvases`, because the projectId a delivery resolved there must look up
   * the same project here.
   *
   * The ack deliberately never comes from the parsed file: a repo hand-carrying `capabilityAck`
   * is a forgery attempt (workspace-files.ts says the same at the fileToProject boundary), and
   * `agent-messaging-switch.test.ts` drives that exact file through a real store. An inline entry
   * stores the Project verbatim (ack included — splitWorkspace gives it no localState), so there
   * the project object IS the entry-local record.
   */
  capabilityProjectFor(
    projectId: string
  ): (Partial<Record<ProjectCapability, boolean>> & { capabilityAck?: CapabilityAckMap }) | undefined {
    for (const e of this.index?.entries ?? []) {
      if (e.project) {
        if (e.project.id !== projectId) continue
        return {
          ...readProjectCapabilities(e.project),
          ...(e.project.capabilityAck ? { capabilityAck: e.project.capabilityAck } : {})
        }
      }
      if (e.id !== projectId) continue
      const ack = e.capabilityAck ? { capabilityAck: e.capabilityAck } : {}
      if (e.cache) return { ...readProjectCapabilities(e.cache), ...ack }
      if (folderFileCwd(e) && e.cwd) {
        const raw = this.lastWritten.get(projectFilePath(e.cwd))
        if (!raw) return { ...ack } // file never read this run: no flag known, so nothing grants
        try {
          return { ...readProjectCapabilities(JSON.parse(raw)), ...ack }
        } catch {
          return { ...ack } // corrupt file: fail closed, like every other reader of this cache
        }
      }
      return undefined
    }
    return undefined
  }

  getNodeTitle(nodeId: string): string | undefined {
    for (const e of this.index?.entries ?? []) {
      let nodes: CanvasNodeState[] | undefined
      if (e.project) nodes = e.project.nodes
      else if (e.cache) nodes = e.cache.nodes
      else if (folderFileCwd(e) && e.cwd) {
        const raw = this.lastWritten.get(projectFilePath(e.cwd))
        if (raw) {
          try {
            nodes = (JSON.parse(raw) as ProjectFileV1).nodes
          } catch {
            // Corrupt cached content: skip this entry, keep scanning the others.
          }
        }
      }
      const node = nodes?.find((n) => n.id === nodeId)
      if (node) {
        const title = node.title?.trim()
        return title ? title : undefined
      }
    }
    return undefined
  }

  /** A throttled trailing mirror write was acked but later dropped (connection died inside the
   *  throttle window): re-owe it so the next save retries. Wired from makeRemoteWorkspaceIO. */
  markUnmirrored(projectId: string): void {
    this.unmirrored.add(projectId)
  }

  /** Remembers a project.json payload handed to `remoteIO.write` (see `recentMirrorHashes`).
   *  Called only on an acked write: an ack may be optimistic (the throttle's trailing write), but
   *  a read can only ever return these bytes if they actually landed — so a dropped trailing
   *  write leaves a harmless unused hash, never a false echo. */
  private recordMirrored(projectId: string, content: string): void {
    const hashes = this.recentMirrorHashes.get(projectId) ?? []
    hashes.push(contentHash(content))
    while (hashes.length > RECENT_MIRROR_CAP) hashes.shift()
    this.recentMirrorHashes.set(projectId, hashes)
  }

  /** True when `content` is byte-identical to a payload this store recently mirrored — a
   *  self-write echo, never an external change. Exact bytes only: any other writer's edit
   *  (a phone append, another machine's save with its own savedAt) hashes differently. */
  private isOwnMirrorContent(projectId: string, content: string): boolean {
    return this.recentMirrorHashes.get(projectId)?.includes(contentHash(content)) ?? false
  }

  /**
   * Registers a PHONE-STARTED session as a node in a LOCAL ref project's file — the host side of
   * the relay `projects.registerNode` verb. v1 scope: local-cwd projects only (an ssh ref's file
   * lives on another machine; the phone reaches that one over its own SSH path).
   *
   * The renderer must adopt the node onto the live canvas, so the change IS announced — but
   * explicitly, via workspaceExternalChange, not by leaving `lastWritten` stale so the watcher
   * fires. That side channel only worked while every self-write matched byte-for-byte, and it made
   * an OUR-write indistinguishable from a teammate's; the store's own caches (getNode,
   * persistedCanvases) were left holding a file they knew was outdated. Record the write like any
   * other and send the notification ourselves.
   *
   * It runs ON `saveChain`, like save(): this is a read-modify-write of the SAME project.json a save
   * rewrites whole, and off the chain the two interleave — the phone registers its node, an autosave
   * that read the file first lands last, and the node the phone was told about ("true", card shown)
   * never existed. Queued, the append reads what the save just wrote and the save cannot un-write it.
   */
  appendRemoteNode(
    projectId: string,
    input: RemoteNodeInput,
    now = new Date(),
    accountColor?: string
  ): Promise<boolean> {
    const run = this.saveChain.then(() =>
      this.appendRemoteNodeNow(projectId, input, now, accountColor)
    )
    this.saveChain = run.catch(() => {})
    return run
  }

  private async appendRemoteNodeNow(
    projectId: string,
    input: RemoteNodeInput,
    now: Date,
    accountColor?: string
  ): Promise<boolean> {
    const data = this.index?.entries.find((x) => x.id === projectId && isFolderDataRef(x))
    if (data) {
      return (await this.transformDataFile(data, (raw) => appendProjectNode(raw, input, now, accountColor)))
        ?.written ?? false
    }
    const e = this.index?.entries.find((x) => x.id === projectId && folderFileCwd(x))
    if (!e?.cwd) return false
    const file = projectFilePath(e.cwd)
    let raw: string
    try {
      raw = await fs.readFile(file, 'utf-8')
    } catch {
      return false
    }
    const updated = appendProjectNode(raw, input, now, accountColor)
    if (updated === null) return false
    try {
      await writeAtomic(file, updated)
    } catch {
      return false
    }
    this.lastWritten.set(file, updated)
    // appendProjectNode only returns a string it produced from a valid ProjectFileV1, so this parse
    // cannot realistically fail — but a throw here would turn a landed write into a `false`.
    try {
      const parsed = JSON.parse(updated) as ProjectFileV1
      this.revs.set(e.id, parsed.rev)
      platform().broadcast(
        IPC.workspaceExternalChange,
        fileToProject(parsed, {
          id: e.id,
          cwd: e.cwd,
          closed: e.closed,
          closedAt: e.closedAt,
          handedOffTo: e.handedOffTo,
          viewport: e.viewport,
          defaultAccountId: e.defaultAccountId,
          breadcrumbs: e.breadcrumbs,
          closedSessions: e.closedSessions,
          layoutViewports: e.layoutViewports,
          capabilityAck: e.capabilityAck,
          localExec: e.localExec
        })
      )
    } catch { /* the file is written and cached; the next load/poll surfaces the node */ }
    return true
  }

  /**
   * Takes a DESTROYED session's node off its project's canvas — the host side of the relay
   * `pty.destroy` verb ("End session" on the phone), run AFTER the tmux kill so the file only ever
   * loses a node whose session is already gone. Node ids are globally unique (they are tmux
   * session names), so the node is looked up by SCAN across the local ref projects — the phone
   * addresses sessions by streamId→nodeId and knows no projectId. Same v1 scope and the same
   * announce-and-record discipline as `appendRemoteNode` above, and queued on `saveChain` for the
   * same read-modify-write reason. A node found in NO file is an answer (an unregistered phone
   * session, an inline project), not an error: the caller treats false as "nothing to remove".
   */
  removeRemoteNode(nodeId: string, now = new Date()): Promise<boolean> {
    const run = this.saveChain.then(() => this.removeRemoteNodeNow(nodeId, now))
    this.saveChain = run.catch(() => {})
    return run
  }

  private async removeRemoteNodeNow(nodeId: string, now: Date): Promise<boolean> {
    for (const e of this.index?.entries ?? []) {
      // Local ref projects only, like appendRemoteNode: an ssh ref's file lives on another
      // machine (and a relay `pty.attach` only ever reaches THIS machine's tmux anyway).
      if (isFolderDataRef(e)) {
        if (!e.project?.nodes.some((n) => n.id === nodeId)) continue
        const done = await this.transformDataFile(e, (raw) => removeProjectNode(raw, nodeId, now))
        if (done?.written) return true
        if (!done) return false
        continue
      }
      if (!folderFileCwd(e) || !e.cwd || e.ssh) continue
      const file = projectFilePath(e.cwd)
      let raw: string
      try {
        raw = await fs.readFile(file, 'utf-8')
      } catch {
        continue
      }
      const updated = removeProjectNode(raw, nodeId, now)
      if (updated === null) continue // not in this project (or unreadable file) — keep looking
      try {
        await writeAtomic(file, updated)
      } catch {
        return false
      }
      this.lastWritten.set(file, updated)
      try {
        const parsed = JSON.parse(updated) as ProjectFileV1
        this.revs.set(e.id, parsed.rev)
        platform().broadcast(
          IPC.workspaceExternalChange,
          fileToProject(parsed, {
            id: e.id,
            cwd: e.cwd,
            closed: e.closed,
            closedAt: e.closedAt,
            handedOffTo: e.handedOffTo,
            viewport: e.viewport,
            defaultAccountId: e.defaultAccountId,
            breadcrumbs: e.breadcrumbs,
            closedSessions: e.closedSessions,
            layoutViewports: e.layoutViewports,
            capabilityAck: e.capabilityAck,
            localExec: e.localExec
          })
        )
      } catch { /* the file is written and cached; the next load/poll drops the node */ }
      return true
    }
    return false
  }

  /**
   * Give a project a kanban board if it has none — the host side of the relay
   * `projects.ensureBoard` verb, i.e. the phone tapping "Board" on a project that has never had
   * one. Returns the board's columns (the ones it just seeded, or the ones already there), or null
   * when this project cannot have a board written at all.
   *
   * **Why the phone needs a verb for this at all.** The desktop's board is a LAZY default: the
   * canvas renders `kanban ?? defaultKanban(projectId)` and the `kanban` block is not written to
   * the file until the user's first board edit. So on a fresh project the columns exist only in the
   * renderer's memory — and the phone, which knows a project solely by its `.nodeterm/project.json`,
   * saw a project with no board and could not offer one. (Measured on the author's own machine:
   * 1 of 13 project files had a `kanban` block.) Seeding the SAME three columns from the SAME
   * shared definition (`@shared/kanban-default-board`) is what makes a board created on the phone
   * and a board created on the desktop the same board.
   *
   * IDEMPOTENT, and that is the safety property: an existing board is returned untouched and
   * nothing is written, so the phone may ask on every tap.
   */
  ensureRemoteBoard(projectId: string, now = new Date()): Promise<KanbanColumn[] | null> {
    const run = this.saveChain.then(() =>
      this.kanbanWriteNow(projectId, (raw) => ensureProjectBoard(raw, now))
    )
    this.saveChain = run.catch(() => {})
    // The board that is THERE NOW, whether this call seeded it or found it. `ensureProjectBoard`
    // returns null for BOTH "already has one" and "this board is not a shape I may replace", so the
    // answer comes off the file rather than off whether a write happened — a project with a
    // board is a project with a board, and the phone asks this on every Board tap.
    return run.then((res) => (res ? (res.file.kanban?.columns ?? null) : null))
  }

  /**
   * Move one session card to a board column (`columnId: null` = the virtual Ungrouped column) — the
   * host side of the relay `projects.setCardColumn` verb.
   *
   * The phone has been able to do this over DIRECT SSH since the board shipped, by rewriting the
   * whole project.json itself. That path has two holes this verb closes: it cannot reach an SSH
   * project (whose file lives on a third machine), and it carries the entire file in one argv
   * string, so it stops working — silently — once the file passes Linux's 128 KB `MAX_ARG_STRLEN`
   * (the author's own `nodeterm` project file measured 114,695 bytes, ~15 KB under the ceiling).
   * Over this verb the phone sends `{projectId, nodeId, columnId}` and the size of the canvas is
   * irrelevant.
   *
   * False = nothing was written, and the caller says so out loud rather than pretending: the
   * project is unknown or has no writable file, the file is not the shape we know, the column does
   * not exist on this board, or the card is already there (a retry — see `setProjectCardColumn`).
   */
  setRemoteCardColumn(
    projectId: string,
    nodeId: string,
    columnId: string | null,
    now = new Date()
  ): Promise<boolean> {
    const run = this.saveChain.then(() =>
      this.kanbanWriteNow(projectId, (raw) => setProjectCardColumn(raw, nodeId, columnId, now))
    )
    this.saveChain = run.catch(() => {})
    return run.then((res) => res?.written === true)
  }

  /**
   * Add / remove / create board labels on one session card — the host side of the relay
   * `projects.editCardLabels` verb, i.e. the phone's long-press label sheet.
   *
   * There is ONE label model (the per-project palette in `kanban.labels` + per-card ids in
   * `kanban.meta[].labels`, the same one the canvas node's "+ Label" row and the kanban card edit),
   * and this writes into it through the same shared transforms and the same `kanbanWriteNow`
   * read-modify-write as `setRemoteCardColumn` — so the change is announced to the renderer and the
   * canvas node + kanban card adopt it live, local and SSH projects alike.
   *
   * Answers the palette and this card's label ids AS THEY NOW STAND, whether or not this call
   * changed them (`edited` says which): a refused `add` (the phone's palette is stale) comes back as
   * `edited: false` with the current palette, so the sheet can redraw instead of guessing. Null =
   * the project is unknown or has no readable project file.
   */
  editRemoteCardLabels(
    projectId: string,
    nodeId: string,
    edit: CardLabelEdit,
    now = new Date()
  ): Promise<{ edited: boolean; labels: KanbanLabel[]; cardLabelIds: string[] } | null> {
    const run = this.saveChain.then(() =>
      this.kanbanWriteNow(projectId, (raw) => editProjectCardLabels(raw, nodeId, edit, now))
    )
    this.saveChain = run.catch(() => {})
    return run.then((res) => {
      if (!res) return null
      const k = res.file.kanban
      if (!k || typeof k !== 'object') return { edited: res.written, labels: [], cardLabelIds: [] }
      const labels = boardLabels(k)
      const known = new Set(labels.map((l) => l.id))
      const ids = cardMeta(k, nodeId)?.labels
      return {
        edited: res.written,
        labels,
        // Dangling ids (a label deleted elsewhere) are dropped exactly as every desktop reader drops them.
        cardLabelIds: Array.isArray(ids) ? ids.filter((id) => known.has(id)) : []
      }
    })
  }

  /**
   * The one read-modify-write behind every kanban verb, for BOTH kinds of ref project.
   *
   * Queued on `saveChain` by its callers for the same reason `appendRemoteNode` is: this rewrites
   * the very file a save rewrites whole, and off the chain a save that read the file first lands
   * last and un-writes the move the phone was told had landed.
   *
   * - **local ref** (`cwd`): read the file, transform, write it atomically — exactly
   *   `appendRemoteNodeNow`'s shape, including recording the write in `lastWritten` and announcing
   *   it on `workspaceExternalChange` rather than letting the watcher discover our own edit.
   * - **ssh ref** (`ssh` + `cache`): the file is on ANOTHER machine and only this desktop writes
   *   it. So the write goes where the desktop's own board edits go — into `e.cache` — and is then
   *   pushed by the ordinary mirror (`mirrorSshCache`, which re-reads and rescues the server's own
   *   node additions first). This is why extending the phone's reach to SSH projects does not need
   *   any new reconciliation: `reconcileSsh` decides between cache and server by `rev` and unions
   *   only `nodes`, and this produces exactly the cache-side, rev-bumped change a desktop card drag
   *   produces. What it must NOT skip is the broadcast: the renderer holds its own copy of the
   *   board and the next whole-workspace save serializes THAT, so a change the renderer never heard
   *   about is a change the next autosave reverts.
   *
   * Returns null when there was no readable project file to work on at all. Otherwise it returns
   * the file as it now stands together with whether this call CHANGED it — the two are different
   * answers and both callers need the difference: a refused move is `written: false` (the phone
   * says so out loud), while a board that was already there is `written: false` with the board
   * right there in `file` (nothing to do, and the honest answer is the board).
   */
  private async kanbanWriteNow(
    projectId: string,
    transform: (raw: string) => string | null
  ): Promise<{ file: ProjectFileV1; written: boolean } | null> {
    const e = this.index?.entries.find((x) => x.id === projectId)
    if (!e) return null

    if (e.ssh && e.cache) {
      // Handed to a hosted team: the server core is the only writer of this file now. Refused
      // BEFORE the transform, so the local cache never diverges and the renderer is never told
      // about a change that will not land.
      if (e.handedOffTo) return null
      const updated = transform(serializeProjectFile(e.cache))
      if (updated === null) return { file: e.cache, written: false }
      let parsed: ProjectFileV1
      try {
        parsed = JSON.parse(updated) as ProjectFileV1
      } catch {
        return { file: e.cache, written: false }
      }
      e.cache = parsed
      this.revs.set(e.id, parsed.rev)
      // Owed BEFORE the push, so a mirror that fails (the host is asleep, the dial flaps) is
      // retried by the next save instead of being lost with the answer already given.
      this.unmirrored.add(e.id)
      // The ssh cache IS the local copy of that file — it lives in workspace.json, not on this
      // machine's disk as a project.json — so an unpersisted cache change is one an app restart
      // loses even though the server already has it. (The local branch below needs no equivalent:
      // its project.json is the record.)
      await this.writeIndexNow().catch(() => {})
      this.announceProjectFile(e, parsed)
      await this.mirrorSshCache(e)
      return { file: parsed, written: true }
    }

    if (isFolderDataRef(e)) return this.transformDataFile(e, transform)
    if (!folderFileCwd(e) || !e.cwd) return null
    const file = projectFilePath(e.cwd)
    let raw: string
    try {
      raw = await fs.readFile(file, 'utf-8')
    } catch {
      return null
    }
    const current = (): { file: ProjectFileV1; written: boolean } | null => {
      try {
        return { file: JSON.parse(raw) as ProjectFileV1, written: false }
      } catch {
        return null // unparsable: there is no board to report and none was written
      }
    }
    const updated = transform(raw)
    if (updated === null) return current()
    try {
      await writeAtomic(file, updated)
    } catch {
      return current()
    }
    this.lastWritten.set(file, updated)
    let parsed: ProjectFileV1
    try {
      parsed = JSON.parse(updated) as ProjectFileV1
    } catch {
      // The transforms only ever return a string they serialized themselves, so this cannot
      // realistically happen — but the write DID land, and reporting it as a failure would have
      // the phone tell the user their move was refused while the file says otherwise.
      return { file: { version: 1, rev: 0, savedAt: '', name: e.name, color: e.color, nodes: [] }, written: true }
    }
    this.revs.set(e.id, parsed.rev)
    this.announceProjectFile(e, parsed)
    return { file: parsed, written: true }
  }

  /**
   * The phone writers' leg for a FOLDER-DATA-REF (issue #1145): the same read-transform-write the
   * folder leg does on `<cwd>/.nodeterm/project.json`, on the project's data file instead — so a
   * session registered or ended from the phone, or a board move, lands in app data and never
   * recreates the folder file. Three differences, each because this file is the inline kind:
   *  - the write goes through `writeDataFile`, under its rev rule (a second instance may share it);
   *  - node cwds are absolute here, so a portable one the transform produced (the append copies a
   *    sibling's, or defaults to '.') is resolved against the project's folder before it lands;
   *  - the index `project` cache is put in step, since the sync readers consult it first.
   * Null when the entry is not this kind or the file could not be written.
   */
  private async transformDataFile(
    e: IndexEntryV3,
    transform: (raw: string) => string | null
  ): Promise<{ file: ProjectFileV1; written: boolean } | null> {
    if (!isFolderDataRef(e) || !e.cwd || !isInlineProjectFileId(e.id)) return null
    const read = await this.readDataFile(e.id, false)
    if (!read) return null
    const updated = transform(read.raw)
    if (updated === null) return { file: read.file, written: false }
    let parsed: ProjectFileV1
    try {
      parsed = JSON.parse(updated) as ProjectFileV1
    } catch {
      return { file: read.file, written: false }
    }
    const candidate = { ...parsed, nodes: resolveNodes(parsed.nodes, e.cwd) }
    const landed = await this.writeDataFile(e.id, candidate)
    if (landed !== 'written' && landed !== 'unchanged') return null
    const file = this.parsedLastWritten(inlineFilePath(e.id)) ?? candidate
    const project = fileToProject(file, {
      id: e.id,
      closed: e.closed,
      closedAt: e.closedAt,
      handedOffTo: e.handedOffTo,
      viewport: e.viewport,
      defaultAccountId: e.defaultAccountId,
      breadcrumbs: e.breadcrumbs,
      closedSessions: e.closedSessions,
      layoutViewports: e.layoutViewports,
      capabilityAck: e.capabilityAck,
      localExec: e.localExec
    })
    e.project = project
    // The data file is the record and wins at load, so a cache write that fails costs nothing lasting.
    await this.writeIndexNow().catch(() => {})
    platform().broadcast(IPC.workspaceExternalChange, { ...project, cwd: e.cwd, storeInAppData: true })
    return { file, written: true }
  }

  /** Tell the renderer about a project file THIS store just rewrote outside of `save()`. Shared by
   *  the kanban verbs; the same payload `appendRemoteNode`/`removeRemoteNode` build by hand. */
  private announceProjectFile(e: IndexEntryV3, file: ProjectFileV1): void {
    try {
      platform().broadcast(
        IPC.workspaceExternalChange,
        fileToProject(file, {
          id: e.id,
          cwd: e.cwd,
          ssh: e.ssh,
          closed: e.closed,
          closedAt: e.closedAt,
          handedOffTo: e.handedOffTo,
          viewport: e.viewport,
          defaultAccountId: e.defaultAccountId,
          breadcrumbs: e.breadcrumbs,
          closedSessions: e.closedSessions,
          capabilityAck: e.capabilityAck,
          localExec: e.localExec
        })
      )
    } catch { /* the file is written and cached; the next load/poll surfaces the change */ }
  }

  /**
   * The mirror write for one ssh entry, with the server's own additions rescued first.
   *
   * Never write the server file without looking at it: between two of our saves the OTHER writer of
   * this same file (the mobile companion, appending a session it just started) may have added a node
   * that exists nowhere else. Serializing our cache over it is a silent, permanent delete of a live
   * session — the canvas node is gone on both machines while the tmux session keeps running.
   */
  private async mirrorSshCache(e: IndexEntryV3): Promise<void> {
    // Handed to a hosted team: the server core is the only writer now. Together with
    // `reconcileSsh`'s guard this covers every `remoteIO.write`, whatever the caller checked.
    if (e.handedOffTo) return
    if (!e.ssh || !e.cache || !this.remoteIO) return
    const rescued = await this.rescueRemoteNodes(e)
    // AFTER the rescue: it replaces e.cache with the merged copy, which is what must land.
    const content = serializeProjectFile(e.cache)
    const ok = await this.remoteIO.write(e.id, e.ssh, content)
    if (ok) {
      this.recordMirrored(e.id, content)
      this.unmirrored.delete(e.id)
      // The tombstones deliberately SURVIVE this ack — see `confirmClearedDeletions`. An ack is not
      // evidence that the server holds our deletions; only a read that no longer lists them is.
    } else {
      this.unmirrored.add(e.id)
    }
    // A rescued node is live on the server and missing from the live canvas: say so now, the same
    // way the reconcile path does, instead of leaving the user to wait for the next poll.
    if (rescued) platform().broadcast(IPC.workspaceExternalChange, rescued)
  }

  /**
   * Reads the server file and unions in the session nodes it has that our cache lacks. Returns the
   * merged project to announce, or null when nothing moved — which includes every case where the
   * read could not answer (error, absent, corrupt) and the DIFFERENT-lineage case: a failed read is
   * never evidence of absence, so it changes nothing and the caller writes exactly what it would
   * have written before. Which lineage wins is `reconcileSsh`'s call alone; merging a stranger's
   * nodes into our canvas would not be a rescue.
   */
  private async rescueRemoteNodes(e: IndexEntryV3): Promise<Project | null> {
    if (!e.ssh || !e.cache || !this.remoteIO) return null
    const res = await this.remoteIO.read(e.id, e.ssh)
    if (res.status !== 'ok') return null
    let remote: ProjectFileV1 | null = null
    try {
      const parsed = JSON.parse(res.content) as ProjectFileV1
      if (parsed?.version === 1 && Array.isArray(parsed.nodes)) remote = parsed
    } catch { /* corrupt server file — our cache is the only readable copy; it is written as-is */ }
    if (!remote || remote.id !== e.cache.id) return null
    this.confirmClearedDeletions(e.id, remote.nodes)
    const rescued = this.rescuableNodes(e.id, e.cache.nodes, remote.nodes)
    if (!rescued.length) return null
    // The merged set must outrank both sides, or the next reconcile could rev-decide it away.
    e.cache = {
      ...e.cache,
      nodes: [...e.cache.nodes, ...rescued],
      rev: Math.max(e.cache.rev, remote.rev) + 1
    }
    this.revs.set(e.id, e.cache.rev)
    return fileToProject(e.cache, {
      id: e.id, ssh: e.ssh, closed: e.closed, closedAt: e.closedAt, handedOffTo: e.handedOffTo,
      viewport: e.viewport, defaultAccountId: e.defaultAccountId, breadcrumbs: e.breadcrumbs,
      closedSessions: e.closedSessions, layoutViewports: e.layoutViewports,
      capabilityAck: e.capabilityAck, localExec: e.localExec
    })
  }

  /** The remote-only nodes worth rescuing: on the server, absent from `ours`, and NOT among the ones
   *  we deliberately deleted (see `clearedNodes` — those must propagate, not resurrect). */
  private rescuableNodes(
    projectId: string,
    ours: CanvasNodeState[],
    theirs: CanvasNodeState[]
  ): CanvasNodeState[] {
    const cleared = this.clearedNodes.get(projectId)
    const missing = nodesMissingFrom(ours, theirs)
    return cleared ? missing.filter((n) => !cleared.has(n.id)) : missing
  }

  /**
   * Retire the tombstones the SERVER has confirmed: ids `clearedNodes` holds that the file we just
   * read no longer lists. Our deletion has travelled, so the record has done its job — and the id
   * becomes an ordinary unknown one again, so a later re-appearance (another machine restored the
   * node, a git checkout) is rescued like any other foreign addition.
   *
   * This — plus an adopt, which overrules our deletions outright — is the ONLY thing that retires a
   * tombstone. It used to be the mirror write's ACK, and that was the 2026-09-06 field bug: the real
   * remote IO acks the 5 s throttle's TRAILING write optimistically, before it is on the wire (see
   * `recordMirrored`). When the connection died inside that window the write was dropped,
   * `markUnmirrored` re-owed the mirror but had nothing with which to restore the tombstones, and the
   * retry's re-read found all 16 just-deleted nodes still on the server with no filter left — so it
   * "rescued" every one of them back onto the canvas and announced them as sessions from another
   * device. An ack is a claim about a write; a tombstone is a claim about the server's CONTENT, and
   * only a read can settle that. Same rule the reconciler already lives by ("a failed read is never
   * evidence of absence") applied to the other direction.
   *
   * It costs no extra round-trip: both call sites are reads the store already makes.
   */
  private confirmClearedDeletions(projectId: string, remoteNodes: CanvasNodeState[]): void {
    const cleared = this.clearedNodes.get(projectId)
    if (!cleared) return
    const onServer = new Set(remoteNodes.map((n) => n.id))
    for (const id of cleared) if (!onServer.has(id)) cleared.delete(id)
    if (!cleared.size) this.clearedNodes.delete(projectId)
  }

  /** Record the nodes a save removed from an ssh cache (see `clearedNodes`). */
  private recordLocalDeletions(
    projectId: string,
    before: CanvasNodeState[] | undefined,
    after: CanvasNodeState[]
  ): void {
    if (!before?.length) return
    const kept = new Set(after.map((n) => n.id))
    const gone = before.filter((n) => !kept.has(n.id))
    if (!gone.length) return
    const cleared = this.clearedNodes.get(projectId) ?? new Set<string>()
    for (const n of gone) cleared.add(n.id)
    this.clearedNodes.set(projectId, cleared)
  }

  /**
   * The ONE place that decides who wins between an ssh entry's cache and the server's
   * .nodeterm/project.json. Rules, in order:
   * - read ERROR → decide nothing (a failed read is never evidence of absence): stay
   *   un-reconciled, mirror stays owed, no write.
   * - the server holds bytes THIS store recently mirrored (`recentMirrorHashes`) → a self-write
   *   echo, not an external change: the cache stands, nothing is adopted or merged, nothing is
   *   broadcast (no conflict bar); an owed mirror still pushes.
   * - absent/corrupt remote → push our cache up.
   * - same lineage (ids match): higher remote rev wins (rev is this file's save counter) —
   *   including an emptier remote (the user really cleared their canvas elsewhere).
   * - DIFFERENT lineage (the server file belongs to another project id — a re-added folder, a
   *   second machine, a git checkout): an empty side never beats a populated one, regardless of
   *   rev. Adoption re-keys the file to OUR entry id (node ids — tmux session names — are kept,
   *   so the terminals reattach); a push outbids the losing lineage's rev so it stays beaten.
   * Returns the adopted project (for the caller to surface) or null when our cache stood/pushed.
   */
  private async reconcileSsh(e: IndexEntryV3, pushIfStanding = true): Promise<Project | null> {
    if (e.handedOffTo) return null // handed to a hosted team: the server core is the only writer now
    if (!e.ssh || !this.remoteIO) return null
    const res = await this.remoteIO.read(e.id, e.ssh)
    if (res.status === 'error') {
      this.unmirrored.add(e.id)
      return null
    }
    let remote: ProjectFileV1 | null = null
    if (res.status === 'ok') {
      try {
        const parsed = JSON.parse(res.content) as ProjectFileV1
        if (parsed?.version === 1 && Array.isArray(parsed.nodes)) remote = parsed
      } catch { /* corrupt remote file → treat as absent, our cache pushes up */ }
      // Before the self-write nulling below: an id absent from the file ON THE SERVER is confirmed
      // gone whoever wrote those bytes, and an older own write that still lists it confirms nothing.
      if (remote && e.cache && remote.id === e.cache.id) this.confirmClearedDeletions(e.id, remote.nodes)
      // Self-write echo: the server holds bytes this store itself mirrored (a poll reading right
      // behind a save's write, or an OLDER own write the 5 s throttle has not yet replaced).
      // Nothing foreign is there to adopt, merge or announce — decide exactly as if the remote
      // said nothing new: the cache stands, and an owed mirror still pushes below. Matching by
      // exact bytes keeps the genuine-external-edit path untouched (any other writer's file —
      // a phone append, another machine's save — hashes differently).
      if (remote && this.isOwnMirrorContent(e.id, res.content)) remote = null
    }
    this.reconciled.add(e.id)
    const cacheRev = e.cache?.rev ?? 0
    const cacheNodes = e.cache?.nodes.length ?? 0
    const sameLineage = !e.cache || !remote || remote.id === e.cache.id
    const remoteWins =
      remote !== null &&
      (sameLineage
        ? remote.rev > cacheRev
        : (cacheNodes === 0 && remote.nodes.length > 0) ||
          (remote.nodes.length > 0 && remote.rev > cacheRev))
    // Whichever side wins, rescue the OTHER side's session nodes it doesn't have. The two writers of a
    // same-lineage file (this desktop's throttled mirror + the mobile companion's direct append) are
    // ordered only by a single `rev` counter, and that counter DRIFTS: a dropped/forgotten final mirror
    // write or an offline edit leaves the server behind our cache, so the phone's append (rev = the
    // server file + 1) lands BELOW our cache rev and a rev-only decision silently discards it — the
    // field bug where a phone-created SSH session never reached the desktop canvas.
    //
    // The guard is same-lineage + a POPULATED REMOTE, and deliberately no longer "our cache has
    // nodes too". That half read an empty cache with a drifted rev as a deliberate clear and pushed
    // the emptiness up — but an empty desktop canvas is precisely where a phone-started session is
    // the ONLY node in the file, so it deleted the very thing this rescue exists to save. The
    // deliberate clear is now told apart by WHAT the cache is missing rather than by how much:
    // `clearedNodes` holds the ids this run removed, and `rescuableNodes` never brings those back,
    // so a real clear still travels. The remote half of the guard is untouched: an empty REMOTE with
    // a higher rev is the user clearing the canvas on another machine and still wins by rev.
    const mergeable = sameLineage && !!e.cache && !!remote && remote.nodes.length > 0
    if (remote && remoteWins) {
      let adopted = remote.id === e.id ? remote : { ...remote, id: e.id }
      let owed = false
      if (mergeable) {
        const rescued = nodesMissingFrom(adopted.nodes, e.cache!.nodes) // our local-only additions
        if (rescued.length) {
          adopted = { ...adopted, nodes: [...adopted.nodes, ...rescued], rev: Math.max(adopted.rev, cacheRev) + 1 }
          owed = true // the server file lacks the merged-in nodes → owe a mirror write
        }
      }
      e.cache = adopted
      e.name = adopted.name
      e.color = adopted.color
      this.revs.set(e.id, adopted.rev)
      // The remote won on rev, so its content — including anything we had deleted — is the truth
      // now: our pending deletions are settled (overruled) and must not haunt a later rescue.
      this.clearedNodes.delete(e.id)
      if (owed) this.unmirrored.add(e.id)
      else this.unmirrored.delete(e.id) // pure adopt: the server copy IS the truth now — nothing owed
      return fileToProject(adopted, {
        id: e.id, ssh: e.ssh, closed: e.closed, closedAt: e.closedAt, handedOffTo: e.handedOffTo,
        viewport: e.viewport, defaultAccountId: e.defaultAccountId, breadcrumbs: e.breadcrumbs,
        closedSessions: e.closedSessions, layoutViewports: e.layoutViewports,
        capabilityAck: e.capabilityAck, localExec: e.localExec
      })
    }
    // Our cache stood. Before it clobbers the server, merge in any remote-only session nodes (the
    // phone's drifted append) so the push carries them instead of erasing them.
    let merged: Project | null = null
    if (mergeable && e.cache && remote) {
      const rescued = this.rescuableNodes(e.id, e.cache.nodes, remote.nodes)
      if (rescued.length) {
        e.cache = { ...e.cache, nodes: [...e.cache.nodes, ...rescued], rev: Math.max(cacheRev, remote.rev) + 1 }
        this.revs.set(e.id, e.cache.rev)
        this.unmirrored.add(e.id) // the merged set must land on the server
        merged = fileToProject(e.cache, {
          id: e.id, ssh: e.ssh, closed: e.closed, closedAt: e.closedAt, handedOffTo: e.handedOffTo,
          viewport: e.viewport, defaultAccountId: e.defaultAccountId, breadcrumbs: e.breadcrumbs,
          closedSessions: e.closedSessions, layoutViewports: e.layoutViewports,
          capabilityAck: e.capabilityAck, localExec: e.localExec
        })
      }
    }
    if (e.cache && (pushIfStanding || this.unmirrored.has(e.id))) {
      // Our cache stood. If it just beat a FOREIGN lineage on the merits (not on rev), outbid that
      // lineage's rev so a later rev-only reconcile can't resurrect the losing side.
      if (remote && !sameLineage && remote.rev >= e.cache.rev) {
        e.cache.rev = remote.rev + 1
        this.revs.set(e.id, e.cache.rev)
      }
      // Push-up runs with the master just up, but record the outcome anyway: a failed write
      // (connection flapped) stays owed so the next save retries it.
      const content = serializeProjectFile(e.cache)
      const ok = await this.remoteIO.write(e.id, e.ssh, content)
      if (ok) {
        this.recordMirrored(e.id, content)
        this.unmirrored.delete(e.id)
        // Tombstones survive the ack here too (see `confirmClearedDeletions`): this write is the
        // same optimistically-acked throttled write the mirror path makes.
      } else this.unmirrored.add(e.id)
    }
    // Surface a rescued merge to the renderer even on a read-only poll (pushIfStanding:false) — the
    // whole point is the phone's session reaching the live desktop canvas without a reconnect.
    return merged
  }
}

/** The nodes of `from` whose id is NOT present in `base` — the additions one writer has that the
 *  other lacks. Used to UNION a same-lineage divergence so neither writer's session nodes are lost
 *  when the shared `rev` counter can't order the two writes (see reconcileSsh). */
function nodesMissingFrom(base: CanvasNodeState[], from: CanvasNodeState[]): CanvasNodeState[] {
  const have = new Set(base.map((n) => n.id))
  return from.filter((n) => !have.has(n.id))
}

/** A labeled grey placeholder for a ref whose file can't be read right now. */
function unavailableProject(e: {
  id: string; name: string; color: string; closed?: boolean; closedAt?: number
  handedOffTo?: HandedOffTo; cwd?: string; ssh?: Project['ssh']
}): Project {
  return {
    id: e.id, name: e.name, color: e.color,
    viewport: { x: 0, y: 0, zoom: 1 }, nodes: [],
    ...(e.cwd ? { cwd: e.cwd } : {}), ...(e.ssh ? { ssh: e.ssh } : {}),
    ...(e.closed ? { closed: true } : {}),
    ...(e.closedAt ? { closedAt: e.closedAt } : {}),
    // The placeholder is what the renderer saves back for this entry, so the guard must ride it:
    // an unreachable handed-off project must stay handed off.
    ...(e.handedOffTo ? { handedOffTo: e.handedOffTo } : {}),
    unavailable: true
  }
}

const isObjectEntry = (e: unknown): boolean => typeof e === 'object' && e !== null && !Array.isArray(e)

/** Normalize legacy on-disk shapes (v1 single canvas, v2 projects) into a v2-shaped workspace.
 *  Anything else answers `EMPTY_WORKSPACE` itself (by identity: `loadInner` reads that as "no index
 *  this build recognises"). */
function migrateLegacy(parsed: unknown): Workspace {
  const ws = parsed as Partial<Workspace> & Partial<WorkspaceV1>
  if (ws?.version === 2 && Array.isArray(ws.projects)) {
    const active = ws.projects.some((p) => p.id === ws.activeProjectId)
      ? (ws.activeProjectId as string)
      : (ws.projects[0]?.id ?? '')
    // A pre-v3 workspace.json is hand-editable input too, same as an inline v3 entry — and this
    // path skips loadV3 entirely (the first save() is what actually migrates it), so without this
    // a malformed `closedSessions` reaches `mergeClosedHistory`'s `for...of` before that save ever
    // runs and takes the sidebar render down on the very first load.
    const projects = ws.projects.map((p) => {
      const history = sanitizeLoadedClosedSessions(p.closedSessions)
      // Same reason as `closedSessions` above, for the geometry snapshots: this path skips loadV3
      // entirely, so a non-finite coordinate would reach React Flow before the first save ever
      // migrates the file.
      const layouts = sanitizeLayouts(p.layouts)
      const views = pruneLayoutViewports(sanitizeLayoutViewports(p.layoutViewports), layouts)
      // And the canvas links, for the same reason: a malformed rope threw at project load.
      const bridges = p.bridges ? sanitizeLinks(p.bridges) : undefined
      const ropes = p.ropes ? sanitizeLinks(p.ropes) : undefined
      const unchanged = history === p.closedSessions
        && layouts === p.layouts
        && views === p.layoutViewports
        && bridges === p.bridges
        && ropes === p.ropes
      if (unchanged) return p
      const { closedSessions: _c, layouts: _l, layoutViewports: _v, bridges: _b, ropes: _r, ...rest } = p
      return {
        ...rest,
        ...(bridges ? { bridges } : {}),
        ...(ropes ? { ropes } : {}),
        ...(history ? { closedSessions: history } : {}),
        ...(layouts ? { layouts } : {}),
        ...(views ? { layoutViewports: views } : {})
      }
    })
    return { version: 2, activeProjectId: active, projects }
  }
  if (ws?.version === 1 && Array.isArray(ws.nodes)) {
    return {
      version: 2,
      activeProjectId: DEFAULT_PROJECT_ID,
      projects: [{
        id: DEFAULT_PROJECT_ID, name: 'Project 1', color: '#7aa2f7',
        viewport: ws.viewport ?? { x: 0, y: 0, zoom: 1 }, nodes: ws.nodes
      }]
    }
  }
  return EMPTY_WORKSPACE
}