@love-moon/conductor-cli 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @love-moon/conductor-cli
 
+## 0.4.0
+
+### Minor Changes
+
+- 4ecc359: Publish the chat-web browser runtime and wire it into the CLI and AI SDK for
+  ChatGPT and Gemini web sessions, including provider error handling and local
+  development installation support.
+
+  Ship app SDK realtime history catch-up and the CLI/AI SDK goal-mode and custom
+  command runtime updates included in this release.
+
+### Patch Changes
+
+- d83cb65: Fix pnpm-installed daemon PTY support by allowing the `node-pty` build script during pnpm CLI updates and by failing native dependency repair with a clear error when pnpm has already recorded `node-pty` under ignored builds.
+- Updated dependencies [4ecc359]
+  - @love-moon/ai-sdk@0.4.0
+  - @love-moon/conductor-sdk@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- 8e1d4a8: Prefer the bundled Copilot platform executable before the JS entrypoint so Node
+  20 installs do not fail with `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite`.
+- Updated dependencies [8e1d4a8]
+  - @love-moon/ai-sdk@0.3.2
+  - @love-moon/ai-manager@0.3.2
+  - @love-moon/conductor-sdk@0.3.2
+
 ## 0.3.1
 
 ### Patch Changes

package/bin/conductor-config.js

@@ -42,6 +42,14 @@ const DEFAULT_CLIs = {
     execArgs: "",
     description: "GitHub Copilot (built in via SDK)"
   },
+  "chat-web": {
+    command: "chat-web",
+    // Add `--model gemini` to use Google AI Studio's Gemini instead of
+    // the default ChatGPT. The CLI parses --model from this entry and
+    // forwards it to ai-sdk; it doesn't actually exec the command line.
+    execArgs: "",
+    description: "Chat web automation (ChatGPT / Gemini via @love-moon/chat-web)"
+  },
 };
 
 const backendUrl =
@@ -75,6 +83,13 @@ function isBuiltInCopilotAvailable() {
   );
 }
 
+function isBuiltInChatWebAvailable() {
+  return Boolean(
+    packageJson?.dependencies?.["@love-moon/chat-web"] ||
+    packageJson?.optionalDependencies?.["@love-moon/chat-web"],
+  );
+}
+
 function buildConfigEntryLines(cli, info, { commented = false } = {}) {
   const fullCommand = info.execArgs
     ? `${info.command} ${info.execArgs}`
@@ -86,6 +101,13 @@ function buildConfigEntryLines(cli, info, { commented = false } = {}) {
   if (cli === "opencode") {
     lines.push(`${commentPrefix}opencode runs via ai-sdk server mode with permission=allow`);
   }
+  if (cli === "chat-web") {
+    // chat-web defaults to its `chatgpt` sub-provider. The CLI extracts
+    // `--model` from this line and forwards it to ai-sdk; the command
+    // itself is never spawned (chat-web is an in-process SDK).
+    lines.push(`${commentPrefix}chat-web drives a real Chromium browser via @love-moon/chat-web`);
+    lines.push(`${commentPrefix}defaults to ChatGPT; use \`chat-web --model gemini\` for AI Studio (Gemini)`);
+  }
 
   lines.push(`${entryPrefix}${cli}: ${fullCommand}`);
   return lines;
@@ -294,6 +316,10 @@ function detectInstalledCLIs() {
       detected.push(key);
       continue;
     }
+    if (key === "chat-web" && isBuiltInChatWebAvailable()) {
+      detected.push(key);
+      continue;
+    }
     if (isCommandAvailable(info.command)) {
       detected.push(key);
     }

package/bin/conductor-fire.js

@@ -926,6 +926,19 @@ async function main() {
         const currentRefreshSessionRequest = pendingRefreshSessionRequest;
         let runnerError = null;
 
+        // Per-message /goal detection: sessions for goal-capable backends
+        // (claude, codex) must boot with `goalMode: true` so the underlying
+        // transport advertises `capabilities.goal === true`. Codex specifically
+        // needs `--enable goals` at boot — it cannot be flipped on later. At
+        // dispatch time, BridgeRunner.dispatchBackendTurn parses each user
+        // message for a leading `/goal` directive and routes to runGoal vs
+        // runTurn accordingly.
+        const backendForGoalCheck = String(
+          cliArgs.sessionBackend || cliArgs.backend || "",
+        )
+          .trim()
+          .toLowerCase();
+        const enableGoalsForBackend = GOAL_CAPABLE_BACKENDS.includes(backendForGoalCheck);
         backendSession = createAiSession(cliArgs.sessionBackend || cliArgs.backend, {
           initialImages: cliArgs.initialImages,
           cwd: runtimeProjectPath,
@@ -933,6 +946,7 @@ async function main() {
           configFile: cliArgs.configFile,
           ...(cliArgs.sessionOptions || {}),
           ...(sessionCommandLine ? { commandLine: sessionCommandLine } : {}),
+          ...(enableGoalsForBackend ? { goalMode: true } : {}),
           logger: { log },
           sessionStoreKey: taskContext.taskId ? `task-${taskContext.taskId}` : undefined,
           resumePersistedSession: Boolean(!nextResumeSessionId && taskContext.taskId),
@@ -1392,14 +1406,84 @@ function normalizeTaskId(value) {
   return value.trim();
 }
 
-function resolveFireStateDir(workingDirectory = process.cwd()) {
+function resolveFireStateDir(workingDirectory) {
+  // Priority:
+  //   1. CONDUCTOR_FIRE_STATE_DIR env override (used by tests to isolate the
+  //      marker dir into a tmpdir; also handy for ops to relocate state).
+  //   2. Explicit `workingDirectory` argument (legacy callers).
+  //   3. ~/.conductor/state — matches the conductor convention used by the
+  //      session bootstrap locks (see line ~311).
+  //
+  // We deliberately do NOT default to process.cwd(), which would pollute
+  // every project directory a user runs `conductor fire` from and cause tests
+  // to leak marker files into the repo.
+  const envOverride =
+    typeof process.env.CONDUCTOR_FIRE_STATE_DIR === "string" &&
+    process.env.CONDUCTOR_FIRE_STATE_DIR.trim()
+      ? process.env.CONDUCTOR_FIRE_STATE_DIR.trim()
+      : "";
+  if (envOverride) {
+    return path.resolve(envOverride);
+  }
   const baseDir =
     typeof workingDirectory === "string" && workingDirectory.trim()
       ? path.resolve(workingDirectory.trim())
-      : process.cwd();
+      : os.homedir();
   return path.join(baseDir, ".conductor", "state");
 }
 
+/**
+ * Backends that ship a native goal protocol via the ai-sdk. Sessions for
+ * these backends MUST boot with `goalMode: true` so the underlying transport
+ * advertises `capabilities.goal === true`. Per-message `/goal` detection then
+ * routes to runGoal vs runTurn at dispatch time.
+ *
+ * Codex specifically requires `--enable goals` at boot — it cannot be flipped
+ * on dynamically — so we always enable goals on session creation for these
+ * backends regardless of whether the first user message contains `/goal`.
+ *
+ * Sibling lists that must be kept in sync:
+ *   - `web/src/app/api/issues/goal.ts` → `GOAL_CAPABLE_BACKENDS` Set
+ *   - `modules/ai-sdk/src/providers/*.js` → `static capabilities.goal`
+ *
+ * If you add a new goal-capable backend, update ALL THREE locations and run
+ * `cd cli && pnpm test` + `cd web && pnpm test`.
+ */
+export const GOAL_CAPABLE_BACKENDS = ["claude", "codex"];
+
+/**
+ * Per-message `/goal` detector. Matches the semantics of
+ * `web/src/app/api/issues/goal.ts::parseGoalDirective`:
+ *
+ *   - First non-empty line is `/goal` (case-insensitive), optionally with
+ *     inline text after the keyword and a space.
+ *   - Objective = inline text + "\n\n" + remaining body, trimmed.
+ *   - Returns null if no directive or empty objective.
+ */
+export function parseGoalDirectiveFromMessage(content) {
+  if (typeof content !== "string") {
+    return null;
+  }
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === "") {
+    i += 1;
+  }
+  if (i >= lines.length) {
+    return null;
+  }
+  const firstLine = lines[i];
+  const match = firstLine.trim().match(/^\/goal(?:\s+(.*))?$/i);
+  if (!match) {
+    return null;
+  }
+  const inline = (match[1] || "").trim();
+  const rest = lines.slice(i + 1).join("\n").trim();
+  const parts = [inline, rest].filter(Boolean);
+  const objective = parts.join("\n\n").trim();
+  return objective ? { objective } : null;
+}
+
 export function injectResolvedTaskId(taskId, env = process.env) {
   const normalizedTaskId = normalizeTaskId(taskId);
   if (!normalizedTaskId) {
@@ -1882,6 +1966,7 @@ export class BridgeRunner {
     this.pendingInterruptRetryTimers = new Map();
     this.activeTurnReplyTo = "";
     this.sessionAnnouncementSent = false;
+    this.sessionAnnouncementSubscribed = false;
     this.boundSessionId = "";
     this.errorLoop = null;
     this.errorLoopWindowMs = getBoundedEnvInt(
@@ -1927,6 +2012,30 @@ export class BridgeRunner {
     log(`[copilot-debug] task=${this.taskId} ${message}`);
   }
 
+  /**
+   * Listen for follow-up `session` events from the backend so that a
+   * provider with a deferred session id (currently only chat-web) can
+   * tell us "the real conversation id is ready, please announce now".
+   *
+   * Idempotent — repeated calls only register the listener once.
+   * Single-use semantics on the daemon side: after the first announce
+   * succeeds (sessionAnnouncementSent flips true), subsequent session
+   * events are ignored by `announceBackendSession()`.
+   */
+  subscribeToBackendSessionUpdates() {
+    if (this.sessionAnnouncementSubscribed) return;
+    if (!this.backendSession || typeof this.backendSession.on !== "function") return;
+    this.sessionAnnouncementSubscribed = true;
+    this.backendSession.on("session", () => {
+      if (this.sessionAnnouncementSent) return;
+      void this.announceBackendSession().catch((error) => {
+        this.copilotLog(
+          `session re-announce failed: ${sanitizeForLog(error?.message || error, 160)}`,
+        );
+      });
+    });
+  }
+
   async announceBackendSession() {
     if (this.sessionAnnouncementSent) {
       return;
@@ -1941,6 +2050,17 @@ export class BridgeRunner {
       this.copilotLog(`session announce skipped: ${sanitizeForLog(error?.message || error, 160)}`);
       return;
     }
+    // chat-web's session id is the provider-side conversation id
+    // (e.g. ChatGPT /c/{uuid}), which only materialises AFTER the first
+    // turn. The backend exposes `sessionIdDeferred: true` to ask us to
+    // hold the "session started" message until the real id lands.
+    // `subscribeToBackendSessionUpdates()` arms a one-shot listener that
+    // re-runs this announce once the real id is emitted.
+    if (sessionInfo && sessionInfo.sessionIdDeferred === true) {
+      this.subscribeToBackendSessionUpdates();
+      this.copilotLog("session announce deferred: backend reports sessionIdDeferred=true");
+      return;
+    }
     const discoveredSessionId = String(sessionInfo?.sessionId || "").trim();
     const fallbackSessionId = this.resumeSessionId;
     const sessionId = discoveredSessionId || fallbackSessionId;
@@ -2618,8 +2738,10 @@ export class BridgeRunner {
     const statusLine = payload.status_line ? String(payload.status_line) : "";
     const statusDoneLine = payload.status_done_line ? String(payload.status_done_line) : "";
     const replyPreview = payload.reply_preview ? String(payload.reply_preview) : "";
+    const aiModeRaw = typeof payload.aiMode === "string" ? payload.aiMode.trim().toLowerCase() : "";
+    const aiMode = aiModeRaw === "goal" || aiModeRaw === "turn" ? aiModeRaw : "";
 
-    if (!state && !phase && !statusLine && !statusDoneLine && !replyPreview) {
+    if (!state && !phase && !statusLine && !statusDoneLine && !replyPreview && !aiMode) {
       return null;
     }
 
@@ -2633,6 +2755,7 @@ export class BridgeRunner {
       reply_preview: truncateText(replyPreview, 240) || undefined,
       reply_to: replyTo,
       backend: this.backendName,
+      aiMode: aiMode || undefined,
       thread_id:
         String(
           payload.thread_id || payload.session_id || runtimeContext?.session_id || "",
@@ -2948,7 +3071,7 @@ export class BridgeRunner {
         );
       }
 
-      const turnPromise = this.backendSession.runTurn(content, {
+      const turnPromise = this.dispatchBackendTurn(content, {
         useInitialImages,
         onProgress: (payload) => {
           void this.reportRuntimeStatus(payload, replyTo);
@@ -3105,6 +3228,76 @@ export class BridgeRunner {
     });
   }
 
+  /**
+   * Emit a runtime-status update carrying the per-turn aiMode so the frontend
+   * can show "goal" vs "normal" in real time. Best-effort: failure to emit must
+   * not block the actual dispatch.
+   */
+  async emitAiModeStatus(mode) {
+    const normalized = mode === "goal" ? "goal" : "turn";
+    try {
+      await this.reportRuntimeStatus({ aiMode: normalized });
+    } catch (error) {
+      log(`[ai-mode] failed to emit aiMode=${normalized}: ${error?.message || error}`);
+    }
+  }
+
+  /**
+   * Execute the next turn against the backend session. Each user message is
+   * inspected for a leading `/goal` directive (see
+   * `parseGoalDirectiveFromMessage`). When present AND the underlying session
+   * advertises `capabilities.goal === true`, we route through
+   * `session.runGoal()`; otherwise we fall back to `session.runTurn()` so a
+   * `/goal` typed at a non-goal-capable backend degrades gracefully into a
+   * normal message.
+   *
+   * Returns the same `{ text, items, usage, metadata, ... }` shape as runTurn
+   * so callers can keep their existing event-stream / persistence logic.
+   */
+  async dispatchBackendTurn(content, options = {}) {
+    const goalDirective = parseGoalDirectiveFromMessage(content);
+    const snapshot =
+      typeof this.backendSession?.getSnapshot === "function"
+        ? this.backendSession.getSnapshot()
+        : null;
+    const goalCapable = Boolean(
+      snapshot && snapshot.capabilities && snapshot.capabilities.goal === true,
+    );
+    const willRunGoal =
+      goalDirective != null &&
+      goalCapable &&
+      typeof this.backendSession?.runGoal === "function";
+
+    // Best-effort runtime-status emit. Failure must NOT block the dispatch.
+    try {
+      await this.emitAiModeStatus(willRunGoal ? "goal" : "turn");
+    } catch {
+      // best-effort
+    }
+
+    if (willRunGoal) {
+      const goalResult = await this.backendSession.runGoal(
+        { objective: goalDirective.objective, source: { type: "manual" } },
+        options,
+      );
+      // Goal SDK is expected to return `{ text, goal, usage, metadata }`. We
+      // normalize back into the runTurn-compatible shape downstream consumers
+      // expect (text, items, usage, metadata, provider, events).
+      return {
+        text: goalResult?.text || "",
+        items: Array.isArray(goalResult?.items) ? goalResult.items : [],
+        usage: goalResult?.usage || null,
+        provider: goalResult?.provider || this.backendName,
+        events: Array.isArray(goalResult?.events) ? goalResult.events : [],
+        metadata: {
+          ...(goalResult?.metadata || {}),
+          ...(goalResult?.goal ? { goal: goalResult.goal } : {}),
+        },
+      };
+    }
+    return this.backendSession.runTurn(content, options);
+  }
+
   async handlePrePromptMessage(content) {
     const text = typeof content === "string" ? content.trim() : "";
     if (!text) {
@@ -3169,7 +3362,7 @@ export class BridgeRunner {
       }
     }
     try {
-      const result = await this.backendSession.runTurn(content, {
+      const result = await this.dispatchBackendTurn(content, {
         useInitialImages: Boolean(includeImages),
         onProgress: (payload) => {
           void this.reportRuntimeStatus(payload, replyTarget);

package/bin/conductor-update.js

@@ -19,6 +19,7 @@ import {
   detectPackageManager,
 } from "../src/version-check.js";
 import {
+  buildPnpmAllowBuildArgs,
   ensurePnpmOnlyBuiltDependencies,
   repairAndVerifyGlobalNodePty,
 } from "../src/native-deps.js";
@@ -177,7 +178,7 @@ async function performUpdate() {
   switch (packageManager) {
     case "pnpm":
       cmd = "pnpm";
-      args = ["add", "-g", `${PACKAGE_NAME}@latest`];
+      args = ["add", "-g", ...buildPnpmAllowBuildArgs(["node-pty"]), `${PACKAGE_NAME}@latest`];
       break;
     case "yarn":
       cmd = "yarn";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.3.1",
-  "gitCommitId": "03b4582",
+  "version": "0.4.0",
+  "gitCommitId": "2d1526c",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -23,9 +23,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-manager": "0.3.1",
-    "@love-moon/ai-sdk": "0.3.1",
-    "@love-moon/conductor-sdk": "0.3.1",
+    "@love-moon/ai-sdk": "0.4.0",
+    "@love-moon/conductor-sdk": "0.4.0",
     "@github/copilot-sdk": "^0.2.2",
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0",
@@ -37,17 +36,19 @@
     "yargs": "^17.7.2"
   },
   "optionalDependencies": {
-    "@roamhq/wrtc": "^0.10.0"
+    "@roamhq/wrtc": "^0.10.0",
+    "@love-moon/chat-web": "0.4.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
       "node-pty",
-      "@roamhq/wrtc"
+      "@roamhq/wrtc",
+      "playwright"
     ],
     "overrides": {
       "@love-moon/ai-sdk": "file:../modules/ai-sdk",
-      "@love-moon/ai-manager": "file:../modules/ai-manager",
-      "@love-moon/conductor-sdk": "file:../modules/conductor-sdk"
+      "@love-moon/conductor-sdk": "file:../modules/conductor-sdk",
+      "@love-moon/chat-web": "file:../modules/chat-web"
     }
   }
 }

package/src/ai-manager-handlers.js

@@ -1,14 +1,15 @@
-// Daemon-side glue between the realtime WebSocket and the @love-moon/ai-manager module.
+// Daemon-side glue between the realtime WebSocket and the @love-moon/ai-sdk manager facade.
 // The web backend sends `ai_manager_request`; we dispatch by `action`, run it, and
 // reply with `ai_manager_response` carrying the same `request_id`.
 
-import { AiManager } from "@love-moon/ai-manager";
+import { AiManager } from "@love-moon/ai-sdk";
 
 const VALID_ACTIONS = new Set(["status", "quota", "list_accounts", "switch_account"]);
+const BASE_QUOTA_TOOLS = ["codex", "claude", "kimi", "copilot"];
 
 /**
  * @param {object} opts
- * @param {string} [opts.configPath] Path to ~/.conductor/config.yaml. Defaults to ai-manager's default.
+ * @param {string} [opts.configPath] Path to ~/.conductor/config.yaml. Defaults to the manager facade default.
  */
 export function createAiManagerHandlers(opts = {}) {
   const manager = new AiManager(opts.configPath ? { configPath: opts.configPath } : undefined);
@@ -69,10 +70,30 @@ export function createAiManagerHandlers(opts = {}) {
     addJob("copilot", () => manager.getCopilotQuota({
       forceRefresh,
     }));
+    const externalBackends = pickExternalQuotaBackends(args);
+    for (const backend of externalBackends) {
+      if (!tools.has(backend)) {
+        continue;
+      }
+      jobs.push((async () => {
+        try {
+          const result = await manager.getExternalQuotaList({ backend, forceRefresh });
+          return ["external", backend, result];
+        } catch (err) {
+          return ["external", backend, { backend, error: errMsg(err), source: "unknown" }];
+        }
+      })());
+    }
 
     const entries = await Promise.all(jobs);
-    for (const [tool, result] of entries) {
-      out[tool] = result;
+    for (const entry of entries) {
+      const [kind, key, result] = entry;
+      if (kind === "external") {
+        out.external = out.external || {};
+        out.external[key] = result;
+      } else {
+        out[kind] = key;
+      }
     }
     return out;
   }
@@ -169,8 +190,24 @@ export async function handleAiManagerRequest(client, handlers, payload) {
 
 function pickToolFilter(args = {}) {
   const tool = typeof args.tool === "string" ? args.tool.trim().toLowerCase() : "";
-  if (tool && ["codex", "claude", "kimi", "copilot"].includes(tool)) return new Set([tool]);
-  return new Set(["codex", "claude", "kimi", "copilot"]);
+  if (tool) return new Set([tool]);
+  return new Set([...BASE_QUOTA_TOOLS, ...pickExternalQuotaBackends(args)]);
+}
+
+function pickExternalQuotaBackends(args = {}) {
+  const fromArray = Array.isArray(args.externalQuotaBackends) ? args.externalQuotaBackends : [];
+  const fromString = typeof args.externalQuotaBackends === "string"
+    ? args.externalQuotaBackends.split(",")
+    : [];
+  const backends = [...fromArray, ...fromString]
+    .map((item) => String(item || "").trim().toLowerCase())
+    .filter(Boolean)
+    .filter((backend) => !BASE_QUOTA_TOOLS.includes(backend));
+  const tool = typeof args.tool === "string" ? args.tool.trim().toLowerCase() : "";
+  if (tool && !BASE_QUOTA_TOOLS.includes(tool)) {
+    backends.push(tool);
+  }
+  return [...new Set(backends)];
 }
 
 function errMsg(err) {

package/src/custom-command-handlers.js

@@ -0,0 +1,338 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+import yaml from "js-yaml";
+
+const VALID_ACTIONS = new Set(["list", "run", "status"]);
+const MAX_TAIL_CHARS = 12_000;
+const MAX_RUNS = 200;
+export const CUSTOM_COMMANDS_CAPABILITY = "custom_commands";
+
+/**
+ * @typedef {{
+ *   key: string;
+ *   scriptPath: string;
+ * }} CustomCommand
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.configPath]
+ * @param {typeof spawn} [opts.spawnFn]
+ */
+export function createCustomCommandHandlers(opts = {}) {
+  const configPath = opts.configPath || path.join(os.homedir(), ".conductor", "config.yaml");
+  const spawnFn = opts.spawnFn || spawn;
+  const runs = new Map();
+  const runningByKey = new Map();
+
+  async function list() {
+    const commands = await loadCustomCommands(configPath);
+    return {
+      commands: commands.map((command) => {
+        const runId = runningByKey.get(command.key) || null;
+        return {
+          key: command.key,
+          running: Boolean(runId),
+          ...(runId ? { runId } : {}),
+        };
+      }),
+    };
+  }
+
+  async function run(args = {}) {
+    const key = normalizeCommandKey(args.key);
+    if (!key) {
+      throw new Error("run requires a `key` string");
+    }
+    const existingRunId = runningByKey.get(key);
+    if (existingRunId) {
+      const existing = runs.get(existingRunId);
+      throw new Error(`custom command ${key} is already running as ${existing?.runId || existingRunId}`);
+    }
+
+    const commands = await loadCustomCommands(configPath);
+    const command = commands.find((entry) => entry.key === key);
+    if (!command) {
+      throw new Error(`custom command not found: ${key}`);
+    }
+    await validateScript(command.scriptPath);
+
+    const runId = randomUUID();
+    const startedAt = new Date().toISOString();
+    const runState = {
+      runId,
+      key,
+      status: "running",
+      pid: null,
+      exitCode: null,
+      signal: null,
+      stdoutTail: "",
+      stderrTail: "",
+      error: null,
+      startedAt,
+      finishedAt: null,
+    };
+    rememberRun(runs, runState);
+    runningByKey.set(key, runId);
+
+    const child = spawnFn(command.scriptPath, [], {
+      cwd: path.dirname(command.scriptPath),
+      env: buildScriptEnv(configPath, key),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    runState.pid = typeof child.pid === "number" ? child.pid : null;
+
+    child.stdout?.on("data", (chunk) => {
+      runState.stdoutTail = appendTail(runState.stdoutTail, chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      runState.stderrTail = appendTail(runState.stderrTail, chunk);
+    });
+    child.on("error", (error) => {
+      finishRun(runState, runningByKey, "failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+    child.on("close", (code, signal) => {
+      finishRun(runState, runningByKey, code === 0 ? "completed" : "failed", {
+        exitCode: typeof code === "number" ? code : null,
+        signal: signal || null,
+      });
+    });
+
+    return toPublicRun(runState, { includeOutput: false, started: true });
+  }
+
+  async function status(args = {}) {
+    const runId = typeof args.runId === "string" ? args.runId.trim() : "";
+    if (!runId) {
+      throw new Error("status requires a `runId` string");
+    }
+    const runState = runs.get(runId);
+    if (!runState) {
+      throw new Error(`custom command run not found: ${runId}`);
+    }
+    return toPublicRun(runState, { includeOutput: true });
+  }
+
+  /**
+   * Run a single action and return a `result` object, never throwing.
+   * @param {{action:string,args?:object}} payload
+   */
+  async function dispatch(payload) {
+    const action = payload?.action;
+    if (!VALID_ACTIONS.has(action)) {
+      return { error: `unknown action: ${action}` };
+    }
+    try {
+      switch (action) {
+        case "list":
+          return { result: await list() };
+        case "run":
+          return { result: await run(payload?.args ?? {}) };
+        case "status":
+          return { result: await status(payload?.args ?? {}) };
+        default:
+          return { error: `unhandled action: ${action}` };
+      }
+    } catch (err) {
+      return { error: errMsg(err) };
+    }
+  }
+
+  return { dispatch, configPath, runs, runningByKey };
+}
+
+/**
+ * @param {object} client
+ * @param {ReturnType<typeof createCustomCommandHandlers>} handlers
+ * @param {object} payload
+ */
+export async function handleCustomCommandsRequest(client, handlers, payload) {
+  const requestId = payload?.request_id ? String(payload.request_id) : "";
+  const action = payload?.action ? String(payload.action) : "";
+  if (!requestId) {
+    return { error: "missing request_id" };
+  }
+
+  const response = await handlers.dispatch({
+    action,
+    args: payload?.args && typeof payload.args === "object" ? payload.args : {},
+  });
+
+  const outgoing = {
+    type: "custom_commands_response",
+    payload: {
+      request_id: requestId,
+      action,
+      ...(response?.error ? { error: response.error } : { result: response?.result }),
+    },
+  };
+  await client.sendJson(outgoing).catch(() => {});
+  return response;
+}
+
+/**
+ * @param {string} configPath
+ * @returns {Promise<CustomCommand[]>}
+ */
+export async function loadCustomCommands(configPath) {
+  let raw = "";
+  try {
+    raw = await fsp.readFile(configPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const parsed = yaml.load(raw);
+  return parseCustomCommandsConfig(parsed, configPath);
+}
+
+/**
+ * @param {unknown} config
+ * @param {string} configPath
+ * @returns {CustomCommand[]}
+ */
+export function parseCustomCommandsConfig(config, configPath = path.join(os.homedir(), ".conductor", "config.yaml")) {
+  const root = config && typeof config === "object" ? config : {};
+  const rawCommands = root.custom_commands;
+  if (rawCommands === undefined || rawCommands === null) {
+    return [];
+  }
+  if (Array.isArray(rawCommands) || typeof rawCommands !== "object") {
+    throw new Error("custom_commands must be a mapping from key to script path");
+  }
+
+  const commands = [];
+  const seen = new Set();
+  for (const [rawKey, rawValue] of Object.entries(rawCommands)) {
+    const key = normalizeCommandKey(rawKey);
+    if (!key) {
+      throw new Error("custom_commands contains an invalid empty key");
+    }
+    if (seen.has(key)) {
+      throw new Error(`duplicate custom command key: ${key}`);
+    }
+    seen.add(key);
+    if (typeof rawValue !== "string" || !rawValue.trim()) {
+      throw new Error(`custom command ${key} must point to a script path string`);
+    }
+    commands.push({
+      key,
+      scriptPath: resolveScriptPath(rawValue, configPath),
+    });
+  }
+  return commands;
+}
+
+export function normalizeCommandKey(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const key = value.trim();
+  if (!key || key.length > 80 || /[\x00-\x1F\x7F/\\]/.test(key)) {
+    return "";
+  }
+  return key;
+}
+
+function resolveScriptPath(value, configPath) {
+  const raw = value.trim();
+  const expanded = raw === "~" || raw.startsWith("~/")
+    ? path.join(os.homedir(), raw.slice(2))
+    : raw;
+  if (path.isAbsolute(expanded)) {
+    return path.normalize(expanded);
+  }
+  return path.resolve(path.dirname(configPath), expanded);
+}
+
+async function validateScript(scriptPath) {
+  let stat;
+  try {
+    stat = await fsp.stat(scriptPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`custom command script not found: ${scriptPath}`);
+    }
+    throw error;
+  }
+  if (!stat.isFile()) {
+    throw new Error(`custom command script is not a file: ${scriptPath}`);
+  }
+  try {
+    await fsp.access(scriptPath, fs.constants.X_OK);
+  } catch {
+    throw new Error(`custom command script is not executable: ${scriptPath}`);
+  }
+}
+
+function rememberRun(runs, runState) {
+  runs.set(runState.runId, runState);
+  while (runs.size > MAX_RUNS) {
+    const oldest = [...runs.values()].find((entry) => entry.status !== "running")?.runId;
+    if (!oldest) break;
+    runs.delete(oldest);
+  }
+}
+
+function finishRun(runState, runningByKey, status, updates = {}) {
+  if (runState.status !== "running") {
+    return;
+  }
+  runState.status = status;
+  runState.finishedAt = new Date().toISOString();
+  runState.exitCode = updates.exitCode ?? runState.exitCode;
+  runState.signal = updates.signal ?? runState.signal;
+  runState.error = updates.error ?? runState.error;
+  runningByKey.delete(runState.key);
+}
+
+function appendTail(current, chunk) {
+  const next = current + String(chunk);
+  return next.length > MAX_TAIL_CHARS ? next.slice(next.length - MAX_TAIL_CHARS) : next;
+}
+
+function buildScriptEnv(configPath, key) {
+  const env = { ...process.env };
+  for (const name of Object.keys(env)) {
+    if (name.startsWith("CONDUCTOR_")) {
+      delete env[name];
+    }
+  }
+  env.CONDUCTOR_CONFIG_FILE = configPath;
+  env.CONDUCTOR_CUSTOM_COMMAND_KEY = key;
+  return env;
+}
+
+function toPublicRun(runState, { includeOutput, started = false } = {}) {
+  return {
+    ...(started ? { started: true } : {}),
+    runId: runState.runId,
+    key: runState.key,
+    status: runState.status,
+    pid: runState.pid,
+    exitCode: runState.exitCode,
+    signal: runState.signal,
+    error: runState.error,
+    startedAt: runState.startedAt,
+    finishedAt: runState.finishedAt,
+    ...(includeOutput ? {
+      stdoutTail: runState.stdoutTail,
+      stderrTail: runState.stderrTail,
+    } : {}),
+  };
+}
+
+function errMsg(err) {
+  return err?.message ?? String(err);
+}

package/src/daemon.js

@@ -17,6 +17,11 @@ import {
 } from "@love-moon/conductor-sdk";
 import { DaemonLogCollector } from "./log-collector.js";
 import { createAiManagerHandlers, handleAiManagerRequest } from "./ai-manager-handlers.js";
+import {
+  CUSTOM_COMMANDS_CAPABILITY,
+  createCustomCommandHandlers,
+  handleCustomCommandsRequest,
+} from "./custom-command-handlers.js";
 import { resolveResumeContext } from "./fire/resume.js";
 import {
   filterRuntimeSupportedAllowCliList,
@@ -39,6 +44,7 @@ import {
   resolveInstallMethod,
 } from "./version-check.js";
 import {
+  buildPnpmAllowBuildArgs,
   ensurePnpmOnlyBuiltDependencies,
   repairAndVerifyGlobalNodePty,
 } from "./native-deps.js";
@@ -482,6 +488,39 @@ function normalizeLaunchConfig(value) {
   return value;
 }
 
+/**
+ * Build the argv passed to the `conductor-fire` child process. Centralized so
+ * both production daemon code and tests can exercise the same logic.
+ *
+ * Per-message `/goal` detection lives inside fire itself
+ * (`parseGoalDirectiveFromMessage`), so the daemon never appends a `--goal`
+ * flag. When `launch_config.goal.objective` is present we still prefer it over
+ * the bare `initialContent` for backward-compat with older envelopes; the new
+ * web envelope already prefixes the objective with `/goal\n` so fire's
+ * per-message detector kicks in on the first turn.
+ */
+export function buildFireSpawnArgs({ selectedBackend, initialContent, launchConfig } = {}) {
+  const args = [];
+  if (selectedBackend) {
+    args.push("--backend", String(selectedBackend));
+  }
+  const goalObjective =
+    launchConfig &&
+    typeof launchConfig === "object" &&
+    launchConfig.goal &&
+    typeof launchConfig.goal === "object" &&
+    typeof launchConfig.goal.objective === "string"
+      ? launchConfig.goal.objective.trim()
+      : "";
+  const prefill = typeof initialContent === "string" ? initialContent : "";
+  const effectivePrefill = prefill || goalObjective;
+  if (effectivePrefill) {
+    args.push("--prefill", effectivePrefill);
+  }
+  args.push("--");
+  return args;
+}
+
 function normalizeBooleanFlag(value) {
   if (typeof value === "boolean") {
     return value;
@@ -1965,7 +2004,12 @@ export function startDaemon(config = {}, deps = {}) {
     "x-conductor-backends": SUPPORTED_BACKENDS.join(","),
     "x-conductor-version": cliVersion,
   };
-  const advertisedCapabilities = ["project_path_validation", "restart_daemon", "refresh_session_inplace"];
+  const advertisedCapabilities = [
+    "project_path_validation",
+    "restart_daemon",
+    "refresh_session_inplace",
+    CUSTOM_COMMANDS_CAPABILITY,
+  ];
   if (ptyTaskCapabilityEnabled) {
     advertisedCapabilities.push("pty_task", "terminal_snapshot");
   }
@@ -1973,6 +2017,7 @@ export function startDaemon(config = {}, deps = {}) {
     extraHeaders["x-conductor-capabilities"] = advertisedCapabilities.join(",");
   }
   const aiManagerHandlers = createAiManagerHandlers({ configPath: config.CONFIG_FILE });
+  const customCommandHandlers = createCustomCommandHandlers({ configPath: config.CONFIG_FILE });
 
   const client = createWebSocketClient(sdkConfig, {
     extraHeaders,
@@ -1992,6 +2037,13 @@ export function startDaemon(config = {}, deps = {}) {
       sendAgentResume(isReconnect).catch((error) => {
         logError(`sendAgentResume failed: ${error?.message || error}`);
       });
+      // RFC 0029: regardless of first connect / reconnect, immediately
+      // declare which tasks this daemon believes are still alive so the
+      // backend can revoke any `daemon_disconnected` killed-flags it set
+      // while the ws was silent. We deliberately fire-and-forget — a stale
+      // backend that doesn't understand the event just ignores it, and the
+      // existing reconcile loop catches anything this push misses.
+      void pushAgentAliveTasks(isReconnect ? "agent_reconnect" : "agent_first_connect");
       if (!didRecoverStaleTasks) {
         didRecoverStaleTasks = true;
         recoverStaleTasks().catch((error) => {
@@ -2342,7 +2394,7 @@ export function startDaemon(config = {}, deps = {}) {
       switch (pm) {
         case "pnpm":
           cmd = "pnpm";
-          args = ["add", "-g", pkgSpec];
+          args = ["add", "-g", ...buildPnpmAllowBuildArgs(["node-pty"]), pkgSpec];
           break;
         case "yarn":
           cmd = "yarn";
@@ -2798,6 +2850,34 @@ export function startDaemon(config = {}, deps = {}) {
     }
   }
 
+  // RFC 0029: after every (re)connect push an agent_alive_tasks snapshot so
+  // the backend can pre-emptively revoke `killed_reason=daemon_disconnected`
+  // for tasks whose fire processes never actually died (e.g. host sleep, ws
+  // half-close). Fires raise their own ws to backend independently — this is
+  // the daemon's *own* belief about which tasks it is hosting. The backend
+  // arbitrates between this push and the persisted task state.
+  function pushAgentAliveTasks(reason) {
+    const aliveTaskIds = getActiveTaskIds();
+    if (aliveTaskIds.length === 0) {
+      return Promise.resolve();
+    }
+    return client
+      .sendJson({
+        type: "agent_alive_tasks",
+        payload: {
+          agent_host: AGENT_NAME || os.hostname(),
+          alive_task_ids: aliveTaskIds,
+          reason: typeof reason === "string" && reason ? reason : "agent_reconnect",
+          reported_at: new Date().toISOString(),
+        },
+      })
+      .catch((err) => {
+        logError(
+          `Failed to push agent_alive_tasks (${aliveTaskIds.length} task(s)): ${err?.message || err}`,
+        );
+      });
+  }
+
   async function sendAgentResume(isReconnect = false) {
     await client.sendJson({
       type: "agent_resume",
@@ -4053,6 +4133,21 @@ export function startDaemon(config = {}, deps = {}) {
         });
         return;
       }
+      if (event.type === "reclaim_task") {
+        // Reject the reclaim during shutdown so the backend immediately
+        // falls back to spawn restart instead of waiting out the 60s ack
+        // timeout. We never touch the task state — backend owns the next
+        // step.
+        const requestId = event?.payload?.request_id ? String(event.payload.request_id) : "";
+        const taskId = event?.payload?.task_id ? String(event.payload.task_id) : "";
+        sendAgentCommandAck({
+          requestId,
+          taskId,
+          eventType: "reclaim_task",
+          accepted: false,
+        }).catch(() => {});
+        return;
+      }
       if (event.type === "create_pty_task") {
         rejectCreatePtyTaskDuringShutdown(event.payload);
         return;
@@ -4086,6 +4181,14 @@ export function startDaemon(config = {}, deps = {}) {
       void handleRestartTask(event.payload);
       return;
     }
+    if (event.type === "reclaim_task") {
+      // RFC 0029: backend asks us to confirm an "assumed killed" fire is
+      // actually still alive so it can avoid spawning a new one.
+      void handleReclaimTask(event.payload).catch((error) => {
+        logError(`Unhandled reclaim_task failure: ${error?.message || error}`);
+      });
+      return;
+    }
     if (event.type === "create_pty_task") {
       void handleCreatePtyTask(event.payload);
       return;
@@ -4130,6 +4233,11 @@ export function startDaemon(config = {}, deps = {}) {
         logError(`Unhandled ai_manager_request failure: ${error?.message || error}`);
       });
     }
+    if (event.type === "custom_commands_request") {
+      handleCustomCommandsRequest(client, customCommandHandlers, event.payload).catch((error) => {
+        logError(`Unhandled custom_commands_request failure: ${error?.message || error}`);
+      });
+    }
     if (event.type === "restart_daemon") {
       void handleRestartDaemon(event.payload).catch((error) => {
         logError(`Unhandled restart_daemon failure: ${error?.message || error}`);
@@ -4221,6 +4329,7 @@ export function startDaemon(config = {}, deps = {}) {
       repoRoot: null,
       worktreeBranch: null,
       lastCommit: null,
+      lastCommitAt: null,
       fileCount: null,
       error: null,
       errorCode: null,
@@ -4263,6 +4372,10 @@ export function startDaemon(config = {}, deps = {}) {
             typeof snapshot?.lastCommit === "string" && snapshot.lastCommit.trim()
               ? snapshot.lastCommit.trim()
               : null,
+          lastCommitAt:
+            typeof snapshot?.lastCommitAt === "string" && snapshot.lastCommitAt.trim()
+              ? snapshot.lastCommitAt.trim()
+              : null,
           gitRemoteUrl:
             typeof snapshot?.gitRemoteUrl === "string" && snapshot.gitRemoteUrl.trim()
               ? snapshot.gitRemoteUrl.trim()
@@ -4291,6 +4404,7 @@ export function startDaemon(config = {}, deps = {}) {
           repo_root: result.repoRoot,
           worktree_branch: result.worktreeBranch,
           last_commit: result.lastCommit,
+          last_commit_at: result.lastCommitAt,
           git_remote_url: result.gitRemoteUrl,
           file_count: result.fileCount,
           error: result.error,
@@ -4443,6 +4557,110 @@ export function startDaemon(config = {}, deps = {}) {
     return Boolean(record?.forceDaemonTerminalStatusReport) || !Boolean(record?.managedByFireBridge);
   }
 
+  // RFC 0029: confirm that a task the backend believes is dead is actually
+  // still hosting a live fire on this daemon. The check is intentionally
+  // conservative:
+  //   * activeTaskProcesses must hold an entry for the task — that's the
+  //     daemon's own bookkeeping of fires it spawned and hasn't reaped;
+  //   * for tmux-mode fires (the common case) we re-probe `tmux has-session`
+  //     so we don't accept stale entries left over from a previously crashed
+  //     reaper. The activeTaskProcesses entry is updated on the spot if the
+  //     session has gone away;
+  //   * for non-tmux fires (rare; only used in dev) we accept as long as the
+  //     child process record still exists. The exit handler removes the
+  //     entry on real exit, so a present entry implies a live pid.
+  //
+  // We do NOT validate `expected_session_id` or `expected_backend_type`
+  // against the in-tmux fire — the daemon has no IPC into a detached fire
+  // process, so that comparison can only happen on the backend or via fire's
+  // own ws back to the backend (the agent_alive_tasks push in this RFC).
+  // What we *do* check is that they were sent (purely defensive — old web
+  // clients won't include them, and that's fine).
+  async function handleReclaimTask(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const requestId = payload?.request_id ? String(payload.request_id) : "";
+    const expectedSessionId = payload?.expected_session_id
+      ? String(payload.expected_session_id)
+      : "";
+    const expectedBackendType = payload?.expected_backend_type
+      ? String(payload.expected_backend_type)
+      : "";
+
+    if (!taskId) {
+      logError(`Invalid reclaim_task payload: ${JSON.stringify(payload)}`);
+      if (requestId) {
+        sendAgentCommandAck({
+          requestId,
+          taskId,
+          eventType: "reclaim_task",
+          accepted: false,
+        }).catch(() => {});
+      }
+      return;
+    }
+
+    if (requestId && !markRequestSeen(requestId)) {
+      log(
+        `Duplicate reclaim_task ignored for ${taskId} (request_id=${requestId})`,
+      );
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "reclaim_task",
+        accepted: completedCommandRequestAckResults.get(requestId) ?? false,
+      }).catch(() => {});
+      return;
+    }
+
+    const finalize = (accepted, summary) => {
+      if (requestId) {
+        rememberCommandRequestAckResult(requestId, accepted);
+      }
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "reclaim_task",
+        accepted,
+      }).catch((err) => {
+        logError(
+          `Failed to report agent_command_ack(reclaim_task) for ${taskId}: ${err?.message || err}`,
+        );
+      });
+      log(
+        `reclaim_task ${taskId} -> ${accepted ? "alive" : "stale"}${
+          summary ? ` (${summary})` : ""
+        }${expectedSessionId ? ` expected_session=${expectedSessionId}` : ""}${
+          expectedBackendType ? ` expected_backend=${expectedBackendType}` : ""
+        }`,
+      );
+    };
+
+    let entry = activeTaskProcesses.get(taskId);
+    if (entry?.tmuxMode && entry.tmuxSession) {
+      const alive = await tmuxSessionExists(entry.tmuxSession);
+      if (!alive) {
+        if (activeTaskProcesses.get(taskId) === entry) {
+          if (entry.stopForceKillTimer) {
+            clearTimeout(entry.stopForceKillTimer);
+            entry.stopForceKillTimer = null;
+          }
+          activeTaskProcesses.delete(taskId);
+        }
+        entry = undefined;
+      }
+    } else if (entry?.child && entry.child.exitCode !== null) {
+      // Non-tmux fire has already exited; treat as stale.
+      entry = undefined;
+    }
+
+    if (!entry) {
+      finalize(false, "no live fire");
+      return;
+    }
+
+    finalize(true, entry.tmuxMode ? `tmux=${entry.tmuxSession}` : `pid=${entry.child?.pid ?? "unknown"}`);
+  }
+
   function handleStopTask(payload) {
     const taskId = payload?.task_id;
     if (!taskId) return;
@@ -4914,14 +5132,11 @@ export function startDaemon(config = {}, deps = {}) {
         logPath = path.join(taskDir, "conductor.log");
       }
 
-      const args = [];
-      if (selectedBackend) {
-        args.push("--backend", selectedBackend);
-      }
-      if (initialContent) {
-        args.push("--prefill", initialContent);
-      }
-      args.push("--");
+      const args = buildFireSpawnArgs({
+        selectedBackend,
+        initialContent,
+        launchConfig,
+      });
 
       const env = {
         ...process.env,

package/src/native-deps.js

@@ -87,6 +87,44 @@ export function mergeBuiltDependencies(existing, required) {
   return [...merged];
 }
 
+export function parsePnpmIgnoredBuildsOutput(value) {
+  const ignored = [];
+  for (const rawLine of String(value || "").split(/\r?\n/)) {
+    const line = rawLine
+      .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "")
+      .trim();
+    if (!line || line.toLowerCase().includes("none")) {
+      continue;
+    }
+    const match = line.match(/^(?:[-*]\s*)?(@?[^@\s][^\s@]*)(?:@[\w.-]+)?$/);
+    if (!match) {
+      continue;
+    }
+    const name = match[1].trim();
+    if (name && !ignored.includes(name)) {
+      ignored.push(name);
+    }
+  }
+  return ignored;
+}
+
+export async function detectPnpmIgnoredBuilds({
+  runCommand = defaultRunCommand,
+  cwd = process.cwd(),
+} = {}) {
+  const result = await runCommand("pnpm", ["ignored-builds"], { cwd });
+  if (!result.success) {
+    return [];
+  }
+  return parsePnpmIgnoredBuildsOutput(result.stdout);
+}
+
+export function buildPnpmAllowBuildArgs(dependencies = ["node-pty"]) {
+  return normalizeBuiltDependencyList(dependencies).flatMap((dependency) => [
+    `--allow-build=${dependency}`,
+  ]);
+}
+
 export async function ensurePnpmOnlyBuiltDependencies({
   runCommand = defaultRunCommand,
   dependencies = ["node-pty"],
@@ -322,6 +360,22 @@ export async function repairAndVerifyGlobalNodePty({
   });
 
   if (packageManager === "pnpm") {
+    const ignoredBuilds = await detectPnpmIgnoredBuilds({
+      runCommand,
+      cwd: packageDirectory,
+    });
+    const blockedDependencies = normalizeBuiltDependencyList(dependencies).filter((dependency) =>
+      ignoredBuilds.includes(dependency),
+    );
+    if (blockedDependencies.length > 0) {
+      throw new Error(
+        `pnpm ignored native build scripts for ${blockedDependencies.join(
+          ", ",
+        )}. Reinstall Conductor with pnpm's build allowlist enabled, for example: pnpm add -g ${buildPnpmAllowBuildArgs(
+          blockedDependencies,
+        ).join(" ")} ${packageName}@latest`,
+      );
+    }
     const rebuildResult = await runCommand("pnpm", ["rebuild", ...dependencies], {
       cwd: packageDirectory,
     });

package/src/runtime-backends.js

@@ -8,8 +8,20 @@ import { BUILT_IN_BACKENDS as AI_SDK_BUILT_IN_BACKENDS } from "@love-moon/ai-sdk
 // CLI display order for built-in backends. ai-sdk owns the canonical set of
 // built-in backends; CLI just picks an ordering for "Supported Backends:" log
 // output. The self-check below ensures this list always matches ai-sdk's set.
-const BUILT_IN_RUNTIME_BACKENDS = ["codex", "claude", "kimi", "opencode", "copilot"];
+const BUILT_IN_RUNTIME_BACKENDS = ["codex", "claude", "kimi", "opencode", "copilot", "chat-web"];
 const BUILT_IN_RUNTIME_BACKEND_SET = new Set(BUILT_IN_RUNTIME_BACKENDS);
+// Backends that don't shell out to a CLI binary AND should be advertised
+// without any user-side allow_cli_list entry. `copilot` is the only such
+// backend today — it ships with @github/copilot-sdk as a hard dep so
+// every install gets it for free.
+//
+// chat-web is intentionally NOT here even though it's also command-optional
+// (it drives a Chromium browser, not a CLI). The reason: chat-web has
+// configurable sub-providers (chatgpt / gemini / deepseek) selected via
+// `--model`, and surfacing a bare `chat-web` backend alongside user
+// aliases like `web-chatgpt` / `web-gemini` is just confusing — the alias
+// IS the sub-provider choice. Users who want chat-web must declare an
+// explicit allow_cli_list entry (which is also where `--model` lives).
 const COMMAND_OPTIONAL_BUILT_IN_RUNTIME_BACKENDS = ["copilot"];
 const COMMAND_OPTIONAL_BUILT_IN_RUNTIME_BACKEND_SET = new Set(COMMAND_OPTIONAL_BUILT_IN_RUNTIME_BACKENDS);