peachsim 0.1.527

package/cli/commands/version.ts

@@ -0,0 +1,63 @@
+// rnx version — one overview of both halves you're running.
+//
+// the rnx CLI and the engine runtime (versioned tarball
+// rendered in the browser/electron shell) are versioned independently, which
+// is a frequent "I upgraded but the version didn't change" trap. the terse
+// `rnx --version` flag prints both for scripts; this command adds the
+// channel, a "newer runtime available" hint, and a what's-new pointer.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { getCliVersion } from '../../src/cli-version'
+import { runtimeDir } from '../../src/home-paths'
+import { RNX_CHANGELOG_URL, rnxRuntime } from '../../src/runtime-delivery'
+import { resolveRNXAppConfig } from '../app-config'
+import { readCachedCliUpdate, refreshCliUpdateCache } from '../cli-update'
+import { getRuntimeSummary } from '../runtime-summary'
+import { IS_STANDALONE } from '../standalone'
+
+export async function runVersion(_args: string[]): Promise<void> {
+  const cliUpdatePromise = IS_STANDALONE
+    ? refreshCliUpdateCache().catch(() => readCachedCliUpdate())
+    : Promise.resolve(null)
+  const { IS_BETA, BETA_LABEL } = await import('../../src/beta')
+  const suffix = IS_BETA ? ` · ${BETA_LABEL}` : ''
+  console.log(`rnx v${getCliVersion()}${suffix}`)
+
+  const runtime = getRuntimeSummary()
+  const channel = rnxRuntime.resolveChannel()
+  if (runtime.isDevBridge) {
+    console.log(runtime.primary)
+    if (runtime.installedRuntime) console.log(`${runtime.installedRuntime} · ${channel}`)
+  } else if (runtime.primary === 'runtime not installed') {
+    console.log(`runtime not installed — run \`rnx runtime install\``)
+  } else {
+    console.log(`${runtime.primary} · ${channel}`)
+  }
+
+  const { config } = await resolveRNXAppConfig()
+  if (config?.runtimeVersion) {
+    const installed = fs.existsSync(
+      path.join(runtimeDir(config.runtimeVersion), 'index.html'),
+    )
+    console.log(
+      `project runtime v${config.runtimeVersion} · configured · ${
+        installed ? 'installed' : 'installs on open'
+      }`,
+    )
+  }
+
+  // best-effort network check; never fail the command on a flaky network.
+  const [check, cliUpdate] = await Promise.all([
+    rnxRuntime.checkUpToDate({ channel }),
+    cliUpdatePromise,
+  ])
+  if (cliUpdate?.outdated) {
+    console.log(`\n  ↑ CLI v${cliUpdate.latestVersion} available; run \`rnx upgrade\``)
+  }
+  if (check.outdated && check.latest) {
+    console.log(`\n  ↑ default runtime v${check.latest} available; run \`rnx upgrade\``)
+  }
+
+  console.log(`\n  what's new: ${RNX_CHANGELOG_URL}`)
+}

package/cli/commands/welcome.ts

@@ -0,0 +1,17 @@
+import { isOnboardingComplete } from '../../src/home-paths'
+import { canPromptForPrivacyChoice } from '../privacy'
+import { printBrand } from '../ui'
+import { runOpenCommand } from './control'
+import { runSetup } from './setup'
+
+export async function runWelcome(): Promise<number> {
+  if (!isOnboardingComplete() && canPromptForPrivacyChoice()) {
+    await runSetup([], { launchConnectRN: true })
+    return 0
+  }
+
+  printBrand('Run any React Native app in a local simulator.')
+  console.log(`\n  Opening ConnectRN`)
+  await runOpenCommand(['ConnectRN', '--no-describe', '--quiet'])
+  return 0
+}

package/cli/commands/what-happened.ts

@@ -0,0 +1,328 @@
+// rnx what-happened — show recent events from the semantic timeline
+//
+// the agent-facing read verb for the SootSim.bridges.timeline API. by default
+// shows everything since the previous CLI call from the same agent
+// identity (cursor model). after rendering, advances the cursor past
+// the events it displayed so the next call shows only new events.
+//
+// usage:
+//   rnx what-happened                      # since last call
+//   rnx what-happened --summary            # one-line counts
+//   rnx what-happened --all                # full ring (no cursor)
+//   rnx what-happened --since 5s           # absolute window
+//   rnx what-happened --kinds toast,fetch  # filter
+//   rnx what-happened --json               # structured
+//   rnx what-happened --limit 50           # cap (default 200)
+
+import { getCliIdentityKey } from '../current-sim'
+import { rnxExit } from '../run-rnx'
+import { createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
+import {
+  formatTimelineEvent,
+  formatTimelineSummary,
+  inspectTimelineAdvanceCursor,
+  inspectTimelineRecent,
+  inspectTimelineSummary,
+  NOISY_TIMELINE_KINDS,
+} from './inspect/core'
+import type { SootSimTimelineEvent, SootSimTimelineQuery } from '@rnx/globals'
+
+interface WhatHappenedOptions {
+  port?: number
+  verbose?: boolean
+}
+
+function parseSinceFlag(args: string[]): { since?: number; consumed: number[] } {
+  const consumed: number[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--since' && i + 1 < args.length) {
+      consumed.push(i, i + 1)
+      const v = args[i + 1].trim()
+      // accept '5s', '500ms', or absolute ms epoch
+      const m = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(v)
+      if (m) {
+        const n = Number(m[1])
+        const unit = m[2] ?? 'ms'
+        const ms = unit === 's' ? n * 1000 : unit === 'm' ? n * 60_000 : n
+        return { since: Date.now() - ms, consumed }
+      }
+      const asNum = Number(v)
+      if (Number.isFinite(asNum) && asNum > 1_000_000_000_000) {
+        return { since: asNum, consumed }
+      }
+    }
+  }
+  return { consumed }
+}
+
+function parseKindsFlag(args: string[]): { kinds?: string[]; consumed: number[] } {
+  const consumed: number[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--kinds' && i + 1 < args.length) {
+      consumed.push(i, i + 1)
+      return {
+        kinds: args[i + 1]
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean),
+        consumed,
+      }
+    }
+  }
+  return { consumed }
+}
+
+function parseLimitFlag(args: string[]): { limit?: number; consumed: number[] } {
+  const consumed: number[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--limit' && i + 1 < args.length) {
+      consumed.push(i, i + 1)
+      const n = Number(args[i + 1])
+      if (Number.isFinite(n) && n > 0) return { limit: n, consumed }
+    }
+  }
+  return { consumed }
+}
+
+interface FlowSection {
+  label: string
+  events: SootSimTimelineEvent[]
+  startedAt: number | null
+}
+
+// section the events by screen/route boundaries for `what-happened
+// --flow`. each screen-name (or route-path) becomes a section
+// header; every event that lands between two screen changes belongs
+// to the first one's section. events before the first screen change
+// land in an "initial state" section so nothing gets dropped.
+//
+// design note: this groups by *appearance* events only (phase ===
+// 'enter' or no phase). disappearance events (`exit`) end the
+// current section but don't start a new one — they're listed inside
+// the section that contained them.
+function groupByScreen(events: SootSimTimelineEvent[]): FlowSection[] {
+  const sections: FlowSection[] = []
+  let current: FlowSection = {
+    label: 'initial state',
+    events: [],
+    startedAt: events[0]?.t ?? null,
+  }
+  sections.push(current)
+  for (const ev of events) {
+    current.events.push(ev)
+    if (ev.kind === 'screen' || ev.kind === 'route') {
+      const data = ev.data as Record<string, unknown> | null
+      const phase = data?.phase as string | undefined
+      // only treat 'enter' (and the legacy no-phase form) as a
+      // section boundary. an 'exit' event is the tail of a screen,
+      // not the start of a new one.
+      if (!phase || phase === 'enter' || phase === 'appear' || phase === 'active') {
+        const name =
+          (data?.name as string) ||
+          (data?.activeName as string) ||
+          (data?.path as string) ||
+          (data?.pathname as string) ||
+          ev.kind
+        if (sections.length === 1 && current.events.length === 1) {
+          // first screen event — rename "initial state" inline so it
+          // doesn't show an empty initial-state section before it.
+          current.label = `${ev.kind}: ${name}`
+        } else {
+          current = {
+            label: `${ev.kind}: ${name}`,
+            events: [],
+            startedAt: ev.t,
+          }
+          sections.push(current)
+        }
+      }
+    }
+  }
+  return sections
+}
+
+export async function runWhatHappened(args: string[], opts: WhatHappenedOptions) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: [
+      '--summary',
+      '--all',
+      '--json',
+      '--no-advance',
+      '--help',
+      '-h',
+      // `--flow` groups events under screen/route boundaries instead of
+      // printing a strict chronological list. demo-friendly for the
+      // "what just happened in this sim" recap.
+      '--flow',
+      // by default we hide high-frequency render/layout/scroll noise so
+      // a single tap doesn't get buried under 1000+ rows. enable
+      // `react-commit` with `rnx timeline start react-commit`, then pass
+      // `--noisy` (or an explicit `--kinds react-commit,…` filter) when you
+      // actually want to see them.
+      '--noisy',
+    ],
+    stripValueFlags: ['--since', '--kinds', '--limit'],
+  })
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+rnx what-happened — show recent events from the semantic timeline
+
+usage:
+  rnx what-happened                  # since last CLI call
+  rnx what-happened --summary        # one-line counts
+  rnx what-happened --all            # full ring (ignore cursor)
+  rnx what-happened --since 5s       # absolute window
+  rnx what-happened --kinds toast,fetch
+  rnx what-happened --noisy          # include react-commit/layout/scroll
+  rnx what-happened --limit 50
+  rnx what-happened --json
+  rnx what-happened --no-advance     # don't advance cursor after read
+
+note: react-commit, layout, and scroll are opt-in/noisy events. enable them
+with "rnx timeline start <kind>", then pass --noisy or include them in
+--kinds to see them.
+`)
+    rnxExit(0)
+  }
+
+  const summaryMode = args.includes('--summary')
+  const flowMode = args.includes('--flow')
+  const allMode = args.includes('--all')
+  const jsonMode = args.includes('--json')
+  const noAdvance = args.includes('--no-advance')
+  const noisyMode = args.includes('--noisy')
+
+  const { since } = parseSinceFlag(args)
+  const { kinds } = parseKindsFlag(args)
+  const { limit } = parseLimitFlag(args)
+
+  const cursorKey = getCliIdentityKey()
+  const query: SootSimTimelineQuery = {
+    limit: limit ?? 200,
+    ...(kinds && kinds.length ? { kinds: kinds as SootSimTimelineQuery['kinds'] } : {}),
+    ...(since !== undefined ? { since } : allMode ? {} : { sinceCursor: cursorKey }),
+  }
+
+  const bridge = createBridgeFromParsed(parsed)
+  try {
+    if (summaryMode) {
+      const summary = await inspectTimelineSummary(bridge, query)
+      if (jsonMode) {
+        console.log(JSON.stringify(summary))
+      } else {
+        const since_label = allMode
+          ? 'all time'
+          : since !== undefined
+            ? `last ${((Date.now() - since) / 1000).toFixed(1)}s`
+            : 'since last call'
+        console.log(`  ${since_label}: ${formatTimelineSummary(summary)}`)
+      }
+      // advance cursor past the summary window's end
+      if (!noAdvance && !allMode && summary.lastAt) {
+        await inspectTimelineAdvanceCursor(bridge, cursorKey, summary.lastAt)
+      }
+      return
+    }
+
+    const result = await inspectTimelineRecent(bridge, query)
+
+    // hide high-frequency render/layout/scroll noise unless the caller
+    // explicitly asked for it (--noisy or --kinds containing one of
+    // these). this is the single most common reason `what-happened`
+    // output drowns out the meaningful events for the user/agent.
+    const userPickedNoisyKind =
+      Array.isArray(kinds) && kinds.some((k) => NOISY_TIMELINE_KINDS.has(k))
+    const suppressNoisy = !noisyMode && !userPickedNoisyKind
+    let suppressedNoisyCount = 0
+    if (suppressNoisy) {
+      const kept = result.events.filter((ev) => {
+        if (NOISY_TIMELINE_KINDS.has(ev.kind)) {
+          suppressedNoisyCount += 1
+          return false
+        }
+        return true
+      })
+      result.events = kept
+    }
+
+    if (jsonMode) {
+      if (flowMode) {
+        // grouped JSON shape — sections by screen/route. agents who want
+        // a chronological stream can still get it from the default
+        // shape (without --flow).
+        console.log(JSON.stringify(groupByScreen(result.events), null, 2))
+      } else {
+        console.log(JSON.stringify(result, null, 2))
+      }
+    } else {
+      if (result.events.length === 0) {
+        // distinguish "truly no events" from "events present but all
+        // filtered as noise". the second case is the much more common
+        // misdiagnosis — agents think a tap did nothing when actually
+        // it just produced react-commits and no shell-state change.
+        if (suppressedNoisyCount > 0) {
+          console.log(
+            `  no non-noise events (${suppressedNoisyCount} react-commit/layout/scroll hidden)`,
+          )
+        } else if (allMode) {
+          console.log('  no events recorded')
+        } else if (since !== undefined) {
+          console.log('  no events in window')
+        } else {
+          console.log('  no new events since last call')
+        }
+      } else if (flowMode) {
+        // section-per-screen render. each section heads with the
+        // screen/route name and lists every event that landed in
+        // that section in chronological order. unattributed events
+        // (events that landed before the first screen change) go in
+        // an "initial state" section.
+        const anchor = result.events[0]?.t ?? null
+        const sections = groupByScreen(result.events)
+        const header = allMode
+          ? `─── ${result.events.length} event(s) total — flow view ───`
+          : since !== undefined
+            ? `─── ${result.events.length} event(s) in last ${((Date.now() - since) / 1000).toFixed(1)}s — flow view ───`
+            : `─── ${result.events.length} event(s) since last call — flow view ───`
+        console.log(`  ${header}`)
+        for (const section of sections) {
+          console.log(
+            `\n  ── ${section.label} (${section.events.length} event${section.events.length === 1 ? '' : 's'}) ──`,
+          )
+          for (const ev of section.events) {
+            console.log(formatTimelineEvent(ev, anchor))
+          }
+        }
+      } else {
+        const anchor = result.events[0]?.t ?? null
+        const header = allMode
+          ? `─── ${result.events.length} event(s) total ───`
+          : since !== undefined
+            ? `─── ${result.events.length} event(s) in last ${((Date.now() - since) / 1000).toFixed(1)}s ───`
+            : `─── ${result.events.length} event(s) since last call ───`
+        console.log(`  ${header}`)
+        for (const ev of result.events) {
+          console.log(formatTimelineEvent(ev, anchor))
+        }
+      }
+      // when at least one real event printed, append the suppression
+      // note so the user knows the picture isn't complete. when the
+      // window was entirely noise, the empty-state branch above already
+      // mentioned it — don't double up.
+      if (suppressedNoisyCount > 0 && result.events.length > 0) {
+        process.stderr.write(
+          `\n  ${suppressedNoisyCount} high-frequency event(s) hidden (react-commit/layout/scroll)\n` +
+            `  rerun with --noisy or --kinds react-commit,layout,scroll to include them\n`,
+        )
+      }
+    }
+
+    if (!noAdvance && !allMode && result.watermark > 0) {
+      await inspectTimelineAdvanceCursor(bridge, cursorKey, result.watermark)
+    }
+  } finally {
+    bridge.close()
+  }
+}

package/cli/current-sim.ts

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { basename, dirname, join, resolve } from 'path'
+import { getParentPid, getProcessComm } from './parent-pid'
+import { writeSecureJsonAtomic } from './secure-file'
+
+const CURRENT_SIM_VERSION = 2 as const
+const CURRENT_SIM_PATH_ENV = 'SOOTSIM_CLI_CURRENT_SIM_PATH'
+
+export interface LocalCurrentTarget {
+  version: 2
+  plane: 'local'
+  simId: string
+  updatedAt: string
+}
+
+// env vars that tend to identify a specific terminal, pane, or agent run.
+// checked in order — the first one present wins. anything further down is a
+// progressively weaker signal of "same caller across invocations".
+const IDENTITY_ENV_VARS = [
+  'RNX_CLI_IDENTITY', // explicit override — fastest path, skips all pid lookups
+  'TM_SESSION', // Team Machine session id; routes prompt-bar followups back to this agent
+  'CLAUDE_CODE_SESSION_ID', // claude code, if ever set
+  'CODEX_THREAD_ID', // codex / openai agent thread, stable across tool invocations
+  'TERM_SESSION_ID', // macOS Terminal.app + iTerm2
+  'ITERM_SESSION_ID', // iTerm2 (older variant)
+  'TMUX_PANE', // tmux — stable per pane
+  'STY', // GNU screen session
+  'KITTY_WINDOW_ID', // kitty
+  'WEZTERM_PANE', // wezterm
+  'ALACRITTY_WINDOW_ID', // alacritty
+  'WINDOWID', // X11 terminals
+  'VSCODE_INJECTION', // vscode integrated terminal
+] as const
+
+export interface CliIdentity {
+  key: string
+  source: (typeof IDENTITY_ENV_VARS)[number] | 'grand-ppid' | 'ppid' | 'explicit-sim-id'
+  stable: boolean
+}
+
+// derive a stable per-terminal identity key so different agents/terminals
+// don't share state. priority:
+//   1. explicit env vars (iTerm, tmux, etc.)
+//   2. grand-ppid — the parent of our invoking shell, which in Claude Code's
+//      Bash tool is the per-agent claude process (stable across invocations,
+//      distinct between agents). generic — not claude-specific.
+//   3. ppid — the invoking shell's pid. stable when the shell is reused
+//      across invocations (claude's bash tool, persistent tty sessions).
+//      unstable when each call spawns a fresh shell — in that case set an
+//      env var from IDENTITY_ENV_VARS to pin the identity.
+// an earlier env-hash fallback was removed: sha'ing process.env looks stable
+// but in practice any per-turn env drift (timestamps, cwd, agent vars)
+// flipped the hash and made the same agent look like a new client.
+// walk up to the topmost non-init ancestor. needed because intermediate
+// pids drift across invocations:
+//   - claude code's bash tool spawns a fresh shell per call, so the
+//     immediate gppid (the shell's parent) can change
+//   - shell pipelines (`rnx list | grep`) wrap the command in a
+//     subshell, adding an extra ppid layer that shifts gppid down by one
+// the topmost user process (just below init/launchd) is stable across
+// all of these — same agent / login shell / terminal across calls.
+// terminal-multiplexer servers are effectively immortal (the tmux server
+// lives while ANY session exists), so an owner-pid walk that climbs into one
+// produces an owner that never dies — detached browser hosts then leak until
+// an explicit close (real incident: a tmux-launched sim's chrome survived its
+// pane at 129% cpu). the Team Machine daemon is the same class: it spawns worker
+// harnesses directly, outlives them all, and additionally collapses every
+// worker into one shared identity key (real incident 2026-07-14: three film
+// render hosts leaked with owner = the daemon while load hit 224). stop
+// BELOW these hosts: the child (pane shell / worker harness) dies with the
+// session, which is the lifetime a sim owner should have.
+// these are matched against libproc's pbi_comm, the executable's basename,
+// truncated to 16 chars. Team Machine reports comm `tm`; matching its product
+// name never fired and every agent-launched sim resolved its owner to the terminal
+// tab's /usr/bin/login instead (real incident 2026-08-06: six chrome hosts
+// survived their agents, 17GB rss, load 19 with the GPU saturated).
+const IMMORTAL_HOST_COMM_RE = /^(?:tmux|screen)|^tm$/i
+
+function findTopAncestor(start: number, maxDepth = 20): number | null {
+  // check each CANDIDATE's own comm and return the child below a multiplexer
+  // (prev). checking only the parent's comm looked equivalent but was not: on
+  // macOS the tmux server is launchd's direct child, so it arrives as the
+  // candidate via the initializer and the parent<=1 branch returned it before
+  // any comm check ran (runtime-caught on a real tmux box: owner resolved to
+  // the immortal server). prev starts at `start` so a pane shell directly
+  // under the server resolves to itself.
+  let prev = start
+  let pid = getParentPid(start)
+  if (!pid || pid <= 1) {
+    // a readable ordinary process directly below init is itself the stable
+    // session root. this is the shape produced by detached job launchers, and
+    // returning null here used to disable the browser owner's lifetime watch.
+    // an unreadable or known-immortal process has no defensible child bound at
+    // this point, so leave it unresolved and make the launcher fail loudly.
+    const comm = getProcessComm(start)
+    return start > 1 && comm && !IMMORTAL_HOST_COMM_RE.test(comm) ? start : null
+  }
+  for (let i = 0; i < maxDepth; i++) {
+    const comm = getProcessComm(pid)
+    if (comm && IMMORTAL_HOST_COMM_RE.test(comm)) return prev
+    const parent = getParentPid(pid)
+    if (!parent || parent <= 1) {
+      // top of the tree we can read. an unreadable comm means a root-owned
+      // session host — /usr/bin/login under a terminal tab — which outlives
+      // every agent and shell inside it, so stop below it. a readable top is
+      // an ordinary user process (a CI job root) and is a valid owner.
+      return comm ? pid : prev
+    }
+    prev = pid
+    pid = parent
+  }
+  return pid
+}
+
+export function getCliIdentity(): CliIdentity {
+  for (const name of IDENTITY_ENV_VARS) {
+    const value = process.env[name]
+    if (value && value.trim()) {
+      return { key: `${name}:${value.trim()}`, source: name, stable: true }
+    }
+  }
+  const topPid = findTopAncestor(process.ppid)
+  if (topPid && topPid > 1) {
+    return { key: `gppid-${topPid}`, source: 'grand-ppid', stable: true }
+  }
+  return { key: `pid-${process.ppid}`, source: 'ppid', stable: false }
+}
+
+export function getCliIdentityKey(): string {
+  return getCliIdentity().key
+}
+
+// the stable owning-session pid: the topmost non-init ancestor of this CLI
+// process — in Claude Code's Bash tool the per-agent process, otherwise the
+// login shell / terminal / CI process-tree root. it lives exactly as long as
+// the session that wants a sim, and dies when that session does. used to tie
+// a detached browser host's lifetime to its owner so the host self-terminates
+// (closing Chrome) when the owner exits, instead of leaking a headless
+// browser forever. returns null on platforms where ancestry can't be read.
+export function getStableOwnerPid(): number | null {
+  return findTopAncestor(process.ppid)
+}
+
+export function getCurrentSimPath() {
+  if (process.env[CURRENT_SIM_PATH_ENV]) {
+    return resolve(process.env[CURRENT_SIM_PATH_ENV])
+  }
+  const key = getCliIdentityKey()
+  return join(tmpdir(), `rnx-current-sim-${key}.json`)
+}
+
+function legacyCloudCredentialDirectory(filepath: string): string {
+  return join(dirname(filepath), `${basename(filepath)}.credentials`)
+}
+
+export function readCurrentTarget(): LocalCurrentTarget | null {
+  const filepath = getCurrentSimPath()
+  rmSync(legacyCloudCredentialDirectory(filepath), { recursive: true, force: true })
+  if (!existsSync(filepath)) return null
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filepath, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object') {
+      rmSync(filepath, { force: true })
+      return null
+    }
+    const version = Reflect.get(parsed, 'version')
+    const plane = Reflect.get(parsed, 'plane')
+    const simId = Reflect.get(parsed, 'simId')
+    const updatedAt = Reflect.get(parsed, 'updatedAt')
+    if (
+      (version !== 1 && version !== CURRENT_SIM_VERSION) ||
+      (version === CURRENT_SIM_VERSION && plane !== 'local') ||
+      typeof simId !== 'string' ||
+      !simId.trim() ||
+      typeof updatedAt !== 'string'
+    ) {
+      rmSync(filepath, { force: true })
+      return null
+    }
+
+    const target = {
+      version: CURRENT_SIM_VERSION,
+      plane: 'local',
+      simId: simId.trim(),
+      updatedAt,
+    } satisfies LocalCurrentTarget
+    if (version === 1) writeSecureJsonAtomic(filepath, target)
+    return target
+  } catch {
+    rmSync(filepath, { force: true })
+    return null
+  }
+}
+
+export const readCurrentSim = readCurrentTarget
+
+export function readCurrentSimId() {
+  return readCurrentTarget()?.simId ?? null
+}
+
+export function saveCurrentSimId(simId: string) {
+  const normalized = simId.trim()
+  if (!normalized) return
+
+  writeSecureJsonAtomic(getCurrentSimPath(), {
+    version: CURRENT_SIM_VERSION,
+    plane: 'local',
+    simId: normalized,
+    updatedAt: new Date().toISOString(),
+  } satisfies LocalCurrentTarget)
+}
+
+export function clearCurrentSimId() {
+  rmSync(getCurrentSimPath(), { force: true })
+}