visual-remote 0.3.0 → 0.3.1

package/apps/cli/dist/index.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { realpathSync } from "node:fs";
+import { realpathSync as realpathSync2 } from "node:fs";
 import { resolve as resolve8 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command, InvalidArgumentError } from "commander";
 
+// src/bridge.ts
+import { createConnection } from "node:net";
+
 // ../../packages/bridge-core/src/bridge/control-service.ts
 var ControlServiceError = class extends Error {
   statusCode;
@@ -161,6 +164,11 @@ function pairingTokensMatch(expected, candidate) {
   const candidateBytes = Buffer.from(candidate);
   return expectedBytes.length === candidateBytes.length && timingSafeEqual(expectedBytes, candidateBytes);
 }
+function createPairingUrl(baseUrl, token) {
+  const url = new URL(baseUrl);
+  url.hash = `visual-pair=${encodeURIComponent(token)}`;
+  return url.toString();
+}
 
 // ../../packages/bridge-core/src/runtime/ports.ts
 import { createServer } from "node:net";
@@ -284,7 +292,7 @@ function originAllowed(request, allowedOrigins) {
   }
 }
 function tokenAccess(token, controlToken, viewerSessions, now) {
-  if (token === void 0 || token.length === 0) return "control";
+  if (token === void 0 || token.length === 0) return void 0;
   if (pairingTokensMatch(controlToken, token)) return "control";
   const expiresAt = viewerSessions.get(token);
   if (expiresAt !== void 0) {
@@ -689,7 +697,12 @@ function createGatewayServer(options) {
         const access3 = requestAccess(request, options.pairingToken, viewerSessions);
         if (access3 === void 0) {
           response.setHeader("www-authenticate", "Bearer");
-          writeApiError(response, 401, "unauthorized", "A valid viewer token is required");
+          writeApiError(
+            response,
+            401,
+            "unauthorized",
+            "A valid control or viewer token is required"
+          );
           return;
         }
         try {
@@ -982,7 +995,65 @@ function itemFiles(item) {
   if (direct) files.push(direct);
   return [...new Set(files)];
 }
-function parseCodexJsonLine(line) {
+function stringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+}
+function formatArgv(argv) {
+  return argv.map((argument) => /^[A-Za-z0-9_./:=@%+,-]+$/u.test(argument) ? argument : JSON.stringify(argument)).join(" ");
+}
+function isDirectExecItem(item) {
+  return item.type === "mcp_tool_call" && item.server === "visual_remote_exec" && item.tool === "run_readonly";
+}
+function directExecSummary(item) {
+  const arguments_ = asRecord(item.arguments);
+  const commands = Array.isArray(arguments_?.commands) ? arguments_.commands : [];
+  const summaries = commands.flatMap((candidate) => {
+    const command = asRecord(candidate);
+    const argv = stringArray(command?.argv);
+    return argv === void 0 ? [] : [formatArgv(argv)];
+  });
+  return summaries.length === 0 ? void 0 : summaries.join(" \xB7 ");
+}
+function directExecResults(item, defaultCwd) {
+  const result = asRecord(item.result);
+  const structured = asRecord(result?.structured_content ?? result?.structuredContent);
+  const results = Array.isArray(structured?.results) ? structured.results : [];
+  return results.flatMap((candidate) => {
+    const command = asRecord(candidate);
+    const argv = stringArray(command?.argv);
+    if (argv === void 0) return [];
+    const exitCode = typeof command?.exitCode === "number" ? command.exitCode : void 0;
+    const durationMs = typeof command?.durationMs === "number" ? command.durationMs : void 0;
+    return [{
+      command: formatArgv(argv),
+      cwd: asText(command?.cwd) ?? defaultCwd,
+      ok: exitCode === 0,
+      ...exitCode === void 0 ? {} : { exitCode },
+      ...durationMs === void 0 ? {} : { durationMs },
+      ...typeof command?.usedRtk === "boolean" ? { usedRtk: command.usedRtk } : {},
+      ...typeof command?.timedOut === "boolean" ? { timedOut: command.timedOut } : {},
+      ...typeof command?.truncated === "boolean" ? { truncated: command.truncated } : {}
+    }];
+  });
+}
+function normalizedUsage(record) {
+  const result = asRecord(record.result);
+  const usage = asRecord(record.usage) ?? (result ? asRecord(result.usage) : void 0);
+  if (usage === void 0) return void 0;
+  const inputTokens = usage.input_tokens ?? usage.inputTokens;
+  const outputTokens = usage.output_tokens ?? usage.outputTokens;
+  const cachedInputTokens = usage.cached_input_tokens ?? usage.cachedInputTokens;
+  if (typeof inputTokens !== "number" || typeof outputTokens !== "number") {
+    return void 0;
+  }
+  return {
+    type: "usage",
+    inputTokens,
+    outputTokens,
+    ...typeof cachedInputTokens === "number" ? { cachedInputTokens } : {}
+  };
+}
+function parseCodexJsonLine(line, defaultCwd = "") {
   const trimmed = line.trim();
   if (!trimmed) return [];
   let value;
@@ -1002,7 +1073,12 @@ function parseCodexJsonLine(line) {
   if (type === "turn.completed") {
     const result = asRecord(record.result);
     const summary = asText(record.summary) ?? (result ? asText(result.summary) : void 0);
-    return [...events, summary ? { type: "complete", summary } : { type: "complete" }];
+    const usage = normalizedUsage(record);
+    return [
+      ...events,
+      ...usage === void 0 ? [] : [usage],
+      summary ? { type: "complete", summary } : { type: "complete" }
+    ];
   }
   if (type === "turn.failed" || type === "error") {
     const error = asRecord(record.error);
@@ -1012,8 +1088,9 @@ function parseCodexJsonLine(line) {
   const item = asRecord(record.item);
   if (type === "item.started" && item) {
     const itemType = asText(item.type) ?? "item";
-    const summary = asText(item.command) ?? asText(item.text);
-    const start = summary ? { type: "tool_start", name: itemType, summary } : { type: "tool_start", name: itemType };
+    const directExec = isDirectExecItem(item);
+    const summary = directExec ? directExecSummary(item) : asText(item.command) ?? asText(item.text);
+    const start = summary ? { type: "tool_start", name: directExec ? "direct_exec" : itemType, summary } : { type: "tool_start", name: directExec ? "direct_exec" : itemType };
     return [...events, start];
   }
   if (type === "item.completed" && item) {
@@ -1028,13 +1105,30 @@ function parseCodexJsonLine(line) {
         events.push({
           type: "command",
           command,
-          cwd: asText(item.cwd) ?? ""
+          cwd: asText(item.cwd) ?? defaultCwd
         });
       }
     }
+    const directResults = isDirectExecItem(item) ? directExecResults(item, defaultCwd) : [];
+    for (const result of directResults) {
+      events.push({
+        type: "command",
+        command: result.command,
+        cwd: result.cwd,
+        ...result.exitCode === void 0 ? {} : { exitCode: result.exitCode },
+        ...result.durationMs === void 0 ? {} : { durationMs: result.durationMs },
+        ...result.usedRtk === void 0 ? {} : { usedRtk: result.usedRtk },
+        ...result.timedOut === void 0 ? {} : { timedOut: result.timedOut },
+        ...result.truncated === void 0 ? {} : { truncated: result.truncated }
+      });
+    }
     for (const path of itemFiles(item)) events.push({ type: "file_hint", path });
     const exitCode = typeof item.exit_code === "number" ? item.exit_code : void 0;
-    events.push({ type: "tool_end", name: itemType, ok: exitCode === void 0 || exitCode === 0 });
+    events.push({
+      type: "tool_end",
+      name: isDirectExecItem(item) ? "direct_exec" : itemType,
+      ok: directResults.length > 0 ? directResults.every((result) => result.ok) : exitCode === void 0 || exitCode === 0
+    });
     return events;
   }
   const message = asText(record.message);
@@ -1043,7 +1137,10 @@ function parseCodexJsonLine(line) {
 }
 
 // ../../packages/bridge-core/src/agents/codex-adapter.ts
-import { spawn as spawn2 } from "node:child_process";
+import { execFile, spawn as spawn2 } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { promisify } from "node:util";
 
 // ../../packages/bridge-core/src/agents/async-queue.ts
 var AsyncQueue = class {
@@ -1242,6 +1339,7 @@ async function startManagedProcess(options) {
 }
 
 // ../../packages/bridge-core/src/agents/codex-adapter.ts
+var execFileAsync = promisify(execFile);
 var INHERITED_ENVIRONMENT = [
   "PATH",
   "HOME",
@@ -1282,13 +1380,72 @@ function splitLines(chunk, previous, onLine) {
   for (const line of lines) onLine(line);
   return remainder;
 }
+function defaultDirectExecMcpScript() {
+  const candidates = [
+    fileURLToPath2(new URL("./direct-exec-mcp.js", import.meta.url)),
+    fileURLToPath2(
+      new URL("../../../../apps/cli/dist/direct-exec-mcp.js", import.meta.url)
+    )
+  ];
+  return candidates.find((candidate) => existsSync(candidate));
+}
 var CodexAdapter = class {
   id = "codex";
   #executable;
   #killGraceMs;
+  #rtkExecutable;
+  #directExecMcpScript;
+  #rtkVersion;
   constructor(options = {}) {
     this.#executable = options.executable ?? "codex";
     this.#killGraceMs = options.killGraceMs ?? 2e3;
+    this.#rtkExecutable = options.rtkExecutable ?? "rtk";
+    this.#directExecMcpScript = options.directExecMcpScript === false ? void 0 : options.directExecMcpScript ?? defaultDirectExecMcpScript();
+  }
+  #probeRtk(environment) {
+    if (this.#rtkExecutable === false) return Promise.resolve(void 0);
+    this.#rtkVersion ??= execFileAsync(this.#rtkExecutable, ["--version"], {
+      encoding: "utf8",
+      env: environment,
+      timeout: 1e3,
+      windowsHide: true,
+      maxBuffer: 16 * 1024
+    }).then(({ stdout }) => stdout.trim().split(/\r?\n/, 1)[0] || void 0).catch(() => void 0);
+    return this.#rtkVersion;
+  }
+  async #runtimePrompt(input, environment) {
+    const commandGuidance = this.#rtkExecutable === false ? "" : await this.#probeRtk(environment).then((version) => version ? `RTK command proxy:
+- ${version} is installed and available in this runtime.
+- Prefix shell commands with RTK by default (for example: rtk git status, rtk rg <pattern>, rtk read <file>, rtk npm test).
+- Use the native command only when RTK has no suitable proxy or RTK execution fails. Do not spend time rediscovering or reinstalling RTK.` : `RTK command proxy:
+- RTK was not detected in this runtime. Use native repository commands directly and do not spend time searching for RTK.`);
+    const directExecGuidance = this.#directExecMcpScript === void 0 ? "" : `Direct read-only command runner:
+- Use the visual_remote_exec run_readonly MCP tool (mcp__visual_remote_exec__run_readonly) for repository inspection by default: pwd, version checks, file listing/reading/search, and read-only Git status/diff/log/show.
+- Send argv arrays, batch independent reads in one tool call, and keep cwd at the registered workspace unless a known subdirectory is required.
+- The tool executes without a shell and applies RTK automatically when supported.
+- Use command_execution only for edits, tests/builds, or commands that genuinely require shell syntax. Do not retry a policy-rejected command through another shell unless the requested work requires that non-read-only operation.`;
+    const guidance = [directExecGuidance, commandGuidance].filter(Boolean).join("\n\n");
+    return guidance.length === 0 ? input.prompt : `${input.prompt.trimEnd()}
+
+${guidance}
+`;
+  }
+  #directExecConfig(input) {
+    if (this.#directExecMcpScript === void 0) return [];
+    const serverArgs = [
+      this.#directExecMcpScript,
+      "--repo-root",
+      input.repoRoot,
+      "--workspace-root",
+      input.workspaceRoot,
+      ...this.#rtkExecutable === false ? ["--no-rtk"] : ["--rtk", this.#rtkExecutable]
+    ];
+    return [
+      "-c",
+      `mcp_servers.visual_remote_exec.command=${JSON.stringify(process.execPath)}`,
+      "-c",
+      `mcp_servers.visual_remote_exec.args=${JSON.stringify(serverArgs)}`
+    ];
   }
   async probe() {
     return await new Promise((resolve9) => {
@@ -1324,7 +1481,8 @@ var CodexAdapter = class {
       "-s",
       "workspace-write",
       "-C",
-      input.repoRoot,
+      input.workspaceRoot,
+      ...this.#directExecConfig(input),
       "-"
     ];
     yield* this.#execute(input, signal, args);
@@ -1341,7 +1499,8 @@ var CodexAdapter = class {
       "-s",
       "workspace-write",
       "-C",
-      input.repoRoot,
+      input.workspaceRoot,
+      ...this.#directExecConfig(input),
       "resume",
       input.sessionId,
       "-"
@@ -1350,9 +1509,11 @@ var CodexAdapter = class {
   }
   async *#execute(input, signal, args) {
     const queue = new AsyncQueue();
+    const environment = processEnv(input.environment);
+    const prompt = await this.#runtimePrompt(input, environment);
     const child = spawn2(this.#executable, args, {
-      cwd: input.repoRoot,
-      env: processEnv(input.environment),
+      cwd: input.workspaceRoot,
+      env: environment,
       detached: process.platform !== "win32",
       shell: false,
       stdio: ["pipe", "pipe", "pipe"]
@@ -1383,7 +1544,7 @@ var CodexAdapter = class {
     if (signal.aborted) abort();
     child.stdout.on("data", (chunk) => {
       stdoutRemainder = splitLines(chunk, stdoutRemainder, (line) => {
-        for (const event of parseCodexJsonLine(line)) queue.push(event);
+        for (const event of parseCodexJsonLine(line, input.workspaceRoot)) queue.push(event);
       });
     });
     child.stderr.on("data", (chunk) => {
@@ -1398,7 +1559,9 @@ var CodexAdapter = class {
       void (async () => {
         await requestTermination();
         if (stdoutRemainder.trim()) {
-          for (const event of parseCodexJsonLine(stdoutRemainder)) queue.push(event);
+          for (const event of parseCodexJsonLine(stdoutRemainder, input.workspaceRoot)) {
+            queue.push(event);
+          }
         }
         if (stderrRemainder.trim()) queue.push({ type: "warning", text: stderrRemainder });
         if (timedOut) queue.end(new AgentTimeoutError());
@@ -1419,7 +1582,7 @@ var CodexAdapter = class {
     child.stdin.on("error", (error) => {
       if (error.code !== "EPIPE") queue.end(error);
     });
-    child.stdin.end(input.prompt);
+    child.stdin.end(prompt);
     try {
       for await (const event of queue) yield event;
     } finally {
@@ -1438,6 +1601,9 @@ var CodexAdapter = class {
   }
 };
 
+// ../../packages/bridge-core/src/agents/direct-exec.ts
+var DEFAULT_OUTPUT_BYTES = 64 * 1024;
+
 // ../../packages/bridge-core/src/config/loader.ts
 import { readFile, realpath, stat as stat2 } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -1867,6 +2033,20 @@ function isWithin(root, candidate) {
   const path = relative2(root, candidate);
   return path === "" || !path.startsWith(`..${sep2}`) && path !== ".." && !isAbsolute2(path);
 }
+function rebaseWorkspacePatterns(repoRoot, workspaceRoot, patterns) {
+  const repository = resolve2(repoRoot);
+  const workspace = resolve2(workspaceRoot);
+  if (!isWithin(repository, workspace)) {
+    throw new PathSafetyError(
+      "PATH_OUTSIDE_REPOSITORY",
+      workspaceRoot,
+      `Workspace is outside the repository: ${workspaceRoot}`
+    );
+  }
+  const prefix = repositoryRelative(repository, workspace);
+  if (!prefix) return [...patterns];
+  return patterns.map((pattern) => normalizeSlashes(`${prefix}/${pattern}`));
+}
 var PathPolicy = class {
   repoRoot;
   allowedPatterns;
@@ -2710,6 +2890,9 @@ var TERMINAL = /* @__PURE__ */ new Set(["accepted", "reverted", "failed", "cance
 function isActiveTaskStatus(status) {
   return status !== "queued" && status !== "review" && !TERMINAL.has(status);
 }
+function isWorkingTaskStatus(status) {
+  return status === "queued" || isActiveTaskStatus(status);
+}
 function isTerminalTaskStatus(status) {
   return TERMINAL.has(status);
 }
@@ -2764,14 +2947,18 @@ Follow-up context:
 - Previous request: ${options.parent.requestText}
 - Previous diff summary: ${options.parent.diffSummary || "No file changes"}
 ` : "";
-  return `You are editing the repository at: ${options.repoRoot}
-Workspace: ${options.workspaceRoot}
+  return `Target service context (authoritative):
+- Repository worktree: ${options.repoRoot}
+- Workspace: ${options.workspaceRoot}
+- Browser URL: ${options.context.page.url}
+${options.upstreamUrl ? `- Local upstream URL: ${options.upstreamUrl}
+` : ""}
+Treat the workspace above as the already-resolved service directory and the repository worktree as its safety boundary. Run project commands from the workspace; do not search parent directories or run directory-discovery commands to locate the project again.
 
 User request:
 ${options.context.request.text}
 
 Selected UI context:
-- URL: ${options.context.page.url}
 - Route: ${options.context.page.pathname}
 - Selection mode: ${options.context.selection.mode}
 ${targets || "- No concrete target; use the page context and repository search."}
@@ -3246,6 +3433,7 @@ function repositoryGuardMessage(result) {
 var TaskService = class {
   #projectId;
   #workspaceRoot;
+  #upstreamUrl;
   #adapter;
   #store;
   #git;
@@ -3269,6 +3457,7 @@ var TaskService = class {
   constructor(options) {
     this.#projectId = options.projectId;
     this.#workspaceRoot = resolve6(options.workspaceRoot ?? options.git.repoRoot);
+    this.#upstreamUrl = options.upstreamUrl;
     if (!isWithin3(options.git.repoRoot, this.#workspaceRoot)) {
       throw new TaskServiceError(
         "WORKSPACE_OUTSIDE_REPOSITORY",
@@ -3655,6 +3844,7 @@ var TaskService = class {
       const prompt = buildAgentPrompt({
         repoRoot: this.#git.repoRoot,
         workspaceRoot: this.#workspaceRoot,
+        ...this.#upstreamUrl === void 0 ? {} : { upstreamUrl: this.#upstreamUrl },
         contextBundlePath: contextPath,
         context,
         allowedPatterns: this.#git.pathPolicy.allowedPatterns,
@@ -3887,6 +4077,18 @@ var TaskService = class {
 };
 
 // ../../packages/bridge-core/src/verification/browser-sessions.ts
+function errorSignature(event) {
+  return `${event.level}\0${event.message}`;
+}
+function samePage(left, right) {
+  try {
+    const leftUrl = new URL(left);
+    const rightUrl = new URL(right);
+    return leftUrl.origin === rightUrl.origin && leftUrl.pathname === rightUrl.pathname && leftUrl.search === rightUrl.search;
+  } catch {
+    return left === right;
+  }
+}
 var BrowserSessionManager = class {
   #sessions = /* @__PURE__ */ new Map();
   #maxConsoleEvents;
@@ -3962,7 +4164,13 @@ var BrowserSessionManager = class {
     return {
       browserSessionId: id,
       renderRevision: session.renderRevision,
-      startedAt: now.toISOString()
+      startedAt: now.toISOString(),
+      url: session.url,
+      knownErrorSignatures: [
+        ...new Set(
+          session.consoleEvents.filter((event) => event.level === "error" || event.level === "unhandled").map(errorSignature)
+        )
+      ]
     };
   }
   verify(baseline, options = {}) {
@@ -3975,10 +4183,16 @@ var BrowserSessionManager = class {
         summary: "Origin browser session is disconnected."
       };
     }
-    const newErrors = session.consoleEvents.filter(
-      (event) => event.createdAt >= baseline.startedAt && (event.level === "error" || event.level === "unhandled")
-    );
+    const knownErrors = new Set(baseline.knownErrorSignatures);
+    const newErrors = [
+      ...new Map(
+        session.consoleEvents.filter(
+          (event) => event.createdAt > baseline.startedAt && (event.level === "error" || event.level === "unhandled") && !knownErrors.has(errorSignature(event))
+        ).map((event) => [errorSignature(event), event])
+      ).values()
+    ];
     const renderChanged = session.renderRevision > baseline.renderRevision;
+    const pageUnchanged = samePage(baseline.url, session.url);
     const targetResult = options.taskId === void 0 ? void 0 : session.targetResults.filter(
       (result) => result.taskId === options.taskId && result.createdAt >= baseline.startedAt
     ).at(-1);
@@ -3991,6 +4205,15 @@ var BrowserSessionManager = class {
         summary: `${newErrors.length} new browser error${newErrors.length === 1 ? "" : "s"} detected.`
       };
     }
+    if (!pageUnchanged) {
+      return {
+        status: "partial",
+        renderChanged,
+        newErrors: [],
+        ...targetResult ? { targetResult } : {},
+        summary: "Origin browser navigated to a different page during verification."
+      };
+    }
     if (options.targetEvidenceRequired) {
       const targetChanged = targetResult?.state === "found-and-changed" && targetResult.targetCount > 0 && targetResult.foundCount === targetResult.targetCount && targetResult.changedCount > 0 && targetResult.renderRevision > baseline.renderRevision;
       if (targetChanged) {
@@ -4579,7 +4802,7 @@ ${output2}` : ""}`
       status: "ok",
       bridge: "online",
       projectId: options.project.id,
-      activeTask: taskService.list().find((task) => !["accepted", "reverted", "failed", "canceled", "unsafe"].includes(task.status))?.id ?? null
+      activeTask: taskService.list().find((task) => isWorkingTaskStatus(task.status))?.id ?? null
     }),
     project: () => ({
       id: options.project.id,
@@ -4630,14 +4853,23 @@ async function createDefaultControlService(context, environment = process.env) {
     );
   }
   const git = await GitTransactionManager.open(context.repoRoot, {
-    allowed: loaded.config.paths.allowed,
-    denied: loaded.config.paths.denied
+    allowed: rebaseWorkspacePatterns(
+      context.repoRoot,
+      context.workspaceRoot,
+      loaded.config.paths.allowed
+    ),
+    denied: rebaseWorkspacePatterns(
+      context.repoRoot,
+      context.workspaceRoot,
+      loaded.config.paths.denied
+    )
   });
   const storagePaths = await resolveStoragePaths(context.repoRoot, environment);
   const store = new SqliteTaskStore(storagePaths.databasePath);
   const taskService = new TaskService({
     projectId: context.projectId,
     workspaceRoot: context.workspaceRoot,
+    upstreamUrl: context.upstreamUrl,
     adapter: new CodexAdapter(),
     store,
     git,
@@ -4646,7 +4878,7 @@ async function createDefaultControlService(context, environment = process.env) {
     resumeMode: loaded.config.agent.resumeMode,
     environment: {}
   });
-  return createTaskControlService({
+  const controlService = createTaskControlService({
     taskService,
     hmrWaitMs: loaded.config.verification.hmrWaitMs,
     verificationCommands: loaded.config.verification.commands,
@@ -4658,10 +4890,32 @@ async function createDefaultControlService(context, environment = process.env) {
       upstreamUrl: context.upstreamUrl
     }
   });
+  const reportRuntimeState = () => {
+    const activeTask = taskService.list().find((task) => isWorkingTaskStatus(task.status));
+    context.onRuntimeState?.({
+      status: activeTask === void 0 ? "idle" : "working",
+      ...activeTask === void 0 ? {} : { activeTaskId: activeTask.id }
+    });
+  };
+  const unsubscribeRuntime = taskService.subscribe(reportRuntimeState);
+  reportRuntimeState();
+  return {
+    ...controlService,
+    close: async () => {
+      unsubscribeRuntime();
+      await controlService.close?.();
+    }
+  };
 }
 
 // ../../packages/bridge-core/src/runtime/registry.ts
 import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
+import {
+  readFileSync,
+  realpathSync,
+  rmSync,
+  unlinkSync
+} from "node:fs";
 import {
   mkdir as mkdir2,
   link,
@@ -4702,6 +4956,11 @@ async function repositoryKey(repositoryRoot) {
   const canonicalRoot = await realpath8(repositoryRoot);
   return createHash3("sha256").update(canonicalRoot).digest("hex");
 }
+function runtimeDirectoryForSync(repositoryRoot, options) {
+  const canonicalRoot = realpathSync(repositoryRoot);
+  const repoKey = createHash3("sha256").update(canonicalRoot).digest("hex");
+  return join3(runtimeRoot(options), repoKey);
+}
 async function runtimeDirectoryFor(repositoryRoot, options = {}) {
   return join3(runtimeRoot(options), await repositoryKey(repositoryRoot));
 }
@@ -4740,6 +4999,13 @@ async function readJson(path) {
     return void 0;
   }
 }
+function readJsonSync(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
 async function readInstance(repositoryRoot, options = {}) {
   const directory = await runtimeDirectoryFor(repositoryRoot, options);
   const value = await readJson(join3(directory, "instance.json"));
@@ -4757,6 +5023,21 @@ async function writeInstance(repositoryRoot, instance, options = {}) {
   });
   await rename(temporaryPath, path);
 }
+async function updateInstance(repositoryRoot, expectedPid, update, options = {}) {
+  const current = await readInstance(repositoryRoot, options);
+  if (current === void 0 || current.pid !== expectedPid) return void 0;
+  const next = {
+    ...current,
+    ...update.status === void 0 ? {} : { status: update.status }
+  };
+  if (update.activeTaskId === null) {
+    delete next.activeTaskId;
+  } else if (update.activeTaskId !== void 0) {
+    next.activeTaskId = update.activeTaskId;
+  }
+  await writeInstance(repositoryRoot, next, options);
+  return next;
+}
 async function removeInstance(repositoryRoot, expectedPid, options = {}) {
   const directory = await runtimeDirectoryFor(repositoryRoot, options);
   const path = join3(directory, "instance.json");
@@ -4768,6 +5049,17 @@ async function removeInstance(repositoryRoot, expectedPid, options = {}) {
   }
   await rm3(path, { force: true });
 }
+function removeInstanceSync(repositoryRoot, expectedPid, options = {}) {
+  const directory = runtimeDirectoryForSync(repositoryRoot, options);
+  const path = join3(directory, "instance.json");
+  if (expectedPid !== void 0) {
+    const current = readJsonSync(path);
+    if (!isBridgeInstanceRecord(current) || current.pid !== expectedPid) {
+      return;
+    }
+  }
+  rmSync(path, { force: true });
+}
 async function acquireWorktreeLock(repositoryRoot, options = {}) {
   const repoRoot = await realpath8(repositoryRoot);
   const repoKey = await repositoryKey(repoRoot);
@@ -4799,23 +5091,43 @@ async function acquireWorktreeLock(repositoryRoot, options = {}) {
         await rm3(candidatePath, { force: true });
       }
       let released = false;
+      let releasePromise;
       return {
         repoKey,
         runtimeDirectory,
         lockPath,
-        async release() {
+        release() {
           if (released) {
+            return Promise.resolve();
+          }
+          releasePromise ??= (async () => {
+            const current = await readJson(lockPath);
+            if (isLockRecord(current) && current.ownerId === ownerId) {
+              await unlink(lockPath).catch((error) => {
+                if (error.code !== "ENOENT") {
+                  throw error;
+                }
+              });
+            }
+            released = true;
+          })();
+          return releasePromise;
+        },
+        releaseSync() {
+          if (released || releasePromise !== void 0) {
             return;
           }
-          released = true;
-          const current = await readJson(lockPath);
+          const current = readJsonSync(lockPath);
           if (isLockRecord(current) && current.ownerId === ownerId) {
-            await unlink(lockPath).catch((error) => {
-              if (error.code !== "ENOENT") {
+            try {
+              unlinkSync(lockPath);
+            } catch (error) {
+              if (typeof error !== "object" || error === null || !("code" in error) || error.code !== "ENOENT") {
                 throw error;
               }
-            });
+            }
           }
+          released = true;
         }
       };
     } catch (error) {
@@ -4835,10 +5147,10 @@ async function acquireWorktreeLock(repositoryRoot, options = {}) {
 }
 
 // ../../packages/bridge-core/src/runtime/repository.ts
-import { execFile } from "node:child_process";
+import { execFile as execFile2 } from "node:child_process";
 import { realpath as realpath9 } from "node:fs/promises";
-import { promisify } from "node:util";
-var execFileAsync = promisify(execFile);
+import { promisify as promisify2 } from "node:util";
+var execFileAsync2 = promisify2(execFile2);
 var GitWorktreeNotFoundError = class extends Error {
   constructor(cwd, options = {}) {
     super(
@@ -4850,7 +5162,7 @@ var GitWorktreeNotFoundError = class extends Error {
 };
 async function discoverGitWorktreeRoot(cwd = process.cwd()) {
   try {
-    const { stdout } = await execFileAsync(
+    const { stdout } = await execFileAsync2(
       "git",
       ["-C", cwd, "rev-parse", "--show-toplevel"],
       {
@@ -4869,6 +5181,91 @@ async function discoverGitWorktreeRoot(cwd = process.cwd()) {
 }
 
 // src/bridge.ts
+var DEFAULT_UPSTREAM_MONITOR_INTERVAL_MS = 1e3;
+var DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS = 500;
+var DEFAULT_UPSTREAM_FAILURE_GRACE_MS = 5e3;
+function positiveMilliseconds(value, fallback) {
+  return value === void 0 || !Number.isFinite(value) || value <= 0 ? fallback : Math.max(1, Math.floor(value));
+}
+async function probeUpstream(upstreamUrl, timeoutMs) {
+  const upstream = new URL(upstreamUrl);
+  const hostname = upstream.hostname.startsWith("[") ? upstream.hostname.slice(1, -1) : upstream.hostname;
+  const port = Number(
+    upstream.port || (upstream.protocol === "https:" ? 443 : 80)
+  );
+  return await new Promise((resolve9) => {
+    let settled = false;
+    let timeout;
+    const socket = createConnection({ host: hostname, port });
+    socket.unref();
+    const finish = (reachable) => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== void 0) clearTimeout(timeout);
+      socket.destroy();
+      resolve9(reachable);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    timeout = setTimeout(() => finish(false), timeoutMs);
+    timeout.unref();
+  });
+}
+function monitorUpstream(bridge, options) {
+  const intervalMs = positiveMilliseconds(
+    options.intervalMs,
+    DEFAULT_UPSTREAM_MONITOR_INTERVAL_MS
+  );
+  const connectTimeoutMs = positiveMilliseconds(
+    options.connectTimeoutMs,
+    DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS
+  );
+  const initialTimeoutMs = positiveMilliseconds(
+    options.initialTimeoutMs,
+    6e4
+  );
+  const failureGraceMs = positiveMilliseconds(
+    options.failureGraceMs,
+    DEFAULT_UPSTREAM_FAILURE_GRACE_MS
+  );
+  let connected = false;
+  let unavailableSince;
+  let stopped = false;
+  let timer;
+  const stop = () => {
+    stopped = true;
+    if (timer !== void 0) clearTimeout(timer);
+  };
+  const schedule = () => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      void check().catch(() => void 0);
+    }, intervalMs);
+    timer.unref();
+  };
+  const check = async () => {
+    if (stopped) return;
+    const reachable = await probeUpstream(bridge.upstreamUrl, connectTimeoutMs);
+    if (stopped) return;
+    const now = Date.now();
+    if (reachable) {
+      connected = true;
+      unavailableSince = void 0;
+      schedule();
+      return;
+    }
+    unavailableSince ??= now;
+    const timeoutMs = connected ? failureGraceMs : initialTimeoutMs;
+    if (now - unavailableSince >= timeoutMs) {
+      stop();
+      await bridge.close();
+      return;
+    }
+    schedule();
+  };
+  void bridge.closed.then(stop);
+  void check().catch(() => void 0);
+}
 function normalizeUpstream(value) {
   const url = new URL(value);
   if (url.protocol !== "http:" && url.protocol !== "https:") {
@@ -4905,6 +5302,26 @@ async function startBridgeCore(options, dependencies) {
   let gateway;
   let controlService;
   let registryWritten = false;
+  let registryUpdate = Promise.resolve();
+  let latestRuntimeState = { status: "idle" };
+  const updateRuntimeState = (status, activeTaskId) => {
+    latestRuntimeState = {
+      status,
+      ...activeTaskId === void 0 ? {} : { activeTaskId }
+    };
+    if (!registryWritten) return;
+    registryUpdate = registryUpdate.then(async () => {
+      await updateInstance(
+        loadedConfig.repoRoot,
+        process.pid,
+        {
+          status,
+          activeTaskId: activeTaskId ?? null
+        },
+        { environment }
+      );
+    }).catch(() => void 0);
+  };
   try {
     lock = options.lock ?? await acquireWorktreeLock(loadedConfig.repoRoot, { environment });
     const host = options.host ?? loadedConfig.config.gateway.host;
@@ -4918,7 +5335,10 @@ async function startBridgeCore(options, dependencies) {
       repoRoot: loadedConfig.repoRoot,
       configRoot: loadedConfig.configRoot,
       workspaceRoot: loadedConfig.workspaceRoot,
-      upstreamUrl: options.upstreamUrl
+      upstreamUrl: options.upstreamUrl,
+      onRuntimeState: (state) => {
+        updateRuntimeState(state.status, state.activeTaskId);
+      }
     };
     controlService = await resolveControlService(dependencies, controlContext);
     const allowedOrigins = new Set(loadedConfig.config.security.allowedOrigins);
@@ -4933,20 +5353,33 @@ async function startBridgeCore(options, dependencies) {
       allowedOrigins: [...allowedOrigins]
     });
     const address = await gateway.start();
-    const openUrl = publicUrl ?? address.url;
+    const openUrl = createPairingUrl(publicUrl ?? address.url, token);
     const instance = {
       projectId: loadedConfig.config.project.id,
       repoRoot: loadedConfig.repoRoot,
       pid: process.pid,
       gatewayUrl: address.url,
       upstreamUrl: options.upstreamUrl,
-      status: "idle",
+      status: latestRuntimeState.status,
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...latestRuntimeState.activeTaskId === void 0 ? {} : { activeTaskId: latestRuntimeState.activeTaskId },
       ...publicUrl === void 0 ? {} : { publicUrl }
     };
     await writeInstance(loadedConfig.repoRoot, instance, { environment });
     registryWritten = true;
-    let closed = false;
+    const emergencyExitCleanup = () => {
+      try {
+        removeInstanceSync(loadedConfig.repoRoot, process.pid, { environment });
+        lock?.releaseSync();
+      } catch {
+      }
+    };
+    process.once("exit", emergencyExitCleanup);
+    let resolveClosed = () => void 0;
+    const closed = new Promise((resolve9) => {
+      resolveClosed = resolve9;
+    });
+    let closePromise;
     return {
       mode: options.mode,
       projectId: loadedConfig.config.project.id,
@@ -4958,18 +5391,33 @@ async function startBridgeCore(options, dependencies) {
       openUrl,
       gateway,
       ...options.managedProcess === void 0 ? {} : { managedProcess: options.managedProcess },
-      async close() {
-        if (closed) {
-          return;
-        }
-        closed = true;
-        await Promise.allSettled([
-          gateway?.close(),
-          options.managedProcess?.stop(),
-          controlService?.close?.()
-        ]);
-        await removeInstance(loadedConfig.repoRoot, process.pid, { environment });
-        await lock?.release();
+      closed,
+      close() {
+        closePromise ??= (async () => {
+          process.off("exit", emergencyExitCleanup);
+          try {
+            await registryUpdate;
+            await updateInstance(
+              loadedConfig.repoRoot,
+              process.pid,
+              { status: "stopping", activeTaskId: null },
+              { environment }
+            );
+            await Promise.allSettled([
+              gateway?.close(),
+              options.managedProcess?.stop(),
+              controlService?.close?.()
+            ]);
+            await removeInstance(loadedConfig.repoRoot, process.pid, { environment });
+          } finally {
+            try {
+              await lock?.release();
+            } finally {
+              resolveClosed();
+            }
+          }
+        })();
+        return closePromise;
       }
     };
   } catch (error) {
@@ -4990,7 +5438,7 @@ async function startAttachBridge(options, dependencies = {}) {
   const repoRoot = await discoverGitWorktreeRoot(cwd);
   const configRoot = await discoverVisualDevConfigRoot(cwd, repoRoot);
   const loadedConfig = await loadVisualDevConfig(repoRoot, { configRoot });
-  return await startBridgeCore(
+  const bridge = await startBridgeCore(
     {
       mode: "attach",
       loadedConfig,
@@ -5001,6 +5449,13 @@ async function startAttachBridge(options, dependencies = {}) {
     },
     dependencies
   );
+  if (dependencies.upstreamMonitor !== false) {
+    monitorUpstream(bridge, {
+      initialTimeoutMs: loadedConfig.config.upstream.ready.timeoutMs,
+      ...dependencies.upstreamMonitor
+    });
+  }
+  return bridge;
 }
 async function startManagedBridge(options = {}, dependencies = {}) {
   const cwd = dependencies.cwd ?? process.cwd();
@@ -5102,6 +5557,7 @@ async function runBridgeUntilSignal(bridge, processLike = process, gracefulTimeo
     };
     for (const signal of signals) processLike.once(signal, shutdown);
     void bridge.managedProcess?.exit.then(shutdown);
+    void bridge.closed?.then(shutdown);
   });
 }
 function formatBridgeSummary(bridge) {
@@ -5120,9 +5576,9 @@ function formatBridgeSummary(bridge) {
 import { constants } from "node:fs";
 import { access as access2, stat as stat3 } from "node:fs/promises";
 import { delimiter, isAbsolute as isAbsolute5, join as join4, relative as relative6, resolve as resolve7 } from "node:path";
-import { execFile as execFile2 } from "node:child_process";
-import { promisify as promisify2 } from "node:util";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile3 } from "node:child_process";
+import { promisify as promisify3 } from "node:util";
+var execFileAsync3 = promisify3(execFile3);
 async function fileExists(path) {
   try {
     await stat3(path);
@@ -5136,7 +5592,7 @@ async function fileExists(path) {
 }
 async function isIgnored(repoRoot, path) {
   try {
-    await execFileAsync2("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", path], {
+    await execFileAsync3("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", path], {
       windowsHide: true
     });
     return true;
@@ -5178,6 +5634,7 @@ async function runDoctor(dependencies = {}) {
       repoRoot
     );
     const loaded = await loadVisualDevConfig(repoRoot, { configRoot });
+    const environment = dependencies.environment ?? process.env;
     checks.push({
       name: "config",
       status: loaded.loadedFiles.length === 0 ? "warning" : "pass",
@@ -5198,7 +5655,7 @@ async function runDoctor(dependencies = {}) {
       const available = executable !== void 0 && await executableAvailable(
         executable,
         loaded.workspaceRoot,
-        dependencies.environment ?? process.env
+        environment
       );
       checks.push({
         name: "dev-command",
@@ -5206,6 +5663,65 @@ async function runDoctor(dependencies = {}) {
         message: available ? `${executable} is executable.` : `${executable ?? "<empty>"} was not found or is not executable.`
       });
     }
+    const adapter = loaded.config.agent.adapter;
+    const adapterSupported = adapter === "codex";
+    const agentAvailable = await executableAvailable(
+      adapter,
+      loaded.workspaceRoot,
+      environment
+    );
+    checks.push({
+      name: "agent",
+      status: adapterSupported && agentAvailable ? "pass" : "fail",
+      message: !adapterSupported ? `${adapter} is configured but is not implemented in this build.` : agentAvailable ? `${adapter} is executable.` : `${adapter} was not found or is not executable.`
+    });
+    const rtkAvailable = await executableAvailable(
+      "rtk",
+      loaded.workspaceRoot,
+      environment
+    );
+    checks.push({
+      name: "rtk",
+      status: rtkAvailable ? "pass" : "warning",
+      message: rtkAvailable ? "rtk is available for token-efficient command output." : "rtk was not found; agent commands will use their native output."
+    });
+    const verificationCommands = loaded.config.verification.commands;
+    if (verificationCommands.length === 0) {
+      checks.push({
+        name: "verification",
+        status: "warning",
+        message: "No verification commands are configured."
+      });
+    } else {
+      const availability = await Promise.all(
+        verificationCommands.map(async ({ command: command2, name }) => ({
+          name,
+          available: await executableAvailable(
+            command2[0] ?? "",
+            loaded.workspaceRoot,
+            environment
+          )
+        }))
+      );
+      const missing = availability.filter(({ available }) => !available).map(({ name }) => name);
+      checks.push({
+        name: "verification",
+        status: missing.length === 0 ? "pass" : "fail",
+        message: missing.length === 0 ? `${verificationCommands.length} verification command(s) are ready.` : `Missing executable for: ${missing.join(", ")}.`
+      });
+    }
+    const publicUrl = loaded.config.gateway.publicUrl;
+    checks.push({
+      name: "public-url",
+      status: publicUrl === void 0 ? "warning" : "pass",
+      message: publicUrl === void 0 ? "No gateway.publicUrl is configured; pairing links will use the local gateway URL." : `Pairing links will use ${publicUrl}.`
+    });
+    const allowedOrigins = loaded.config.security.allowedOrigins;
+    checks.push({
+      name: "allowed-origins",
+      status: allowedOrigins.length > 0 || publicUrl !== void 0 ? "pass" : "warning",
+      message: allowedOrigins.length > 0 ? `${allowedOrigins.length} browser origin(s) are explicitly allowed.` : publicUrl !== void 0 ? "The configured public URL origin will be allowed automatically." : "No browser origins are configured; add security.allowedOrigins before remote access."
+    });
   } catch (error) {
     checks.push({
       name: "config",
@@ -5666,13 +6182,18 @@ function formatBridgeStatus(status) {
     return "No Visual Bridge is running for this worktree.";
   }
   const { instance } = status;
-  return [
+  const rows = [
     `Project:  ${instance.projectId}`,
     `Status:   ${instance.status}`,
     `PID:      ${instance.pid}`,
     `Gateway:  ${instance.gatewayUrl}`,
     `Upstream: ${instance.upstreamUrl}`
-  ].join("\n");
+  ];
+  if (instance.publicUrl !== void 0) rows.push(`Public:   ${instance.publicUrl}`);
+  if (instance.activeTaskId !== void 0) {
+    rows.push(`Active:   ${instance.activeTaskId}`);
+  }
+  return rows.join("\n");
 }
 
 // src/index.ts
@@ -5697,7 +6218,7 @@ function setExitCode(dependencies, code) {
   }
 }
 function createCli(dependencies = {}) {
-  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.3.0");
+  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.3.1");
   program.command("init").description("Configure Visual Remote for the current Vite or Next.js project").action(async () => {
     const result = await initializeVisualDev(dependencies);
     output(dependencies, formatInitResult(result));
@@ -5749,7 +6270,7 @@ async function main(argv = process.argv, dependencies = {}) {
 }
 function isDirectEntry(entryPath2) {
   try {
-    return pathToFileURL(realpathSync(resolve8(entryPath2))).href === import.meta.url;
+    return pathToFileURL(realpathSync2(resolve8(entryPath2))).href === import.meta.url;
   } catch {
     return false;
   }