@minhspark/codex-mcp-bridge 1.25.3 → 1.26.0

package/scripts/install-antigravity-bridge.mjs

@@ -7,6 +7,7 @@ import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mc
 import { isMainModule, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 import { homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 
 const NAME = "antigravity-bridge";
 const SIDECAR = "codex-bridge";
@@ -59,17 +60,21 @@ export function validateCodexExecutable(executable, { platform = process.platfor
   return resolved;
 }
 
-function ownEntry(entry, expected, label, retarget = false) {
+function ownEntry(entry, expected, label, retarget = false, supervised = false) {
   if (entry === undefined || entry === null) return;
   object(entry, label);
   const script = entry.args?.[0];
-  if (!Array.isArray(entry.args) || entry.args.length !== 1 || typeof script !== "string") {
+  const managed = supervised && Array.isArray(entry.args) && entry.args.length === 2
+    && typeof script === "string" && path.basename(script) === "mcp-supervisor.mjs" && entry.args[1] === path.basename(expected);
+  if (!Array.isArray(entry.args) || !managed && entry.args.length !== 1 || typeof script !== "string") {
     throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
   }
-  if (path.resolve(script) === path.resolve(expected)) return;
+  const target = managed ? path.join(path.dirname(expected), "mcp-supervisor.mjs") : expected;
+  if (path.resolve(script) === path.resolve(target) && !managed) return;
   const source = path.dirname(script);
-  if (!retarget || !path.isAbsolute(script) || script.includes("\0") || path.basename(script) !== path.basename(expected)
-    || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge") {
+  if (!path.isAbsolute(script) || script.includes("\0") || path.resolve(script) !== path.resolve(target)
+    && (!retarget || path.basename(script) !== path.basename(target)
+      || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge")) {
     throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
   }
   const command = entry.command;
@@ -91,31 +96,35 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
   const entry = path.join(root, "src", "antigravity-bridge.mjs");
   const sidecarEntry = path.join(root, "src", "antigravity-sidecar.mjs");
   const outboundEntry = path.join(root, "src", "antigravity-outbound-bridge.mjs");
+  const supervisorEntry = path.join(root, "src", "mcp-supervisor.mjs");
   const edits = [];
   const notices = [];
+  const runtimeCaches = new Set();
   let backgroundPreference = null;
   const retarget = setup && !remove;
   let codex = null;
   if (targets.includes("codex")) {
     if (codexExisting && codexExisting.transport?.type !== "stdio") throw new Error("The existing Antigravity MCP transport is not stdio");
-    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget);
+    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget, true);
     const existingCaller = codexExisting?.transport?.env?.ANTIGRAVITY_BRIDGE_CALLER;
     if (existingCaller !== undefined && existingCaller !== "codex") throw new Error("The existing Codex bridge has a conflicting caller identity");
-    codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry, envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
+    codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry: supervisorEntry, entryArgs: [path.basename(entry)], envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
+    if (!remove) runtimeCaches.add(snapshotRoot({ ...process.env, ...codex.environment }));
   }
   if (targets.includes("claude")) {
     const original = snapshot(path.join(codeConfigDir, ".claude.json"));
     const value = structuredClone(original.value);
     if (value.mcpServers !== undefined) object(value.mcpServers, "Claude mcpServers");
     const existing = value.mcpServers?.[NAME];
-    ownEntry(existing, entry, "Claude Antigravity bridge", retarget);
+    ownEntry(existing, entry, "Claude Antigravity bridge", retarget, true);
     if (existing?.type !== undefined && existing.type !== "stdio") throw new Error("The existing Claude bridge transport is not stdio");
     if (existing?.env !== undefined) object(existing.env, "Claude bridge environment");
     if (existing?.env?.ANTIGRAVITY_BRIDGE_CALLER !== undefined && existing.env.ANTIGRAVITY_BRIDGE_CALLER !== "claude") throw new Error("The existing Claude bridge has a conflicting caller identity");
     if (remove) { if (existing) delete value.mcpServers[NAME]; }
     else {
       value.mcpServers ??= {};
-      value.mcpServers[NAME] = { ...existing, type: "stdio", command: node, args: [entry], env: { ...existing?.env, ANTIGRAVITY_BRIDGE_CALLER: "claude" } };
+      value.mcpServers[NAME] = { ...existing, type: "stdio", command: node, args: [supervisorEntry, path.basename(entry)], env: { ...existing?.env, ANTIGRAVITY_BRIDGE_CALLER: "claude" } };
+      runtimeCaches.add(snapshotRoot({ ...process.env, ...value.mcpServers[NAME].env }));
     }
     const edit = changed(original, value);
     if (edit) edits.push(edit);
@@ -126,7 +135,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const mcp = structuredClone(originalMcp.value);
     if (mcp.mcpServers !== undefined) object(mcp.mcpServers, "Antigravity mcpServers");
     const outbound = mcp.mcpServers?.[OUTBOUND];
-    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget);
+    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget, true);
     if (outbound?.type !== undefined && outbound.type !== "stdio" || outbound?.url !== undefined || outbound?.serverUrl !== undefined || outbound?.httpUrl !== undefined) throw new Error("The existing Antigravity outbound bridge transport is not stdio");
     if (outbound?.env !== undefined) object(outbound.env, "Antigravity outbound bridge environment");
     if (Object.keys(outbound?.env ?? {}).some((name) => /^(?:CLAUDE|CODEX_|ANTIGRAVITY_BRIDGE_CALLER$)/i.test(name))) throw new Error("The existing Antigravity outbound bridge contains a foreign caller environment; review it before installation");
@@ -136,7 +145,8 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     if (remove) { if (outbound) delete mcp.mcpServers[OUTBOUND]; }
     else {
       mcp.mcpServers ??= {};
-      mcp.mcpServers[OUTBOUND] = { ...outbound, command: node, args: [outboundEntry] };
+      mcp.mcpServers[OUTBOUND] = { ...outbound, command: node, args: [supervisorEntry, path.basename(outboundEntry)] };
+      runtimeCaches.add(snapshotRoot({ ...process.env, ...outbound?.env }));
     }
     const mcpEdit = changed(originalMcp, mcp);
     if (mcpEdit) edits.push(mcpEdit);
@@ -180,7 +190,8 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
       if (backgroundPreference.detail) notices.push(backgroundPreference.detail);
     }
   }
-  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry, backgroundPreference };
+  if (!remove) notices.push("Running direct Antigravity MCP processes retain their current version until the host reconnects normally. Future supervised workers update automatically when quiescent.");
+  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry, supervisorEntry, runtimeCaches: [...runtimeCaches], backgroundPreference };
 }
 
 function assertCurrent(edit) {
@@ -224,7 +235,7 @@ export function installerArguments(args) {
   return { targets: args.includes("--all") || !selected.length ? ["codex", "claude", "desktop"] : selected, remove: args.includes("--remove"), dryRun: args.includes("--dry-run"), setup: args.includes("--setup"), help: args.includes("--help") };
 }
 
-export function runAntigravityInstaller(args = process.argv.slice(2)) {
+export function runAntigravityInstaller(args = process.argv.slice(2), { prepareRuntime = createReleaseSnapshot } = {}) {
   const options = installerArguments(args);
   if (options.help) {
     console.log("Usage: antigravity-mcp-bridge-install [--all|--codex|--claude|--desktop] [--remove] [--dry-run] [--setup]");
@@ -244,7 +255,7 @@ export function runAntigravityInstaller(args = process.argv.slice(2)) {
   }
   const plan = planAntigravityInstallation({ ...options, home, root, node, codexExisting });
   if (!options.remove) {
-    for (const entry of [plan.entry, ...(options.targets.includes("desktop") ? [plan.sidecarEntry, plan.outboundEntry] : [])]) {
+    for (const entry of [plan.supervisorEntry, plan.entry, ...(options.targets.includes("desktop") ? [plan.sidecarEntry, plan.outboundEntry] : [])]) {
       if (!fs.existsSync(entry)) throw new Error(`Missing bridge entrypoint: ${entry}`);
     }
   }
@@ -252,6 +263,7 @@ export function runAntigravityInstaller(args = process.argv.slice(2)) {
     console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, backgroundPreference: plan.backgroundPreference, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
     return plan;
   }
+  for (const cache of plan.runtimeCaches) prepareRuntime(root, { cache });
   for (const edit of plan.edits) assertCurrent(edit);
   if (plan.codex) {
     if (options.remove) { if (plan.codex.remove) run(["mcp", "remove", NAME]); }

package/scripts/install-background-relay.mjs

@@ -0,0 +1,428 @@
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { callBackgroundRelay } from "../src/background-relay-client.mjs";
+import { readRelayConfiguration, writeRelayJson } from "../src/background-relay-config.mjs";
+import { RELAY_SERVICE_OWNER, relayServiceRuntimeId } from "../src/background-relay-service.mjs";
+import { isMainModule, stableNodeBin } from "../src/install-paths.mjs";
+import { readRegularConfigFile } from "../src/project-policy.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const TASK_SCRIPT = String.raw`$ErrorActionPreference = 'Stop'
+$relayRequest = [Console]::In.ReadToEnd() | ConvertFrom-Json
+try {
+  $relayScheduler = New-Object -ComObject Schedule.Service
+  $relayScheduler.Connect()
+  $relayFolder = $relayScheduler.GetFolder('\')
+  if ($relayRequest.action -eq 'register') {
+    $null = $relayFolder.RegisterTask($relayRequest.name, $relayRequest.xml, 6, $null, $null, 3, $null)
+  }
+  $relayTask = $null
+  try { $relayTask = $relayFolder.GetTask($relayRequest.name) }
+  catch {
+    $relayException = $_.Exception
+    $relayMissing = $false
+    while ($null -ne $relayException) {
+      if ($relayException.HResult -eq -2147024894) { $relayMissing = $true }
+      $relayException = $relayException.InnerException
+    }
+    if (-not $relayMissing) { throw }
+  }
+  if ($relayRequest.action -eq 'start') {
+    if ($null -eq $relayTask) { throw 'Missing task' }
+    $null = $relayTask.Run($null)
+  }
+  $relayUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+  if ($null -eq $relayTask) {
+    @{ exists = $false; user = $relayUser } | ConvertTo-Json -Compress
+  } else {
+    $relayDefinition = $relayTask.Definition
+    $relayAction = $relayDefinition.Actions.Item(1)
+    $relayPrincipalId = [string]$relayDefinition.Principal.UserId
+    $relayPrincipalSid = $null
+    try {
+      if ($relayPrincipalId -match '^S-\d+(?:-\d+)+$') {
+        $relayPrincipalSid = [Security.Principal.SecurityIdentifier]::new($relayPrincipalId).Value
+      } else {
+        $relayPrincipalSid = [Security.Principal.NTAccount]::new($relayPrincipalId).Translate([Security.Principal.SecurityIdentifier]).Value
+      }
+    } catch {}
+    @{ exists = $true; user = $relayUser; enabled = [bool]$relayTask.Enabled; state = [int]$relayTask.State;
+       description = [string]$relayDefinition.RegistrationInfo.Description;
+       command = [string]$relayAction.Path; arguments = [string]$relayAction.Arguments;
+       actions = [int]$relayDefinition.Actions.Count; logonType = [int]$relayDefinition.Principal.LogonType;
+       principalId = $relayPrincipalId; principalSid = $relayPrincipalSid; userSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value;
+       runLevel = [int]$relayDefinition.Principal.RunLevel; hidden = [bool]$relayDefinition.Settings.Hidden;
+       executionTimeLimit = [string]$relayDefinition.Settings.ExecutionTimeLimit;
+       multipleInstances = [int]$relayDefinition.Settings.MultipleInstances } | ConvertTo-Json -Compress
+  }
+} catch {
+  @{ error = 'TASK_SCHEDULER_UNAVAILABLE' } | ConvertTo-Json -Compress
+  exit 1
+}`;
+
+function execute(command, args, options) {
+  try { return { status: 0, stdout: execFileSync(command, args, options), stderr: "" }; }
+  catch (error) { return { status: Number.isInteger(error.status) ? error.status : 1, stdout: error.stdout ?? "", stderr: "" }; }
+}
+
+function installFailure(code) { return Object.assign(new Error(code), { code }); }
+const escapeXml = (value) => String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const quoteWindows = (value) => `"${String(value).replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/g, "$1$1")}"`;
+const quoteSystemd = (value, expandDollar = true) => `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%").replace(/\$/g, () => expandDollar ? "$$" : "$")}"`;
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function startupLocation(input, segments) {
+  if (typeof input !== "string" || !path.isAbsolute(input) || /[\u0000-\u001f\u007f]/.test(input)) throw installFailure("SERVICE_STORAGE_UNSAFE");
+  let ancestor = path.resolve(input);
+  const suffix = [];
+  while (true) {
+    try { fs.lstatSync(ancestor); break; }
+    catch (error) {
+      if (error.code !== "ENOENT" || ancestor === path.dirname(ancestor)) throw installFailure("SERVICE_STORAGE_UNSAFE");
+      suffix.unshift(path.basename(ancestor));
+      ancestor = path.dirname(ancestor);
+    }
+  }
+  ancestor = fs.realpathSync.native(ancestor);
+  const root = path.resolve(ancestor, ...suffix);
+  const file = path.resolve(root, ...segments);
+  if (!file.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`)) throw installFailure("SERVICE_STORAGE_UNSAFE");
+  const location = { root, file, ancestor, identities: new Map() };
+  startupDirectories(location);
+  return location;
+}
+
+function startupDirectories(location, create = false) {
+  const relative = path.relative(location.ancestor, path.dirname(location.file));
+  if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) throw installFailure("SERVICE_STORAGE_UNSAFE");
+  let current = location.ancestor;
+  for (const segment of ["", ...relative.split(path.sep).filter(Boolean)]) {
+    if (segment) current = path.join(current, segment);
+    let entry;
+    try { entry = fs.lstatSync(current, { bigint: true }); }
+    catch (error) {
+      if (error.code !== "ENOENT" || location.identities.has(current)) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+      if (!create) return;
+      fs.mkdirSync(current, { mode: 0o700 });
+      entry = fs.lstatSync(current, { bigint: true });
+    }
+    const identity = `${entry.dev}:${entry.ino}:${entry.birthtimeNs}`;
+    if (!entry.isDirectory() || entry.isSymbolicLink() || path.relative(current, fs.realpathSync.native(current))) throw installFailure("SERVICE_STORAGE_UNSAFE");
+    if (location.identities.has(current) && location.identities.get(current) !== identity) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+    location.identities.set(current, identity);
+  }
+}
+
+function startupText(location) {
+  startupDirectories(location);
+  return readRegularConfigFile(location.file, { missing: true, maxBytes: 128 * 1024 });
+}
+
+function sameStartupFile(location, candidate) {
+  if (typeof candidate !== "string" || !path.isAbsolute(candidate) || path.basename(candidate) !== path.basename(location.file)) return false;
+  try {
+    const entry = fs.lstatSync(candidate);
+    return entry.isFile() && !entry.isSymbolicLink() && path.relative(location.file, fs.realpathSync.native(candidate)) === "";
+  } catch { return false; }
+}
+
+function atomicText(location, content, previous) {
+  startupDirectories(location, true);
+  const file = location.file;
+  if (startupText(location) !== previous) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+  const directory = path.dirname(file);
+  const temporary = path.resolve(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  if (!temporary.startsWith(directory.endsWith(path.sep) ? directory : `${directory}${path.sep}`)) throw installFailure("SERVICE_STORAGE_UNSAFE");
+  let descriptor;
+  let identity;
+  const sameTemporary = (entry) => entry.isFile() && !entry.isSymbolicLink() && entry.nlink === 1n
+    && ["dev", "ino", "birthtimeNs"].every((field) => entry[field] === identity[field]);
+  try {
+    descriptor = fs.openSync(temporary, "wx", 0o600);
+    identity = fs.fstatSync(descriptor, { bigint: true });
+    fs.writeFileSync(descriptor, content);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    if (startupText(location) !== previous || !sameTemporary(fs.lstatSync(temporary, { bigint: true }))) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    if (identity) {
+      startupDirectories(location);
+      let remaining;
+      try { remaining = fs.lstatSync(temporary, { bigint: true }); } catch (error) { if (error.code !== "ENOENT") throw error; }
+      if (remaining) {
+        if (!sameTemporary(remaining)) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+        fs.unlinkSync(temporary);
+      }
+    }
+  }
+}
+
+function taskXml({ command, args, user, enabled }) {
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+<RegistrationInfo><Description>${escapeXml(RELAY_SERVICE_OWNER)}</Description></RegistrationInfo>
+<Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${escapeXml(user)}</UserId></LogonTrigger></Triggers>
+<Principals><Principal id="Author"><UserId>${escapeXml(user)}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+<Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><AllowHardTerminate>false</AllowHardTerminate><StartWhenAvailable>true</StartWhenAvailable><AllowStartOnDemand>true</AllowStartOnDemand><Enabled>${enabled}</Enabled><Hidden>true</Hidden><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure></Settings>
+<Actions Context="Author"><Exec><Command>${escapeXml(command)}</Command><Arguments>${escapeXml(args)}</Arguments></Exec></Actions>
+</Task>\n`;
+}
+
+function savedEnvironment(env, config) {
+  const result = { AGENT_RELAY_DIRECTORY: config.paths.root, AGENT_RELAY_SERVICE_OWNER: RELAY_SERVICE_OWNER };
+  for (const name of ["HOME", "PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME"]) {
+    if (typeof env[name] === "string" && env[name] && !/[\u0000-\u001f\u007f]/.test(env[name])) result[name] = env[name];
+  }
+  return result;
+}
+
+function plist(label, node, service, environment, enabled) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${escapeXml(label)}</string>
+<key>ProgramArguments</key><array><string>${escapeXml(node)}</string><string>${escapeXml(service)}</string></array>
+<key>EnvironmentVariables</key><dict>${Object.entries(environment).map(([key, value]) => `<key>${escapeXml(key)}</key><string>${escapeXml(value)}</string>`).join("")}</dict>
+<key>RunAtLoad</key><${enabled ? "true" : "false"}/><key>Disabled</key><${enabled ? "false" : "true"}/>
+<key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+<key>ThrottleInterval</key><integer>10</integer><key>ProcessType</key><string>Background</string>
+<key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string>
+</dict></plist>\n`;
+}
+
+function unit(node, service, environment) {
+  return `[Unit]
+Description=${RELAY_SERVICE_OWNER}
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+ExecStart=${quoteSystemd(node)} ${quoteSystemd(service)}
+${Object.entries(environment).map(([name, value]) => `Environment=${quoteSystemd(`${name}=${value}`, false)}`).join("\n")}
+Restart=on-failure
+RestartSec=10
+TimeoutStopSec=infinity
+StandardOutput=null
+StandardError=null
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+async function installWindows(context) {
+  const { env, config, root, node, service, label, invoke, mutate } = context;
+  const command = path.win32.join(env.SystemRoot || env.WINDIR || "C:\\Windows", "System32", "wscript.exe");
+  const launcher = path.join(root, "scripts", "background-relay-hidden.vbs");
+  if (![node, service, launcher].every((value) => !/["%\r\n\0]/.test(value))) throw installFailure("SERVICE_LAUNCH_PATH_UNSUPPORTED");
+  if (!fs.existsSync(launcher)) throw installFailure("SERVICE_RUNTIME_MISSING");
+  if (context.nativeRun && !fs.existsSync(command)) throw installFailure("SERVICE_HIDDEN_LAUNCHER_UNAVAILABLE");
+  const args = ["//B", "//Nologo", quoteWindows(launcher), quoteWindows(node), quoteWindows(service), quoteWindows(config.paths.root)].join(" ");
+  const powershell = path.win32.join(env.SystemRoot || env.WINDIR || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const task = async (action, extra = {}) => {
+    const response = await invoke(powershell, ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-EncodedCommand", Buffer.from(TASK_SCRIPT, "utf16le").toString("base64")], {
+      input: JSON.stringify({ action, name: label, ...extra }),
+    });
+    let value;
+    try { value = JSON.parse(response.stdout); } catch { throw installFailure("TASK_SCHEDULER_UNAVAILABLE"); }
+    if (response.status !== 0 || value.error || typeof value.exists !== "boolean") throw installFailure("TASK_SCHEDULER_UNAVAILABLE");
+    return value;
+  };
+  let current = await task("query");
+  if (current.exists && current.description !== RELAY_SERVICE_OWNER) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+  const sameUser = (value) => typeof value.principalSid === "string" && /^S-\d+(?:-\d+)+$/i.test(value.principalSid)
+    && typeof value.userSid === "string" && value.principalSid.toLowerCase() === value.userSid.toLowerCase();
+  if (current.exists && !sameUser(current)) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+  const enabled = config.enabled && (!current.exists || current.enabled === true);
+  const matches = (value) => value.exists && value.description === RELAY_SERVICE_OWNER && value.command.toLowerCase() === command.toLowerCase()
+    && value.arguments === args && value.actions === 1 && value.logonType === 3 && value.runLevel === 0
+    && value.hidden === true && value.executionTimeLimit === "PT0S" && value.multipleInstances === 2 && value.enabled === enabled && sameUser(value);
+  const changed = !matches(current);
+  if (changed && mutate) {
+    if (typeof current.user !== "string" || !current.user || /[\r\n\0]/.test(current.user)) throw installFailure("TASK_SCHEDULER_UNAVAILABLE");
+    await task("register", { xml: taskXml({ command, args, user: current.user, enabled }) });
+    current = await task("query");
+  }
+  if (mutate && !matches(current)) throw installFailure("SERVICE_READBACK_FAILED");
+  if (mutate) await context.prepareRuntime();
+  let started = false;
+  if (enabled && mutate && current.state !== 4) { await task("start"); started = true; }
+  return { configured: matches(current), enabled, changed, started, registration: label, activationPending: changed && current.state === 4 };
+}
+
+async function installMac(context) {
+  const { env, config, node, service, label, invoke, mutate, uid } = context;
+  if (!Number.isSafeInteger(uid) || uid < 0) throw installFailure("SERVICE_USER_UNAVAILABLE");
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const location = startupLocation(home, ["Library", "LaunchAgents", `${label}.plist`]);
+  const file = location.file;
+  const previous = startupText(location);
+  if (previous !== null && !previous.includes(escapeXml(RELAY_SERVICE_OWNER))) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+  const domain = `gui/${uid}`;
+  const disabled = await invoke("/bin/launchctl", ["print-disabled", domain]);
+  if (disabled.status !== 0) throw installFailure("LAUNCH_AGENT_UNAVAILABLE");
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const userDisabled = new RegExp(`"${escaped}"\\s*=>\\s*true`).test(disabled.stdout)
+    || /<key>Disabled<\/key>\s*<true\s*\/>/.test(previous ?? "");
+  const enabled = config.enabled && !userDisabled;
+  const wanted = plist(label, node, service, savedEnvironment(env, config), enabled);
+  const loaded = await invoke("/bin/launchctl", ["print", `${domain}/${label}`]);
+  if (loaded.status === 0 && previous === null) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+  if (loaded.status !== 0 && loaded.status !== 113) throw installFailure("LAUNCH_AGENT_UNAVAILABLE");
+  const changed = previous !== wanted;
+  if (changed && mutate) atomicText(location, wanted, previous);
+  const configured = startupText(location) === wanted;
+  if (mutate && !configured) throw installFailure("SERVICE_READBACK_FAILED");
+  if (mutate) await context.prepareRuntime();
+  let started = false;
+  if (enabled && mutate) {
+    const args = loaded.status === 0 ? ["kickstart", `${domain}/${label}`] : ["bootstrap", domain, file];
+    if (loaded.status !== 0 || !/\bstate = running\b/.test(loaded.stdout)) {
+      if ((await invoke("/bin/launchctl", args)).status !== 0) throw installFailure("SERVICE_START_FAILED");
+      started = true;
+    }
+  }
+  return { configured, enabled, changed, started, registration: label, activationPending: changed && loaded.status === 0 };
+}
+
+async function installLinux(context) {
+  const { env, config, node, service, label, invoke, mutate } = context;
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const location = startupLocation(env.XDG_CONFIG_HOME || path.join(home, ".config"), ["systemd", "user", `${label}.service`]);
+  const file = location.file;
+  const query = async () => {
+    const response = await invoke("systemctl", ["--user", "show", `${label}.service`, "--property=LoadState,UnitFileState,ActiveState,FragmentPath", "--no-pager"]);
+    const values = Object.fromEntries(response.stdout.split(/\r?\n/).filter((line) => line.includes("=")).map((line) => [line.slice(0, line.indexOf("=")), line.slice(line.indexOf("=") + 1)]));
+    if (!values.LoadState || response.status !== 0 && values.LoadState !== "not-found") throw installFailure("USER_SYSTEMD_UNAVAILABLE");
+    return values;
+  };
+  const values = await query();
+  if (values.UnitFileState === "masked" || values.UnitFileState === "masked-runtime") return { configured: false, enabled: false, changed: false, started: false, registration: label, code: "SERVICE_MASKED" };
+  const previous = startupText(location);
+  if (previous !== null && !previous.includes(`Description=${RELAY_SERVICE_OWNER}\n`)
+      || values.FragmentPath && !sameStartupFile(location, values.FragmentPath)) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+  const userDisabled = previous !== null && ["disabled", "disabled-runtime"].includes(values.UnitFileState);
+  const enabled = config.enabled && !userDisabled;
+  const wanted = unit(node, service, savedEnvironment(env, config));
+  const changed = previous !== wanted;
+  if (changed && mutate) {
+    atomicText(location, wanted, previous);
+    if ((await invoke("systemctl", ["--user", "daemon-reload"])).status !== 0) throw installFailure("USER_SYSTEMD_UNAVAILABLE");
+  }
+  if (enabled && mutate && !["enabled", "enabled-runtime"].includes(values.UnitFileState)) {
+    if ((await invoke("systemctl", ["--user", "enable", `${label}.service`])).status !== 0) throw installFailure("SERVICE_REGISTRATION_FAILED");
+  }
+  if (mutate) await context.prepareRuntime();
+  let started = false;
+  if (enabled && mutate && values.ActiveState !== "active") {
+    if ((await invoke("systemctl", ["--user", "start", `${label}.service`])).status !== 0) throw installFailure("SERVICE_START_FAILED");
+    started = true;
+  }
+  const verified = mutate ? await query() : values;
+  const configured = startupText(location) === wanted
+    && verified.LoadState === "loaded" && sameStartupFile(location, verified.FragmentPath)
+    && (!enabled || ["enabled", "enabled-runtime"].includes(verified.UnitFileState));
+  if (mutate && !configured) throw installFailure("SERVICE_READBACK_FAILED");
+  return { configured, enabled, changed, started, registration: label };
+}
+
+export async function installBackgroundRelay({ env = process.env, platform = process.platform, root = ROOT, run = execute,
+  dryRun = false, check = false, health = callBackgroundRelay, sleep = pause, pollAttempts = 15, uid = process.getuid?.() } = {}) {
+  const base = { configured: false, enabled: false, started: false, liveVerified: false, ready: false };
+  let config;
+  try {
+    config = readRelayConfiguration({ env, platform, missing: true });
+    if (!config) return { ...base, code: "WORKER_RELAY_NOT_CONFIGURED", reason: "Configure the background relay before installing its user service" };
+    if (!["win32", "darwin", "linux"].includes(platform)) return { ...base, code: "SERVICE_PLATFORM_UNSUPPORTED", reason: "Background relay user startup is unsupported on this platform" };
+    if (!path.isAbsolute(root)) throw installFailure("SERVICE_RUNTIME_MISSING");
+    root = fs.realpathSync.native(root);
+    const node = stableNodeBin(env);
+    const service = path.join(root, "src", "background-relay-service.mjs");
+    if (!path.isAbsolute(root) || !fs.existsSync(service) || !fs.existsSync(path.join(root, "src", "background-relay-daemon.mjs"))) throw installFailure("SERVICE_RUNTIME_MISSING");
+    let packageVersion;
+    try { packageVersion = JSON.parse(readRegularConfigFile(path.join(root, "package.json"), { maxBytes: 128 * 1024 })).version; }
+    catch { throw installFailure("SERVICE_RUNTIME_INVALID"); }
+    if (typeof packageVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.+-]+)?$/.test(packageVersion) || packageVersion.length > 96) throw installFailure("SERVICE_RUNTIME_INVALID");
+    if ([root, config.paths.root, node].some((value) => /[\u0000-\u001f\u007f]/.test(value))) throw installFailure("SERVICE_LAUNCH_PATH_UNSUPPORTED");
+    const hash = createHash("sha256").update(platform === "win32" ? config.paths.root.toLowerCase() : config.paths.root).digest("hex").slice(0, 12);
+    const label = platform === "win32" ? `MinhSpark Agent Relay ${hash}` : `com.minhspark.agent-relay.${hash}`;
+    const invoke = async (command, args, extra = {}) => {
+      const result = await run(command, args, { env, encoding: "utf8", windowsHide: true, shell: false, timeout: 15000, maxBuffer: 256 * 1024, stdio: ["pipe", "pipe", "pipe"], ...extra });
+      return { status: result?.status ?? result?.exitCode ?? 0, stdout: String(result?.stdout ?? "") };
+    };
+    const runtimeFile = path.join(config.paths.root, "service-runtime.json");
+    const desiredRuntime = { schemaVersion: 1, owner: RELAY_SERVICE_OWNER, packageRoot: root, nodeExecutable: node, packageVersion,
+      environment: Object.fromEntries(Object.entries(savedEnvironment(env, config)).filter(([name]) => !name.startsWith("AGENT_RELAY_"))) };
+    const expectedRuntimeId = relayServiceRuntimeId(desiredRuntime);
+    const readRuntime = () => {
+      const raw = readRegularConfigFile(runtimeFile, { missing: true, maxBytes: 64 * 1024 });
+      if (raw === null) return null;
+      let value;
+      try { value = JSON.parse(raw); } catch { throw installFailure("SERVICE_RUNTIME_INVALID"); }
+      if (value?.schemaVersion !== 1 || value.owner !== RELAY_SERVICE_OWNER) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+      return value;
+    };
+    const previousRuntime = readRuntime();
+    const runtimeChanged = JSON.stringify(previousRuntime) !== JSON.stringify(desiredRuntime);
+    const prepareRuntime = async () => {
+      if (JSON.stringify(readRuntime()) !== JSON.stringify(previousRuntime)) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
+      if (runtimeChanged) writeRelayJson(runtimeFile, desiredRuntime);
+      if (JSON.stringify(readRuntime()) !== JSON.stringify(desiredRuntime)) throw installFailure("SERVICE_READBACK_FAILED");
+    };
+    const context = { env, config, root, node, service, label, invoke, mutate: !dryRun && !check, uid, nativeRun: run === execute, prepareRuntime };
+    const installed = await ({ win32: installWindows, darwin: installMac, linux: installLinux })[platform](context);
+    installed.configured = installed.configured && JSON.stringify(readRuntime()) === JSON.stringify(desiredRuntime);
+    const result = { ...base, ...installed, dryRun, deliveryEnabled: installed.enabled, liveVerified: false,
+      expectedVersion: packageVersion, runtimeChanged, activationPending: installed.activationPending === true || runtimeChanged && previousRuntime !== null };
+    if (!installed.enabled) {
+      result.notice = config.enabled ? "User startup is intentionally disabled; the installer preserved that choice" : "Background relay is intentionally disabled in its configuration";
+      return result;
+    }
+    if (!installed.configured || dryRun) return result;
+    const attempts = check ? 1 : Math.max(1, Math.min(30, pollAttempts));
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      try {
+        const status = await health("status", {}, { env, connection: { endpoint: config.endpoint, token: config.token, workerId: null }, timeoutMs: 1000 });
+        const serviceState = JSON.parse(readRegularConfigFile(path.join(config.paths.root, "service-status.json"), { maxBytes: 64 * 1024 }));
+        const owned = status?.schemaVersion === 1 && status.transportReady === true && status.desktopRequired === false
+            && Number.isSafeInteger(status.pid) && status.pid > 0 && serviceState?.owner === RELAY_SERVICE_OWNER
+            && serviceState.status === "running" && serviceState.daemonPid === status.pid;
+        if (owned && typeof status.version === "string" && /^[A-Za-z0-9.+_-]{1,96}$/.test(status.version)) result.version = status.version;
+        if (owned && (serviceState.runtimeId !== expectedRuntimeId || status.runtimeId !== expectedRuntimeId || status.version !== packageVersion)) result.activationPending = true;
+        if (owned && serviceState.runtimeId === expectedRuntimeId && status.runtimeId === expectedRuntimeId && status.version === packageVersion) {
+          return { ...result, activationPending: false, liveVerified: true, ready: status.accepting === true, pid: status.pid,
+            version: typeof status.version === "string" && /^[A-Za-z0-9.+_-]{1,96}$/.test(status.version) ? status.version : null,
+            ...(status.accepting === true ? {} : { code: "SERVICE_DRAINING", notice: "The relay is finishing existing work before accepting new jobs" }) };
+        }
+      } catch {}
+      if (attempt + 1 < attempts) await sleep(250);
+    }
+    return { ...result, code: result.activationPending ? "SERVICE_UPDATE_PENDING" : "SERVICE_NOT_READY",
+      reason: result.activationPending ? "User startup is configured; the running service has not yet verified the desired idle runtime update"
+        : "User startup is configured, but its owned daemon did not report healthy transport" };
+  } catch (error) {
+    const allowed = /^(?:SERVICE_[A-Z_]+|TASK_SCHEDULER_UNAVAILABLE|LAUNCH_AGENT_UNAVAILABLE|USER_SYSTEMD_UNAVAILABLE|WORKER_CONFIG_INVALID|WORKER_STORAGE_UNSAFE)$/;
+    const code = typeof error.code === "string" && allowed.test(error.code) ? error.code : "SERVICE_INSTALL_FAILED";
+    return { ...base, code, reason: "The background relay user service could not be safely configured or verified" };
+  }
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.some((arg) => !["--check", "--dry-run", "--json"].includes(arg)) || args.includes("--check") && args.includes("--dry-run")) {
+    process.stderr.write("Usage: install-background-relay.mjs [--check|--dry-run] [--json]\n");
+    process.exitCode = 2;
+  } else {
+    const result = await installBackgroundRelay({ check: args.includes("--check"), dryRun: args.includes("--dry-run") });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.configured && !args.includes("--dry-run") && result.code !== "SERVICE_MASKED") process.exitCode = 1;
+  }
+}

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.3";
+const VERSION = "1.26.0";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/scripts/setup-background-relay.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "../src/install-paths.mjs";
+import { backgroundAdapters } from "../src/background-relay.mjs";
+import { BACKGROUND_AGENTS, canStartBackgroundWorker, configureRelay, readRelayConfiguration, relayFailure } from "../src/background-relay-config.mjs";
+import { configureBackgroundWorkerMcp } from "../src/background-relay-registration.mjs";
+import { installBackgroundRelay } from "./install-background-relay.mjs";
+import { diagnosticText, withBridgeDiagnostic } from "../src/recipient-preflight.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export async function setupBackgroundRelay({ env = process.env, platform = process.platform, root = ROOT, check = false, dryRun = false,
+  adapters, readConfig = readRelayConfiguration, configure = configureRelay, registration = configureBackgroundWorkerMcp, service = installBackgroundRelay } = {}) {
+  if (dryRun) return { configured: false, dryRun: true, liveVerified: false,
+    planned: ["Independent relay configuration", "Scoped worker MCP communication", "Per-user background service"], opensApps: false, opensChats: false };
+  const workers = adapters ?? await backgroundAdapters();
+  const saved = readConfig({ env, platform, missing: true });
+  const readiness = await Promise.all(BACKGROUND_AGENTS.map(async agent => {
+    try { return { agent, ...await workers[agent].inspect({ env, platform, executable: saved?.providers[agent]?.executable ?? undefined }) }; }
+    catch (error) { return { agent, available: false, authenticated: null, ready: false, code: error.code ?? "WORKER_INSPECTION_FAILED" }; }
+  }));
+  const config = check ? saved
+    : configure({ env, platform });
+  if (!config) throw relayFailure("WORKER_RELAY_NOT_CONFIGURED", "The independent relay has not been configured; rerun the package setup command");
+  const mcp = registration({ env, platform, root, check });
+  const installed = await service({ env, platform, root, check });
+  const notices = [
+    "Background tasks have separate CLI identities and receipts; they never resume Desktop chats.",
+    ...(!fs.existsSync(config.projectPolicy) ? ["No shared project policy is saved yet. Explicitly authorize a selected project with bridge-projects allow-project before sending background work."] : []),
+    ...(mcp.blocked ? [mcp.reason ?? "An existing permission or disabled-server choice blocks worker MCP communication; that choice was preserved."] : []),
+    ...readiness.filter(item => !item.available || item.authenticated === false).map(item => `${item.agent}: ${item.code ?? "WORKER_NOT_READY"}; CLI authentication and installation remain separate from Desktop sign-in.`),
+    ...(installed.code ? [diagnosticText(`${installed.code}: ${installed.notice ?? installed.reason ?? "Inspect worker-relay status for service readiness."}`)]
+      : installed.notice ? [diagnosticText(installed.notice)] : []),
+  ];
+  return { configured: mcp.configured === true && installed.configured === true, enabled: config.enabled,
+    liveVerified: installed.liveVerified === true, transportReady: installed.ready === true,
+    desktopRequired: false, opensApps: false, opensChats: false, notices,
+    workerReadiness: readiness.map(({ agent, available, authenticated, ready, version, code }) => ({ agent, available, authenticated, ready, version, code,
+      canAcceptWork: config.enabled && config.providers[agent].enabled && canStartBackgroundWorker(agent, { available, authenticated, ready, code }) })),
+    permissions: { blocked: mcp.blocked === true, ...(mcp.code ? { code: mcp.code } : {}) },
+    service: { configured: installed.configured, started: installed.started, activationPending: installed.activationPending, code: installed.code, version: installed.version } };
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  const args = process.argv.slice(2);
+  try {
+    if (args.some(arg => !["--check", "--dry-run", "--json"].includes(arg))) throw relayFailure("WORKER_SETUP_ARGUMENT_INVALID", "Unsupported background relay setup argument");
+    const result = await setupBackgroundRelay({ check: args.includes("--check"), dryRun: args.includes("--dry-run") });
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    if (!result.configured && !result.dryRun) process.exitCode = 1;
+  } catch (error) {
+    const result = withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "background-relay", operation: "setup" });
+    process.stderr.write(result.content.map(item => item.text ?? "").join("\n") + "\n");
+    process.exitCode = 1;
+  }
+}