machine-bridge-mcp 1.2.10 → 2.0.0

package/src/local/operation-risk.mjs

@@ -0,0 +1,221 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const OPERATION_APPROVAL_SCOPES = Object.freeze([
+  "shell",
+  "external-write",
+  "sensitive-write",
+  "external-read",
+  "sensitive-read",
+  "browser-session",
+  "data-export",
+  "persistent-job",
+  "application-control",
+  "credential-operation",
+  "full",
+]);
+
+const SHELL_TOOLS = new Set(["exec_command", "run_process", "start_process", "run_local_command", "read_process", "write_process", "kill_process"]);
+const PERSISTENT_TOOLS = new Set(["stage_job", "start_job", "list_jobs", "read_job", "cancel_job"]);
+const APPLICATION_CONTROL_TOOLS = new Set(["open_local_application", "inspect_local_application", "operate_local_application"]);
+const CREDENTIAL_TOOLS = new Set(["generate_ssh_key_resource"]);
+const BROWSER_PROFILE_TOOLS = new Set([
+  "pair_browser_extension", "browser_list_tabs", "browser_manage_tabs", "browser_get_source",
+  "browser_inspect_page", "browser_wait", "browser_action", "browser_fill_form", "browser_screenshot",
+]);
+const AUTOMATIC_TOOLS = new Set([
+  "server_info", "project_overview", "list_local_applications", "browser_status", "list_roots",
+  "diagnose_runtime", "list_local_resources",
+]);
+const FILE_WRITE_TOOLS = new Set(["write_file", "edit_file"]);
+const FILE_READ_TOOLS = new Set([
+  "session_bootstrap", "resolve_task_capabilities", "agent_context", "list_local_skills", "load_local_skill", "list_local_commands",
+  "list_dir", "list_files", "read_file", "view_image", "search_text",
+  "git_status", "git_diff", "git_log", "git_show",
+]);
+const SENSITIVE_SEGMENTS = new Set([
+  ".ssh", ".aws", ".azure", ".gnupg", ".kube", ".docker", ".npmrc", ".pypirc",
+  "keychains", "cookies", "login data", "credentials", "secrets",
+]);
+
+export function reviewedOperationToolNames() {
+  return new Set([
+    ...AUTOMATIC_TOOLS,
+    ...SHELL_TOOLS,
+    ...PERSISTENT_TOOLS,
+    ...APPLICATION_CONTROL_TOOLS,
+    ...CREDENTIAL_TOOLS,
+    ...BROWSER_PROFILE_TOOLS,
+    ...FILE_WRITE_TOOLS,
+    ...FILE_READ_TOOLS,
+    "browser_upload_files",
+    "apply_patch",
+  ]);
+}
+
+export async function classifyOperation(tool, args = {}, options = {}) {
+  const name = String(tool || "");
+  if (SHELL_TOOLS.has(name)) return requirement("shell", "remote shell or process control", name, args);
+  if (PERSISTENT_TOOLS.has(name)) return requirement("persistent-job", "persistent managed job", name, args);
+  if (name === "operate_local_application" && args.value_resource) {
+    return requirement(["application-control", "data-export"], "desktop application control using protected local data", name, {
+      application: args.application,
+      action: args.action,
+      value_resource: args.value_resource,
+    });
+  }
+  if (APPLICATION_CONTROL_TOOLS.has(name)) return requirement("application-control", "desktop application control", name, args);
+  if (CREDENTIAL_TOOLS.has(name)) return requirement("credential-operation", "credential or key operation", name, args);
+  if (name === "browser_upload_files") {
+    return requirement(["browser-session", "data-export"], "existing browser profile file upload", name, args);
+  }
+  if (name === "browser_action" && args.value_resource) {
+    return requirement(["browser-session", "data-export"], "existing browser profile input from protected local data", name, {
+      action: args.action,
+      tab_id: args.tab_id,
+      value_resource: args.value_resource,
+    });
+  }
+  if (name === "browser_fill_form" && Array.isArray(args.fields) && args.fields.some((field) => field?.value_resource || field?.sensitive === true)) {
+    return requirement(["browser-session", "data-export"], "existing browser profile form containing protected local data", name, {
+      tab_id: args.tab_id,
+      resource_fields: args.fields.filter((field) => field?.value_resource || field?.sensitive === true).length,
+      submit: args.submit === true,
+    });
+  }
+  if (BROWSER_PROFILE_TOOLS.has(name)) {
+    return requirement("browser-session", "access to the existing browser profile", name, {
+      action: args.action,
+      tab_id: args.tab_id,
+      frame_id: args.frame_id,
+      submit: args.submit === true,
+    });
+  }
+  if (FILE_WRITE_TOOLS.has(name)) {
+    const target = await canonicalWritePath(args.path, options);
+    const scopes = pathWriteScopes(options.workspace, target);
+    if (scopes.length) return requirement(scopes, pathWriteCategory(scopes), name, { path: target });
+  }
+  if (name === "apply_patch") {
+    const paths = patchPaths(args.patch);
+    const targets = [];
+    for (const candidate of paths) targets.push(await canonicalWritePath(candidate, options));
+    const scopes = normalizeScopes(targets.flatMap((target) => pathWriteScopes(options.workspace, target)));
+    if (scopes.length) return requirement(scopes, pathWriteCategory(scopes, "patch"), name, { paths: targets });
+  }
+  if (FILE_READ_TOOLS.has(name) && args.path !== undefined) {
+    const target = await canonicalExistingPath(args.path, options);
+    const scopes = [];
+    if (!isWithin(options.workspace, target)) scopes.push("external-read");
+    if (isSensitivePath(target)) scopes.push("sensitive-read");
+    if (scopes.length) return requirement(scopes, pathReadCategory(scopes), name, { path: target });
+  }
+  return null;
+}
+
+function requirement(scopes, category, tool, target) {
+  const normalized = normalizeScopes(Array.isArray(scopes) ? scopes : [scopes]);
+  if (!normalized.length) throw new Error("operation approval requirement is missing a scope");
+  return {
+    scope: normalized[0],
+    scopes: normalized,
+    category,
+    targetHash: createHash("sha256").update(JSON.stringify({ tool, target: redactTarget(target) })).digest("hex"),
+  };
+}
+
+function normalizeScopes(scopes) {
+  const requested = new Set(scopes.map((scope) => String(scope || "")));
+  return OPERATION_APPROVAL_SCOPES.filter((scope) => requested.has(scope));
+}
+
+function pathWriteScopes(workspace, target) {
+  const scopes = [];
+  if (!isWithin(workspace, target)) scopes.push("external-write");
+  if (isSensitiveWritePath(target)) scopes.push("sensitive-write");
+  return scopes;
+}
+
+function pathWriteCategory(scopes, subject = "write") {
+  const external = scopes.includes("external-write");
+  const sensitive = scopes.includes("sensitive-write");
+  if (external && sensitive) return `${subject} outside the selected workspace to a credential or persistence-sensitive path`;
+  if (sensitive) return `${subject} to a credential or persistence-sensitive path`;
+  return `${subject} outside the selected workspace`;
+}
+
+function pathReadCategory(scopes) {
+  const external = scopes.includes("external-read");
+  const sensitive = scopes.includes("sensitive-read");
+  if (external && sensitive) return "read outside the selected workspace from a credential-sensitive location";
+  if (sensitive) return "read from a credential-sensitive location";
+  return "read outside the selected workspace";
+}
+
+function redactTarget(value) {
+  if (!value || typeof value !== "object") return String(value || "");
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (["content", "command", "stdin", "value", "old_text", "new_text", "patch"].includes(key)) {
+      out[key] = `<sha256:${createHash("sha256").update(String(item || "")).digest("hex")}>`;
+    } else out[key] = item;
+  }
+  return out;
+}
+
+async function canonicalExistingPath(value, options) {
+  if (typeof options.resolveExistingPath === "function") return options.resolveExistingPath(value);
+  return path.resolve(options.workspace, String(value || "."));
+}
+
+async function canonicalWritePath(value, options) {
+  if (typeof options.resolveWritePath === "function") return options.resolveWritePath(value);
+  return path.resolve(options.workspace, String(value || "."));
+}
+
+function isWithin(workspace, target) {
+  const relative = path.relative(path.resolve(workspace), path.resolve(target));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function isSensitivePath(target) {
+  const lower = path.resolve(target).toLowerCase();
+  const segments = lower.split(/[\\/]+/);
+  if (segments.some((segment) => SENSITIVE_SEGMENTS.has(segment))) return true;
+  const base = path.basename(lower);
+  return isSensitiveEnvironmentFile(base) || /(?:token|secret|credential|private[-_]?key)/.test(base);
+}
+
+function isSensitiveWritePath(target) {
+  const lower = path.resolve(target).toLowerCase();
+  const normalized = lower.split(path.sep).join("/");
+  const base = path.basename(lower);
+  if (isSensitivePath(lower)) return true;
+  if ([".zshrc", ".bashrc", ".bash_profile", ".profile", ".gitconfig", ".netrc", ".curlrc", "authorized_keys", "sshd_config", "sudoers"].includes(base)) return true;
+  return normalized.includes("/.git/hooks/")
+    || normalized.endsWith("/.git/config")
+    || normalized.endsWith("/.config/git/config")
+    || normalized.includes("/library/launchagents/")
+    || normalized.includes("/library/launchdaemons/")
+    || normalized.includes("/.config/autostart/")
+    || normalized.includes("/.config/systemd/user/")
+    || normalized.includes("/start menu/programs/startup/")
+    || normalized.endsWith("/.config/fish/config.fish");
+}
+
+function isSensitiveEnvironmentFile(base) {
+  if (base === ".env") return true;
+  if (!base.startsWith(".env.")) return false;
+  return ![".env.example", ".env.sample", ".env.template", ".env.defaults"].includes(base);
+}
+
+function patchPaths(patch) {
+  const paths = [];
+  for (const line of String(patch || "").split(/\r?\n/)) {
+    const match = /^(?:\*\*\* (?:Add|Update|Delete) File:|\*\*\* Move to:|\+\+\+|---)\s+(.+)$/.exec(line);
+    if (!match) continue;
+    const value = match[1].replace(/^[ab]\//, "").trim();
+    if (value && value !== "/dev/null") paths.push(value);
+  }
+  return paths;
+}

package/src/local/operation-state-lock.mjs

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createExclusiveFileSync, removeOwnedJsonFileSync } from "./exclusive-file.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+
+const LOCK_PURPOSE = "operation-authorization";
+const LOCK_FILE = "operation-authorization.lock";
+const MAX_LOCK_BYTES = 8 * 1024;
+const DEFAULT_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 25;
+
+export async function withOperationStateLock(root, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("operation-state lock requires a callback");
+  const requestedRoot = String(root || "").trim();
+  if (!requestedRoot) throw new Error("operation-state lock root is missing");
+  const directory = path.resolve(requestedRoot);
+  ensureOwnerOnlyDirectorySync(directory);
+  const lockPath = path.join(directory, LOCK_FILE);
+  const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_WAIT_MS);
+  const pollMs = positiveInteger(options.pollMs, DEFAULT_POLL_MS);
+  const deadline = createMonotonicDeadline(timeoutMs);
+  const owner = lockOwner();
+
+  while (true) {
+    try {
+      createExclusiveFileSync(lockPath, `${JSON.stringify(owner, null, 2)}\n`, { mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const existing = readLockOwner(lockPath);
+      if (!existing) throw new Error("operation authorization lock is malformed; inspect the owner-only state directory");
+      if (existing.purpose !== LOCK_PURPOSE) throw new Error("operation authorization lock contains mismatched purpose metadata");
+      const identity = inspectProcessInstance(existing, { maxAgeMs: Number.POSITIVE_INFINITY });
+      if (identity.reclaimable) {
+        if (removeOwnedJsonFileSync(lockPath, { token: existing.token, purpose: LOCK_PURPOSE }, { maxBytes: MAX_LOCK_BYTES })) continue;
+      }
+      if (deadline.expired()) {
+        const pid = Number.isInteger(existing.pid) ? `pid ${existing.pid}` : "unknown process";
+        throw new Error(`operation authorization state is busy (${pid}); retry after the current approval operation finishes`);
+      }
+      await delay(Math.min(pollMs, Math.max(1, deadline.remainingMs())));
+    }
+  }
+
+  let result;
+  let callbackError;
+  try {
+    result = await callback();
+  } catch (error) {
+    callbackError = error;
+  }
+  const released = removeOwnedJsonFileSync(lockPath, { token: owner.token, purpose: LOCK_PURPOSE }, { maxBytes: MAX_LOCK_BYTES });
+  if (!released) throw new Error("operation authorization lock changed before release; approval state may require inspection");
+  if (callbackError) throw callbackError;
+  return result;
+}
+
+function lockOwner() {
+  return {
+    pid: process.pid,
+    token: randomBytes(16).toString("hex"),
+    purpose: LOCK_PURPOSE,
+    startedAt: new Date().toISOString(),
+    processStartedAt: new Date(currentProcessStartTimeMs()).toISOString(),
+    entryScript: String(process.argv[1] || "").slice(0, 4096),
+  };
+}
+
+function readLockOwner(file) {
+  if (!existsSync(file)) return null;
+  let parsed;
+  try { parsed = JSON.parse(readBoundedRegularFileSync(file, MAX_LOCK_BYTES, "operation authorization lock").toString("utf8")); } catch { return null; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  if (!Number.isInteger(parsed.pid) || parsed.pid <= 0) return null;
+  if (!/^[a-f0-9]{32}$/.test(String(parsed.token || ""))) return null;
+  if (parsed.purpose !== LOCK_PURPOSE) return null;
+  if (!Number.isFinite(Date.parse(String(parsed.startedAt || "")))) return null;
+  if (!Number.isFinite(Date.parse(String(parsed.processStartedAt || "")))) return null;
+  return parsed;
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}

package/src/local/process-execution.mjs

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { basename } from "node:path";
 import { stat } from "node:fs/promises";
 import { BoundedOutput } from "./bounded-output.mjs";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
@@ -6,10 +7,21 @@ import { MAX_COMMAND_BYTES, validateArgv } from "./process-contract.mjs";
 import { terminateProcessTreeWithEscalation } from "./process-tree.mjs";
 import { BridgeError } from "./errors.mjs";
 import { clampInteger } from "./numbers.mjs";
+import { ProcessOutputStream } from "./process-output-stream.mjs";
+import { processFailureMessage, publicProcessToolResult } from "./process-result-projection.mjs";
 import {
-  DEFAULT_PROCESS_OUTPUT_BYTES, MAX_PROCESS_STDIN_BYTES, MAX_PROCESS_TIMEOUT_SECONDS, MIN_PROCESS_TIMEOUT_SECONDS,
+  DEFAULT_PROCESS_OUTPUT_BYTES,
+  MAX_PROCESS_SESSION_OUTPUT_BYTES,
+  MAX_PROCESS_STDIN_BYTES,
+  MAX_PROCESS_TIMEOUT_SECONDS,
+  MIN_PROCESS_TIMEOUT_SECONDS,
+  PROCESS_SESSION_RETENTION_MS,
+  PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
 } from "./execution-limits.mjs";
 
+const PROCESS_OUTPUT_CAPTURE = Symbol("process-output-capture");
+const CONTINUATION_READ_BYTES = 64 * 1024;
+
 function spawnDirectProcess(command, args, options) {
   // Keep the production child_process API call structurally separate from the
   // injectable test seam and enforce non-shell execution at the final boundary.
@@ -23,7 +35,7 @@ function spawnDirectProcess(command, args, options) {
 }
 
 export class ProcessExecutionService {
-  constructor({ workspace, policy, policyGate, runtimeDir, processTracker, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation }) {
+  constructor({ workspace, policy, policyGate, runtimeDir, processTracker, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, retainCompletedOutput = null, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation }) {
     this.workspace = workspace;
     this.policy = policy;
     this.policyGate = policyGate;
@@ -33,6 +45,7 @@ export class ProcessExecutionService {
     this.resolveLocalCommand = resolveLocalCommand;
     this.displayPath = displayPath;
     this.throwIfCancelled = throwIfCancelled;
+    this.retainCompletedOutput = typeof retainCompletedOutput === "function" ? retainCompletedOutput : null;
     this.spawnProcess = spawnProcess;
     this.terminateProcess = terminateProcess;
   }
@@ -42,7 +55,12 @@ export class ProcessExecutionService {
     const argv = validateArgv(args.argv);
     const cwd = await this.resolveExistingPath(args.cwd || ".");
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "cwd is not a directory");
-    return this.run(argv[0], argv.slice(1), clampInteger(args.timeout_seconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context, cwd);
+    const result = await this.runPublic(
+      argv[0], argv.slice(1),
+      clampInteger(args.timeout_seconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      context, cwd,
+    );
+    return publicProcessToolResult(result);
   }
 
   async runRegistered(args, context = {}) {
@@ -55,8 +73,8 @@ export class ProcessExecutionService {
       ? command.timeoutSeconds
       : clampInteger(args.timeout_seconds, command.timeoutSeconds, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS);
     const timeoutSeconds = Math.min(requested, command.timeoutSeconds);
-    const result = await this.run(argv[0], argv.slice(1), timeoutSeconds * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context, cwd);
-    return { name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result };
+    const result = await this.runPublic(argv[0], argv.slice(1), timeoutSeconds * 1000, context, cwd);
+    return publicProcessToolResult({ name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result });
   }
 
   async probeShell(context = {}) {
@@ -70,14 +88,61 @@ export class ProcessExecutionService {
     if (command.includes("\0")) throw new BridgeError("invalid_request", "command contains a NUL byte");
     if (Buffer.byteLength(command) > MAX_COMMAND_BYTES) throw new BridgeError("limit_exceeded", `command exceeds maximum size (${MAX_COMMAND_BYTES} bytes)`);
     const shell = workspaceShellCommand(command);
-    return this.run(shell.cmd, shell.args, clampInteger(timeoutSeconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context);
+    const result = await this.runPublic(
+      shell.cmd, shell.args,
+      clampInteger(timeoutSeconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      context, this.workspace,
+    );
+    return publicProcessToolResult(result);
   }
 
   terminateAll(signal = "SIGTERM", escalate = false) {
     this.processTracker.terminateAll(signal, escalate);
   }
 
-  async run(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null) {
+  async runPublic(cmd, args, timeoutMs, context, cwd) {
+    const startedAt = Date.now();
+    const result = await this.run(
+      cmd, args, timeoutMs, true, PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
+      context, cwd, null, { retainOutput: true },
+    );
+    const capture = result[PROCESS_OUTPUT_CAPTURE];
+    const needsContinuation = result.stdout_truncated_bytes > 0 || result.stderr_truncated_bytes > 0;
+    let continuation = {};
+    if (needsContinuation && capture && this.retainCompletedOutput) {
+      const session = this.retainCompletedOutput({
+        command: basename(cmd), cwd,
+        stdout: capture.stdout, stderr: capture.stderr,
+        exitCode: result.code, startedAt, closedAt: Date.now(),
+      });
+      if (session) {
+        continuation = {
+          output_session_id: session.session_id,
+          output_continuation: {
+            tool: "read_process",
+            session_id: session.session_id,
+            stdout_offset: 0,
+            stderr_offset: 0,
+            max_bytes: CONTINUATION_READ_BYTES,
+            retained_bytes_per_stream: MAX_PROCESS_SESSION_OUTPUT_BYTES,
+            expires_after_ms: PROCESS_SESSION_RETENTION_MS,
+            retention: "best-effort-until-session-expiry-or-capacity-eviction",
+          },
+        };
+      } else {
+        continuation = { output_continuation_unavailable: "process session capacity reached" };
+      }
+    }
+    const publicResult = { ...result, ...continuation };
+    if (result.code !== 0) {
+      throw new BridgeError("execution_failed", processFailureMessage(publicResult), {
+        details: { process: publicResult },
+      });
+    }
+    return publicResult;
+  }
+
+  async run(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null, options = {}) {
     this.throwIfCancelled(context);
     if (stdin !== null && Buffer.byteLength(String(stdin)) > MAX_PROCESS_STDIN_BYTES) {
       throw new BridgeError("limit_exceeded", "process stdin exceeds 1 MiB");
@@ -86,6 +151,8 @@ export class ProcessExecutionService {
     return new Promise((resolvePromise, rejectPromise) => {
       const stdout = new BoundedOutput(maxOutputBytes);
       const stderr = new BoundedOutput(maxOutputBytes);
+      const retainedStdout = options.retainOutput ? new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES) : null;
+      const retainedStderr = options.retainOutput ? new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES) : null;
       let child;
       try {
         child = this.spawnProcess(cmd, args, {
@@ -147,13 +214,19 @@ export class ProcessExecutionService {
       }, timeoutMs);
       timeoutTimer.unref?.();
 
-      child.stdout?.on?.("data", (chunk) => stdout.append(chunk));
-      child.stderr?.on?.("data", (chunk) => stderr.append(chunk));
+      child.stdout?.on?.("data", (chunk) => {
+        stdout.append(chunk);
+        retainedStdout?.append(chunk);
+      });
+      child.stderr?.on?.("data", (chunk) => {
+        stderr.append(chunk);
+        retainedStderr?.append(chunk);
+      });
 
       child.on("error", (error) => {
         cleanupAfterClose();
         settle(() => {
-          if (allowFailure) resolvePromise(processResult(127, stdout, error.message || stderr.text()));
+          if (allowFailure) resolvePromise(processResult(127, stdout, error.message || stderr.text(), retainedStdout, retainedStderr));
           else rejectPromise(error);
         });
       });
@@ -165,9 +238,9 @@ export class ProcessExecutionService {
           settle(() => rejectPromise(error));
           return;
         }
-        const result = processResult(code, stdout, stderr);
+        const result = processResult(code, stdout, stderr, retainedStdout, retainedStderr);
         if (code === 0 || allowFailure) settle(() => resolvePromise(result));
-        else settle(() => rejectPromise(new BridgeError("execution_failed", result.stderr.trim() || result.stdout.trim() || `${cmd} exited ${code}`)));
+        else settle(() => rejectPromise(new BridgeError("execution_failed", processFailureMessage(result), { details: { process: result } })));
       });
 
       if (signal?.aborted) rejectCancelled();
@@ -175,15 +248,22 @@ export class ProcessExecutionService {
   }
 }
 
-function processResult(code, stdout, stderr) {
+function processResult(code, stdout, stderr, retainedStdout = null, retainedStderr = null) {
   const stderrBuffer = stderr instanceof BoundedOutput ? stderr : null;
-  return {
+  const result = {
     code,
     stdout: stdout instanceof BoundedOutput ? stdout.text() : String(stdout || ""),
     stderr: stderrBuffer ? stderrBuffer.text() : boundedErrorMessage(stderr),
     stdout_truncated_bytes: stdout instanceof BoundedOutput ? stdout.truncatedBytes : 0,
     stderr_truncated_bytes: stderrBuffer ? stderrBuffer.truncatedBytes : 0,
   };
+  if (retainedStdout && retainedStderr) {
+    Object.defineProperty(result, PROCESS_OUTPUT_CAPTURE, {
+      value: { stdout: retainedStdout, stderr: retainedStderr },
+      enumerable: false,
+    });
+  }
+  return result;
 }
 
 export function boundedErrorMessage(error) {

package/src/local/process-output-stream.mjs

@@ -0,0 +1,82 @@
+// @ts-check
+
+/**
+ * Bounded byte stream shared by interactive process sessions and completed
+ * one-shot command continuations. It retains the newest bytes while keeping
+ * monotonic offsets so callers can detect data that aged out of the buffer.
+ */
+export class ProcessOutputStream {
+  /** @param {number} maximumBytes */
+  constructor(maximumBytes) {
+    const maximum = Number(maximumBytes);
+    if (!Number.isSafeInteger(maximum) || maximum < 1) {
+      throw new Error("maximum retained output bytes must be a positive safe integer");
+    }
+    this.maximumBytes = maximum;
+    this.buffer = Buffer.alloc(0);
+    this.baseOffset = 0;
+    this.totalBytes = 0;
+  }
+
+  /** @param {unknown} chunk */
+  append(chunk) {
+    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ""));
+    if (!input.length) return;
+    this.totalBytes += input.length;
+    let combined = this.buffer.length ? Buffer.concat([this.buffer, input]) : Buffer.from(input);
+    if (combined.length > this.maximumBytes) {
+      const dropped = combined.length - this.maximumBytes;
+      combined = combined.subarray(dropped);
+      this.baseOffset += dropped;
+    }
+    this.buffer = combined;
+  }
+
+  /** @param {unknown} requestedOffset @param {unknown} maximumBytes */
+  read(requestedOffset, maximumBytes) {
+    const requested = nonNegativeInteger(requestedOffset);
+    const maximum = positiveInteger(maximumBytes);
+    const clampedOffset = Math.min(requested, this.totalBytes);
+    const effectiveOffset = Math.max(clampedOffset, this.baseOffset);
+    const start = effectiveOffset - this.baseOffset;
+    const slice = this.buffer.subarray(start, Math.min(this.buffer.length, start + maximum));
+    const decoded = decodeProcessBytes(slice);
+    return {
+      ...decoded,
+      requested_offset: requested,
+      start_offset: effectiveOffset,
+      next_offset: effectiveOffset + slice.length,
+      total_offset: this.totalBytes,
+      retained_start_offset: this.baseOffset,
+      truncated_before: requested < this.baseOffset,
+      truncated_after: effectiveOffset + slice.length < this.totalBytes,
+    };
+  }
+}
+
+/** @param {Buffer} bytes */
+function decodeProcessBytes(bytes) {
+  try {
+    return { data: new TextDecoder("utf-8", { fatal: true }).decode(bytes), encoding: "utf8" };
+  } catch {
+    return {
+      data: new TextDecoder("utf-8").decode(bytes),
+      data_base64: bytes.toString("base64"),
+      encoding: "base64",
+    };
+  }
+}
+
+/** @param {unknown} value */
+function nonNegativeInteger(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 0) return 0;
+  return number;
+}
+
+/** @param {unknown} value */
+function positiveInteger(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 1) return 1;
+  return number;
+}

package/src/local/process-result-projection.mjs

@@ -0,0 +1,25 @@
+// @ts-check
+
+import { MCP_TEXT_PROJECTION_KEY } from "../shared/result-projection.mjs";
+
+/** @param {Record<string, any>} value */
+export function publicProcessToolResult(value) {
+  const truncated = Number(value.stdout_truncated_bytes) + Number(value.stderr_truncated_bytes);
+  const continuation = value.output_session_id
+    ? ` Continue with read_process session ${value.output_session_id}.`
+    : truncated > 0 ? " Additional output could not be retained because the process-session limit was reached." : "";
+  const summary = `Process exited with code ${value.code}.${truncated > 0 ? ` ${truncated} inline byte(s) omitted.` : ""}${continuation}`;
+  return { ...value, [MCP_TEXT_PROJECTION_KEY]: summary };
+}
+
+/** @param {Record<string, any>} result */
+export function processFailureMessage(result) {
+  const source = String(result.stderr || result.stdout || `process exited ${result.code}`)
+    .replace(/[\r\n]+/g, " ").trim().slice(0, 2000);
+  const suffix = result.output_session_id
+    ? `; additional output is available through read_process session ${result.output_session_id}`
+    : result.stdout_truncated_bytes > 0 || result.stderr_truncated_bytes > 0
+      ? "; additional output was truncated"
+      : "";
+  return `${source || `process exited ${result.code}`}${suffix}`;
+}