baychat 0.19.0 → 0.20.1

package/README.md

@@ -30,10 +30,49 @@ Coding sessions show idle after five minutes without use and expire after
 24 hours. `end_session` closes one immediately. History survives and the same
 name can rejoin. Persistent agents such as Hermes keep their own lifecycle.
 
-This workflow requires CLI 0.19.0 and its matching API deployment. Update npm,
+This workflow requires CLI 0.20.1 and the existing session-chat API deployment. Update npm,
 rerun `baychat connect <runtime>` to refresh its skill, and restart running
 relays and MCP clients. Updating npm alone does not deploy the remote MCP.
 
+## What the package and MCP each do
+
+The npm package contains the CLI, installed runtime commands, local relay,
+local stdio MCP server and bundled Hermes plugin. The remote MCP is the BayChat
+API running on the server. It owns sessions, room membership and chat tools.
+Updating npm updates this computer; deploying the API updates remote MCP.
+
+The installed session command runs one foreground command:
+
+```sh
+baychat join Atlas "Coding" --runtime codex
+baychat join --group "Coding" --runtime codex
+```
+
+It joins through remote MCP, uses the server-confirmed identity, checks the relay
+and connects incoming messages. Claude runs this command with its persistent
+Monitor and re-arms automatically after a wake. Codex verifies native queue
+support and returns as soon as the relay confirms registration. It needs no
+waiting terminal or manual re-arming. Failed delivery setup is reported as
+incomplete, even when the room join succeeded.
+
+The Windows relay runs without a visible console, including after login and
+network reconnects. Incoming messages appear as `@Sender` in the coding task.
+The skill echoes BayChat chat replies locally; raw tool output stays local.
+Codex can queue messages behind an active turn, so an accepted message is not
+proof of an immediate reply.
+
+For a persistent Hermes installation, run this on the Hermes machine:
+
+```sh
+baychat connect hermes
+```
+
+Approve the QR once and choose its agent on the phone. The command installs the
+bundled plugin, configures remote MCP tools, and enables its gateway. Existing
+Hermes settings and other MCP servers are preserved, with a backup before changes.
+The MCP header references the credential in .env. An existing agent credential is reused;
+a failed enable or restart returns an error. Hermes must already be installed.
+
 ## Pair a persistent agent
 
 Connect an AI agent session — Claude Code, Codex, or any CLI with a shell — to

package/dist/commands.js

@@ -19,6 +19,7 @@ exports.cmdCheck = cmdCheck;
 exports.cmdWatch = cmdWatch;
 exports.cmdLink = cmdLink;
 exports.claudeMcpAddSpawn = claudeMcpAddSpawn;
+exports.registerWithClaude = registerWithClaude;
 exports.cmdLogin = cmdLogin;
 exports.deviceExpiryWarning = deviceExpiryWarning;
 exports.printDeviceExpiryWarning = printDeviceExpiryWarning;
@@ -688,7 +689,7 @@ function registerWithClaude(baseUrl, token) {
         // Windows only, and only for a value a quoted cmd.exe argument cannot hold.
         console.log("\nCould not add BayChat to Claude Code safely on Windows — add it manually:");
         printManualMcpAdd(baseUrl);
-        return;
+        return false;
     }
     // stderr is captured (not ignored) so a failure can quote claude's own words;
     // the timeout keeps a hung binary from hanging a login whose credential is
@@ -725,19 +726,19 @@ function registerWithClaude(baseUrl, token) {
             if (readded.status === 0) {
                 console.log("✓ BayChat re-registered with Claude Code (credential renewed)");
                 installClaudeSkill();
-                return;
+                return true;
             }
         }
     }
     if (recipe.shell && res.status === 9009) {
         console.log("\nClaude Code CLI not found — add BayChat manually:");
         printManualMcpAdd(baseUrl);
-        return;
+        return false;
     }
     if (res.error && res.error.code === "ENOENT") {
         console.log("\nClaude Code CLI not found — add BayChat manually:");
         printManualMcpAdd(baseUrl);
-        return;
+        return false;
     }
     if (res.error || res.status !== 0) {
         const reason = res.error?.code ??
@@ -758,10 +759,11 @@ function registerWithClaude(baseUrl, token) {
         // because of it: a session with the rules and no tools still knows how to
         // ask for them, while one with neither knows nothing at all.
         installClaudeSkill();
-        return;
+        return false;
     }
     console.log("✓ BayChat added to Claude Code");
     installClaudeSkill();
+    return true;
 }
 /**
  * Install Claude Code's BayChat skill, the other half of registering the server.

package/dist/connect-claude.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdConnectClaude = cmdConnectClaude;
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+const commands_2 = require("./relay/commands");
+const runtime_install_1 = require("./runtime-install");
+/** One-time Claude setup reuses a valid login, registers MCP, and refreshes its skill. */
+async function cmdConnectClaude(opts = {}) {
+    try {
+        const existing = (0, config_1.loadDeviceCredentials)();
+        const base = (opts.base || process.env.BAYCHAT_API_URL || existing?.baseUrl || config_1.DEFAULT_API_URL).replace(/\/$/, "");
+        const expires = existing ? Date.parse(existing.expiresAt) : NaN;
+        if (!existing || existing.baseUrl.replace(/\/$/, "") !== base || !Number.isFinite(expires) || expires <= Date.now()) {
+            if (!await (0, commands_1.cmdLogin)({ base, registerClaude: false, hint: false }))
+                return 2;
+        }
+        const device = (0, config_1.loadDeviceCredentials)();
+        if (!device)
+            throw new Error("No device login was saved. Retry baychat connect claude.");
+        const registered = (0, commands_1.registerWithClaude)(device.baseUrl, device.token);
+        for (const line of (0, runtime_install_1.describeInstall)((0, runtime_install_1.installRuntimeCommand)("claude")))
+            console.log("  " + line);
+        if (!registered)
+            return 1;
+        console.log("  " + await (0, commands_2.ensureRelayInstalled)());
+        console.log('  Restart Claude Code once, then use /baychat <name> "<group>".');
+        return 0;
+    }
+    catch (err) {
+        console.error("Could not connect Claude Code: " + (err instanceof Error ? err.message : String(err)));
+        return 1;
+    }
+}

package/dist/connect-hermes.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdConnectHermes = cmdConnectHermes;
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+const hermes_1 = require("./hermes");
+/** Hermes owns a persistent agent. The owner chooses its name and Bay on the phone. */
+async function cmdConnectHermes(opts = {}) {
+    const existing = (0, config_1.loadCredentials)();
+    if (!existing || (opts.base && opts.base.replace(/\/$/, "") !== existing.baseUrl.replace(/\/$/, ""))) {
+        console.log("Connect Hermes — approve the QR and choose its agent in BayChat.");
+        if (!await (0, commands_1.cmdLink)(opts))
+            return 2;
+    }
+    if (!(0, config_1.loadCredentials)()) {
+        console.error("No paired agent credential was saved. Retry baychat connect hermes.");
+        return 1;
+    }
+    return (0, hermes_1.cmdHermesInit)(["--enable"]);
+}

package/dist/connect.js

@@ -31,11 +31,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdConnectClaude = void 0;
 exports.renderConnectMenu = renderConnectMenu;
 exports.isClaudeConnectTarget = isClaudeConnectTarget;
 exports.parseConnectClient = parseConnectClient;
 exports.writeClientConfig = writeClientConfig;
-exports.cmdConnectClaude = cmdConnectClaude;
 exports.cmdConnect = cmdConnect;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -49,6 +49,10 @@ const commands_2 = require("./relay/commands");
 const runtime_install_1 = require("./runtime-install");
 const runtimes_1 = require("./runtimes");
 const runtime_binary_1 = require("./runtime-binary");
+const connect_claude_1 = require("./connect-claude");
+var connect_claude_2 = require("./connect-claude");
+Object.defineProperty(exports, "cmdConnectClaude", { enumerable: true, get: function () { return connect_claude_2.cmdConnectClaude; } });
+const connect_hermes_1 = require("./connect-hermes");
 /** Clients `connect` can configure. `claude` is an alias users reach for. */
 const CLIENT_ALIASES = {
     codex: "codex",
@@ -63,7 +67,8 @@ function renderConnectMenu() {
         "Connect this laptop to BayChat, once, and configure your client:",
         "",
         ...rows,
-        "  npx baychat connect claude  → Claude Code (refreshes its skill)",
+        "  npx baychat connect claude  → Claude Code (login, MCP and skill)",
+        "  npx baychat connect hermes  → Hermes (pair and enable its persistent agent)",
         "",
         "You approve a QR on your phone. After that, in any coding session:",
         "",
@@ -179,29 +184,6 @@ const realIo = {
  *
  * @returns 0 on success, 2 when the laptop login expired without approval.
  */
-/**
- * `baychat connect claude` — refresh Claude Code's skill.
- *
- * Deliberately does NOT touch the credential or the MCP registration. Both are
- * `login`'s job, and re-doing them would put a device-pairing QR in front of
- * somebody whose login is fine. Writing the skill needs no auth at all: it is
- * generated locally from this CLI's own version, which is exactly why it goes
- * stale on upgrade and exactly why this command has to exist.
- */
-function cmdConnectClaude() {
-    try {
-        for (const line of (0, runtime_install_1.describeInstall)((0, runtime_install_1.installRuntimeCommand)("claude")))
-            console.log(`  ${line}`);
-        console.log("");
-        console.log("  Restart Claude Code once so it picks the skill up.");
-        console.log("  Not logged in yet? `npx baychat login` — that registers the MCP server too.");
-        return 0;
-    }
-    catch (err) {
-        console.log(`Could not install the Claude Code skill: ${err instanceof Error ? err.message : String(err)}`);
-        return 1;
-    }
-}
 async function cmdConnect(clientArg, opts = {}) {
     if (clientArg === undefined) {
         console.log(renderConnectMenu());
@@ -210,7 +192,9 @@ async function cmdConnect(clientArg, opts = {}) {
     // Claude Code first: it is not an MCP-config client, so it must not reach
     // `parseConnectClient`, which would reject it.
     if (isClaudeConnectTarget(clientArg))
-        return cmdConnectClaude();
+        return (0, connect_claude_1.cmdConnectClaude)(opts);
+    if (clientArg.trim().toLowerCase() === "hermes")
+        return (0, connect_hermes_1.cmdConnectHermes)(opts);
     const client = parseConnectClient(clientArg);
     const base = (opts.base || process.env.BAYCHAT_API_URL || config_1.DEFAULT_API_URL).replace(/\/$/, "");
     const steps = (0, connect_plan_1.planConnect)({

package/dist/hermes-mcp.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeHermesMcp = writeHermesMcp;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const yaml_1 = require("yaml");
+/** Preserve other Hermes settings, comments, tools policies and MCP servers.
+ * The credential stays in .env; config only references BAYCHAT_TOKEN.
+ */
+function writeHermesMcp(home, baseUrl) {
+    const written = node_path_1.default.join(home, "config.yaml");
+    const existing = node_fs_1.default.existsSync(written) ? node_fs_1.default.readFileSync(written, "utf8") : "";
+    const doc = (0, yaml_1.parseDocument)(existing);
+    // Never quote parser errors: they can contain lines holding another API key.
+    if (doc.errors.length || (doc.contents !== null && !(0, yaml_1.isMap)(doc.contents))) {
+        throw new Error("Hermes config.yaml is not a valid YAML mapping. Fix it before connecting.");
+    }
+    if (doc.contents === null)
+        doc.contents = doc.createNode({});
+    for (const keys of [["mcp_servers"], ["mcp_servers", "baychat"], ["mcp_servers", "baychat", "headers"]]) {
+        if (!doc.hasIn(keys))
+            doc.setIn(keys, doc.createNode({}));
+        if (!(0, yaml_1.isMap)(doc.getIn(keys, true))) {
+            throw new Error("Hermes mcp_servers.baychat configuration must use YAML mappings. Existing config was preserved.");
+        }
+    }
+    const root = ["mcp_servers", "baychat"];
+    // A former stdio/SSE entry cannot coexist with the remote HTTP transport.
+    for (const key of ["command", "args", "transport"])
+        doc.deleteIn([...root, key]);
+    doc.setIn([...root, "url"], new URL("/api/mcp", baseUrl).href);
+    doc.setIn([...root, "headers", "Authorization"], "Bearer ${BAYCHAT_TOKEN}");
+    doc.setIn([...root, "enabled"], true);
+    const next = doc.toString();
+    if (next === existing)
+        return { written };
+    node_fs_1.default.mkdirSync(home, { recursive: true });
+    const suffix = (0, node_crypto_1.randomUUID)();
+    const backup = existing ? written + ".baychat-backup-" + suffix : undefined;
+    if (backup) {
+        node_fs_1.default.copyFileSync(written, backup, node_fs_1.default.constants.COPYFILE_EXCL);
+        node_fs_1.default.chmodSync(backup, 0o600);
+    }
+    const temporary = written + ".baychat-" + suffix;
+    try {
+        node_fs_1.default.writeFileSync(temporary, next, { mode: 0o600, flag: "wx" });
+        node_fs_1.default.renameSync(temporary, written);
+    }
+    finally {
+        if (node_fs_1.default.existsSync(temporary))
+            node_fs_1.default.unlinkSync(temporary);
+    }
+    return { written, backup };
+}

package/dist/hermes.js

@@ -56,6 +56,7 @@ const path = __importStar(require("path"));
 const args_1 = require("./args");
 const config_1 = require("./config");
 const hermes_plugin_content_1 = require("./hermes-plugin-content");
+const hermes_mcp_1 = require("./hermes-mcp");
 /** The two commands Hermes needs after the files are in place. */
 exports.ENABLE_STEPS = [
     "hermes config set gateway.platforms.baychat.enabled true",
@@ -128,9 +129,15 @@ function writeHermesEnv(home, token, baseUrl) {
     return envPath;
 }
 function installHermes(home) {
+    const creds = (0, config_1.loadCredentials)();
+    // Refuse a malformed config before changing the gateway or its credential.
+    const mcp = creds ? (0, hermes_mcp_1.writeHermesMcp)(home, creds.baseUrl) : null;
     const { written, backedUp } = installHermesPlugin(home);
+    if (mcp)
+        written.push(mcp.written);
+    if (mcp?.backup)
+        backedUp.push(mcp.backup);
     const report = { home, written, backedUp, envWritten: null };
-    const creds = (0, config_1.loadCredentials)();
     if (!creds) {
         report.envSkipped =
             "no agent token on this machine — run `baychat pair <code>` (get the code in the BayChat app: Agents → your agent), then re-run this";
@@ -139,18 +146,19 @@ function installHermes(home) {
     report.envWritten = writeHermesEnv(home, creds.token, creds.baseUrl);
     return report;
 }
-/** Run the two enablement commands. Returns false if `hermes` is not on PATH. */
-function runEnableSteps() {
-    const probe = (0, child_process_1.spawnSync)("hermes", ["--version"], { stdio: "ignore" });
+/** Fail visibly if the executable or either gateway setup step fails. */
+function runEnableSteps(home) {
+    const env = { ...process.env, HERMES_HOME: home };
+    const probe = (0, child_process_1.spawnSync)("hermes", ["--version"], { stdio: "ignore", env });
     if (probe.error)
         return false;
     for (const step of exports.ENABLE_STEPS) {
         const [bin, ...rest] = step.split(" ");
         console.log(`  $ ${step}`);
-        const run = (0, child_process_1.spawnSync)(bin, rest, { stdio: "inherit" });
+        const run = (0, child_process_1.spawnSync)(bin, rest, { stdio: "inherit", env });
         if (run.status !== 0) {
             console.log(`  ↑ exited ${run.status ?? "abnormally"} — finish the remaining steps by hand.`);
-            return true;
+            return false;
         }
     }
     return true;
@@ -169,13 +177,16 @@ function cmdHermesInit(args) {
     }
     else {
         console.log(`\nNo token written — ${report.envSkipped}`);
+        if (args.includes("--enable"))
+            return 1;
     }
     console.log("\nEnable it in Hermes:");
     if (args.includes("--enable")) {
-        if (!runEnableSteps()) {
-            console.log("  `hermes` is not on PATH — run these wherever Hermes is installed:");
+        if (!runEnableSteps(home)) {
+            console.log("  Hermes could not be enabled. Resolve the error, then run:");
             for (const step of exports.ENABLE_STEPS)
                 console.log(`    ${step}`);
+            return 1;
         }
     }
     else {

package/dist/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commands_1 = require("./commands");
 const approve_hook_1 = require("./approve-hook");
 const session_name_1 = require("./session-name");
+const session_command_1 = require("./session-command");
 const doctor_command_1 = require("./doctor-command");
 const hermes_1 = require("./hermes");
 const connect_1 = require("./connect");
@@ -17,6 +18,8 @@ const profiles_1 = require("./relay/profiles");
 const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
 
 Usage:
+  baychat join [name] [group] [--group <title>] [--runtime <runtime>]
+                                        Join and connect incoming messages in this terminal
   baychat session-name --runtime <runtime>
                                         Stable automatic name for this verified session
   baychat onboard [conversationId] [--catch-up]
@@ -153,6 +156,8 @@ function numberFlag(args, name) {
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
+        case "join":
+            return (0, session_command_1.cmdJoinSession)(args);
         case "session-name": {
             (0, args_1.rejectUnknownFlags)(args, ["--runtime"], "baychat session-name --runtime <runtime>");
             const runtime = (0, args_1.flag)(args, "--runtime") ?? (0, owner_pid_1.detectRuntime)(profiles_1.RUNTIME_PROFILES);

package/dist/relay/adapters.js

@@ -197,7 +197,11 @@ const codexAdapter = {
      */
     async runTurn({ binaryPath, target, prompt }) {
         if (process.env.BAYCHAT_CODEX_TRANSPORT === "exec") {
-            return { kind: "failed", transportUnusable: true, reason: "BAYCHAT_CODEX_TRANSPORT=exec" };
+            return {
+                kind: "failed",
+                transportUnusable: true,
+                reason: "BAYCHAT_CODEX_TRANSPORT=exec",
+            };
         }
         return (0, codex_app_server_1.runCodexTurn)({
             binaryPath,
@@ -234,7 +238,10 @@ const cursorAdapter = {
         // Nothing to discover: Cursor writes no on-disk session state this package
         // can identify a conversation from, and a search that cannot succeed is
         // only a way to produce a confident-looking wrong answer.
-        return { ok: false, reason: "Cursor records no resumable session id on this machine" };
+        return {
+            ok: false,
+            reason: "Cursor records no resumable session id on this machine",
+        };
     },
     headlessCommand() {
         // Unreachable: the daemon consults canResume first and reports pending.
@@ -259,7 +266,10 @@ const hermesAdapter = {
     async discoverResume() {
         // Nothing to discover: Hermes runs somewhere else and leaves no local
         // transcript. Searching would only produce a confident-looking wrong answer.
-        return { ok: false, reason: "Hermes keeps no local session state on this machine" };
+        return {
+            ok: false,
+            reason: "Hermes keeps no local session state on this machine",
+        };
     },
     headlessCommand() {
         // Unreachable: the daemon consults canResume first and reports pending.
@@ -317,7 +327,9 @@ function profileAdapter(profile) {
             // `session-name` runtimes are resumed by the name the human chose, which
             // IS the BayChat session name — so there is nothing to discover and
             // nothing that could name someone else's session.
-            const id = profile.sessionId.kind === "session-name" ? target.name : target.resumeId;
+            const id = profile.sessionId.kind === "session-name"
+                ? target.name
+                : target.resumeId;
             if (!id) {
                 return {
                     ok: false,
@@ -337,7 +349,9 @@ function profileAdapter(profile) {
         headlessCommand(target, prompt) {
             if (!profile.headless)
                 throw new Error(`${profile.id} has no headless command`);
-            const id = profile.sessionId.kind === "session-name" ? target.name : target.resumeId;
+            const id = profile.sessionId.kind === "session-name"
+                ? target.name
+                : target.resumeId;
             return {
                 file: target.runtimeBin ?? profile.bin,
                 args: (0, profiles_1.fillTemplate)(profile.headless.args, { id, prompt }),
@@ -353,7 +367,10 @@ function adapterFor(runtime) {
     return profile ? profileAdapter(profile) : unknownAdapter(runtime);
 }
 /** The runtimes we ship knowledge of, for help text. NOT a list of what is accepted. */
-exports.KNOWN_RUNTIMES = [...Object.keys(ADAPTERS), ...profiles_1.RUNTIME_PROFILES.map((p) => p.id)];
+exports.KNOWN_RUNTIMES = [
+    ...Object.keys(ADAPTERS),
+    ...profiles_1.RUNTIME_PROFILES.map((p) => p.id),
+];
 /**
  * Do we ship knowledge of this runtime?
  *
@@ -364,7 +381,8 @@ exports.KNOWN_RUNTIMES = [...Object.keys(ADAPTERS), ...profiles_1.RUNTIME_PROFIL
  * us, and the Cursor outage was the same mistake from the other side.
  */
 function isKnownRuntime(value) {
-    return Object.prototype.hasOwnProperty.call(ADAPTERS, value) || (0, profiles_1.profileFor)(value) !== undefined;
+    return (Object.prototype.hasOwnProperty.call(ADAPTERS, value) ||
+        (0, profiles_1.profileFor)(value) !== undefined);
 }
 /**
  * Run a headless turn to completion.
@@ -377,6 +395,7 @@ function isKnownRuntime(value) {
 function runHeadless(file, args, opts = {}) {
     return new Promise((resolve) => {
         const child = (0, child_process_1.spawn)(file, args, {
+            windowsHide: true,
             cwd: opts.cwd,
             // An npm-installed runtime is a script with a `#!/usr/bin/env node`
             // shebang, and the daemon's systemd PATH has no node. See ./spawn-env.ts.

package/dist/relay/autostart.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTOSTART_IMPLEMENTATIONS = exports.LingerUnavailable = exports.SYSTEMD_UNIT_NAME = exports.SERVICE_LABEL = void 0;
+exports.AUTOSTART_IMPLEMENTATIONS = exports.WINDOWS_RELAY_LAUNCHER = exports.LingerUnavailable = exports.SYSTEMD_UNIT_NAME = exports.SERVICE_LABEL = void 0;
 exports.autostartForPlatform = autostartForPlatform;
 exports.relayCommand = relayCommand;
 // Making the relay come back by itself, on all three platforms.
@@ -101,9 +101,17 @@ WantedBy=default.target
         fs.mkdirSync(path.dirname(target), { recursive: true });
         fs.writeFileSync(target, systemd.unit(cmd), { mode: 0o644 });
         await execFileAsync("systemctl", ["--user", "daemon-reload"]);
-        await execFileAsync("systemctl", ["--user", "enable", "--now", exports.SYSTEMD_UNIT_NAME]);
+        await execFileAsync("systemctl", [
+            "--user",
+            "enable",
+            "--now",
+            exports.SYSTEMD_UNIT_NAME,
+        ]);
         try {
-            await execFileAsync("loginctl", ["enable-linger", os.userInfo().username]);
+            await execFileAsync("loginctl", [
+                "enable-linger",
+                os.userInfo().username,
+            ]);
         }
         catch {
             // Not fatal and not silent: the caller prints the degraded promise rather
@@ -112,7 +120,12 @@ WantedBy=default.target
         }
     },
     async uninstall() {
-        await execFileAsync("systemctl", ["--user", "disable", "--now", exports.SYSTEMD_UNIT_NAME]).catch(() => undefined);
+        await execFileAsync("systemctl", [
+            "--user",
+            "disable",
+            "--now",
+            exports.SYSTEMD_UNIT_NAME,
+        ]).catch(() => undefined);
         fs.rmSync(systemd.unitPath(), { force: true });
     },
 };
@@ -175,12 +188,18 @@ const launchd = {
         const domain = `gui/${os.userInfo().uid}`;
         // Replacing an agent means removing the old one first; bootout on a label
         // that was never loaded exits non-zero, which is not a failure here.
-        await execFileAsync("launchctl", ["bootout", `${domain}/${exports.SERVICE_LABEL}`]).catch(() => undefined);
+        await execFileAsync("launchctl", [
+            "bootout",
+            `${domain}/${exports.SERVICE_LABEL}`,
+        ]).catch(() => undefined);
         await execFileAsync("launchctl", ["bootstrap", domain, target]);
     },
     async uninstall() {
         const domain = `gui/${os.userInfo().uid}`;
-        await execFileAsync("launchctl", ["bootout", `${domain}/${exports.SERVICE_LABEL}`]).catch(() => undefined);
+        await execFileAsync("launchctl", [
+            "bootout",
+            `${domain}/${exports.SERVICE_LABEL}`,
+        ]).catch(() => undefined);
         fs.rmSync(launchd.unitPath(), { force: true });
     },
 };
@@ -246,8 +265,8 @@ const scheduledTask = {
   </Settings>
   <Actions Context="Author">
     <Exec>
-      <Command>${escapeXml(cmd.node)}</Command>
-      <Arguments>"${escapeXml(cmd.entry)}" relay start --foreground</Arguments>
+      <Command>${escapeXml(path.win32.join(process.env.SystemRoot || "C:\\Windows", "System32", "wscript.exe"))}</Command>
+      <Arguments>//B //NoLogo ${escapeXml(`"${windowsLauncherPath()}" "${cmd.node}" "${cmd.entry}"`)} relay start --foreground</Arguments>
     </Exec>
   </Actions>
 </Task>
@@ -258,17 +277,47 @@ const scheduledTask = {
     async install(cmd) {
         const target = scheduledTask.unitPath();
         fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(windowsLauncherPath(), exports.WINDOWS_RELAY_LAUNCHER, "utf8");
         // UTF-16LE with a BOM, because that is what the XML declaration above claims
         // and what schtasks refuses the file without.
-        fs.writeFileSync(target, "\ufeff" + scheduledTask.unit(cmd), { encoding: "utf16le" });
-        await execFileAsync("schtasks", ["/create", "/tn", exports.SERVICE_LABEL, "/xml", target, "/f"]);
-        await execFileAsync("schtasks", ["/run", "/tn", exports.SERVICE_LABEL]);
+        fs.writeFileSync(target, "\ufeff" + scheduledTask.unit(cmd), {
+            encoding: "utf16le",
+        });
+        await execFileAsync("schtasks", ["/create", "/tn", exports.SERVICE_LABEL, "/xml", target, "/f"], { windowsHide: true });
+        await execFileAsync("schtasks", ["/run", "/tn", exports.SERVICE_LABEL], {
+            windowsHide: true,
+        });
     },
     async uninstall() {
-        await execFileAsync("schtasks", ["/delete", "/tn", exports.SERVICE_LABEL, "/f"]).catch(() => undefined);
+        // Deleting a task does not stop its running child. End the supervised
+        // process first so `relay stop` cannot leave an invisible orphan behind.
+        await execFileAsync("schtasks", ["/end", "/tn", exports.SERVICE_LABEL], {
+            windowsHide: true,
+        }).catch(() => undefined);
+        await execFileAsync("schtasks", ["/delete", "/tn", exports.SERVICE_LABEL, "/f"], {
+            windowsHide: true,
+        }).catch(() => undefined);
         fs.rmSync(scheduledTask.unitPath(), { force: true });
+        fs.rmSync(windowsLauncherPath(), { force: true });
     },
 };
+/** WSH is a GUI executable, so starting it never allocates a visible console.
+ * Run's window style 0 hides the child too. Waiting and forwarding its exit
+ * code keeps Task Scheduler's restart supervision attached to the actual relay.
+ * This is Windows Script Host JScript, not Node; no cmd.exe or shell is involved.
+ */
+exports.WINDOWS_RELAY_LAUNCHER = `var shell = new ActiveXObject("WScript.Shell");
+var command = [];
+for (var index = 0; index < WScript.Arguments.length; index++) {
+  var argument = WScript.Arguments(index);
+  if (/["\\r\\n]/.test(argument)) throw new Error("Invalid relay startup argument");
+  command.push('"' + argument + '"');
+}
+WScript.Quit(shell.Run(command.join(" "), 0, true));
+`;
+function windowsLauncherPath() {
+    return path.join(configHome(), "relay-launcher.js");
+}
 /** `DOMAIN\user`, which is what a task's `UserId` wants. `USERDOMAIN` is absent
  * on a machine that was never joined to a domain; the bare username is correct
  * there, and inventing a domain would register a task for a principal that does
@@ -316,9 +365,19 @@ function autostartForPlatform(platform = process.platform) {
  * `process.argv[1]` is the script node was given; resolving it is what keeps an
  * npx-run or `npm link`ed CLI producing a unit that still works after the shell
  * that installed it is gone. */
-function relayCommand() {
-    return { node: process.execPath, entry: path.resolve(process.argv[1] ?? "") };
+function relayCommand(physicalPath = (value) => fs.realpathSync.native(value)) {
+    // Windows packaged apps virtualize AppData. A path visible inside Codex can
+    // be absent from Task Scheduler's filesystem view. Resolve the actual file
+    // before handing it to a process outside that package (observed on Windows).
+    return {
+        node: physicalPath(process.execPath),
+        entry: physicalPath(path.resolve(process.argv[1] ?? "")),
+    };
 }
 /** Exported for tests, which need to reach a platform other than the one they
  * run on. Production code goes through {@link autostartForPlatform}. */
-exports.AUTOSTART_IMPLEMENTATIONS = { systemd, launchd, scheduledTask };
+exports.AUTOSTART_IMPLEMENTATIONS = {
+    systemd,
+    launchd,
+    scheduledTask,
+};