sootsim 0.1.169 → 0.1.170

package/skills/sootsim-test.md

@@ -0,0 +1,292 @@
+---
+name: sootsim-test
+description: Run automated tests against your React Native app under sootsim — native YAML flows, Maestro drop-in, or Detox drop-in
+---
+
+# sootsim test
+
+one skill for "run automated tests against sootsim". three runtimes share
+the same shell and the same auto-settling contract; pick the one that
+matches your existing toolchain and stay with it.
+
+> needs a connected, pinned sim. if `sootsim describe` errors, load
+> `/sootsim-setup` first.
+
+## route in (decision tree)
+
+- have an existing `.maestro/` directory? → [maestro drop-in](#branch--maestro-drop-in)
+- have existing Detox specs? → [detox drop-in](#branch--detox-drop-in)
+- writing tests fresh, or want the recorder? → [native YAML flows](#branch--native-yaml-flows)
+
+each runtime accepts the same compat surface — flows author once, run
+many ways. start with whichever your team already uses; you don't pay a
+migration tax to try sootsim.
+
+## anti-patterns (apply to every runtime)
+
+- **`sleep` is almost always a bug.** the underlying CLI auto-settles
+  before reads and polls layout hash after writes. if a flow fails
+  without a `sleep`, the fix is `waitFor`, `waitForAnimationToEnd`, or
+  `wait idle` — not a blind timer. the one legitimate case: a
+  user-controlled debounce ("press and hold for 2s").
+- **prefer testID (`tapId`, `by.id(testID)`) over text.** text breaks
+  under i18n, copy churn, and duplicate strings. add `testID` during
+  implementation and author flows against it.
+- **pin a sim before running a suite.** parallel CI jobs colliding
+  on the default bridge port is the #1 flake source. pass `--port` in
+  CI and `sootsim use <id>` locally.
+- **every flow ends with an assert, not a screenshot.** a screenshot
+  passes as long as the flow didn't throw. `assertVisible` (or
+  `expect(...).toBeVisible()`) actually verifies the happy path.
+- **don't run a 40-step "smoke everything" flow.** when it fails, you
+  can't tell what regressed. split into `login.yaml`, `compose.yaml`,
+  `settings.yaml`, chain with `runFlow`.
+
+## you're done when
+
+- the suite passes locally and in CI
+- every flake is either fixed or marked `xfail` with a written reason
+  and a removal date
+- the green run took noticeably less wall-clock than the previous
+  baseline (a suite that grows slower without growing wider is a smell)
+
+## branch — native YAML flows
+
+write declarative YAML against sootsim's maestro-compatible verb set.
+flows are portable, readable, and can record video for failing CI runs.
+
+```sh
+sootsim flow flows/login.yaml             # run a flow
+sootsim flow flows/login.yaml --video     # record webm
+sootsim flow flows/login.yaml --profile   # include perf stats per step
+sootsim flow flows/                       # every flow in a directory
+```
+
+the recorder is the killer feature for writing a flow from a live
+interaction — author by demonstration:
+
+```sh
+sootsim flow start                        # begin recording a draft
+sootsim do tap-id loginButton             # drive the app via the CLI
+sootsim flow keep                         # save the step
+sootsim do type "user@example.com"
+sootsim flow keep
+sootsim do tap-id submit
+sootsim flow keep
+sootsim flow end --output flows/login.yaml
+```
+
+the recorder emits minimal YAML — no coordinate dumps, no `sleep` noise —
+because the underlying CLI already settled between every action.
+
+exemplar flow:
+
+```yaml
+# flows/login.yaml
+- launchApp: {}
+
+- waitFor:
+    text: 'Sign in'
+    timeout: 10000
+
+- tapId: emailInput
+- typeText: '${USERNAME}'
+
+- tapId: passwordInput
+- typeText: '${PASSWORD}'
+
+- tapId: signInButton
+- waitForAnimationToEnd: true
+
+- assertVisible: 'Welcome back'
+```
+
+run with env interpolation:
+
+```sh
+sootsim flow flows/login.yaml \
+  --env USERNAME=alice \
+  --env PASSWORD=hunter2 \
+  --video --profile
+```
+
+automatic settling inside flows: every tap, type, scroll, swipe, and
+drag is backed by the same primitives that auto-wait for transitions on
+the way in and layout stability on the way out. you rarely need
+explicit waits; when you do, `waitForAnimationToEnd: true` maps to the
+CLI's `wait idle` with a generous budget. use it before any
+`assertVisible` that depends on a transition longer than ~1.2 s.
+
+generating a starter flow by crawling the app:
+
+```sh
+sootsim flow generate --max-screens 20
+```
+
+useful as a parity-coverage starting point; always review before
+committing — generated flows are conservative and skip assertions.
+
+## branch — maestro drop-in
+
+if you already have a `.maestro/` directory, the migration is one
+command change:
+
+```sh
+# before
+maestro test .maestro/login.yaml
+
+# after
+sootsim maestro test .maestro/login.yaml
+```
+
+no test rewrites, no detox config, no simulator. the runtime auto-launches
+a sootsim shell if one isn't running.
+
+```sh
+sootsim maestro                           # auto-discover .maestro/ or maestro/
+sootsim maestro test .maestro/login.yaml
+sootsim maestro test .maestro/            # every flow in a directory
+sootsim maestro init                      # scaffold a starter flow
+sootsim maestro --list-compat             # supported / partial / unsupported
+sootsim maestro --env USERNAME=alice test .maestro/login.yaml
+```
+
+### supported verbs
+
+`launchApp`, `stopApp`, `clearState`, `tapOn`, `tapAtCoords`, `inputText`,
+`pressKey`, `dispatchKey`, `hideKeyboard`, `eraseText`, `assertVisible`,
+`assertNotVisible`, `assertTreeContains`, `waitFor`, `extendedWaitUntil`,
+`waitForAnimationToEnd`, `scroll`, `scrollUntilVisible`, `scrollTo`,
+`swipe`, `pinch`, `takeScreenshot`, `dumpTree`, `back`, `repeat.times`,
+`runFlow`, `when` (`visible` / `notVisible` / `platform` / `true`),
+`optional: true`, `onFlowStart` / `onFlowComplete`, `copyTextFrom` +
+`${maestroCopiedText}`, `evalScript`, `openLink`, env var `${NAME}`
+interpolation.
+
+### partial
+
+- `clearKeychain` — no keychain in sootsim; logs a warning and continues.
+  if a test depends on keychain state being reset, add an explicit
+  in-app "sign out" step instead.
+- `when.platform` — sootsim emulates iOS; android branches are skipped.
+- `openLink` — navigates `window.location`; no OS-level app routing.
+
+### not yet implemented
+
+these throw `unsupported maestro verb: X`:
+
+- `travel`, `setLocation`, `setAirplaneMode`, `killApp`
+- `addMedia`
+- `repeat.while` (use `repeat.times`)
+
+### troubleshooting
+
+- **"no maestro flows found"** — pass an explicit path
+  (`sootsim maestro test path/to/flow.yaml`) or run `sootsim maestro
+  init` to scaffold one.
+- **"missing environment variable for flow placeholder: FOO"** — pass
+  `--env FOO=bar` or export it. pick one mechanism per repo and document
+  it in the flow directory's README.
+- **flow can't find an element** — sootsim's matcher uses testID + visible
+  text. UIKit-only labels that real maestro scrapes from the host OS won't
+  resolve here; switch to testID.
+- **flow runs but nothing renders** — confirm the bundler your flow
+  targets is reachable and pass `--url <port>` or add `app: <port>`
+  frontmatter at the top of the YAML.
+
+## branch — detox drop-in
+
+an existing detox suite runs against sootsim with **one line** of jest
+config and zero test changes.
+
+`import { by, device, element, expect, waitFor } from 'detox'` is
+rewritten by jest to a sootsim-backed driver that drives the real shell
+over playwright. matchers, assertions, and the `waitFor` API match the
+upstream detox surface.
+
+### one-line install
+
+```js
+// sootsim-detox.config.cjs
+module.exports = {
+  preset: 'sootsim/detox/jest-preset',
+  rootDir: __dirname,
+  testMatch: ['<rootDir>/e2e/**/*.test.ts'],
+}
+```
+
+or, if you already have a jest config, pull in just the module mapper:
+
+```js
+moduleNameMapper: {
+  '^detox$': require.resolve('sootsim/detox'),
+}
+```
+
+keep the **preset**, not just the mapper — the preset wires up the
+global setup/teardown that tears the shell down between suites. mapper-only
+works until your first hung shell.
+
+### commands
+
+```sh
+sootsim detox                             # run e2e/, test/e2e/, or detox/
+sootsim detox --config my.cjs             # use a specific jest config
+sootsim detox --watch                     # jest watch mode
+sootsim detox -t "login"                  # --testNamePattern
+sootsim detox --headed                    # keep the shell window visible
+sootsim detox --no-launch                 # don't auto-launch a shell
+sootsim detox --port 5173                 # explicit bridge port for CI
+sootsim detox init                        # scaffold config + e2e/example.test.ts
+```
+
+### compat surface
+
+| detox API                          | sootsim |
+| ---------------------------------- | ------- |
+| `element(by.id(...))`              | supported |
+| `element(by.text(...))`            | supported — but prefer `by.id` |
+| `element(by.label(...))`           | supported |
+| `element(by.traits([...]))`        | supported for the iOS trait set |
+| `.toBeVisible()` / `.not.toBeVisible()` | supported |
+| `.toHaveText(...)` / `.toHaveLabel(...)` | supported |
+| `.tap()` / `.longPress()`          | supported |
+| `.typeText(...)` / `.replaceText(...)` | supported |
+| `.scroll(...)` / `.scrollTo(...)`  | supported |
+| `.swipe(...)`                      | supported |
+| `waitFor(...).toBeVisible().withTimeout(...)` | supported |
+| `device.launchApp(...)` / `device.reloadReactNative()` | supported |
+| `device.shake()`                    | partial — emits the JS event, no haptic |
+| `device.sendUserNotification(...)`  | not yet |
+
+### troubleshooting
+
+- **"no sootsim shell reachable"** — start one yourself
+  (`sootsim open <port>`) or pass `--port <n>`.
+- **"jest cannot find module 'detox'"** — the preset isn't wired. confirm
+  `preset: 'sootsim/detox/jest-preset'` is in the jest config jest
+  actually loaded (`--config` overrides package.json).
+- **matchers fail on elements that exist** — canvas has no DOM. use
+  `by.id` (testID); `sootsim describe` shows what the shell sees.
+- **passes locally, flakes in CI** — the shell boots asynchronously.
+  bump jest `testTimeout` to 10–15 s and add a `waitFor(element(...))
+  .toBeVisible().withTimeout(10000)` before the first assertion.
+- **port conflicts under parallel CI** — pass `--port` explicitly per
+  job so workers don't collide on the default bridge port.
+
+## recovery — common failure modes (all runtimes)
+
+- **"no flows found"** — confirm working directory and explicit path;
+  some runtimes look at `.maestro/` while others look at `maestro/` or
+  `e2e/`.
+- **"missing env variable"** — set with `--env` (or jest env config) and
+  document the variable list in the flow directory's README so new
+  contributors aren't guessing.
+- **CI flakes but local passes** — bump test timeouts to 10–15 s before
+  the first assertion, pin the bridge port, and run with `--video` so
+  failing runs land a webm next to the junit output.
+- **a flake reproduces but resists fixing** — don't paper over with
+  `sleep`. open `/sootsim-debug` against the same sim, capture
+  the timeline (`sootsim timeline start` → reproduce → `sootsim
+  what-happened`), and look for the missing animation-completion or
+  the unresolved fetch that's racing the assertion.

package/skills/sootsim-visual.md

@@ -0,0 +1,122 @@
+---
+name: sootsim-visual
+description: Pixel-level rendering comparison between sootsim and native iOS — fonts, gradients, shadows, image fidelity
+---
+
+# sootsim visual
+
+pixel-level rendering fidelity: does the sootsim canvas match native iOS
+for text, gradients, shadows, blur, and image rendering? the `sootsim`
+CLI gives you two primitives — **canvas capture** (`sootsim screenshot`)
+and **structural diff** (`sootsim debug snapshot`/`diff`). pixel
+comparison itself is "capture both sides, diff the PNGs with a standard
+image tool" — there is no single oracle-diff command, and that's fine:
+the capture step is the hard part and it's fully reproducible.
+
+> needs a connected, pinned sim. if `sootsim describe` errors,
+> load `/sootsim-setup` first.
+
+## route in
+
+- structural change ("which nodes / which props changed?") → load
+  `/sootsim-debug`, debugging branch — `debug snapshot` + `debug
+  diff` is faster, deterministic, and tells you *why*.
+- visual change (color, gradient, shadow, font metric, blur, image)? →
+  continue here.
+- comparing sootsim to your iOS simulator for fidelity? → continue.
+- regressing your own app against itself across commits? → continue.
+
+## anti-patterns (read first)
+
+- **run structural diff before pixel work.** `sootsim debug snapshot` /
+  `debug diff` (in `/sootsim-debug`) is cheaper, deterministic, and
+  points at the responsible nodes. only when it's empty (or the change is
+  pure rendering) does a pixel comparison add information.
+- **don't single-screenshot animated surfaces.** a gradient
+  mid-animation never matches. gate the capture behind `sootsim wait
+  idle` first.
+- **a > 5% pixel threshold hides regressions.** ~1% is the right
+  ballpark for catching real font / shadow / gradient drift without
+  flagging anti-alias noise. go higher only with a written reason.
+- **pin device and theme.** capture both sides on the same simulated
+  device and appearance, or you're diffing layout, not rendering. use
+  `--themes` to capture light and dark together.
+- **commit baselines alongside the code change that produced them.**
+  baseline churn without code churn means someone captured noise.
+
+## capturing — `sootsim screenshot`
+
+fast, no extra setup, works on any loaded app:
+
+```sh
+sootsim screenshot --output app.png            # full canvas
+sootsim screenshot --area 0,200,393,400        # crop to a logical rect
+sootsim screenshot --id loginButton -o btn.png # crop to a node by testID
+sootsim screenshot --text "Sign in"            # crop to a node by text
+sootsim screenshot --gallery --themes          # crawl screens → HTML gallery, light+dark
+sootsim screenshot --no-shell -o tenant.png    # tenant surface only, no iOS chrome
+sootsim screenshot --shell-only                # only the simulated iOS chrome
+```
+
+`--gallery` crawls reachable screens and writes a browsable HTML gallery
+— the fastest way to eyeball a whole app for surprise rendering changes.
+
+## comparing pixels
+
+capture both sides to PNGs, then diff with any standard image tool.
+
+**sootsim vs sootsim (regression across your own commits):**
+
+```sh
+sootsim screenshot -o before.png                      # baseline, before your change
+# … make the rendering change, let the sim hot-reload …
+sootsim screenshot -o after.png                       # after your change
+npx pixelmatch before.png after.png diff.png 0.1      # writes diff.png
+# or: magick compare before.png after.png diff.png
+```
+
+**sootsim vs native iOS (fidelity to the real thing):**
+
+```sh
+# native side — capture from your booted iOS simulator
+xcrun simctl io booted screenshot native.png
+# sootsim side — same screen, same appearance
+sootsim screenshot -o sootsim.png
+npx pixelmatch native.png sootsim.png diff.png 0.1
+```
+
+crop both to the same region (`--area` / `--id`) when you only care
+about one element — a full-screen diff buries a 3px font-baseline shift
+under unrelated chrome.
+
+## typical workflow
+
+1. structural diff first — confirm the change is genuinely visual.
+2. capture the affected screen with `sootsim screenshot` (crop to the
+   element if you can).
+3. diff against the baseline (previous commit, or a native capture).
+4. iterate the rendering until the diff is under threshold.
+5. open the gallery (`--gallery`) and scroll through every screen — a red
+   patch on one icon is easy to miss when you're focused on one case.
+
+## you're done when
+
+- the diff is under threshold on every affected case, **or**
+- the differences are explicitly accepted, baselines re-captured, and
+  both halves (code + baselines) committed together.
+- the gallery shows no surprise changes when you scroll through every
+  screen, not just the one you targeted.
+
+## recovery — common failure modes
+
+- **a single icon/glyph diffs** — font-load race or image not yet
+  cached. recapture after `sootsim wait idle`, or navigate away and back
+  to seed the cache.
+- **everything diffs by a constant offset** — you captured the two sides
+  on different devices or appearances. pin both, recapture.
+- **baselines churn without a code change** — someone captured noise (a
+  lingering badge, half-open keyboard, a drifting clock). revert and
+  recapture from a clean, idle state.
+- **persistent delta on the same font / shadow / gradient across
+  unrelated screens** — that's an engine-level rendering fidelity issue,
+  not your app. report it with the affected captures attached.

package/src/agent-daemon-client.ts

@@ -15,7 +15,7 @@ import net from 'node:net'
 import { WebSocket } from 'ws'
 import { resolveSootsimInvocation, type Provider } from './agent-sessions.ts'
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from './bridge-constants.ts'
-import { isDevWorkstation, shouldSkipPersistentDaemon } from './home-paths.ts'
+import { shouldSkipPersistentDaemon } from './home-paths.ts'
 import type { AgentEvent } from './agent-events.ts'
 import type { AgentPromptEnvelope } from './agent-prompt.ts'
 import type { AgentSession, AttachedProject } from './attached-projects.ts'
@@ -346,24 +346,14 @@ export async function ensureDaemonRunning(
   if (await isBridgeUp(port)) {
     return { alreadyRunning: true }
   }
-  // never spawn a standalone daemon on a dev host. on a dev workstation the
-  // live `bun dev` stack already owns the bridge in-process; spawning one here
-  // lands it on a fallback port serving the published runtime, which shadows
-  // the dev build (the :7669 / 0.1.310 footgun). agents must connect to the
-  // live bridge, not resurrect a stale one. override: SOOTSIM_FORCE_DAEMON_INSTALL=1.
   if (shouldSkipPersistentDaemon()) {
-    const why = isDevWorkstation()
-      ? `this is a dev workstation (IS_TAMAGUI_DEV=1)`
-      : `this is a dev checkout`
     throw new AgentDaemonError(
-      `no sootsim bridge on port ${port} and refusing to spawn a standalone daemon — ${why}. ` +
-        `start the live \`bun dev\` stack so the bridge is up, or set ` +
-        `SOOTSIM_FORCE_DAEMON_INSTALL=1 to spawn one here on purpose.`,
+      `no sootsim bridge on port ${port}. run \`sootsim setup\` to install the background daemon, or \`sootsim serve\` in another shell.`,
       'DEV_HOST_REFUSED',
     )
   }
   const { cmd, prefixArgs } = resolveSootsimInvocation()
-  const args = [...prefixArgs, 'server', '--quiet']
+  const args = [...prefixArgs, 'serve', '--quiet']
   if (port !== DEFAULT_SOOTSIM_BRIDGE_PORT) {
     args.push('--port', String(port))
   }
@@ -383,7 +373,7 @@ export async function ensureDaemonRunning(
   }
   throw new AgentDaemonError(
     `spawned sootsim daemon on port ${port} but it did not come up in time. ` +
-      `run \`sootsim server\` manually to diagnose.`,
+      `run \`sootsim serve\` manually to diagnose.`,
     'SPAWN_TIMEOUT',
   )
 }

package/src/beta.ts

@@ -7,15 +7,13 @@
 
 export const IS_BETA = true
 
-export const BETA_VERSION_TARGET = '1.0.0'
-
 // short label — used on the rail pill, electron title, etc.
 export const BETA_LABEL = 'public beta'
 
-// one-line tagline — used in the CLI banner + privacy disclosures.
-export const BETA_TAGLINE = `${BETA_LABEL} · free until ${BETA_VERSION_TARGET}`
+// one-line tagline — used in the CLI banner.
+export const BETA_TAGLINE = BETA_LABEL
 
 // what we ask for in return — kept here so the onboarding flow, the
 // privacy page, and any future surface render the same words.
 export const BETA_ASK_HEADLINE =
-  'free for everyone until 1.0 — we send anonymous error and dependency data while you use it'
+  'we send anonymous error and dependency data while you use it'

package/src/dev-bundle-resolution.ts

@@ -202,20 +202,7 @@ export async function resolveConnectionInput(input: string): Promise<ResolvedDev
     const port = parseInt(trimmed, 10)
     const resolved = await probePortBundle(port)
     if (resolved) return resolved
-    // soot's demo launcher allocates ports via `preferredPort` + shift if the
-    // preferred port is in use, so a flow YAML that hardcodes `app: 8081`
-    // breaks the day someone else binds 8081 first. probe a small window of
-    // higher ports for a metro server before giving up. only the *first* hit
-    // is used — we never scan past 3 to keep the search bounded and avoid
-    // grabbing a completely unrelated dev server.
-    const SHIFT_WINDOW = 3
-    for (let offset = 1; offset <= SHIFT_WINDOW; offset++) {
-      const shifted = await probePortBundle(port + offset)
-      if (shifted) return shifted
-    }
-    throw buildUnresolvedTargetError(
-      `localhost:${port} (also scanned +1..+${SHIFT_WINDOW})`,
-    )
+    throw buildUnresolvedTargetError(`localhost:${port}`)
   }
 
   const bundleUrl = trimmed.startsWith('http') ? trimmed : `http://${trimmed}`

package/src/home-paths.ts

@@ -14,6 +14,7 @@
 //   ├── cache/
 //   │   └── sootsim-runtime-<version>.tar.gz
 //   ├── daemon.json        lockfile: pid, ports, active runtime, heartbeat
+//   ├── dev-bridge.json    live Vite dev bridge pointer for local CLI commands
 //   └── config.json        user prefs: update channel, cdn origin override
 
 import fs from 'node:fs'
@@ -23,6 +24,7 @@ import path from 'node:path'
 export const SOOTSIM_HOME_ENV = 'SOOTSIM_HOME'
 export const ACTIVE_RUNTIME_FILE = 'active'
 export const DAEMON_LOCKFILE = 'daemon.json'
+export const DEV_BRIDGE_LOCKFILE = 'dev-bridge.json'
 export const CONFIG_FILE = 'config.json'
 export const DAEMON_HEARTBEAT_STALE_MS = 30_000
 
@@ -84,8 +86,8 @@ export function isDevWorkstation(): boolean {
 // the persistent launchd / systemd daemon must never auto-install or run on a
 // dev checkout or a dev workstation. either makes the background agent point at
 // moving workspace artifacts / dev env and serve stale assets that shadow the
-// live dev stack. install, auto-bootstrap, and the launchd-spawned `sootsim
-// server` boot all consult this; a foreground `sootsim server` the dev starts
+// live dev stack. setup and the launchd-spawned `sootsim serve` boot consult
+// this; a foreground `sootsim serve` the dev starts
 // by hand is intentional and stays allowed.
 export function shouldSkipPersistentDaemon(): boolean {
   return isSootsimDevCheckout() || isDevWorkstation()
@@ -145,6 +147,10 @@ export function daemonLockfilePath(): string {
   return path.join(sootsimHomeDir(), DAEMON_LOCKFILE)
 }
 
+export function devBridgeLockfilePath(): string {
+  return path.join(sootsimHomeDir(), DEV_BRIDGE_LOCKFILE)
+}
+
 export function configFilePath(): string {
   return path.join(sootsimHomeDir(), CONFIG_FILE)
 }
@@ -320,6 +326,18 @@ export interface DaemonLockfile {
   bootstrapping?: boolean
 }
 
+export interface DevBridgeLockfile {
+  schema: 1
+  pid: number
+  platform: NodeJS.Platform
+  bridgePort: number
+  runtimePort: number
+  cwd: string
+  startedAt: number
+  heartbeatAt: number
+  source: 'vite-dev'
+}
+
 const DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024
 
 export function readDaemonLockfile(): DaemonLockfile | null {
@@ -352,6 +370,36 @@ export function readDaemonLockfile(): DaemonLockfile | null {
   }
 }
 
+export function readDevBridgeLockfile(): DevBridgeLockfile | null {
+  try {
+    const fd = fs.openSync(devBridgeLockfilePath(), 'r')
+    try {
+      const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES)
+      const bytesRead = fs.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0)
+      const raw = buf.subarray(0, bytesRead).toString('utf8')
+      const parsed = JSON.parse(raw) as Partial<DevBridgeLockfile>
+      if (
+        parsed &&
+        parsed.schema === 1 &&
+        parsed.source === 'vite-dev' &&
+        typeof parsed.pid === 'number' &&
+        typeof parsed.bridgePort === 'number' &&
+        typeof parsed.runtimePort === 'number' &&
+        typeof parsed.cwd === 'string' &&
+        typeof parsed.startedAt === 'number' &&
+        typeof parsed.heartbeatAt === 'number'
+      ) {
+        return parsed as DevBridgeLockfile
+      }
+      return null
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
 /** true when the lockfile exists, the named pid is alive, and the heartbeat
  *  is recent. callers should reach for this before trusting any of the
  *  ports inside.
@@ -379,6 +427,20 @@ export function isDaemonLockfileFresh(
   }
 }
 
+export function isDevBridgeLockfileFresh(
+  lock: DevBridgeLockfile | null,
+  now = Date.now(),
+): lock is DevBridgeLockfile {
+  if (!lock) return false
+  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false
+  try {
+    process.kill(lock.pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
 export function writeDaemonLockfile(data: DaemonLockfile): void {
   ensureSootsimHome()
   const tmp = `${daemonLockfilePath()}.tmp`
@@ -386,6 +448,13 @@ export function writeDaemonLockfile(data: DaemonLockfile): void {
   fs.renameSync(tmp, daemonLockfilePath())
 }
 
+export function writeDevBridgeLockfile(data: DevBridgeLockfile): void {
+  ensureSootsimHome()
+  const tmp = `${devBridgeLockfilePath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, devBridgeLockfilePath())
+}
+
 /** try to claim the lockfile atomically on daemon boot. returns true if
  *  we now own it. returns false when another fresh daemon beat us to the
  *  punch — callers should refuse to start. a stale lockfile (dead pid or
@@ -406,3 +475,9 @@ export function removeDaemonLockfile(): void {
     fs.unlinkSync(daemonLockfilePath())
   } catch {}
 }
+
+export function removeDevBridgeLockfile(): void {
+  try {
+    fs.unlinkSync(devBridgeLockfilePath())
+  } catch {}
+}

package/src/host/agent-host.ts

@@ -61,7 +61,7 @@ interface PendingPromptEcho {
 export interface AgentHostOptions {
   /** callback so hosts with a soot-env context (electron, dev middleware)
    *  can inject their own exclude list. defaults to the env-derived list
-   *  the rest of the repo uses, so `sootsim server` standalone does the
+   *  the rest of the repo uses, so `sootsim serve` standalone does the
    *  right thing. */
   getExcludePorts?: () => number[]
 }