@love-moon/conductor-cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @love-moon/conductor-cli
 
+## 0.15.0
+
+### Minor Changes
+
+- b61c881: Global AI backend tasks (RFC 0041) that work directly in another daemon's
+  project directory (`launch_config.remoteWorkspace`) now get the same
+  `conductor remote mcp` tools as remote-worktree tasks, bound to that
+  repository and starting in the project directory.
+
+  The daemon advertises `global_backend_v1` so the web app only offers a daemon
+  as a global AI backend when its CLI can drive another daemon.
+
+- cc1e290: New Terminal and Resume Session previews in the create-task dialog.
+
+  - `@love-moon/ai-sdk`: `listSessions` (claude, codex) returns `preview` with
+    the first user message, the assistant reply to it, and the session's last
+    message.
+  - The daemon passes the preview to `list_backend_sessions` as
+    `first_user_message`, `first_reply`, `last_message` and `last_message_role`.
+  - A PTY task with no project path now starts its shell in `$HOME`. The
+    terminal log stays in the dated workspace directory.
+
+- 55b65db: `conductor remote mcp`: structured tools for a task whose worktree lives on
+  another daemon (RFC 0040).
+
+  - New `conductor remote mcp --host <daemon> --root <dir> [--cwd <dir>]`, a
+    stdio MCP server with `remote_read`, `remote_edit`, `remote_write`,
+    `remote_grep`, `remote_glob` and `remote_bash`, bound to that directory.
+  - For a `launch_config.remoteWorktree` task the daemon passes the binding to
+    fire (`CONDUCTOR_REMOTE_WORKTREE`), and fire attaches the server to Claude
+    (`mcpServers`) and Codex (`-c mcp_servers.*`). The agent token is forwarded
+    by env only, never on argv.
+  - `@love-moon/ai-sdk`: the Codex app-server session accepts `configOverrides`,
+    passed to the app-server as `-c key=value`.
+
+### Patch Changes
+
+- Updated dependencies [cc1e290]
+- Updated dependencies [55b65db]
+  - @love-moon/ai-sdk@0.15.0
+  - @love-moon/conductor-sdk@0.15.0
+
 ## 0.14.0
 
 ### Minor Changes

package/bin/conductor-fire.js

@@ -26,6 +26,11 @@ import {
   resolveSessionRunDirectory as resolveCliSessionRunDirectory,
   resumeProviderForBackend as resumeProviderForCliBackend,
 } from "../src/fire/resume.js";
+import {
+  REMOTE_WORKTREE_ENV,
+  buildRemoteWorktreeSessionOptions,
+  readRemoteWorktreeBinding,
+} from "../src/remote/mcp-launch.js";
 import {
   filterRuntimeSupportedAllowCliList,
   inferBuiltInRuntimeBackendFromCommand,
@@ -616,6 +621,13 @@ async function main() {
     delete process.env.CONDUCTOR_BACKEND_WS_URL;
     process.env.CONDUCTOR_CONFIG = cliArgs.configFile;
   }
+  // RFC 0040: the daemon's binding for a remote-worktree task. Consumed here so
+  // it does not leak into the AI's shell (and from there into a nested fire).
+  const remoteWorktreeBinding = readRemoteWorktreeBinding(process.env);
+  delete process.env[REMOTE_WORKTREE_ENV];
+  if (remoteWorktreeBinding) {
+    log(`Remote worktree tools bound to ${remoteWorktreeBinding.host}:${remoteWorktreeBinding.cwd}`);
+  }
   let runtimeProjectPath = process.cwd();
   let backendSession = null;
 
@@ -1031,6 +1043,13 @@ async function main() {
             resumeSessionId,
             configFile: cliArgs.configFile,
             ...(cliArgs.sessionOptions || {}),
+            ...buildRemoteWorktreeSessionOptions({
+              backend: cliArgs.sessionBackend || cliArgs.backend,
+              binding: remoteWorktreeBinding,
+              sessionOptions: cliArgs.sessionOptions || {},
+              commandLine: sessionCommandLine,
+              configFile: cliArgs.configFile,
+            }),
             ...(sessionCommandLine ? { commandLine: sessionCommandLine } : {}),
             ...(enableGoalsForBackend ? { goalMode: true } : {}),
             logger: { log },

package/bin/conductor-remote.js

@@ -20,6 +20,7 @@ import { EXIT } from "../src/remote/client.js";
 import { runRemoteExec, showHelp as showExecHelp } from "../src/remote/exec.js";
 import { runRemoteCp, showHelp as showCpHelp } from "../src/remote/cp.js";
 import { runRemoteWait, showHelp as showWaitHelp } from "../src/remote/wait.js";
+import { runRemoteMcp, showHelp as showMcpHelp } from "../src/remote/mcp.js";
 
 export { EXIT };
 
@@ -27,6 +28,7 @@ const VERBS = new Map([
   ["exec", runRemoteExec],
   ["cp", runRemoteCp],
   ["wait", runRemoteWait],
+  ["mcp", runRemoteMcp],
 ]);
 
 const isMainModule = (() => {
@@ -45,6 +47,7 @@ Verbs:
   exec   Run a command on another daemon's host
   cp     Copy a file to or from another daemon's host
   wait   Wait for a command that \`exec\` left running (by run id)
+  mcp    Serve MCP tools bound to a directory on another daemon's host
 
 Options:
   -h, --help   Show this help
@@ -59,6 +62,7 @@ For verb-specific help:
   conductor remote exec --help
   conductor remote cp --help
   conductor remote wait --help
+  conductor remote mcp --help
 `);
 }
 
@@ -89,7 +93,7 @@ export async function runRemote(argv, deps = {}) {
   return handler(argv.slice(1), deps);
 }
 
-export { showExecHelp, showCpHelp, showWaitHelp };
+export { showExecHelp, showCpHelp, showWaitHelp, showMcpHelp };
 
 if (isMainModule) {
   // `process.exitCode` rather than `process.exit()`: writes to a pipe are async,

package/bin/conductor.js

@@ -137,7 +137,7 @@ Subcommands:
   project   Manage Conductor projects (list/show/create/...)
   issue     Manage issues (list/show/create/update/start/done)
   task      Manage tasks (create/list/show/send/messages/schedule)
-  remote    Run commands and copy files on another daemon's host (exec/cp/wait)
+  remote    Run commands and copy files on another daemon's host (exec/cp/wait/mcp)
 
 Options:
   -h, --help     Show this help message

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.14.0",
-  "gitCommitId": "6def94c",
+  "version": "0.15.0",
+  "gitCommitId": "a097cd6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -24,8 +24,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-sdk": "0.14.0",
-    "@love-moon/conductor-sdk": "0.14.0",
+    "@love-moon/ai-sdk": "0.15.0",
+    "@love-moon/conductor-sdk": "0.15.0",
     "@github/copilot-sdk": "^0.3.0",
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0",
@@ -38,7 +38,7 @@
   },
   "optionalDependencies": {
     "@roamhq/wrtc": "^0.10.0",
-    "@love-moon/chat-web": "0.14.0"
+    "@love-moon/chat-web": "0.15.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/daemon.js

@@ -44,6 +44,7 @@ import {
   createRemoteExecHandlers,
   handleRemoteExecRequest,
 } from "./remote-exec-handlers.js";
+import { REMOTE_WORKTREE_ENV, remoteWorktreeFireEnv } from "./remote/mcp-launch.js";
 import {
   REMOTE_FILE_CAPABILITY,
   createRemoteFileHandlers,
@@ -792,6 +793,10 @@ export async function collectBackendSessions({
           cwd: normalizeOptionalString(entry?.cwd),
           title: normalizeOptionalString(entry?.title),
           updated_at: Number.isFinite(entry?.updatedAt) ? new Date(entry.updatedAt).toISOString() : null,
+          first_user_message: normalizeOptionalString(entry?.preview?.firstUserMessage),
+          first_reply: normalizeOptionalString(entry?.preview?.firstReply),
+          last_message: normalizeOptionalString(entry?.preview?.lastMessage?.text),
+          last_message_role: normalizeOptionalString(entry?.preview?.lastMessage?.role),
         });
       }
     } catch (error) {
@@ -892,6 +897,7 @@ const PTY_TASK_SCOPED_ENV_KEYS = [
   "CONDUCTOR_PTY_SESSION_ID",
   "CONDUCTOR_LAUNCHED_BY_DAEMON",
   "CONDUCTOR_RESUME_CWD",
+  REMOTE_WORKTREE_ENV,
 ];
 
 // Task-scoped env vars a Fire must NEVER inherit from anywhere but this
@@ -3889,6 +3895,10 @@ export function startDaemon(config = {}, deps = {}) {
     "restart_first_message",
     "persistent_round_v1",
     "task_attachments_v1",
+    // RFC 0041: this CLI can run a global-backend task's AI here — it drives
+    // another daemon over `conductor remote` and binds the remote_* MCP tools
+    // to a remoteWorkspace as well as a remoteWorktree.
+    "global_backend_v1",
     "backend_session_list",
     CUSTOM_COMMANDS_CAPABILITY,
     UPDATE_DAEMON_CAPABILITY,
@@ -5784,6 +5794,9 @@ export function startDaemon(config = {}, deps = {}) {
     let taskDir =
       normalizeOptionalString(launchConfig.cwd) ||
       boundPath;
+    // No project path: the shell starts in HOME; the scratch dir below only
+    // holds the terminal log.
+    const shellCwd = taskDir || homeDir;
     if (!taskDir) {
       const now = new Date();
       const dayDir = path.join(WORKSPACE_ROOT, formatWorkspaceDate(now));
@@ -5809,7 +5822,7 @@ export function startDaemon(config = {}, deps = {}) {
 
     let launchSpec;
     try {
-      launchSpec = resolvePtyLaunchSpec(launchConfig, taskDir);
+      launchSpec = resolvePtyLaunchSpec(launchConfig, shellCwd);
     } catch (error) {
       logError(`Failed to resolve PTY launch config for ${taskId}: ${error?.message || error}`);
       sendAgentCommandAck({
@@ -5838,7 +5851,7 @@ export function startDaemon(config = {}, deps = {}) {
 
     const env = buildPtyTaskEnv(process.env, launchSpec.env);
 
-    const logPath = path.join(launchSpec.cwd, "conductor-terminal.log");
+    const logPath = path.join(taskDir, "conductor-terminal.log");
     let logStream;
     try {
       logStream = createWriteStreamFn(logPath, { flags: "a" });
@@ -5874,7 +5887,6 @@ export function startDaemon(config = {}, deps = {}) {
         rejectCreatePtyTaskDuringShutdown(payload, { sendAck: false });
         return;
       }
-      const resolvedLogPath = path.join(taskDir, "conductor-terminal.log");
 
       const startedAt = new Date().toISOString();
       const record = {
@@ -5883,7 +5895,8 @@ export function startDaemon(config = {}, deps = {}) {
         ptySessionId,
         projectId,
         taskDir,
-        logPath: resolvedLogPath,
+        cwd: launchSpec.cwd,
+        logPath,
         logStream,
         cols: launchSpec.cols,
         rows: launchSpec.rows,
@@ -5904,7 +5917,7 @@ export function startDaemon(config = {}, deps = {}) {
         project_id: projectId,
         pty_session_id: ptySessionId,
         pid: Number.isInteger(pty?.pid) ? pty.pid : null,
-        cwd: taskDir,
+        cwd: launchSpec.cwd,
         shell: launchSpec.shell,
         cols: launchSpec.cols,
         rows: launchSpec.rows,
@@ -6111,7 +6124,7 @@ export function startDaemon(config = {}, deps = {}) {
       project_id: record.projectId,
       pty_session_id: record.ptySessionId,
       pid: Number.isInteger(record.pty?.pid) ? record.pty.pid : null,
-      cwd: record.taskDir,
+      cwd: record.cwd,
       shell: record.shell,
       cols: record.cols,
       rows: record.rows,
@@ -7812,6 +7825,8 @@ export function startDaemon(config = {}, deps = {}) {
         // backend (dsh/copilot) would see e.g. `claude --model opus` here and
         // mis-apply its flags. Fire treats "" as unset.
         CONDUCTOR_CLI_COMMAND: cliCommand,
+        // RFC 0040: lets fire give the AI tools bound to the remote worktree.
+        ...remoteWorktreeFireEnv(launchConfig),
       };
       if (AGENT_TOKEN) {
         env.CONDUCTOR_AGENT_TOKEN = AGENT_TOKEN;
@@ -8571,6 +8586,7 @@ export function startDaemon(config = {}, deps = {}) {
       // gets an explicit `-e CONDUCTOR_CLI_COMMAND=` that overrides any stale
       // value in the tmux SERVER's global environment (see create_task).
       CONDUCTOR_CLI_COMMAND: cliCommand,
+      ...remoteWorktreeFireEnv(targetLaunchConfig),
     };
     env.CONDUCTOR_RESUME_CWD = resolvedResumeCwd;
     if (AGENT_TOKEN) {

package/src/remote/cp.js

@@ -385,7 +385,7 @@ async function downloadChunks({
   }, { sleep });
 }
 
-async function uploadFile(ctx) {
+export async function uploadFile(ctx) {
   const { config, target, localPath, remotePath, fetchImpl, consoleImpl, signal, quiet } = ctx;
   const resolvedLocal = path.resolve(expandHome(localPath));
 
@@ -466,7 +466,7 @@ async function uploadFile(ctx) {
   return { ...delivered, transferId, direction: "up", sizeBytes: stat.size, sha256 };
 }
 
-async function downloadFile(ctx) {
+export async function downloadFile(ctx) {
   const { config, target, remotePath, localPath, fetchImpl, consoleImpl, signal, quiet } = ctx;
   const basePath = `/api/agents/${encodeURIComponent(target)}/files`;
 

package/src/remote/mcp-launch.js

@@ -0,0 +1,167 @@
+/**
+ * Wiring `conductor remote mcp` into a remote-worktree task (RFC 0040).
+ *
+ * The daemon knows the task's `launch_config.remoteWorktree`; fire knows which
+ * AI backend it is about to start. The daemon resolves the binding (which
+ * daemon, which directory) and hands it to fire in one env var; fire turns it
+ * into that backend's MCP configuration. Kept free of heavy imports: both the
+ * daemon and fire load it on every task.
+ */
+
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+export const MCP_SERVER_NAME = "conductor_remote";
+export const REMOTE_WORKTREE_ENV = "CONDUCTOR_REMOTE_WORKTREE";
+
+/** The server's credentials travel by env, never argv (argv is world-readable in `ps`). */
+const FORWARDED_ENV = [
+  "CONDUCTOR_AGENT_TOKEN",
+  "CONDUCTOR_BACKEND_URL",
+  "CONDUCTOR_CONFIG",
+  "CONDUCTOR_HOME",
+  "CONDUCTOR_REMOTE_CHUNK_BYTES",
+  // Codex hands MCP servers only a minimal env; a corporate CA must still reach fetch.
+  "NODE_EXTRA_CA_CERTS",
+];
+
+/** remote_bash may wait up to 10 minutes; Codex's default MCP tool timeout is 60s. */
+const CODEX_TOOL_TIMEOUT_SEC = 900;
+
+const REMOTE_SCRIPT = fileURLToPath(new URL("../../bin/conductor-remote.js", import.meta.url));
+
+const str = (value) => (typeof value === "string" && value.trim() ? value.trim() : "");
+
+const isWindowsStylePath = (value) => /^[A-Za-z]:[\\/]/.test(value) || value.includes("\\");
+
+/**
+ * Where the remote worktree lives, from `launch_config.remoteWorktree`. Same
+ * math as web's `resolveRemoteWorktreePaths` and the daemon's
+ * `buildTaskWorktreeRoot`: `<workspacePath>/.conductor/worktrees/<branch>`, and
+ * the work dir is the project's offset inside the repository under that.
+ */
+export function resolveRemoteWorktreeBinding(launchConfig) {
+  const raw = launchConfig?.remoteWorktree ?? launchConfig?.remote_worktree;
+  if (!raw || typeof raw !== "object") return resolveRemoteWorkspaceBinding(launchConfig);
+  const host = str(raw.host);
+  const repoRoot = str(raw.repoRoot) || str(raw.repo_root);
+  const workspacePath = str(raw.workspacePath) || str(raw.workspace_path);
+  const branch = str(raw.branch);
+  if (!host || !repoRoot || !workspacePath || !branch) return null;
+
+  const pathApi = isWindowsStylePath(repoRoot) || isWindowsStylePath(workspacePath) ? path.win32 : path.posix;
+  const folder = branch.replace(/[/\\]/g, "_").replace(/\.\./g, "_");
+  const root = pathApi.join(workspacePath, ".conductor", "worktrees", folder);
+  const relative = pathApi.relative(repoRoot, workspacePath);
+  if (relative.startsWith("..") || pathApi.isAbsolute(relative)) return null;
+  const cwd = relative && relative !== "." ? pathApi.join(root, relative) : root;
+  return { host, root, cwd };
+}
+
+/**
+ * RFC 0041 direct mode: `launch_config.remoteWorkspace` points at the project
+ * directory itself (no worktree). The tools stay inside the repository and
+ * start in the project's directory.
+ */
+function resolveRemoteWorkspaceBinding(launchConfig) {
+  const raw = launchConfig?.remoteWorkspace ?? launchConfig?.remote_workspace;
+  if (!raw || typeof raw !== "object") return null;
+  const host = str(raw.host);
+  const repoRoot = str(raw.repoRoot) || str(raw.repo_root);
+  const workspacePath = str(raw.workspacePath) || str(raw.workspace_path);
+  if (!host || !repoRoot || !workspacePath) return null;
+  const pathApi = isWindowsStylePath(repoRoot) || isWindowsStylePath(workspacePath) ? path.win32 : path.posix;
+  const relative = pathApi.relative(repoRoot, workspacePath);
+  if (relative.startsWith("..") || pathApi.isAbsolute(relative)) return null;
+  return { host, root: repoRoot, cwd: workspacePath };
+}
+
+/** Env the daemon adds when it spawns fire. Empty for an ordinary task. */
+export function remoteWorktreeFireEnv(launchConfig) {
+  const binding = resolveRemoteWorktreeBinding(launchConfig);
+  return binding ? { [REMOTE_WORKTREE_ENV]: JSON.stringify(binding) } : {};
+}
+
+export function readRemoteWorktreeBinding(env = process.env) {
+  const raw = str(env?.[REMOTE_WORKTREE_ENV]);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    const host = str(parsed?.host);
+    const root = str(parsed?.root);
+    const cwd = str(parsed?.cwd) || root;
+    return host && root ? { host, root, cwd } : null;
+  } catch {
+    return null;
+  }
+}
+
+function serverArgs(binding, configFile, remoteScript) {
+  return [
+    remoteScript,
+    "mcp",
+    "--host", binding.host,
+    "--root", binding.root,
+    "--cwd", binding.cwd,
+    // Absolute: the backend starts the server in the session's cwd, not ours.
+    ...(configFile ? ["--config-file", path.resolve(configFile)] : []),
+  ];
+}
+
+/**
+ * Session options that give the backend the remote workspace tools, merged
+ * over what the user configured. Only Claude and Codex are wired; any other
+ * backend gets nothing and keeps using `conductor remote exec` as before.
+ */
+export function buildRemoteWorktreeSessionOptions({
+  backend,
+  binding,
+  sessionOptions = {},
+  commandLine = "",
+  configFile = "",
+  env = process.env,
+  execPath = process.execPath,
+  remoteScript = REMOTE_SCRIPT,
+} = {}) {
+  if (!binding) return {};
+  const args = serverArgs(binding, configFile, remoteScript);
+  const normalizedBackend = String(backend || "").trim().toLowerCase();
+
+  if (normalizedBackend === "claude") {
+    const allowed = Array.isArray(sessionOptions.allowedTools) ? sessionOptions.allowedTools : [];
+    // Same precedence as the Claude session: explicit option, then the
+    // configured command line's `--permission-mode`.
+    const mode = sessionOptions.permissionMode
+      ?? String(commandLine || "").match(/--permission-mode[=\s]+([^\s"']+)/)?.[1];
+    return {
+      mcpServers: {
+        ...(sessionOptions.mcpServers || {}),
+        [MCP_SERVER_NAME]: { type: "stdio", command: execPath, args },
+      },
+      // Under the default bypassPermissions a root install is downgraded to
+      // acceptEdits, which would deny every remote_* call headless. A mode the
+      // user chose on purpose is left alone rather than widened.
+      ...(mode === undefined || mode === "bypassPermissions"
+        ? { allowedTools: [...new Set([...allowed, `mcp__${MCP_SERVER_NAME}`])] }
+        : {}),
+    };
+  }
+
+  if (normalizedBackend === "codex") {
+    // Values are TOML; JSON strings and string arrays are valid TOML as-is.
+    const prefix = `mcp_servers.${MCP_SERVER_NAME}`;
+    const forwarded = FORWARDED_ENV.filter((name) => str(env?.[name]));
+    return {
+      configOverrides: [
+        ...(Array.isArray(sessionOptions.configOverrides) ? sessionOptions.configOverrides : []),
+        `${prefix}.command=${JSON.stringify(execPath)}`,
+        `${prefix}.args=${JSON.stringify(args)}`,
+        ...(forwarded.length > 0 ? [`${prefix}.env_vars=${JSON.stringify(forwarded)}`] : []),
+        `${prefix}.tool_timeout_sec=${CODEX_TOOL_TIMEOUT_SEC}`,
+      ],
+    };
+  }
+
+  return {};
+}

package/src/remote/mcp.js

@@ -0,0 +1,849 @@
+/**
+ * `conductor remote mcp` — a stdio MCP server whose tools act on one directory
+ * on another daemon's host (RFC 0040).
+ *
+ * The AI runs on this daemon, the task's worktree lives on `--host`. Without
+ * this server the AI reaches it only through `conductor remote exec -- <shell>`:
+ * hand-numbered `sed -n` reads, heredoc/`sed -i` edits that are easy to get
+ * wrong, `rg` output cut to the last 64 000 characters, and nothing stopping a
+ * forgotten `-t/-w` from editing the local checkout instead. Here the target is
+ * fixed at startup and the tools have the shape of the native ones.
+ *
+ * Nothing new runs on the target: reads, searches and shell commands go through
+ * `remote exec`, and edits/writes move whole files with `remote cp`'s transfer
+ * (exact bytes, no shell quoting, atomic rename on the target).
+ */
+
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline";
+import { createRequire } from "node:module";
+
+import { EXIT, UsageError, loadCliConfig } from "./client.js";
+import { execRemote, waitForRun } from "./exec.js";
+import { downloadFile, uploadFile } from "./cp.js";
+import { MCP_SERVER_NAME } from "./mcp-launch.js";
+
+const require = createRequire(import.meta.url);
+const { version: CLI_VERSION } = require("../../package.json");
+
+const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+
+/** `remote exec` keeps the last 64 000 characters; stay well inside that. */
+const OUTPUT_BUDGET_BYTES = 60_000;
+const READ_DEFAULT_LIMIT = 2000;
+const READ_MAX_LINE_CHARS = 2000;
+const SEARCH_DEFAULT_LIMIT = 100;
+const SEARCH_MAX_LIMIT = 1000;
+const FILE_OP_TIMEOUT_MS = 120_000;
+const BASH_DEFAULT_TIMEOUT_MS = 120_000;
+const BASH_MAX_TIMEOUT_MS = 600_000;
+const DEFAULT_FILE_MODE = 0o644;
+
+/** A failure the AI should see as a tool error, not a protocol error. */
+export class ToolError extends Error {}
+
+// ---------------------------------------------------------------------------
+// Remote scripts. Arguments are always passed as positional parameters
+// (`bash -c <script> conductor-mcp <args...>`), never interpolated, so no
+// path or pattern is ever re-parsed by a shell.
+// ---------------------------------------------------------------------------
+
+const READ_SCRIPT = `f=$1; start=$2; end=$3; budget=$4
+if [ -d "$f" ]; then echo "is a directory: $f" >&2; exit 21; fi
+if [ ! -e "$f" ]; then echo "no such file: $f" >&2; exit 2; fi
+if [ ! -r "$f" ]; then echo "permission denied: $f" >&2; exit 13; fi
+awk 'END { print NR }' "$f" || exit $?
+sed -n "\${start},\${end}p" "$f" | head -c "$budget"`;
+
+/**
+ * A symlink is refused rather than followed: the daemon's upload renames over
+ * the link itself, which would silently turn it into a regular file.
+ */
+const SYMLINK_CHECK = `if [ -L "$1" ]; then echo "$1 is a symlink to $(readlink "$1"); edit the target instead" >&2; exit 40; fi`;
+
+/** Hash via stdin: given a file name, GNU sha256sum escapes odd names with a leading "\\". */
+const HASH_SCRIPT = `${SYMLINK_CHECK}
+if command -v sha256sum >/dev/null 2>&1; then sha256sum <"$1"; else shasum -a 256 <"$1"; fi`;
+
+/** Makes the parent directory and reports the current mode, if the file exists. */
+const PREPARE_WRITE_SCRIPT = `${SYMLINK_CHECK}
+f=$1
+if [ -d "$f" ]; then echo "is a directory: $f" >&2; exit 21; fi
+mkdir -p "$(dirname "$f")" || exit $?
+if [ -e "$f" ]; then stat -c %a "$f" 2>/dev/null || stat -f %Lp "$f"; fi`;
+
+/**
+ * Runs "$@" on `target` into a temp file, prints "<d|f> <line count>", then one
+ * page of it. The search runs from inside the target directory (or a file's
+ * parent) on a relative path, because that is the only way ripgrep anchors a
+ * glob like `src/**\/*.ts`; the caller turns the relative paths back into
+ * absolute ones. Every page re-runs the command, so paging relies on each
+ * caller asking for a deterministic order (`--sort`/`--sortr`).
+ */
+const PAGE_SCRIPT = `off=$1; lim=$2; budget=$3; nozero=$4; target=$5; shift 5
+if [ -d "$target" ]; then cd "$target" || exit 2; rel=.; kind=d
+elif [ -e "$target" ]; then cd "$(dirname "$target")" || exit 2; rel=$(basename "$target"); kind=f
+else echo "no such file or directory: $target" >&2; exit 2; fi
+tmp=$(mktemp "\${TMPDIR:-/tmp}/conductor-mcp.XXXXXX") || exit 125
+trap 'rm -f "$tmp" "$tmp.f"' EXIT
+"$@" "$rel" >"$tmp"; code=$?
+if [ "$code" -gt 1 ] && [ ! -s "$tmp" ]; then exit "$code"; fi
+if [ "$nozero" = 1 ]; then grep -v ':0$' "$tmp" >"$tmp.f"; mv "$tmp.f" "$tmp"; fi
+echo "$kind $(wc -l <"$tmp" | tr -d ' ')"
+tail -n "+$((off + 1))" "$tmp" | head -n "$lim" | head -c "$budget"`;
+
+/** Fallback for `remote_glob` on a host without ripgrep: `$1` pattern, `$2` dir. */
+const GLOB_FALLBACK_SCRIPT = `cd "$2" || exit 2
+shopt -s globstar nullglob dotglob 2>/dev/null
+IFS=$'\\n'
+for f in $1; do [ -f "$f" ] && printf '%s/%s\\n' "$PWD" "$f"; done
+exit 0`;
+
+const TOOLS_SCRIPT = `command -v rg >/dev/null 2>&1 && echo rg || echo grep`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const isWindowsStylePath = (value) => /^[A-Za-z]:[\\/]/.test(value) || value.includes("\\");
+
+function countOccurrences(text, needle) {
+  let count = 0;
+  let index = text.indexOf(needle);
+  while (index !== -1) {
+    count += 1;
+    index = text.indexOf(needle, index + needle.length);
+  }
+  return count;
+}
+
+/** Split a page of output into whole lines, dropping a line cut by the byte budget. */
+function splitPage(text, budget) {
+  const hitBudget = Buffer.byteLength(text) >= budget - 3;
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") {
+    lines.pop();
+  } else if (hitBudget && lines.length > 1) {
+    lines.pop();
+  }
+  return lines;
+}
+
+function splitHeader(stdout) {
+  const newline = stdout.indexOf("\n");
+  if (newline === -1) return { header: stdout.trim(), body: "" };
+  return { header: stdout.slice(0, newline).trim(), body: stdout.slice(newline + 1) };
+}
+
+function formatNumbered(lines, firstLine) {
+  return lines
+    .map((line, index) => {
+      const shown = line.length > READ_MAX_LINE_CHARS
+        ? `${line.slice(0, READ_MAX_LINE_CHARS)}… [line truncated]`
+        : line;
+      return `${String(firstLine + index).padStart(6)}\t${shown}`;
+    })
+    .join("\n");
+}
+
+function toInteger(value, name, { min, max, fallback }) {
+  if (value === undefined || value === null) return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || (max !== undefined && number > max)) {
+    throw new ToolError(`${name} must be an integer${max !== undefined ? ` between ${min} and ${max}` : ` >= ${min}`}`);
+  }
+  return number;
+}
+
+function requireString(value, name, { allowEmpty = false } = {}) {
+  if (typeof value !== "string" || (!allowEmpty && value === "")) {
+    throw new ToolError(`${name} is required`);
+  }
+  return value;
+}
+
+function runFailure(run, what) {
+  const detail = (run?.stderrTail || run?.error || run?.stdoutTail || "").trim();
+  const status = run?.status === "running"
+    ? "timed out"
+    : `exited ${run?.exitCode ?? run?.status ?? "?"}`;
+  return new ToolError(detail ? `${what} failed (${status}): ${detail}` : `${what} failed (${status})`);
+}
+
+// ---------------------------------------------------------------------------
+// The workspace: every tool's behaviour, independent of MCP framing.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} opts
+ * @param {string} opts.host   daemon the workspace lives on
+ * @param {string} opts.root   no tool may touch a path outside this directory
+ * @param {string} [opts.cwd]  relative paths resolve here (default: root)
+ * @param {(req: {command: string, args: string[], workspace?: string, timeoutMs: number}) => Promise<object>} opts.exec
+ *        run one command on the host; resolves with the run record
+ * @param {(runId: string, timeoutMs: number) => Promise<object>} opts.wait
+ *        keep waiting for a run `exec` returned while still running
+ * @param {(remotePath: string, localPath: string) => Promise<{sha256: string, mode?: number}>} opts.download
+ * @param {(localPath: string, remotePath: string) => Promise<unknown>} opts.upload
+ *        replaces the remote file atomically, with the local file's mode
+ */
+export function createRemoteWorkspace(opts) {
+  const { host, exec, wait, download, upload } = opts;
+  const pathApi = isWindowsStylePath(opts.root) ? path.win32 : path.posix;
+  const root = pathApi.normalize(opts.root);
+  const cwd = pathApi.normalize(opts.cwd || opts.root);
+  const tmpRoot = opts.tmpDir || os.tmpdir();
+  let searchTool = null;
+
+  function resolvePath(value, name = "file_path") {
+    const raw = requireString(value, name).trim();
+    const absolute = pathApi.isAbsolute(raw) ? pathApi.normalize(raw) : pathApi.join(cwd, raw);
+    const relative = pathApi.relative(root, absolute);
+    if (relative === ".." || relative.startsWith(`..${pathApi.sep}`) || pathApi.isAbsolute(relative)) {
+      throw new ToolError(`${raw} is outside the remote workspace ${root} on ${host}`);
+    }
+    return absolute;
+  }
+
+  async function runScript(script, args, { what, timeoutMs = FILE_OP_TIMEOUT_MS, okCodes = [0] } = {}) {
+    const run = await exec({ command: "bash", args: ["-c", script, "conductor-mcp", ...args.map(String)], timeoutMs });
+    if (run?.status !== "completed" || !okCodes.includes(run.exitCode)) {
+      throw runFailure(run, what);
+    }
+    return run;
+  }
+
+  async function withTempDir(fn) {
+    const dir = await fsp.mkdtemp(path.join(tmpRoot, "conductor-mcp-"));
+    try {
+      return await fn(dir);
+    } finally {
+      await fsp.rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  async function remoteSha256(file) {
+    const run = await runScript(HASH_SCRIPT, [file], { what: `hashing ${file}` });
+    return String(run.stdoutTail || "").trim().split(/\s+/)[0] || "";
+  }
+
+  async function read({ file_path: filePath, offset, limit } = {}) {
+    const file = resolvePath(filePath);
+    const start = toInteger(offset, "offset", { min: 1, fallback: 1 });
+    const count = toInteger(limit, "limit", { min: 1, fallback: READ_DEFAULT_LIMIT });
+    const run = await runScript(READ_SCRIPT, [file, start, start + count - 1, OUTPUT_BUDGET_BYTES], {
+      what: `reading ${file}`,
+    });
+    const { header, body } = splitHeader(String(run.stdoutTail || ""));
+    const total = Number.parseInt(header, 10) || 0;
+    if (total === 0) return `(${file} is empty)`;
+    if (start > total) {
+      throw new ToolError(`offset ${start} is past the end of ${file} (${total} lines)`);
+    }
+    if (body.includes("\u0000")) {
+      throw new ToolError(`${file} looks like a binary file; use remote_bash to inspect it`);
+    }
+    const lines = splitPage(body, OUTPUT_BUDGET_BYTES);
+    const last = start + lines.length - 1;
+    let text = formatNumbered(lines, start);
+    if (last < total) {
+      text += `\n\n[Showing lines ${start}-${last} of ${total}. Continue with offset=${last + 1}.]`;
+    }
+    return text;
+  }
+
+  async function edit({ file_path: filePath, old_string: oldRaw, new_string: newRaw, replace_all: replaceAll } = {}) {
+    const file = resolvePath(filePath);
+    let oldString = requireString(oldRaw, "old_string", { allowEmpty: true });
+    let newString = requireString(newRaw, "new_string", { allowEmpty: true });
+    if (oldString === "") {
+      throw new ToolError("old_string must not be empty; use remote_write to create or overwrite a file");
+    }
+    if (oldString === newString) {
+      throw new ToolError("old_string and new_string are identical; nothing to change");
+    }
+
+    return withTempDir(async (dir) => {
+      const local = path.join(dir, "file");
+      const original = await download(file, local);
+      const bytes = await fsp.readFile(local);
+      if (bytes.includes(0)) {
+        throw new ToolError(`${file} looks like a binary file; refusing to edit it`);
+      }
+      const text = bytes.toString("utf8");
+      if (!Buffer.from(text, "utf8").equals(bytes)) {
+        throw new ToolError(`${file} is not valid UTF-8; refusing to edit it`);
+      }
+
+      let matches = countOccurrences(text, oldString);
+      // A CRLF file edited with LF snippets: match the file's own line endings.
+      if (matches === 0 && text.includes("\r\n") && oldString.includes("\n") && !oldString.includes("\r\n")) {
+        const crlf = (value) => value.replace(/\r?\n/g, "\r\n");
+        oldString = crlf(oldString);
+        newString = crlf(newString);
+        matches = countOccurrences(text, oldString);
+      }
+      if (matches === 0) {
+        throw new ToolError(`old_string was not found in ${file}`);
+      }
+      if (matches > 1 && replaceAll !== true) {
+        throw new ToolError(
+          `old_string matches ${matches} places in ${file}; add surrounding context to make it unique, or set replace_all`,
+        );
+      }
+
+      const firstIndex = text.indexOf(oldString);
+      const updated = replaceAll === true
+        ? text.split(oldString).join(newString)
+        : text.slice(0, firstIndex) + newString + text.slice(firstIndex + oldString.length);
+      await fsp.writeFile(local, updated);
+
+      // Optimistic concurrency: refuse to overwrite a change made since we read.
+      const current = await remoteSha256(file);
+      if (current !== original.sha256) {
+        throw new ToolError(`${file} changed on ${host} while it was being edited; read it again and retry`);
+      }
+      await fsp.chmod(local, Number.isInteger(original.mode) ? original.mode : DEFAULT_FILE_MODE);
+      await upload(local, file);
+
+      const replaced = replaceAll === true ? matches : 1;
+      const firstLine = text.slice(0, firstIndex).split("\n").length;
+      const updatedLines = updated.split("\n");
+      if (updated.endsWith("\n")) updatedLines.pop();
+      const from = Math.max(1, firstLine - 3);
+      const to = Math.min(updatedLines.length, firstLine + newString.split("\n").length + 2);
+      return (
+        `Edited ${file} on ${host}: replaced ${replaced} occurrence${replaced === 1 ? "" : "s"}.\n` +
+        formatNumbered(updatedLines.slice(from - 1, to), from)
+      );
+    });
+  }
+
+  async function write({ file_path: filePath, content } = {}) {
+    const file = resolvePath(filePath);
+    const body = requireString(content, "content", { allowEmpty: true });
+    const prepared = await runScript(PREPARE_WRITE_SCRIPT, [file], { what: `preparing ${file}` });
+    const modeText = String(prepared.stdoutTail || "").trim();
+    const existed = /^[0-7]{3,4}$/.test(modeText);
+    const mode = existed ? Number.parseInt(modeText, 8) & 0o777 : DEFAULT_FILE_MODE;
+
+    return withTempDir(async (dir) => {
+      const local = path.join(dir, "file");
+      await fsp.writeFile(local, body);
+      await fsp.chmod(local, mode);
+      await upload(local, file);
+      return `${existed ? "Updated" : "Created"} ${file} on ${host} (${Buffer.byteLength(body)} bytes).`;
+    });
+  }
+
+  async function resolveSearchTool() {
+    if (!searchTool) {
+      searchTool = runScript(TOOLS_SCRIPT, [], { what: "probing for ripgrep" })
+        .then((run) => (String(run.stdoutTail || "").trim() === "rg" ? "rg" : "grep"))
+        .catch((error) => {
+          searchTool = null;
+          throw error;
+        });
+    }
+    return searchTool;
+  }
+
+  /** Run a search command on `target` and return one page, with absolute paths. */
+  async function page(command, { target, offset, limit, nozero = false }) {
+    const run = await runScript(
+      PAGE_SCRIPT,
+      [offset, limit, OUTPUT_BUDGET_BYTES, nozero ? 1 : 0, target, ...command],
+      { what: `searching ${target}` },
+    );
+    const { header, body } = splitHeader(String(run.stdoutTail || ""));
+    const [kind, count] = header.split(" ");
+    const total = Number.parseInt(count, 10) || 0;
+    const dir = kind === "f" ? pathApi.dirname(target) : target;
+    const prefix = dir.endsWith(pathApi.sep) ? dir : `${dir}${pathApi.sep}`;
+    // `--` separates context groups; everything else starts with a path that
+    // is relative to `dir` (`./x` from GNU tools and rg, bare `x` from BSD grep).
+    const lines = (total > offset ? splitPage(body, OUTPUT_BUDGET_BYTES) : [])
+      .map((line) => (line === "--" || pathApi.isAbsolute(line) ? line : prefix + line.replace(/^\.\//, "")));
+    return { total, lines };
+  }
+
+  function pageFooter(offset, shown, total) {
+    if (offset + shown >= total) return "";
+    return `\n\n[Showing results ${offset + 1}-${offset + shown} of ${total}. Continue with offset=${offset + shown}.]`;
+  }
+
+  async function grep(input = {}) {
+    const pattern = requireString(input.pattern, "pattern");
+    const searchPath = input.path === undefined ? cwd : resolvePath(input.path, "path");
+    const mode = input.output_mode ?? "files_with_matches";
+    if (!["files_with_matches", "content", "count"].includes(mode)) {
+      throw new ToolError("output_mode must be one of files_with_matches, content, count");
+    }
+    const offset = toInteger(input.offset, "offset", { min: 0, fallback: 0 });
+    const limit = toInteger(input.head_limit, "head_limit", { min: 1, max: SEARCH_MAX_LIMIT, fallback: SEARCH_DEFAULT_LIMIT });
+    const context = toInteger(input.context, "context", { min: 0, max: 20, fallback: 0 });
+    const tool = await resolveSearchTool();
+
+    let command;
+    const notes = [];
+    if (tool === "rg") {
+      command = ["rg", "--color=never", "--no-messages", "--hidden", "--glob", "!.git"];
+      if (mode === "files_with_matches") command.push("--files-with-matches", "--sortr=modified");
+      if (mode === "count") command.push("--count", "--with-filename", "--sort=path");
+      if (mode === "content") {
+        command.push("--line-number", "--with-filename", "--no-heading", "--max-columns=500", "--max-columns-preview", "--sort=path");
+        if (context > 0) command.push("--context", String(context));
+      }
+      if (input.case_insensitive === true) command.push("--ignore-case");
+      if (input.glob) command.push("--glob", requireString(input.glob, "glob"));
+      if (input.type) command.push("--type", requireString(input.type, "type"));
+      command.push("-e", pattern, "--");
+    } else {
+      notes.push(`[ripgrep is not installed on ${host}; used grep -E, which ignores .gitignore]`);
+      command = ["grep", "-r", "-I", "-E", "--exclude-dir=.git"];
+      if (mode === "files_with_matches") command.push("-l");
+      if (mode === "count") command.push("-c", "-H");
+      if (mode === "content") {
+        command.push("-n", "-H");
+        if (context > 0) command.push("-C", String(context));
+      }
+      if (input.case_insensitive === true) command.push("-i");
+      if (input.glob) command.push(`--include=${requireString(input.glob, "glob")}`);
+      if (input.type) notes.push("[type is not supported without ripgrep and was ignored]");
+      command.push("-e", pattern, "--");
+    }
+
+    const { total, lines } = await page(command, {
+      target: searchPath, offset, limit, nozero: tool === "grep" && mode === "count",
+    });
+    const prefix = notes.length > 0 ? `${notes.join("\n")}\n` : "";
+    if (total === 0) return `${prefix}No matches found.`;
+    if (lines.length === 0) return `${prefix}offset ${offset} is past the last result (${total} results).`;
+    const heading = mode === "files_with_matches" ? `Found ${total} file${total === 1 ? "" : "s"}\n` : "";
+    return `${prefix}${heading}${lines.join("\n")}${pageFooter(offset, lines.length, total)}`;
+  }
+
+  async function glob(input = {}) {
+    const searchPath = input.path === undefined ? cwd : resolvePath(input.path, "path");
+    let pattern = requireString(input.pattern, "pattern");
+    // Globs match relative to the search path, so an absolute one never would.
+    if (pathApi.isAbsolute(pattern)) {
+      const relative = pathApi.relative(searchPath, pattern);
+      if (!relative || relative.startsWith("..") || pathApi.isAbsolute(relative)) {
+        throw new ToolError(`pattern ${pattern} is not under ${searchPath}`);
+      }
+      pattern = relative;
+    }
+    const offset = toInteger(input.offset, "offset", { min: 0, fallback: 0 });
+    const limit = toInteger(input.head_limit, "head_limit", { min: 1, max: SEARCH_MAX_LIMIT, fallback: SEARCH_DEFAULT_LIMIT });
+    const tool = await resolveSearchTool();
+    const command = tool === "rg"
+      ? ["rg", "--files", "--hidden", "--glob", "!.git", "--glob", pattern, "--sortr=modified", "--color=never", "--"]
+      : ["bash", "-c", GLOB_FALLBACK_SCRIPT, "conductor-mcp-glob", pattern];
+    const { total, lines } = await page(command, { target: searchPath, offset, limit });
+    if (total === 0) return "No files found.";
+    if (lines.length === 0) return `offset ${offset} is past the last result (${total} files).`;
+    return `${lines.join("\n")}${pageFooter(offset, lines.length, total)}`;
+  }
+
+  async function bash(input = {}) {
+    const timeoutMs = toInteger(input.timeout_ms, "timeout_ms", {
+      min: 1000, max: BASH_MAX_TIMEOUT_MS, fallback: BASH_DEFAULT_TIMEOUT_MS,
+    });
+    let run;
+    if (input.run_id !== undefined) {
+      run = await wait(requireString(input.run_id, "run_id"), timeoutMs);
+    } else {
+      const command = requireString(input.command, "command");
+      try {
+        run = await exec({ command: "bash", args: ["-lc", command], workspace: cwd, timeoutMs });
+      } catch (error) {
+        throw new ToolError(
+          `${error.message} (remote_bash runs in ${cwd} on ${host}; if the task worktree has not been created yet, create it first)`,
+        );
+      }
+    }
+
+    const parts = [];
+    if (run?.stdoutTail) parts.push(run.stdoutTail.replace(/\n$/, ""));
+    if (run?.stderrTail) parts.push(`[stderr]\n${run.stderrTail.replace(/\n$/, "")}`);
+    if (run?.truncated) parts.push("[output truncated; showing the tail only]");
+    if (run?.error) parts.push(`[error] ${run.error}`);
+    if (run?.status === "running") {
+      parts.push(
+        `[still running on ${host} after ${Math.round(timeoutMs / 1000)}s; ` +
+          `call remote_bash with run_id="${run.runId}" to keep waiting]`,
+      );
+      return { text: parts.join("\n"), isError: false };
+    }
+    const exitCode = typeof run?.exitCode === "number" ? run.exitCode : null;
+    parts.push(`[exit code ${exitCode ?? run?.status ?? "unknown"}]`);
+    return { text: parts.join("\n"), isError: exitCode !== 0 };
+  }
+
+  return { host, root, cwd, resolvePath, read, edit, write, grep, glob, bash };
+}
+
+// ---------------------------------------------------------------------------
+// Tool catalogue
+// ---------------------------------------------------------------------------
+
+export function buildRemoteWorkspaceTools(workspace) {
+  const where = `on daemon "${workspace.host}"`;
+  const pathNote = `Relative paths resolve against ${workspace.cwd}; paths outside ${workspace.root} are refused.`;
+  return [
+    {
+      name: "remote_read",
+      description: `Read a file in the remote workspace ${where}, with line numbers (cat -n format). ${pathNote}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          file_path: { type: "string", description: "File to read" },
+          offset: { type: "integer", minimum: 1, description: "Line number to start at (default 1)" },
+          limit: { type: "integer", minimum: 1, description: `Number of lines to read (default ${READ_DEFAULT_LIMIT})` },
+        },
+        required: ["file_path"],
+        additionalProperties: false,
+      },
+      handler: workspace.read,
+    },
+    {
+      name: "remote_edit",
+      description:
+        `Replace an exact string in a file in the remote workspace ${where}. Fails without writing if ` +
+        `old_string is missing or matches more than once (unless replace_all). ${pathNote}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          file_path: { type: "string", description: "File to edit" },
+          old_string: { type: "string", description: "Exact text to replace" },
+          new_string: { type: "string", description: "Replacement text" },
+          replace_all: { type: "boolean", description: "Replace every occurrence (default false)" },
+        },
+        required: ["file_path", "old_string", "new_string"],
+        additionalProperties: false,
+      },
+      handler: workspace.edit,
+    },
+    {
+      name: "remote_write",
+      description: `Create or overwrite a file in the remote workspace ${where}; parent directories are created. ${pathNote}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          file_path: { type: "string", description: "File to write" },
+          content: { type: "string", description: "Full file content" },
+        },
+        required: ["file_path", "content"],
+        additionalProperties: false,
+      },
+      handler: workspace.write,
+    },
+    {
+      name: "remote_grep",
+      description:
+        `Search file contents in the remote workspace ${where} with ripgrep regex syntax. ` +
+        `Results are paged: pass offset to continue. ${pathNote}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Regular expression" },
+          path: { type: "string", description: "File or directory to search (default: the work dir)" },
+          glob: { type: "string", description: 'Only files matching this glob, e.g. "*.ts"' },
+          type: { type: "string", description: 'ripgrep file type, e.g. "js", "py"' },
+          output_mode: {
+            type: "string",
+            enum: ["files_with_matches", "content", "count"],
+            description: "files_with_matches (default), content (matching lines), or count",
+          },
+          case_insensitive: { type: "boolean" },
+          context: { type: "integer", minimum: 0, maximum: 20, description: "Lines of context in content mode" },
+          offset: { type: "integer", minimum: 0, description: "Results to skip (default 0)" },
+          head_limit: { type: "integer", minimum: 1, maximum: SEARCH_MAX_LIMIT, description: `Results per page (default ${SEARCH_DEFAULT_LIMIT})` },
+        },
+        required: ["pattern"],
+        additionalProperties: false,
+      },
+      handler: workspace.grep,
+    },
+    {
+      name: "remote_glob",
+      description: `Find files by glob pattern (e.g. "src/**/*.ts") in the remote workspace ${where}, newest first. ${pathNote}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Glob pattern" },
+          path: { type: "string", description: "Directory to search (default: the work dir)" },
+          offset: { type: "integer", minimum: 0, description: "Results to skip (default 0)" },
+          head_limit: { type: "integer", minimum: 1, maximum: SEARCH_MAX_LIMIT, description: `Results per page (default ${SEARCH_DEFAULT_LIMIT})` },
+        },
+        required: ["pattern"],
+        additionalProperties: false,
+      },
+      handler: workspace.glob,
+    },
+    {
+      name: "remote_bash",
+      description:
+        `Run a bash command in ${workspace.cwd} ${where} (git, builds, tests). Output keeps the last 64 000 ` +
+        `characters. A command still running at timeout_ms keeps going; call again with the returned run_id to wait more.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "Command to run with bash -lc" },
+          timeout_ms: {
+            type: "integer",
+            minimum: 1000,
+            maximum: BASH_MAX_TIMEOUT_MS,
+            description: `How long to wait (default ${BASH_DEFAULT_TIMEOUT_MS})`,
+          },
+          run_id: { type: "string", description: "Keep waiting for a command that was still running" },
+        },
+        additionalProperties: false,
+      },
+      handler: workspace.bash,
+    },
+  ];
+}
+
+export function buildServerInstructions(workspace) {
+  return (
+    `The task workspace lives on daemon "${workspace.host}" at ${workspace.cwd}, not on this machine. ` +
+    "Use these remote_* tools to read, edit, write and search files there, and remote_bash for git, builds and tests. " +
+    "Local file tools and local shell commands do not see that workspace."
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MCP framing (JSON-RPC 2.0 over newline-delimited stdio)
+// ---------------------------------------------------------------------------
+
+export function createMcpServer({ tools, instructions, name = MCP_SERVER_NAME, version = CLI_VERSION }) {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+
+  async function callTool(params) {
+    const tool = byName.get(params?.name);
+    if (!tool) {
+      return { content: [{ type: "text", text: `unknown tool: ${params?.name}` }], isError: true };
+    }
+    try {
+      const output = await tool.handler(params?.arguments ?? {});
+      const { text, isError = false } = typeof output === "string" ? { text: output } : output;
+      return { content: [{ type: "text", text }], isError };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error?.message || error}` }], isError: true };
+    }
+  }
+
+  async function dispatch(method, params) {
+    switch (method) {
+      case "initialize": {
+        const requested = params?.protocolVersion;
+        return {
+          protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name, version },
+          ...(instructions ? { instructions } : {}),
+        };
+      }
+      case "ping":
+        return {};
+      case "tools/list":
+        return {
+          tools: tools.map(({ name: toolName, description, inputSchema }) => ({ name: toolName, description, inputSchema })),
+        };
+      case "tools/call":
+        return callTool(params);
+      default: {
+        const error = new Error(`method not found: ${method}`);
+        error.code = -32601;
+        throw error;
+      }
+    }
+  }
+
+  /** Returns the response to write, or null for a notification. */
+  async function handleMessage(message) {
+    if (!message || typeof message !== "object" || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+      if (message && typeof message === "object" && ("result" in message || "error" in message)) {
+        return null; // a response to a request we never send
+      }
+      return { jsonrpc: "2.0", id: message?.id ?? null, error: { code: -32600, message: "invalid request" } };
+    }
+    const isNotification = message.id === undefined || message.id === null;
+    if (isNotification) return null;
+    try {
+      return { jsonrpc: "2.0", id: message.id, result: await dispatch(message.method, message.params) };
+    } catch (error) {
+      return {
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: typeof error?.code === "number" ? error.code : -32603, message: error?.message || String(error) },
+      };
+    }
+  }
+
+  return { handleMessage };
+}
+
+/** Serve until `input` ends. Requests run concurrently; responses go out as they finish. */
+export async function serveStdio(server, { input = process.stdin, output = process.stdout } = {}) {
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const inFlight = new Set();
+  const send = (message) => {
+    if (message) output.write(`${JSON.stringify(message)}\n`);
+  };
+
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+      continue;
+    }
+    const pending = server.handleMessage(message).then(send, (error) => {
+      send({ jsonrpc: "2.0", id: message?.id ?? null, error: { code: -32603, message: String(error?.message || error) } });
+    });
+    inFlight.add(pending);
+    pending.finally(() => inFlight.delete(pending));
+  }
+  await Promise.allSettled([...inFlight]);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const VALUE_FLAGS = new Map([
+  ["--host", "host"],
+  ["--target", "host"],
+  ["-t", "host"],
+  ["--root", "root"],
+  ["--cwd", "cwd"],
+  ["--config-file", "configFile"],
+]);
+
+export function parseMcpArgs(argv) {
+  const options = { help: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      continue;
+    }
+    const splitAt = token.startsWith("--") ? token.indexOf("=") : -1;
+    const name = splitAt > 0 ? token.slice(0, splitAt) : token;
+    if (!VALUE_FLAGS.has(name)) {
+      throw new UsageError(`unknown option: ${token}`);
+    }
+    const value = splitAt > 0 ? token.slice(splitAt + 1) : argv[index + 1];
+    if (value === undefined || value === "") {
+      throw new UsageError(`${name} requires a value`);
+    }
+    options[VALUE_FLAGS.get(name)] = value;
+    if (splitAt <= 0) index += 1;
+  }
+  return options;
+}
+
+export function showHelp(consoleImpl = console) {
+  consoleImpl.log(`conductor remote mcp - serve MCP tools bound to a directory on another daemon
+
+Usage:
+  conductor remote mcp --host <daemon> --root <dir> [--cwd <dir>] [--config-file <path>]
+
+Options:
+  -t, --host <daemon>     Daemon the workspace lives on (required)
+      --root <dir>        Absolute directory on that daemon; no tool may leave it (required)
+      --cwd <dir>         Where relative paths and remote_bash run (default: --root)
+      --config-file <p>   Conductor config file to authenticate with
+  -h, --help              Show this help
+
+Speaks MCP over stdin/stdout. Tools: remote_read, remote_edit, remote_write,
+remote_grep, remote_glob, remote_bash. Fire starts it automatically for tasks
+whose worktree lives on another daemon.
+`);
+}
+
+export async function runRemoteMcp(argv, deps = {}) {
+  const consoleImpl = deps.console || console;
+  const env = deps.env || process.env;
+  const fetchImpl = deps.fetch || globalThis.fetch;
+
+  let options;
+  try {
+    options = parseMcpArgs(argv);
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  }
+  if (options.help) {
+    // stdout is the protocol channel only when serving; help is fine there.
+    showHelp(consoleImpl);
+    return EXIT.OK;
+  }
+
+  const host = typeof options.host === "string" ? options.host.trim() : "";
+  const root = typeof options.root === "string" ? options.root.trim() : "";
+  if (!host || !root) {
+    consoleImpl.error("Error: --host <daemon> and --root <dir> are required");
+    return EXIT.CLI_ERROR;
+  }
+  const pathApi = isWindowsStylePath(root) ? path.win32 : path.posix;
+  if (!pathApi.isAbsolute(root) || (options.cwd && !pathApi.isAbsolute(options.cwd))) {
+    consoleImpl.error("Error: --root and --cwd must be absolute paths on the target");
+    return EXIT.CLI_ERROR;
+  }
+  if (options.cwd) {
+    const relative = pathApi.relative(pathApi.normalize(root), pathApi.normalize(options.cwd));
+    if (relative === ".." || relative.startsWith(`..${pathApi.sep}`) || pathApi.isAbsolute(relative)) {
+      consoleImpl.error("Error: --cwd must be inside --root");
+      return EXIT.CLI_ERROR;
+    }
+  }
+
+  let config;
+  try {
+    config = deps.config || loadCliConfig(options.configFile, env);
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  }
+
+  // Everything below must stay off stdout: it is the MCP channel.
+  const quietConsole = { log: () => {}, error: () => {} };
+  const basePath = `/api/agents/${encodeURIComponent(host)}/exec`;
+  const workspace = createRemoteWorkspace({
+    host,
+    root,
+    cwd: options.cwd,
+    exec: async ({ command, args, workspace: dir, timeoutMs }) =>
+      (await execRemote(config, host, command, { args, workspace: dir, timeoutMs, fetchImpl })).run,
+    wait: async (runId, timeoutMs) =>
+      (await waitForRun(config, basePath, { runId, status: "running" }, {
+        deadline: Date.now() + timeoutMs, fetchImpl,
+      })).run,
+    download: (remotePath, localPath) =>
+      downloadFile({
+        config, target: host, remotePath, localPath, fetchImpl, consoleImpl: quietConsole, quiet: true,
+        deadline: Date.now() + FILE_OP_TIMEOUT_MS, onProgress: () => {},
+      }),
+    upload: (localPath, remotePath) =>
+      uploadFile({
+        config, target: host, localPath, remotePath, fetchImpl, consoleImpl: quietConsole, quiet: true,
+        env, deadline: Date.now() + FILE_OP_TIMEOUT_MS, onProgress: () => {},
+      }),
+  });
+
+  const server = createMcpServer({
+    tools: buildRemoteWorkspaceTools(workspace),
+    instructions: buildServerInstructions(workspace),
+  });
+  await serveStdio(server, { input: deps.stdin || process.stdin, output: deps.stdout || process.stdout });
+  return EXIT.OK;
+}