rtrt-agent 0.1.2 → 0.1.4

package/README.ko.md

@@ -1,20 +1,20 @@
 # rtrt-agent
 
-`rtrt-agent`는 RTRT의 OpenCode provenance 플러그인입니다. 지원되는 OpenCode
-hook 사이에서 상위 session, agent, worktree, invocation 및 permission broker 문맥을
-보존하며 broker는 loopback에서만 실행됩니다.
+`rtrt-agent`는 RTRT의 OpenCode 통합입니다. 지원되는 hook 사이에서 상위 session,
+agent, worktree, invocation 및 permission broker 문맥을 보존하고 로컬 대시보드를
+백그라운드에서 사용할 수 있게 유지합니다.
 
 ## 설치
 
 ```sh
-npm install rtrt-agent@0.1.2
+npm install rtrt-agent@0.1.4
 ```
 
 `opencode.json`의 단수형 `plugin` 배열에 패키지를 등록합니다.
 
 ```json
 {
-  "plugin": ["rtrt-agent@0.1.2"]
+  "plugin": ["rtrt-agent@0.1.4"]
 }
 ```
 
@@ -22,20 +22,41 @@ OpenCode는 이름 있는 `RtrtProvenance` export를 로드합니다. 이 패키
 default export를 제공하지 않습니다. 선택 사항인 RTRT TUI statusline은 별도 소스
 통합으로 유지되며 이 패키지에서 export하거나 pack하지 않습니다.
 
+## 대시보드
+
+플러그인을 로드하면 `rtrt-agent`는 `127.0.0.1:7311`에서 실행되는 사용자별 detached
+`rtrt-dashboard` process를 예약합니다. 시작 과정은 대시보드 준비를 기다리지 않으며
+브라우저를 자동으로 열지 않습니다. 정확히 같은 버전의 플랫폼별 optional npm 패키지가
+실행 파일을 제공하므로 미리 설치된 `rtrt`, `PATH` 검색, install script 또는 project
+build를 사용하지 않습니다.
+
+필요할 때만 브라우저를 엽니다.
+
+```sh
+rtrt-dashboard-open
+```
+
+에이전트는 인자가 없는 `rtrt_dashboard_open` 도구로 같은 명시적 동작을 수행할 수
+있습니다. 두 경로 모두 60초 fragment bootstrap을 사용하고 고정 상태만 반환하므로
+credential이 prompt나 command template에 들어가지 않습니다. 실행 파일 또는 private
+state가 안전하지 않거나 없으면 시작만 fail-soft로 중단되고 OpenCode는 정상적으로
+계속됩니다. 기존 `~/.rtrt` 데이터는 보존합니다.
+
 `rtrt setup --agent opencode --apply`는 전체 RTRT 통합을 관리하지만 npm 설치는 수행하지
 않으며, 설정된 패키지는 OpenCode가 시작할 때 설치합니다. Setup은 먼저 정확한
-`rtrt-agent@0.1.2` 등록과 모든 대체 관리 asset을 기록합니다. 이 기록이 성공한 뒤에만
+`rtrt-agent@0.1.4` 등록과 모든 대체 관리 asset을 기록합니다. 이 기록이 성공한 뒤에만
 인식된 legacy RTRT plugin을 제거하며, 이전 단계가 실패하면 legacy runtime을 보존합니다.
 Setup은 `rtrt-agent`의 정확히 일치하는 bare, pinned, ranged, tuple, object 형식만 소유하고
-정확한 `"rtrt-agent@0.1.2"` string 하나로 정규화합니다. 이전의 미게시 `rtrt`와 초안
+정확한 `"rtrt-agent@0.1.4"` string 하나로 정규화합니다. 이전의 미게시 `rtrt`와 초안
 `rtrt-opencode` 패키지 spec은 외부 값이며 순서를 유지합니다. 위 직접 등록과
-`opencode plugin rtrt-agent@0.1.2 --global`은 계속 유효합니다.
+`opencode plugin rtrt-agent@0.1.4 --global`은 계속 유효합니다.
 
 관리 agent 소유권 상태는 다음 순서의 첫 비어 있지 않은 root에서 읽습니다.
 `$OPENCODE_CONFIG_DIR`, `$XDG_CONFIG_HOME/opencode`, `~/.config/opencode`. 공존은 OMO
 4.19.4를 대상으로 CI에서 검사하고 OpenCode 1.18.29에서 직접 검증했으며, 어느 쪽도
-미래 버전 지원을 보장하지 않습니다. 통합 RTRT 릴리스 워크플로는 정확한
-`rtrt-agent@0.1.2` 패키지를 일치하는 Rust 릴리스와 함께 게시합니다.
+미래 버전 지원을 보장하지 않습니다. 통합 RTRT 릴리스 워크플로는 정확한 버전의
+대시보드 플랫폼 패키지 5개를 `rtrt-agent@0.1.4`보다 먼저 게시한 뒤 일치하는 Rust
+릴리스 artifact를 게시합니다.
 
 ## 라이선스
 

package/README.md

@@ -1,20 +1,20 @@
 # rtrt-agent
 
-`rtrt-agent` is RTRT's OpenCode provenance plugin. It preserves parent session,
-agent, worktree, invocation, and permission-broker context across supported OpenCode
-hooks while keeping the broker loopback-only.
+`rtrt-agent` is RTRT's OpenCode integration. It preserves parent session, agent,
+worktree, invocation, and permission-broker context across supported hooks and keeps
+the local dashboard available in the background.
 
 ## Install
 
 ```sh
-npm install rtrt-agent@0.1.2
+npm install rtrt-agent@0.1.4
 ```
 
 Register the package in the singular `plugin` array in `opencode.json`:
 
 ```json
 {
-  "plugin": ["rtrt-agent@0.1.2"]
+  "plugin": ["rtrt-agent@0.1.4"]
 }
 ```
 
@@ -22,21 +22,41 @@ OpenCode loads the named `RtrtProvenance` export. The package intentionally has
 default export. The optional RTRT TUI statusline remains a separate source integration
 and is not exported or packed by this package.
 
+## Dashboard
+
+On plugin load, `rtrt-agent` schedules `rtrt-dashboard` as a detached per-user process
+on `127.0.0.1:7311`. Startup never waits for dashboard readiness and never opens a
+browser. The matching platform executable comes from an exact-version optional npm
+package; no preinstalled `rtrt`, `PATH` lookup, install script, or project build is used.
+
+Open the browser only when requested:
+
+```sh
+rtrt-dashboard-open
+```
+
+An agent may invoke the argument-free `rtrt_dashboard_open` tool for the same explicit
+action. Both paths use a 60-second fragment bootstrap and return only a fixed status;
+credentials are never written into prompts or command templates. Startup is fail-soft:
+if the binary or private state is unsafe or unavailable, OpenCode continues normally.
+Existing `~/.rtrt` data is preserved.
+
 `rtrt setup --agent opencode --apply` manages the full RTRT integration but performs no
 npm installation; OpenCode installs the configured package at startup. Setup first writes
-the exact `rtrt-agent@0.1.2` registration and every replacement managed asset. Only after
+the exact `rtrt-agent@0.1.4` registration and every replacement managed asset. Only after
 those writes succeed does it remove a recognized legacy RTRT plugin; an earlier failure
 preserves the legacy runtime. Setup owns exact bare, pinned, ranged, tuple, and object forms
-of `rtrt-agent` only and normalizes them to one exact `"rtrt-agent@0.1.2"` string. Old
+of `rtrt-agent` only and normalizes them to one exact `"rtrt-agent@0.1.4"` string. Old
 unpublished `rtrt` and draft `rtrt-opencode` package specs are foreign and retain their
-order. The direct registration above and `opencode plugin rtrt-agent@0.1.2 --global`
+order. The direct registration above and `opencode plugin rtrt-agent@0.1.4 --global`
 remain valid.
 
 Managed-agent ownership state is read from the first nonempty root in this order:
 `$OPENCODE_CONFIG_DIR`, `$XDG_CONFIG_HOME/opencode`, then `~/.config/opencode`.
 Coexistence is CI-gated against OMO 4.19.4 and was verified on OpenCode 1.18.29; neither
 is a future-version guarantee. The unified RTRT release workflow publishes the exact
-`rtrt-agent@0.1.2` package together with the matching Rust release.
+five exact-version dashboard platform packages before `rtrt-agent@0.1.4`, then publishes
+the matching Rust release artifacts.
 
 ## License
 

package/bin/rtrt-dashboard-open.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { realpath } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { createDashboardSupervisor } from "../runtime/dashboard-supervisor.js"
+
+export async function runDashboardOpen({
+  open = () => createDashboardSupervisor().open(), write = (text) => process.stdout.write(text),
+} = {}) {
+  let success = false
+  try { success = await open() === "Dashboard open requested." } catch {
+    // Process/browser failures may contain credentials; emit only a fixed status.
+  }
+  write(success ? "Dashboard open requested.\n" : "Dashboard unavailable.\n")
+  return success ? 0 : 1
+}
+
+if (process.argv[1] && await realpath(process.argv[1]).catch(() => "") === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runDashboardOpen()
+}

package/index.js

@@ -1 +1,3 @@
-export { RtrtProvenance } from "./rtrt-provenance.js"
+import { createDashboardPlugin } from "./runtime/dashboard-plugin.js"
+
+export const RtrtProvenance = createDashboardPlugin()

package/package.json

@@ -1,21 +1,31 @@
 {
   "name": "rtrt-agent",
-  "version": "0.1.2",
-  "description": "RTRT provenance and permission-broker plugin for OpenCode",
+  "version": "0.1.4",
+  "description": "RTRT provenance, permission-broker, and local dashboard plugin for OpenCode",
   "type": "module",
   "main": "./index.js",
   "exports": {
     ".": "./index.js"
   },
+  "bin": {
+    "rtrt-dashboard-open": "./bin/rtrt-dashboard-open.js"
+  },
   "files": [
     "index.js",
     "rtrt-provenance.js",
+    "bin/rtrt-dashboard-open.js",
+    "runtime/dashboard-binary.js",
+    "runtime/dashboard-files.js",
+    "runtime/dashboard-plugin.js",
+    "runtime/dashboard-process.js",
+    "runtime/dashboard-supervisor.js",
     "README.md",
     "README.ko.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test rtrt-provenance.test.mjs package.test.mjs tui/rtrt-statusline.test.mjs"
+    "test": "node --test rtrt-provenance.test.mjs dashboard-binary.test.mjs dashboard-open.test.mjs dashboard-supervisor.test.mjs package.test.mjs platform-package.test.mjs platform-publish.test.mjs tui/rtrt-statusline.test.mjs",
+    "sync:platforms": "node ../../packaging/npm/agent-contract.mjs --sync"
   },
   "engines": {
     "node": ">=20"
@@ -39,5 +49,12 @@
   },
   "dependencies": {
     "@opencode-ai/sdk": "1.15.13"
+  },
+  "optionalDependencies": {
+    "rtrt-dashboard-linux-x64": "0.1.4",
+    "rtrt-dashboard-linux-arm64": "0.1.4",
+    "rtrt-dashboard-darwin-x64": "0.1.4",
+    "rtrt-dashboard-darwin-arm64": "0.1.4",
+    "rtrt-dashboard-win32-x64": "0.1.4"
   }
 }

package/runtime/dashboard-binary.js

@@ -0,0 +1,69 @@
+import { lstat, readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { readRegular, realPath, unavailable } from "./dashboard-files.js"
+
+const PACKAGES = new Map([
+  ["linux-x64", "rtrt-dashboard-linux-x64"],
+  ["linux-arm64", "rtrt-dashboard-linux-arm64"],
+  ["darwin-x64", "rtrt-dashboard-darwin-x64"],
+  ["darwin-arm64", "rtrt-dashboard-darwin-arm64"],
+  ["win32-x64", "rtrt-dashboard-win32-x64"],
+])
+
+// Node's package search layout, anchored to this plugin, without NODE_PATH,
+// cwd, PATH, Cargo target directories, or runtime network downloads.
+function packageRoots() {
+  const roots = []
+  let directory = fileURLToPath(new URL("../", import.meta.url))
+  for (;;) {
+    if (path.basename(directory) !== "node_modules") roots.push(path.join(directory, "node_modules"))
+    const parent = path.dirname(directory)
+    if (parent === directory) return roots
+    directory = parent
+  }
+}
+
+export async function resolveDashboardBinary({
+  home, platform = process.platform, arch = process.arch,
+  version, roots = packageRoots(), uid = process.geteuid?.(),
+}) {
+  const name = PACKAGES.get(`${platform}-${arch}`)
+  if (!name) throw unavailable()
+  const expected = version ?? JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version
+  if (typeof expected !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(expected)) throw unavailable()
+  const validate = (stat) => {
+    if (stat.isSymbolicLink()) throw unavailable()
+    if (platform !== "win32" && ((stat.uid !== uid && stat.uid !== 0) || (stat.mode & 0o7022) !== 0)) throw unavailable()
+  }
+  const cache = path.join(home, ".rtrt", "dashboard", "packages", expected, "node_modules")
+  for (const root of [...roots, cache]) {
+    const directory = path.join(root, name)
+    try {
+      await realPath(directory)
+      // Check ancestors too: a private executable in a writable parent is not trusted.
+      let ancestor = directory
+      for (;;) {
+        const stat = await lstat(ancestor)
+        if (!stat.isDirectory()) throw unavailable()
+        // System-owned sticky temp roots are safe when all descendants are checked.
+        if (!(stat.uid === 0 && (stat.mode & 0o1777) === 0o1777)) validate(stat)
+        const parent = path.dirname(ancestor)
+        if (parent === ancestor) break
+        ancestor = parent
+      }
+      const manifest = JSON.parse(await readRegular(path.join(directory, "package.json"), validate))
+      if (manifest.name !== name || manifest.version !== expected) continue
+      const binary = path.join(directory, "bin", platform === "win32" ? "rtrt-dashboard.exe" : "rtrt-dashboard")
+      await realPath(binary)
+      validate(await lstat(path.dirname(binary)))
+      const stat = await lstat(binary)
+      validate(stat)
+      if (!stat.isFile() || stat.nlink !== 1 || (platform !== "win32" && (stat.mode & 0o111) === 0)) throw unavailable()
+      return binary
+    } catch (error) {
+      if (error.code !== "ENOENT") throw unavailable()
+    }
+  }
+  throw unavailable()
+}

package/runtime/dashboard-files.js

@@ -0,0 +1,104 @@
+import { constants } from "node:fs"
+import { lstat, mkdir, open, rmdir } from "node:fs/promises"
+import path from "node:path"
+
+export const unavailable = () => new Error("Dashboard unavailable.")
+
+export async function realPath(candidate) {
+  if (typeof candidate !== "string" || !path.isAbsolute(candidate) || candidate.includes("\0")) throw unavailable()
+  const normalized = path.resolve(candidate)
+  const parts = normalized.slice(path.parse(normalized).root.length).split(path.sep).filter(Boolean)
+  let current = path.parse(normalized).root
+  for (const part of parts) {
+    current = path.join(current, part)
+    if ((await lstat(current)).isSymbolicLink()) throw unavailable()
+  }
+  return normalized
+}
+
+export function privateMetadata(stat, { uid, platform }, mode) {
+  if (stat.isSymbolicLink()) throw unavailable()
+  if (platform !== "win32" && (stat.uid !== uid || (stat.mode & 0o7777) !== mode)) throw unavailable()
+}
+
+export async function readRegular(file, validate, limit = 16_384) {
+  const before = await lstat(file)
+  validate(before)
+  if (!before.isFile() || before.nlink !== 1 || before.size > limit) throw unavailable()
+  const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
+  try {
+    const opened = await handle.stat()
+    validate(opened)
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) throw unavailable()
+    const buffer = Buffer.alloc(limit + 1)
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+    if (bytesRead > limit) throw unavailable()
+    return buffer.subarray(0, bytesRead).toString("utf8")
+  } finally {
+    await handle.close()
+  }
+}
+
+export function dashboardFiles({ home, uid, platform }) {
+  const identity = { uid, platform }
+  const state = path.join(home, ".rtrt", "dashboard")
+  const credential = path.join(state, "dashboard.env")
+  const lock = path.join(state, "startup.lock")
+  const directory = async (candidate) => {
+    const stat = await lstat(candidate)
+    privateMetadata(stat, identity, 0o700)
+    if (!stat.isDirectory()) throw unavailable()
+  }
+  const checkLock = async () => {
+    try { await directory(lock) } catch (error) {
+      if (error.code !== "ENOENT") throw error
+    }
+  }
+  const prepare = async () => {
+    await realPath(home)
+    const stat = await lstat(home)
+    if (!stat.isDirectory() || (platform !== "win32" && (stat.uid !== uid || (stat.mode & 0o022) !== 0))) throw unavailable()
+    for (const candidate of [path.dirname(state), state]) {
+      try { await mkdir(candidate, { mode: 0o700 }) } catch (error) {
+        if (error.code !== "EEXIST") throw error
+      }
+      await directory(candidate)
+    }
+    await checkLock()
+  }
+  const readToken = async () => {
+    await realPath(state)
+    let raw
+    try { raw = await readRegular(credential, (stat) => privateMetadata(stat, identity, 0o600)) } catch (error) {
+      if (error.code === "ENOENT") return undefined
+      throw error
+    }
+    const entries = raw.split(/\r?\n/).filter((line) => /^\s*RTRT_DASHBOARD_TOKEN\s*=/.test(line))
+    if (entries.length !== 1) throw unavailable()
+    const match = entries[0].match(/^\s*RTRT_DASHBOARD_TOKEN\s*=\s*(?:"([a-fA-F0-9]{64})"|'([a-fA-F0-9]{64})'|([a-fA-F0-9]{64}))\s*$/)
+    if (!match) throw unavailable()
+    return match[1] ?? match[2] ?? match[3]
+  }
+  const createToken = async (token) => {
+    if (!/^[a-fA-F0-9]{64}$/.test(token)) throw unavailable()
+    const handle = await open(credential, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600)
+    try {
+      privateMetadata(await handle.stat(), identity, 0o600)
+      await handle.writeFile(`RTRT_DASHBOARD_TOKEN=${token}\n`)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+  }
+  const acquire = async () => {
+    try { await mkdir(lock, { mode: 0o700 }) } catch (error) {
+      if (error.code !== "EEXIST") throw error
+      await directory(lock)
+      return undefined
+    }
+    await directory(lock)
+    // Never steal a lock on age/PID guesses, or remove another starter's lock.
+    return () => rmdir(lock)
+  }
+  return { state, prepare, readToken, createToken, acquire }
+}

package/runtime/dashboard-plugin.js

@@ -0,0 +1,32 @@
+import { RtrtProvenance } from "../rtrt-provenance.js"
+import { createDashboardSupervisor } from "./dashboard-supervisor.js"
+
+const scheduleStartup = (callback) => setTimeout(callback, 0).unref()
+
+export function createDashboardPlugin({
+  provenance = RtrtProvenance, supervisor = createDashboardSupervisor(), schedule = scheduleStartup,
+} = {}) {
+  return async (input) => {
+    const hooks = await provenance(input)
+    // Startup is best-effort and never blocks plugin initialization or opens a browser.
+    schedule(() => { void supervisor.ensure().catch(() => {}) })
+    return {
+      ...hooks,
+      tool: {
+        ...hooks.tool,
+        rtrt_dashboard_open: {
+          description: "Open the RTRT dashboard in the operator's browser when explicitly requested.",
+          args: {},
+          async execute() {
+            try {
+              const status = await supervisor.open()
+              return status === "Dashboard open requested." ? status : "Dashboard unavailable."
+            } catch {
+              return "Dashboard unavailable."
+            }
+          },
+        },
+      },
+    }
+  }
+}

package/runtime/dashboard-process.js

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process"
+import { get } from "node:http"
+import path from "node:path"
+import { unavailable } from "./dashboard-files.js"
+
+export function probeDashboard({ request = get, timeout = 750 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    let requestHandle
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      requestHandle?.destroy()
+      resolve(result)
+    }
+    const timer = setTimeout(() => finish("conflict"), timeout)
+    try {
+      requestHandle = request({ hostname: "127.0.0.1", port: 7311, path: "/healthz", agent: false }, (response) => {
+        let body = ""
+        response.on("error", () => finish("conflict"))
+        response.on("aborted", () => finish("conflict"))
+        response.on("data", (chunk) => {
+          body += chunk.toString("utf8")
+          if (body.length > 16) finish("conflict")
+        })
+        response.on("end", () => finish(response.statusCode === 200 && body === "ok" ? "healthy" : "conflict"))
+      })
+      requestHandle.once("error", (error) => finish(error.code === "ECONNREFUSED" ? "offline" : "conflict"))
+    } catch {
+      finish("conflict")
+    }
+  })
+}
+
+export function launchDetached(binary, args, { spawnProcess = spawn, ...options } = {}) {
+  return new Promise((resolve, reject) => {
+    if (!path.isAbsolute(binary)) { reject(unavailable()); return }
+    try {
+      const child = spawnProcess(binary, args, {
+        ...options, detached: true, windowsHide: true, stdio: "ignore", shell: false,
+      })
+      child.once("error", () => reject(unavailable()))
+      child.once("spawn", () => { child.unref(); resolve() })
+    } catch {
+      reject(unavailable())
+    }
+  })
+}
+
+export async function openDashboardBrowser(url, { platform = process.platform, launch = launchDetached } = {}) {
+  // Never consult BROWSER or PATH. URL is generated locally, not supplied by a tool argument.
+  switch (platform) {
+    case "linux": return launch("/usr/bin/xdg-open", [url])
+    case "darwin": return launch("/usr/bin/open", [url])
+    case "win32": return launch("C:\\Windows\\System32\\rundll32.exe", ["url.dll,FileProtocolHandler", url])
+    default: throw unavailable()
+  }
+}

package/runtime/dashboard-supervisor.js

@@ -0,0 +1,96 @@
+import { createHmac, randomBytes as systemRandomBytes } from "node:crypto"
+import { homedir } from "node:os"
+import { setTimeout as delay } from "node:timers/promises"
+import { dashboardFiles, unavailable } from "./dashboard-files.js"
+import { resolveDashboardBinary } from "./dashboard-binary.js"
+import { launchDetached, openDashboardBrowser, probeDashboard } from "./dashboard-process.js"
+
+export function createDashboardSupervisor({
+  env = process.env, platform = process.platform, arch = process.arch, uid = process.geteuid?.(),
+  probe = probeDashboard, resolveBinary = resolveDashboardBinary, launch = launchDetached,
+  openBrowser = openDashboardBrowser, wait = delay, now = Date.now, randomBytes = systemRandomBytes,
+} = {}) {
+  const home = env.HOME || env.USERPROFILE || homedir()
+  const files = dashboardFiles({ home, uid, platform })
+  let pending
+  const check = async () => {
+    const status = await probe()
+    switch (status) {
+      case "healthy": return true
+      case "offline": return false
+      case "conflict": throw unavailable()
+      default: throw unavailable()
+    }
+  }
+  const start = async () => {
+    await files.prepare()
+    const token = await files.readToken()
+    if (await check()) {
+      if (!token) throw unavailable()
+      return
+    }
+    let release
+    for (let attempt = 0; attempt < 20; attempt++) {
+      release = await files.acquire()
+      if (release) break
+      await wait(100)
+      await files.prepare()
+      if (await check()) {
+        if (!await files.readToken()) throw unavailable()
+        return
+      }
+    }
+    if (!release) throw unavailable()
+    try {
+      // A different process may have completed startup between first probe and lock.
+      if (await check()) {
+        if (!await files.readToken()) throw unavailable()
+        return
+      }
+      const binary = await resolveBinary({ home, platform, arch, uid })
+      if (!await files.readToken()) await files.createToken(randomBytes(32).toString("hex"))
+      // Keep operator environment, but never inherit loader injection or dashboard credentials.
+      const childEnv = Object.fromEntries(Object.entries(env).filter(([key]) =>
+        !/^(?:LD_|DYLD_|RTRT_DASHBOARD_|NODE_OPTIONS$)/i.test(key)))
+      await launch(binary, ["--machine", "--state-dir", files.state], {
+        cwd: home,
+        env: { ...childEnv, HOME: home, RTRT_DASHBOARD_BIND: "127.0.0.1:7311" },
+      })
+      for (let attempt = 0; attempt < 20; attempt++) {
+        if (await check()) return
+        await wait(100)
+      }
+      throw unavailable()
+    } finally {
+      await release()
+    }
+  }
+  const ensure = () => {
+    if (!pending) {
+      pending = start().catch(() => { throw unavailable() }).finally(() => { pending = undefined })
+    }
+    return pending
+  }
+  const open = async () => {
+    try {
+      await ensure()
+      const token = await files.readToken()
+      if (!token) throw unavailable()
+      const issued = BigInt(Math.floor(now() / 1000))
+      const wire = Buffer.alloc(65)
+      wire[0] = 1
+      wire.writeBigUInt64BE(issued, 1)
+      wire.writeBigUInt64BE(issued + 60n, 9)
+      randomBytes(16).copy(wire, 17)
+      createHmac("sha256", Buffer.from(token, "hex"))
+        .update("rtrt-dashboard-browser-bootstrap\0v1\0")
+        .update(wire.subarray(0, 33)).digest().copy(wire, 33)
+      await openBrowser(`http://127.0.0.1:7311/#bootstrap=${wire.toString("base64url")}`, { platform })
+      return "Dashboard open requested."
+    } catch {
+      // Never expose dependency errors: process errors can contain the bootstrap URL.
+      return "Dashboard unavailable."
+    }
+  }
+  return { ensure, open }
+}