peachsim 0.1.527

package/cli/commands/box/checkout-plane.ts

@@ -0,0 +1,256 @@
+// ProjectFilePlane over a real local checkout: the second host behind the
+// seam Contrast's browser already implements. writes land on the user's actual
+// disk, so nothing here converts content: the plane reads and writes bytes.
+//
+// the file set comes from `git ls-files -co --exclude-standard`, which is the
+// project's own definition of what belongs to it. a hardcoded skip list was
+// measured against this repo and is not viable: it walked 230,229 files
+// (16.5 GB) in 4.9 s, where git returns the same project as 14,984 paths in
+// 67 ms. `index()` is a synchronous whole-project map, so the size of that set
+// is the whole cost model.
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import type { ProjectFileMeta, ProjectFilePlane } from '@rnx/box/plane'
+
+export class CheckoutRequiresGitError extends Error {}
+
+// a NUL byte is the usual "this is not text" test. it is published as metadata
+// rather than acted on here: moving a binary file is byte-exact and perfectly
+// fine, and so is deleting one, but a shell command that produced TEXT cannot
+// be allowed to overwrite it, because that text is a lossy decode of the
+// file's own bytes. BoxProjectFs owns that refusal. detecting it at write
+// time instead is not an option: just-bash's `cat` discards every readFile
+// error and reports "No such file or directory" whatever the error says, so
+// the fact has to be in the index where the filesystem layer can read it.
+const BINARY_SNIFF_BYTES = 8192
+
+// every command a box runs re-indexes first, and the index read waits on a git
+// subprocess. it used to await one, and that await could never finish: measured
+// here over 961 refreshes, the call either answered within 314ms (p50 25ms) or
+// never answered at all, once for 29 seconds while the process's own timer kept
+// firing every second. that is not a slow git, it is a lost answer, and no
+// budget reaches it.
+//
+// a deadline on the async form does not help either, which is why this is
+// synchronous. node's `execFile` timeout kills the child and then still waits
+// for a 'close' event to settle the promise, so the lost event takes the
+// deadline down with it: the bound below was armed and silent through all 29
+// of those seconds. `execFileSync` waits in the runtime instead of on a
+// javascript event, so there is nothing to miss, and its timeout is enforced
+// the same way.
+//
+// it costs nothing. the entry loop below is already synchronous stat and read,
+// and under 24-way load the two forms were indistinguishable over 960 calls
+// each, interleaved: p50 1529ms synchronous against 1520ms asynchronous.
+//
+// 10s is roughly fifteen times the slowest full refresh measured on a
+// 14,889-file checkout (430-840 ms, of which `git ls-files` itself is 67 ms),
+// so it cannot fire for a project that is merely large or a machine that is
+// merely busy.
+const LIST_FILES_TIMEOUT_MS = 10_000
+
+// the same busy machine fails this call in two ways that are both a failed
+// READ rather than an answer: the spawn raises, and a child exits 0 having
+// written nothing. docs/testing.md measured the second one directly on
+// 2026-08-27 under CPU oversubscription, where a git child exited 0 with empty
+// stdout while the very next `/bin/echo` read back fine.
+//
+// the answer to a failed read is to read again. every box command re-indexes
+// before it runs, so a single lost answer is otherwise the difference between
+// `touch created.txt` working and the box telling the user it has no file set
+// to serve: measured here as exit 1 in 103ms, which is what took the box
+// conformance suite red under a load average of 47. the conditions the two
+// tests in test/rnxBoxCheckoutPlane.test.ts hold (a git that never answers, a
+// git that always answers with nothing) are permanent, so they still fail, and
+// they fail naming the same thing.
+const LIST_FILES_ATTEMPTS = 3
+const LIST_FILES_RETRY_MS = 25
+
+function looksBinary(filePath: string, size: number): boolean {
+  if (size === 0) return false
+  let fd: number | undefined
+  try {
+    fd = fs.openSync(filePath, 'r')
+    const buffer = Buffer.alloc(Math.min(BINARY_SNIFF_BYTES, size))
+    const read = fs.readSync(fd, buffer, 0, buffer.length, 0)
+    return buffer.subarray(0, read).includes(0)
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd)
+  }
+}
+
+// the box re-indexes before every command, so the sniff above runs against the
+// whole project every time a user presses return. on a 14,889-file checkout
+// that is 277-644 ms of a 430-840 ms refresh, and nearly all of it re-reads
+// files that did not change. a file whose size and mtime both match the last
+// look has the same first 8 KB, so remember the answer against those two.
+// `statSync` already returns mtimeMs, and it carries sub-millisecond
+// resolution here, so the window in which a same-size rewrite could hide is
+// narrower than a millisecond rather than git's one-second racy-clean case.
+interface SniffedFile {
+  size: number
+  mtimeMs: number
+  binary: boolean
+}
+
+export class CheckoutFilePlane implements ProjectFilePlane {
+  readonly root: string
+  private entries = new Map<string, ProjectFileMeta>()
+  private sniffed = new Map<string, SniffedFile>()
+  // the deadline above, as a number a caller can set. what it changes is how
+  // long a wedged git is waited on, never whether it is waited on, so proving
+  // the kill does not have to cost the production deadline.
+  private readonly listTimeoutMs: number
+  private readonly trackedOnly: boolean
+
+  constructor(
+    root: string,
+    options: { listTimeoutMs?: number; trackedOnly?: boolean } = {},
+  ) {
+    this.root = path.resolve(root)
+    this.listTimeoutMs = options.listTimeoutMs ?? LIST_FILES_TIMEOUT_MS
+    this.trackedOnly = options.trackedOnly ?? false
+  }
+
+  index(): ReadonlyMap<string, ProjectFileMeta> {
+    return this.entries
+  }
+
+  private listFiles(): string {
+    // -z keeps paths containing spaces or newlines intact. a local Box sees
+    // tracked plus visible untracked files, while a durable cloud import is
+    // deliberately restricted to the checkout's tracked source.
+    const args = this.trackedOnly
+      ? ['ls-files', '-z']
+      : ['ls-files', '-co', '--exclude-standard', '-z']
+    const stdout = execFileSync('git', args, {
+      cwd: this.root,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      timeout: this.listTimeoutMs,
+      // stating the environment is not redundant here. bun 1.3.14 resolves
+      // the binary for the synchronous form against the PATH it captured at
+      // startup and ignores a later change to `process.env.PATH`, so without
+      // this it runs a different git than every other call in the process.
+      env: process.env,
+    })
+    // empty child output never means an empty answer. without this the box
+    // would build an empty index and every read would report the file as
+    // missing, which is a broken project rather than a broken box, and nothing
+    // would say so.
+    if (stdout.length === 0) {
+      throw new CheckoutRequiresGitError(
+        `git listed no ${this.trackedOnly ? 'tracked ' : ''}files in ${this.root}. either the checkout contains no eligible files, or this machine could not read the child process's output.`,
+      )
+    }
+    return stdout
+  }
+
+  async refresh(): Promise<void> {
+    let stdout = ''
+    let lastFailure: CheckoutRequiresGitError | undefined
+    for (let attempt = 1; attempt <= LIST_FILES_ATTEMPTS; attempt++) {
+      try {
+        stdout = this.listFiles()
+        lastFailure = undefined
+        break
+      } catch (error) {
+        if (error instanceof CheckoutRequiresGitError) {
+          lastFailure = error
+        } else {
+          const message = error instanceof Error ? error.message : String(error)
+          // the deadline kills with SIGTERM, so that signal is what tells a
+          // bound run apart from git failing on its own terms, and it is worth
+          // naming separately: "git was killed by SIGTERM" reads as git's
+          // problem, when what happened is that it never answered.
+          const killed =
+            error instanceof Error && 'signal' in error && error.signal === 'SIGTERM'
+          lastFailure = new CheckoutRequiresGitError(
+            killed
+              ? `git did not list the project's files in ${this.root} within ${this.listTimeoutMs / 1000}s, so the box has no file set to serve. the checkout may be on a stalled filesystem, or this machine may be too loaded to start a subprocess.`
+              : `could not list the project's files with git in ${this.root}: ${message}`,
+          )
+        }
+        if (attempt < LIST_FILES_ATTEMPTS) {
+          await new Promise((resolve) =>
+            setTimeout(resolve, LIST_FILES_RETRY_MS * attempt),
+          )
+        }
+      }
+    }
+    if (lastFailure) {
+      lastFailure.message = `${lastFailure.message} (${LIST_FILES_ATTEMPTS} attempts)`
+      throw lastFailure
+    }
+
+    const next = new Map<string, ProjectFileMeta>()
+    // rebuilt alongside the index rather than pruned, so a deleted file's
+    // record cannot outlive it in a box that stays open all day
+    const nextSniffed = new Map<string, SniffedFile>()
+    for (const relative of stdout.split('\0')) {
+      if (!relative) continue
+      let stat: fs.Stats
+      try {
+        stat = fs.statSync(path.join(this.root, relative))
+      } catch {
+        // listed but gone (a deleted-but-tracked file); it is simply not there
+        continue
+      }
+      if (!stat.isFile()) continue
+      const seen = this.sniffed.get(relative)
+      const binary =
+        seen && seen.size === stat.size && seen.mtimeMs === stat.mtimeMs
+          ? seen.binary
+          : looksBinary(path.join(this.root, relative), stat.size)
+      nextSniffed.set(relative, { size: stat.size, mtimeMs: stat.mtimeMs, binary })
+      next.set(relative, {
+        size: stat.size,
+        // a checkout carries no write policy of its own; if the user can write
+        // the file, so can the shell
+        readOnly: false,
+        binary,
+      })
+    }
+    this.entries = next
+    this.sniffed = nextSniffed
+  }
+
+  private absolute(planePath: string): string {
+    const resolved = path.resolve(this.root, planePath)
+    // the shell resolves "." and ".." before calling us, but the plane owns the
+    // checkout boundary and must not depend on that.
+    if (resolved !== this.root && !resolved.startsWith(`${this.root}${path.sep}`)) {
+      throw new Error(`path escapes the project: ${planePath}`)
+    }
+    return resolved
+  }
+
+  async read(planePath: string): Promise<string> {
+    return fs.promises.readFile(this.absolute(planePath), 'utf8')
+  }
+
+  async readBytes(planePath: string): Promise<Uint8Array> {
+    return fs.promises.readFile(this.absolute(planePath))
+  }
+
+  async write(planePath: string, content: Uint8Array): Promise<void> {
+    const absolute = this.absolute(planePath)
+    await fs.promises.mkdir(path.dirname(absolute), { recursive: true })
+    await fs.promises.writeFile(absolute, content)
+    this.entries.set(planePath, {
+      size: content.byteLength,
+      readOnly: false,
+      // the bytes are in hand, so the same NUL test costs nothing here
+      binary: content.subarray(0, BINARY_SNIFF_BYTES).includes(0),
+    })
+  }
+
+  async delete(planePath: string): Promise<void> {
+    await fs.promises.rm(this.absolute(planePath), { force: true })
+    this.entries.delete(planePath)
+  }
+}

package/cli/commands/box/plane-share.ts

@@ -0,0 +1,208 @@
+// a local box authorizing its own checkout for browser access.
+//
+// the bridge daemon serves the `plane:*` envelope, but it will not open a root
+// nobody has authorized, because a WebSocket to 127.0.0.1 is not subject to
+// CORS and any page the user visits can open one. so the box registers its
+// root and holds the socket for as long as it runs; when the box exits, the
+// registration goes with it and the tab loses reach.
+//
+// THIS NEVER BLOCKS THE BOX. an earlier version awaited the socket before
+// printing the prompt and cost 1450ms of start time on every box, because a
+// daemon built before `plane:*` existed accepts the socket, ignores the
+// message, and never replies, so the client sat on its timeout. a box that
+// cannot share its plane is a box with one capability missing, not a box that
+// starts slowly.
+//
+// IT ALSO REFUSES TO GUESS A PORT. when no lockfile claims a bridge,
+// resolveBridgeWorld reports source 'default' and hands back
+// DEFAULT_SOOTSIM_BRIDGE_PORT, which on a machine running a real daemon is
+// that daemon. registering there would attach a test's or a benchmark's box to
+// another session's daemon, which is exactly what a private RNX_HOME
+// exists to prevent. so a guessed port is refused by name.
+
+import { WebSocket } from 'ws'
+import { bridgeWsUrl, resolveBridgeWorld } from '../../ws-bridge'
+
+const REGISTER_TIMEOUT_MS = 1500
+
+export interface PlaneShare {
+  /**
+   * resolves when the daemon has accepted the root, or with a reason it did
+   * not. `holders` is how many boxes now hold this checkout, including this
+   * one, so more than one means another box is writing the same tree.
+   */
+  readonly settled: Promise<{ port: number; holders: number } | { declined: string }>
+  close(): void
+}
+
+function target(
+  explicitPort: number | undefined,
+): { port: number } | { declined: string } {
+  if (explicitPort) return { port: explicitPort }
+  const world = resolveBridgeWorld()
+  if (world.source === 'default') {
+    return {
+      declined:
+        'no daemon or dev bridge claims a port, and the default is another session’s daemon on a shared machine',
+    }
+  }
+  return { port: world.bridgePort }
+}
+
+/**
+ * register `root` with the bridge daemon in the background. returns
+ * immediately; the box never waits on it.
+ */
+export function sharePlane(root: string, opts: { port?: number } = {}): PlaneShare {
+  const chosen = target(opts.port)
+  if ('declined' in chosen) {
+    return { settled: Promise.resolve(chosen), close: () => {} }
+  }
+
+  const port = chosen.port
+  let socket: WebSocket | null = null
+  let closed = false
+
+  const settled = new Promise<{ port: number; holders: number } | { declined: string }>(
+    (resolve) => {
+      let done = false
+      const finish = (
+        value: { port: number; holders: number } | { declined: string },
+      ) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        resolve(value)
+      }
+
+      const timer = setTimeout(() => {
+        // an older daemon accepts the socket and ignores plane:* entirely, so
+        // silence is the expected shape of "not supported" rather than a fault.
+        socket?.close()
+        finish({ declined: `bridge on port ${port} did not answer plane:register` })
+      }, REGISTER_TIMEOUT_MS)
+
+      try {
+        socket = new WebSocket(bridgeWsUrl(port))
+      } catch (error) {
+        finish({ declined: error instanceof Error ? error.message : String(error) })
+        return
+      }
+      if (closed) {
+        socket.close()
+        finish({ declined: 'box exited before the plane registered' })
+        return
+      }
+
+      socket.on('error', (error) => finish({ declined: error.message }))
+      socket.on('close', () => finish({ declined: `bridge on port ${port} closed` }))
+      socket.on('open', () => {
+        // node sends no Origin, so this socket is already cli-role. a browser
+        // client has to send bridge:hello to be corrected off the provisional
+        // sim role; see plans/rnx-cloud/transport-decision.md.
+        socket?.send(JSON.stringify({ type: 'plane:register', id: 'register', root }))
+      })
+      socket.on('message', (data) => {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(String(data))
+        } catch {
+          return
+        }
+        if (typeof parsed !== 'object' || parsed === null) return
+        const reply: Record<string, unknown> = { ...parsed }
+        if (reply.id !== 'register') return
+        if (reply.error) {
+          socket?.close()
+          finish({ declined: String(reply.error) })
+          return
+        }
+        // the daemon nests its payload under `result`; reading holders off the
+        // envelope silently reported 1 forever, which is the exact silence this
+        // field exists to remove.
+        const result = (reply.result ?? {}) as Record<string, unknown>
+        finish({ port, holders: Number(result.holders ?? 1) })
+      })
+    },
+  )
+
+  return {
+    settled,
+    close: () => {
+      closed = true
+      try {
+        socket?.close()
+      } catch {}
+    },
+  }
+}
+
+/**
+ * How many boxes hold `root` right now, without registering anything.
+ *
+ * `plane:register` cannot answer this: registering is what makes a root
+ * reachable over a loopback socket, so a readiness probe that asked with it
+ * would both authorize the root and count itself in the answer.
+ */
+export async function planeStatus(
+  root: string,
+  opts: { port?: number } = {},
+): Promise<{ holders: number; registered: boolean } | { declined: string }> {
+  const chosen = target(opts.port)
+  if ('declined' in chosen) return chosen
+  const port = chosen.port
+
+  return new Promise((resolve) => {
+    let done = false
+    let socket: WebSocket | null = null
+    const finish = (
+      value: { holders: number; registered: boolean } | { declined: string },
+    ) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      try {
+        socket?.close()
+      } catch {}
+      resolve(value)
+    }
+    const timer = setTimeout(
+      () => finish({ declined: `bridge on port ${port} did not answer plane:status` }),
+      REGISTER_TIMEOUT_MS,
+    )
+
+    try {
+      socket = new WebSocket(bridgeWsUrl(port))
+    } catch (error) {
+      finish({ declined: error instanceof Error ? error.message : String(error) })
+      return
+    }
+    socket.on('error', (error) => finish({ declined: error.message }))
+    socket.on('close', () => finish({ declined: `bridge on port ${port} closed` }))
+    socket.on('open', () => {
+      socket?.send(JSON.stringify({ type: 'plane:status', id: 'status', root }))
+    })
+    socket.on('message', (data) => {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(String(data))
+      } catch {
+        return
+      }
+      if (typeof parsed !== 'object' || parsed === null) return
+      const reply: Record<string, unknown> = { ...parsed }
+      if (reply.id !== 'status') return
+      if (reply.error) {
+        finish({ declined: String(reply.error) })
+        return
+      }
+      // the daemon nests its payload under `result`, the same shape
+      // plane:register answers in.
+      const result = (reply.result ?? {}) as Record<string, unknown>
+      finish({
+        holders: Number(result.holders ?? 0),
+        registered: Boolean(result.registered),
+      })
+    })
+  })
+}

package/cli/commands/box/rnx-command.ts

@@ -0,0 +1,60 @@
+// step 4: RNX operations registered as just-bash commands.
+//
+// `rnx` inside a box shell is the same CLI, re-invoked as a child process with
+// the shell's own cwd. that is deliberate — spelling the verbs a second time
+// in shell-command form would be a second implementation of every command, and
+// the spec is explicit that the CLI and the in-shell commands are clients of
+// one implementation, not two.
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { defineCommand, type CustomCommand } from '@rnx/box/shell'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
+import { rnxPublicBrand } from '../../../src/public-brand'
+import { rnxSelfInvocation } from '../../self-invocation'
+import { RNX_PLACEMENT_ENV } from '../../ws-bridge'
+
+// map a shell path under /project back onto the real checkout, so a child
+// process started from `cd src && rnx describe` sees the directory the user
+// is actually standing in.
+function hostCwd(root: string, shellCwd: string): string {
+  if (shellCwd === PROJECT_MOUNT) return root
+  if (!shellCwd.startsWith(`${PROJECT_MOUNT}/`)) return root
+  return path.join(root, shellCwd.slice(PROJECT_MOUNT.length + 1))
+}
+
+export function createRnxCommand(options: {
+  root: string
+  shellCwd: () => string
+}): CustomCommand {
+  return defineCommand(rnxPublicBrand.commandName, async (args) => {
+    const { executable, prefixArgs } = rnxSelfInvocation()
+    const child = spawn(executable, [...prefixArgs, ...args], {
+      cwd: hostCwd(options.root, options.shellCwd()),
+      // mark the child as running inside a local box. this is the only thing
+      // that sets a placement — nothing infers one from cwd — and it is what
+      // lets `rnx box` refuse to nest inside itself.
+      env: { ...process.env, [RNX_PLACEMENT_ENV]: 'local-box' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk)
+    })
+
+    const exitCode = await new Promise<number>((resolve) => {
+      child.once('error', (error) => {
+        stderr += `${rnxPublicBrand.commandName}: ${error.message}\n`
+        resolve(1)
+      })
+      child.once('close', (code) => resolve(code ?? 0))
+    })
+
+    return { stdout, stderr, exitCode }
+  })
+}

package/cli/commands/box/search-command.ts

@@ -0,0 +1,157 @@
+// `rg` inside a local box, run by git rather than by a JavaScript matcher.
+//
+// just-bash implements rg in JavaScript and reads every file body through the
+// plane, so one search of this repo is ~15,000 plane reads. MEASURED in the box
+// shell: 14,093ms and two lines of output, which are its abort message. It does
+// not return results at all, and searching is the most common thing an agent
+// does, so that is the box being unusable on a real project.
+//
+// WHY GIT GREP AND NOT RIPGREP. The first version of this shelled out to `rg`,
+// which turned CI red: the Linux runners have no ripgrep binary, and a box that
+// depends on whatever happens to be installed on the host is not a box. Git is
+// different in kind, not degree: `CheckoutFilePlane` already REFUSES to open a
+// project that is not a git repository and runs `git ls-files` before every
+// single command, so git is a hard, already-enforced requirement. Searching
+// with it adds no dependency and cannot be absent where the box already runs.
+//
+// It also makes the file set correct BY CONSTRUCTION rather than by agreement.
+// The box indexes `git ls-files -co --exclude-standard`, tracked AND
+// untracked-not-ignored, and `git grep --untracked` applies those same rules
+// from the same tool. RAN against a checkout built to expose the difference:
+// tracked, untracked-not-ignored, a dotfile and a dotdir file all match, and
+// gitignored trees do not. Ripgrep needed the plane's path list piped into it
+// to get there, because plain `rg .` silently misses dotfiles and `rg --hidden`
+// searches .git/**.
+//
+// MEASURED on this repo, 14,949 indexed files: 391ms p50 against ripgrep's
+// 260ms and just-bash's 14,093ms. Giving up 130ms to remove a host dependency
+// and an entire class of "works on my machine" is the right trade.
+//
+// It also removes the ARG_MAX chunking the ripgrep version needed. Git walks
+// its own index, so there is one process and one exit code rather than several
+// whose "no match here" had to be merged.
+
+import { spawn } from 'node:child_process'
+import { defineCommand, type CustomCommand } from '@rnx/box/shell'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
+
+// generous next to a 414ms p95: this bounds a wedged child, it does not cut off
+// a large search.
+const SEARCH_DEADLINE_MS = 20_000
+
+/**
+ * THE DEADLINE SETTLES THIS PROMISE ITSELF rather than only killing the child.
+ * A spawned child's answer has been observed going missing while the process
+ * stayed alive, with no one able to say which event never arrived, so nothing
+ * that waits on a child event can be trusted to settle. A timer in this process
+ * cannot be missed, so it is the authority and the kill is a side effect.
+ * See docs/testing.md.
+ */
+function runGitGrep(args: string[], cwd: string) {
+  return new Promise<{ stdout: string; stderr: string; exitCode: number }>((resolve) => {
+    const child = spawn('git', args, {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (exitCode: number) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ stdout, stderr, exitCode })
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      } catch {}
+      stderr += `rg: search timed out after ${SEARCH_DEADLINE_MS}ms\n`
+      finish(2)
+    }, SEARCH_DEADLINE_MS)
+
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk)
+    })
+    child.once('error', (error) => {
+      stderr += `rg: ${error.message}\n`
+      finish(2)
+    })
+    child.once('close', (code) => finish(code ?? 0))
+  })
+}
+
+// the rg flags worth honouring, mapped onto git grep's spelling. anything else
+// is REFUSED BY NAME rather than dropped, because a search that silently
+// ignores `-i` returns a confidently wrong answer.
+const FLAG_MAP: Record<string, string> = {
+  '-i': '-i',
+  '--ignore-case': '-i',
+  '-l': '-l',
+  '--files-with-matches': '-l',
+  '-w': '-w',
+  '--word-regexp': '-w',
+  '-c': '-c',
+  '--count': '-c',
+  '-v': '-v',
+  '--invert-match': '-v',
+  '-F': '-F',
+  '--fixed-strings': '-F',
+}
+
+export function createSearchCommand(options: { root: string }): CustomCommand {
+  return defineCommand('rg', async (args) => {
+    const flags: string[] = []
+    const bare: string[] = []
+    for (const arg of args) {
+      if (!arg.startsWith('-')) {
+        bare.push(arg)
+        continue
+      }
+      const mapped = FLAG_MAP[arg]
+      if (!mapped) {
+        return {
+          stdout: '',
+          stderr: `rg: this box does not support ${arg}\n`,
+          exitCode: 2,
+        }
+      }
+      flags.push(mapped)
+    }
+
+    const pattern = bare.shift()
+    if (pattern === undefined) {
+      return { stdout: '', stderr: 'rg: no pattern given\n', exitCode: 2 }
+    }
+
+    // paths are project-relative to git; strip the shell's mount prefix so
+    // `rg x /project/src` and `rg x src` mean the same thing.
+    const scopes = bare.map((p) =>
+      p.startsWith(`${PROJECT_MOUNT}/`) ? p.slice(PROJECT_MOUNT.length + 1) : p,
+    )
+
+    // --untracked is what makes this the plane's set rather than git's tracked
+    // set. -E for extended regex, the closest of git's grammars to ripgrep's.
+    // -e so a pattern beginning with a dash is a pattern, not a flag.
+    const result = await runGitGrep(
+      [
+        'grep',
+        '--no-color',
+        '-n',
+        '-I',
+        '--untracked',
+        '-E',
+        ...flags,
+        '-e',
+        pattern,
+        ...(scopes.length > 0 ? ['--', ...scopes] : []),
+      ],
+      options.root,
+    )
+    return result
+  })
+}