rnxsim 0.1.381 → 0.1.382

package/cli/cloud-session.ts

@@ -0,0 +1,156 @@
+import { fstatSync, writeSync } from 'node:fs'
+import { isLoopbackHost } from '../src/backend-origin'
+
+const CLOUD_SESSION_VERSION = 1 as const
+const SHELL_UPDATE_FD_ENV = 'RNX_SHELL_UPDATE_FD'
+const MAX_ENCODED_SESSION_BYTES = 32 * 1024
+
+export const RNX_CLOUD_SESSION_ENV = 'RNX_CLOUD_SESSION'
+export const RNX_SHELL_UPDATE_PREFIX = '__RNX_SHELL_UPDATE_V1__'
+export const RNX_SHELL_UPDATE_SET_PREFIX = `${RNX_SHELL_UPDATE_PREFIX}set:`
+export const RNX_SHELL_UPDATE_UNSET = `${RNX_SHELL_UPDATE_PREFIX}unset`
+
+export interface CloudSession {
+  version: 1
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function normalizeCloudOrigin(source: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(source)
+  } catch {
+    throw new Error(`invalid RNX Cloud origin: ${source}`)
+  }
+  if (
+    (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') ||
+    parsed.username ||
+    parsed.password ||
+    parsed.pathname !== '/' ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`RNX Cloud origin must be an HTTP(S) origin: ${source}`)
+  }
+  if (parsed.protocol === 'http:' && !isLoopbackHost(parsed.hostname)) {
+    throw new Error(`RNX Cloud origin requires HTTPS outside loopback: ${source}`)
+  }
+  return parsed.origin
+}
+
+export function createCloudSession(input: {
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+}): CloudSession {
+  const session = {
+    version: CLOUD_SESSION_VERSION,
+    simId: input.simId.trim(),
+    apiOrigin: normalizeCloudOrigin(input.apiOrigin.trim()),
+    claimId: input.claimId.trim(),
+    token: input.token,
+  } satisfies CloudSession
+  if (!session.simId || !session.claimId || !session.token) {
+    throw new Error('cloud session requires simulator, origin, claim, and token')
+  }
+  return session
+}
+
+export function serializeCloudSession(session: CloudSession): string {
+  return Buffer.from(JSON.stringify(createCloudSession(session)), 'utf8').toString(
+    'base64url',
+  )
+}
+
+export function parseCloudSession(encoded: string): CloudSession {
+  const value = encoded.trim()
+  if (
+    !value ||
+    value.length > MAX_ENCODED_SESSION_BYTES ||
+    !/^[A-Za-z0-9_-]+$/.test(value)
+  ) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  let parsed: unknown
+  try {
+    const bytes = Buffer.from(value, 'base64url')
+    if (bytes.toString('base64url') !== value) {
+      throw new Error('non-canonical cloud session')
+    }
+    parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+  } catch {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  if (!isRecord(parsed) || parsed.version !== CLOUD_SESSION_VERSION) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  const simId = parsed.simId
+  const apiOrigin = parsed.apiOrigin
+  const claimId = parsed.claimId
+  const token = parsed.token
+  if (
+    typeof simId !== 'string' ||
+    typeof apiOrigin !== 'string' ||
+    typeof claimId !== 'string' ||
+    typeof token !== 'string'
+  ) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  try {
+    return createCloudSession({ simId, apiOrigin, claimId, token })
+  } catch {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+}
+
+export function readCloudSession(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): CloudSession | null {
+  const encoded = environment[RNX_CLOUD_SESSION_ENV]
+  return encoded?.trim() ? parseCloudSession(encoded) : null
+}
+
+function shellUpdateFd(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): number | null {
+  const source = environment[SHELL_UPDATE_FD_ENV]
+  if (!source) return null
+  const descriptor = Number(source)
+  if (!Number.isSafeInteger(descriptor) || descriptor < 3) {
+    throw new Error('RNX shell integration provided an invalid update channel')
+  }
+  try {
+    fstatSync(descriptor)
+  } catch {
+    throw new Error('RNX shell integration update channel is unavailable')
+  }
+  return descriptor
+}
+
+export function requireCloudSessionShellUpdate(): number {
+  const descriptor = shellUpdateFd()
+  if (descriptor === null) {
+    throw new Error(
+      'RNX shell integration is required so this cloud session stays in the current shell; restart the shell after installing RNX',
+    )
+  }
+  return descriptor
+}
+
+export function publishCloudSessionToShell(
+  session: CloudSession | null,
+  descriptor = requireCloudSessionShellUpdate(),
+): void {
+  const update = session
+    ? `${RNX_SHELL_UPDATE_SET_PREFIX}${serializeCloudSession(session)}`
+    : RNX_SHELL_UPDATE_UNSET
+  writeSync(descriptor, `${update}\n`)
+}

package/cli/command-contract.ts

@@ -67,8 +67,8 @@ export interface RnxParsedCommandInput {
 
 export interface RnxPreviewInvocation extends RnxInvocationBase {
   family: 'preview'
-  command: 'web' | 'ios'
-  platform: 'web' | 'ios'
+  command: 'web' | 'ios' | 'android'
+  platform: 'web' | 'ios' | 'android'
   selection: 'select-or-ensure-existing'
 }
 

package/cli/command-registry.ts

@@ -74,6 +74,7 @@ const NODE_COMMAND_NAMES = [
 const BROWSER_FAMILIES = new Map<string, RnxBrowserCommandFamily>([
   ['web', 'preview'],
   ['ios', 'preview'],
+  ['android', 'preview'],
   ['list', 'runtime'],
   ['use', 'runtime'],
   ['state', 'runtime'],
@@ -248,6 +249,14 @@ export function createRnxCommandInvocation(
         platform: 'ios',
         selection: 'select-or-ensure-existing',
       }
+    case 'android':
+      return {
+        ...common,
+        family: 'preview',
+        command: 'android',
+        platform: 'android',
+        selection: 'select-or-ensure-existing',
+      }
     case 'describe':
       return { ...common, family: 'tree' }
     case 'find':

package/cli/commands/agent-wrapper.ts

@@ -1,10 +1,10 @@
-// agent-wrapper — long-running bridge process between sootsim desktop and a
+// agent-wrapper — long-running bridge process between rnx desktop and a
 // local coding agent (codex / claude).
 //
-// shipped as an internal sootsim CLI subcommand so it survives `bun build
+// shipped as an internal rnx CLI subcommand so it survives `bun build
 // --compile` bundling. callers spawn it as:
 //
-//   sootsim agent-wrapper \
+//   rnx agent-wrapper \
 //     --session-id <id> --project-id <id> --provider codex \
 //     --cwd <path> --prompt-in <fifo> --events-out <fifo> \
 //     [--transcript <file>]
@@ -407,7 +407,7 @@ export async function runAgentWrapper(argv: string[]): Promise<number> {
   }
 
   // open prompt.in with O_RDWR so our own write end keeps the FIFO alive
-  // across external writer open/close cycles. `sootsim agent prompt` opens,
+  // across external writer open/close cycles. `rnx agent prompt` opens,
   // writes one line, closes — without a self-writer the reader would EOF
   // after the first prompt and subsequent prompts would be lost.
   const promptFd = openSync(promptIn, fsConstants.O_RDWR)

package/cli/commands/agent.ts

@@ -1,4 +1,4 @@
-// user-facing `sootsim agent` command tree.
+// user-facing `rnx agent` command tree.
 //
 // session-lifecycle commands (start, prompt, end, watch) route through
 // the bridge daemon — the daemon owns the single FIFO reader per
@@ -8,7 +8,7 @@
 //
 // disk-only inspection commands (projects, sessions, paths, transcript,
 // attach, project show/remove) read the attached-projects JSON directly —
-// no daemon needed, so `sootsim agent projects` stays fast when no
+// no daemon needed, so `rnx agent projects` stays fast when no
 // wrapper is live.
 
 import fs from 'node:fs'
@@ -96,7 +96,7 @@ async function withDaemon<T>(fn: (client: AgentDaemonClient) => Promise<T>): Pro
 }
 
 function printHelp(): void {
-  // delegate to the meta-driven renderer so bare `sootsim agent`, `--help`,
+  // delegate to the meta-driven renderer so bare `rnx agent`, `--help`,
   // and `unknown subcommand` paths all show the same rich help (header,
   // options, examples) instead of a sparse hand-coded summary.
   printCommandHelp('agent')

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

@@ -12,7 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
-import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness/plane'
+import type { ProjectFileMeta, ProjectFilePlane } from '@rnx/box/plane'
 
 export class CheckoutRequiresGitError extends Error {}
 
@@ -20,7 +20,7 @@ export class CheckoutRequiresGitError extends Error {}
 // 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. HarnessProjectFs owns that refusal. detecting it at write
+// 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.
@@ -88,10 +88,15 @@ export class CheckoutFilePlane implements ProjectFilePlane {
   // 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 } = {}) {
+  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> {
@@ -101,10 +106,13 @@ export class CheckoutFilePlane implements ProjectFilePlane {
   async refresh(): Promise<void> {
     let stdout: string
     try {
-      // -z so paths containing spaces or newlines survive; -co --exclude-standard
-      // is tracked plus untracked-not-ignored, which is what a person means by
-      // "the files in my project".
-      stdout = execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+      // -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']
+      stdout = execFileSync('git', args, {
         cwd: this.root,
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
@@ -137,7 +145,7 @@ export class CheckoutFilePlane implements ProjectFilePlane {
     // than a broken box, and nothing would say so.
     if (stdout.length === 0) {
       throw new CheckoutRequiresGitError(
-        `git listed no files in ${this.root}. either git tracks nothing there and nothing untracked is visible to it, or this machine could not read the child process's output.`,
+        `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.`,
       )
     }
 

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

@@ -8,8 +8,8 @@
 
 import { spawn } from 'node:child_process'
 import path from 'node:path'
-import { defineCommand, type CustomCommand } from '@contrast/harness/shell'
-import { PROJECT_MOUNT } from '@contrast/harness/shell'
+import { defineCommand, type CustomCommand } from '@rnx/box/shell'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
 import { rnxPublicBrand } from '../../../src/public-brand'
 import { RNX_PLACEMENT_ENV } from '../../ws-bridge'
 

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

@@ -32,8 +32,8 @@
 // whose "no match here" had to be merged.
 
 import { spawn } from 'node:child_process'
-import { defineCommand, type CustomCommand } from '@contrast/harness/shell'
-import { PROJECT_MOUNT } from '@contrast/harness/shell'
+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.

package/cli/commands/box.ts

@@ -1,48 +1,40 @@
 // `rnx box` — the box environment.
 //
-// bare `rnx box` is LOCAL and mounts the current checkout at /project. `rnx box
-// create` provisions a durable cloud box. everything else in the namespace is
-// cloud lifecycle. the cloud side is not built yet; those verbs fail by name
-// and say what works instead, so nothing advertises a capability that always
-// fails.
+// bare `rnx box` is LOCAL and mounts the current checkout at /project. cloud
+// create provisions through the shared client and enters the same shell unless
+// --json asks for a noninteractive result. reconnect still needs an authorized
+// provider lookup from public box identity to the provider reference.
 
 import path from 'node:path'
 import { createInterface } from 'node:readline'
-import {
-  createHarnessShell,
-  HarnessProjectFs,
-  PROJECT_MOUNT,
-} from '@contrast/harness/shell'
+import { BoxClientError, createBoxClient } from '@rnx/box/client'
+import { createBoxHostProvider } from '@rnx/box/host'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
+import { terminalBoxStack } from '@rnx/box/stack'
+import { BoxTemplateRegistry, terminalBoxTemplate } from '@rnx/box/template'
+import { createCloudBoxProvider, heartbeatSession } from 'rnx-cloud-box/client'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { authHeaderOrExit } from '../auth'
 import { findRepositoryPackageRoot } from '../setup-repository'
 import { resolvePlacement } from '../ws-bridge'
 import { CheckoutFilePlane, CheckoutRequiresGitError } from './box/checkout-plane'
-import {
-  CloudBoxError,
-  connectCloudBox,
-  createCloudBox,
-  heartbeatSession,
-  listCloudBoxes,
-  stopCloudBox,
-} from './box/cloud-box'
 import { sharePlane } from './box/plane-share'
 import { createRnxCommand } from './box/rnx-command'
 import { createSearchCommand } from './box/search-command'
-import type { HarnessShellResult } from '@contrast/harness/shell'
+import type { BoxShellSession } from '@rnx/box/client'
+import type { BoxTemplateResolution } from '@rnx/box/template'
 
 interface BoxCommandOptions {
   port?: number
   verbose?: boolean
 }
 
-const CLOUD_SUBCOMMANDS = new Set(['connect'])
-
 // no default. a cloud box service has to be deployed before one can exist, and
 // defaulting to an origin that answers nothing would advertise a capability
 // that always fails.
 const ENDPOINT_ENV = 'RNX_BOX_ENDPOINT'
 const API_ORIGIN_ENV = 'RNX_API_ORIGIN'
+const BOX_TEMPLATES = new BoxTemplateRegistry([terminalBoxTemplate])
 
 function usage(): void {
   const rnx = rnxPublicBrand.commandName
@@ -53,9 +45,12 @@ function usage(): void {
     ${rnx} box                     start a local box over the current checkout
     ${rnx} box create              create a cloud box and enter its shell
     ${rnx} box create --name=<n>   create a named cloud box
+    ${rnx} box create --template=<id>
+                                   create from a registered Box template
     ${rnx} box create --endpoint=<url>
                                    the box service to create it in, or set
                                    ${ENDPOINT_ENV}
+    ${rnx} box create --json       create without entering the shell
     ${rnx} box ls                  cloud boxes running on this account
     ${rnx} box stop --name=<n>     stop a cloud box and its billing
     ${rnx} box delete --name=<n>   stop it and wipe its files
@@ -89,18 +84,18 @@ export async function runBox(
 
   const subcommand = args.find((arg) => !arg.startsWith('-'))
   if (subcommand === 'create') return runCloudBoxCreate(args, opts)
+  if (subcommand === 'connect') {
+    console.error(
+      `  ${rnxPublicBrand.commandName} box connect: the cloud provider cannot yet resolve a Box ID or name to an authorized Box reference.\n` +
+        `  the shared Box client requires that reference's access token, and the CLI does not persist Box tokens.`,
+    )
+    return 1
+  }
   if (subcommand === 'stop' || subcommand === 'delete') {
     return runCloudBoxStop(args, subcommand === 'delete')
   }
   if (subcommand === 'ls') return runCloudBoxList(args)
   if (subcommand !== undefined) {
-    if (CLOUD_SUBCOMMANDS.has(subcommand)) {
-      console.error(
-        `  ${rnxPublicBrand.commandName} box ${subcommand} needs a cloud box, which is not built yet.\n` +
-          `  \`${rnxPublicBrand.commandName} box\` runs the same shell locally over this checkout.`,
-      )
-      return 1
-    }
     console.error(
       `  unknown command: ${rnxPublicBrand.commandName} box ${subcommand}\n` +
         `  run \`${rnxPublicBrand.commandName} box --help\` to see the box surface.`,
@@ -108,6 +103,13 @@ export async function runBox(
     return 1
   }
 
+  if (args.includes('--json')) {
+    console.error(
+      `  ${rnxPublicBrand.commandName} box --json requires a noninteractive cloud subcommand such as create.`,
+    )
+    return 1
+  }
+
   return runLocalBox(opts)
 }
 
@@ -152,13 +154,14 @@ async function runCloudBoxStop(args: string[], purge: boolean): Promise<number>
     return 1
   }
   const { header } = authHeaderOrExit(`box ${label}`)
+  const apiKey = header.replace(/^Bearer /, '')
+  const client = createBoxClient(
+    createCloudBoxProvider({ endpoint, apiOrigin: apiOrigin(args), apiKey }),
+  )
   try {
-    const result = await stopCloudBox({
-      endpoint,
-      name,
-      apiKey: header.replace(/^Bearer /, ''),
-      purge,
-    })
+    const result = purge
+      ? await client.delete({ boxId: name })
+      : await client.stop({ boxId: name })
     console.log(
       purge
         ? `  deleted ${name}, freeing ${Number(result.freedBytes ?? 0)} bytes`
@@ -166,7 +169,7 @@ async function runCloudBoxStop(args: string[], purge: boolean): Promise<number>
     )
     return 0
   } catch (error) {
-    if (error instanceof CloudBoxError) {
+    if (error instanceof BoxClientError) {
       console.error(`  ${rnx} box ${label}: ${error.message}`)
       return 1
     }
@@ -177,22 +180,29 @@ async function runCloudBoxStop(args: string[], purge: boolean): Promise<number>
 async function runCloudBoxList(args: string[]): Promise<number> {
   const rnx = rnxPublicBrand.commandName
   const { header } = authHeaderOrExit('box ls')
-  try {
-    const boxes = await listCloudBoxes({
+  const apiKey = header.replace(/^Bearer /, '')
+  const client = createBoxClient(
+    createCloudBoxProvider({
+      endpoint: flag(args, 'endpoint') ?? process.env[ENDPOINT_ENV]?.trim() ?? '',
       apiOrigin: apiOrigin(args),
-      apiKey: header.replace(/^Bearer /, ''),
-    })
+      apiKey,
+    }),
+  )
+  try {
+    const boxes = await client.list()
     if (boxes.length === 0) {
       console.log(`  no cloud boxes running on this account`)
       return 0
     }
     for (const box of boxes) {
       const minutes = Math.round(box.meteredMs / 60_000)
-      console.log(`  ${box.name ?? box.id}  running ${minutes}m  since ${box.startedAt}`)
+      console.log(
+        `  ${box.name ?? box.boxId}  running ${minutes}m  since ${box.startedAt}`,
+      )
     }
     return 0
   } catch (error) {
-    if (error instanceof CloudBoxError) {
+    if (error instanceof BoxClientError) {
       console.error(`  ${rnx} box ls: ${error.message}`)
       return 1
     }
@@ -205,6 +215,7 @@ async function runCloudBoxCreate(
   opts: BoxCommandOptions,
 ): Promise<number> {
   const rnx = rnxPublicBrand.commandName
+  const json = args.includes('--json')
   const endpoint = flag(args, 'endpoint') ?? process.env[ENDPOINT_ENV]?.trim()
   if (!endpoint) {
     console.error(
@@ -215,6 +226,17 @@ async function runCloudBoxCreate(
     return 1
   }
 
+  const templateName = flag(args, 'template') ?? terminalBoxTemplate.name
+  let template: BoxTemplateResolution
+  try {
+    template = BOX_TEMPLATES.resolve({ name: templateName })
+  } catch (error) {
+    console.error(
+      `  ${rnx} box create: ${error instanceof Error ? error.message : String(error)}.`,
+    )
+    return 1
+  }
+
   const root = findRepositoryPackageRoot(process.cwd())
   if (!root) {
     console.error(
@@ -224,7 +246,7 @@ async function runCloudBoxCreate(
     return 1
   }
 
-  const plane = new CheckoutFilePlane(root)
+  const plane = new CheckoutFilePlane(root, { trackedOnly: true })
   try {
     await plane.refresh()
   } catch (error) {
@@ -242,36 +264,55 @@ async function runCloudBoxCreate(
   const { header } = authHeaderOrExit('box create')
   const apiKey = header.replace(/^Bearer /, '')
 
-  console.log(`  ...creating cloud box ${name}`)
-  let session: Awaited<ReturnType<typeof connectCloudBox>> | null = null
+  if (!json) console.log(`  ...creating cloud box ${name}`)
+  const client = createBoxClient(
+    createCloudBoxProvider({ endpoint, apiOrigin: apiOrigin(args), apiKey }),
+  )
+  let session: BoxShellSession | null = null
   let heartbeat: { stop: () => void } | null = null
   try {
-    const created = await createCloudBox({
-      endpoint,
+    const box = await client.create({
       name,
-      apiKey,
-      plane,
-      onProgress: opts.verbose
-        ? (seeded, total) => console.log(`  ...seeded ${seeded}/${total} files`)
-        : undefined,
+      stack: template.stack,
+      template: template.provenance,
+      source: plane,
+      onProgress:
+        opts.verbose && !json
+          ? (seeded, total) => console.log(`  ...seeded ${seeded}/${total} files`)
+          : undefined,
     })
-    console.log(`  ...seeded ${created.files} project files`)
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ...box.description,
+          ...(box.accessToken ? { accessToken: box.accessToken } : {}),
+        }),
+      )
+      return 0
+    }
+    console.log(`  ...created Box ${box.id}`)
+    if (box.description.stableUrl) {
+      console.log(`  ...live ${box.description.stableUrl}`)
+    }
+    console.log(`  ...seeded ${box.description.files} project files`)
     // shown once and never stored: this process does not own a credential
     // store, and inventing one here would be a second place secrets live.
-    console.log(`  ...box token (shown once): ${created.token}`)
+    console.log(`  ...box token (shown once): ${box.accessToken}`)
     console.log(`  ...accessing shell\n`)
-    session = await connectCloudBox({ endpoint, name, token: created.token })
+    session = await box.connect()
     // bank the wall clock while the shell is open. the box holds no account
     // credential, so the client that is using it is what keeps the session
     // alive; when this process dies the sweep closes it at the last heartbeat.
+    const sessionId = box.description.sessionId
+    if (!sessionId) throw new BoxClientError('the box service returned no session id')
     heartbeat = heartbeatSession({
       apiOrigin: apiOrigin(args),
       apiKey,
-      sessionId: created.sessionId,
+      sessionId,
     })
     return await repl(session, '')
   } catch (error) {
-    if (error instanceof CloudBoxError) {
+    if (error instanceof BoxClientError) {
       console.error(`  ${rnx} box create: ${error.message}`)
       return 1
     }
@@ -311,13 +352,28 @@ async function runLocalBox(opts: BoxCommandOptions): Promise<number> {
     throw error
   }
 
-  const shell = createHarnessShell({
-    projectFs: new HarnessProjectFs(plane),
-    commands: [createRnxCommand({ root, shellCwd: () => shell.cwd })],
-    // just-bash's JavaScript rg reads every file body through the plane.
-    // see search-command.ts for the numbers.
-    builtInCommandOverrides: [createSearchCommand({ root })],
+  let session: BoxShellSession | null = null
+  const client = createBoxClient(
+    createBoxHostProvider({
+      shell: {
+        commands: [
+          createRnxCommand({
+            root,
+            shellCwd: () => session?.cwd ?? PROJECT_MOUNT,
+          }),
+        ],
+        // just-bash's JavaScript rg reads every file body through the plane.
+        // see search-command.ts for the numbers.
+        builtInCommandOverrides: [createSearchCommand({ root })],
+      },
+    }),
+  )
+  const box = await client.create({
+    name: path.basename(root),
+    stack: terminalBoxStack,
+    source: plane,
   })
+  session = await box.connect()
 
   const relative = path.relative(root, process.cwd())
   console.log(`  ...starting local box`)
@@ -362,26 +418,23 @@ async function runLocalBox(opts: BoxCommandOptions): Promise<number> {
 
   try {
     // the checkout is shared with editors, agents, and the user's own terminal.
-    // HarnessProjectFs arms a stale bit on each shell turn and refreshes the
+    // BoxProjectFs arms a stale bit on each shell turn and refreshes the
     // plane synchronously on the first actual file access, so commands that
     // never touch project files pay nothing, while reads always see fresh disk state.
-    return await repl(shell, relative)
+    return await repl(session, relative)
   } finally {
+    session.close()
     shared?.close()
   }
 }
 
 // the REPL drives whatever holds the shell. locally that is an in-process
-// HarnessShell over this checkout; for a cloud box it is a socket to the box,
+// BoxShell over this checkout; for a cloud box it is a socket to the box,
 // which holds both the files and the shell. same loop, because the only
 // difference is where exec runs.
-interface BoxSession {
-  readonly cwd: string
-  exec(command: string): Promise<HarnessShellResult>
-}
 
 async function repl(
-  session: BoxSession,
+  session: BoxShellSession,
   startRelative: string,
   beforeCommand?: () => Promise<void>,
 ): Promise<number> {