Merge branch 'main' into feat/mattermost-channel

2026-01-22 02:49:17 -05:00
parent bf6df6d6b7 40b7447a80
commit fe77d3eb56
502 changed files with 31649 additions and 22281 deletions
--- a/src/infra/exec-approvals.test.ts
+++ b/src/infra/exec-approvals.test.ts
@@ -5,20 +5,34 @@ import path from "node:path";
 import { describe, expect, it, vi } from "vitest";

 import {
+  analyzeArgvCommand,
+  analyzeShellCommand,
+  evaluateExecAllowlist,
+  isSafeBinUsage,
  matchAllowlist,
  maxAsk,
  minSecurity,
+  normalizeSafeBins,
+  requiresExecApproval,
  resolveCommandResolution,
  resolveExecApprovals,
+  resolveExecApprovalsFromFile,
  type ExecAllowlistEntry,
 } from "./exec-approvals.js";

+function makePathEnv(binDir: string): NodeJS.ProcessEnv {
+  if (process.platform !== "win32") {
+    return { PATH: binDir };
+  }
+  return { PATH: binDir, PATHEXT: ".EXE;.CMD;.BAT;.COM" };
+}
+
 function makeTempDir() {
  return fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-exec-approvals-"));
 }

 describe("exec approvals allowlist matching", () => {
-  it("matches by executable name (case-insensitive)", () => {
+  it("ignores basename-only patterns", () => {
    const resolution = {
      rawExecutable: "rg",
      resolvedPath: "/opt/homebrew/bin/rg",
@@ -26,7 +40,7 @@ describe("exec approvals allowlist matching", () => {
    };
    const entries: ExecAllowlistEntry[] = [{ pattern: "RG" }];
    const match = matchAllowlist(entries, resolution);
-    expect(match?.pattern).toBe("RG");
+    expect(match).toBeNull();
  });

  it("matches by resolved path with **", () => {
@@ -51,7 +65,7 @@ describe("exec approvals allowlist matching", () => {
    expect(match).toBeNull();
  });

-  it("falls back to raw executable when no resolved path", () => {
+  it("requires a resolved path", () => {
    const resolution = {
      rawExecutable: "bin/rg",
      resolvedPath: undefined,
@@ -59,7 +73,7 @@ describe("exec approvals allowlist matching", () => {
    };
    const entries: ExecAllowlistEntry[] = [{ pattern: "bin/rg" }];
    const match = matchAllowlist(entries, resolution);
-    expect(match?.pattern).toBe("bin/rg");
+    expect(match).toBeNull();
  });
 });

@@ -68,11 +82,13 @@ describe("exec approvals command resolution", () => {
    const dir = makeTempDir();
    const binDir = path.join(dir, "bin");
    fs.mkdirSync(binDir, { recursive: true });
-    const exe = path.join(binDir, "rg");
+    const exeName = process.platform === "win32" ? "rg.exe" : "rg";
+    const exe = path.join(binDir, exeName);
    fs.writeFileSync(exe, "");
-    const res = resolveCommandResolution("rg -n foo", undefined, { PATH: binDir });
+    fs.chmodSync(exe, 0o755);
+    const res = resolveCommandResolution("rg -n foo", undefined, makePathEnv(binDir));
    expect(res?.resolvedPath).toBe(exe);
-    expect(res?.executableName).toBe("rg");
+    expect(res?.executableName).toBe(exeName);
  });

  it("resolves relative paths against cwd", () => {
@@ -81,6 +97,7 @@ describe("exec approvals command resolution", () => {
    const script = path.join(cwd, "scripts", "run.sh");
    fs.mkdirSync(path.dirname(script), { recursive: true });
    fs.writeFileSync(script, "");
+    fs.chmodSync(script, 0o755);
    const res = resolveCommandResolution("./scripts/run.sh --flag", cwd, undefined);
    expect(res?.resolvedPath).toBe(script);
  });
@@ -91,11 +108,162 @@ describe("exec approvals command resolution", () => {
    const script = path.join(cwd, "bin", "tool");
    fs.mkdirSync(path.dirname(script), { recursive: true });
    fs.writeFileSync(script, "");
+    fs.chmodSync(script, 0o755);
    const res = resolveCommandResolution('"./bin/tool" --version', cwd, undefined);
    expect(res?.resolvedPath).toBe(script);
  });
 });

+describe("exec approvals shell parsing", () => {
+  it("parses simple pipelines", () => {
+    const res = analyzeShellCommand({ command: "echo ok | jq .foo" });
+    expect(res.ok).toBe(true);
+    expect(res.segments.map((seg) => seg.argv[0])).toEqual(["echo", "jq"]);
+  });
+
+  it("rejects chained commands", () => {
+    const res = analyzeShellCommand({ command: "ls && rm -rf /" });
+    expect(res.ok).toBe(false);
+  });
+
+  it("parses argv commands", () => {
+    const res = analyzeArgvCommand({ argv: ["/bin/echo", "ok"] });
+    expect(res.ok).toBe(true);
+    expect(res.segments[0]?.argv).toEqual(["/bin/echo", "ok"]);
+  });
+});
+
+describe("exec approvals safe bins", () => {
+  it("allows safe bins with non-path args", () => {
+    const dir = makeTempDir();
+    const binDir = path.join(dir, "bin");
+    fs.mkdirSync(binDir, { recursive: true });
+    const exeName = process.platform === "win32" ? "jq.exe" : "jq";
+    const exe = path.join(binDir, exeName);
+    fs.writeFileSync(exe, "");
+    fs.chmodSync(exe, 0o755);
+    const res = analyzeShellCommand({
+      command: "jq .foo",
+      cwd: dir,
+      env: makePathEnv(binDir),
+    });
+    expect(res.ok).toBe(true);
+    const segment = res.segments[0];
+    const ok = isSafeBinUsage({
+      argv: segment.argv,
+      resolution: segment.resolution,
+      safeBins: normalizeSafeBins(["jq"]),
+      cwd: dir,
+    });
+    expect(ok).toBe(true);
+  });
+
+  it("blocks safe bins with file args", () => {
+    const dir = makeTempDir();
+    const binDir = path.join(dir, "bin");
+    fs.mkdirSync(binDir, { recursive: true });
+    const exeName = process.platform === "win32" ? "jq.exe" : "jq";
+    const exe = path.join(binDir, exeName);
+    fs.writeFileSync(exe, "");
+    fs.chmodSync(exe, 0o755);
+    const file = path.join(dir, "secret.json");
+    fs.writeFileSync(file, "{}");
+    const res = analyzeShellCommand({
+      command: "jq .foo secret.json",
+      cwd: dir,
+      env: makePathEnv(binDir),
+    });
+    expect(res.ok).toBe(true);
+    const segment = res.segments[0];
+    const ok = isSafeBinUsage({
+      argv: segment.argv,
+      resolution: segment.resolution,
+      safeBins: normalizeSafeBins(["jq"]),
+      cwd: dir,
+    });
+    expect(ok).toBe(false);
+  });
+});
+
+describe("exec approvals allowlist evaluation", () => {
+  it("satisfies allowlist on exact match", () => {
+    const analysis = {
+      ok: true,
+      segments: [
+        {
+          raw: "tool",
+          argv: ["tool"],
+          resolution: {
+            rawExecutable: "tool",
+            resolvedPath: "/usr/bin/tool",
+            executableName: "tool",
+          },
+        },
+      ],
+    };
+    const allowlist: ExecAllowlistEntry[] = [{ pattern: "/usr/bin/tool" }];
+    const result = evaluateExecAllowlist({
+      analysis,
+      allowlist,
+      safeBins: new Set(),
+      cwd: "/tmp",
+    });
+    expect(result.allowlistSatisfied).toBe(true);
+    expect(result.allowlistMatches.map((entry) => entry.pattern)).toEqual(["/usr/bin/tool"]);
+  });
+
+  it("satisfies allowlist via safe bins", () => {
+    const analysis = {
+      ok: true,
+      segments: [
+        {
+          raw: "jq .foo",
+          argv: ["jq", ".foo"],
+          resolution: {
+            rawExecutable: "jq",
+            resolvedPath: "/usr/bin/jq",
+            executableName: "jq",
+          },
+        },
+      ],
+    };
+    const result = evaluateExecAllowlist({
+      analysis,
+      allowlist: [],
+      safeBins: normalizeSafeBins(["jq"]),
+      cwd: "/tmp",
+    });
+    expect(result.allowlistSatisfied).toBe(true);
+    expect(result.allowlistMatches).toEqual([]);
+  });
+
+  it("satisfies allowlist via auto-allow skills", () => {
+    const analysis = {
+      ok: true,
+      segments: [
+        {
+          raw: "skill-bin",
+          argv: ["skill-bin", "--help"],
+          resolution: {
+            rawExecutable: "skill-bin",
+            resolvedPath: "/opt/skills/skill-bin",
+            executableName: "skill-bin",
+          },
+        },
+      ],
+    };
+    const result = evaluateExecAllowlist({
+      analysis,
+      allowlist: [],
+      safeBins: new Set(),
+      skillBins: new Set(["skill-bin"]),
+      autoAllowSkills: true,
+      cwd: "/tmp",
+    });
+    expect(result.allowlistSatisfied).toBe(true);
+  });
+});
+
 describe("exec approvals policy helpers", () => {
  it("minSecurity returns the more restrictive value", () => {
    expect(minSecurity("deny", "full")).toBe("deny");
@@ -106,6 +274,49 @@ describe("exec approvals policy helpers", () => {
    expect(maxAsk("off", "always")).toBe("always");
    expect(maxAsk("on-miss", "off")).toBe("on-miss");
  });
+
+  it("requiresExecApproval respects ask mode and allowlist satisfaction", () => {
+    expect(
+      requiresExecApproval({
+        ask: "always",
+        security: "allowlist",
+        analysisOk: true,
+        allowlistSatisfied: true,
+      }),
+    ).toBe(true);
+    expect(
+      requiresExecApproval({
+        ask: "off",
+        security: "allowlist",
+        analysisOk: true,
+        allowlistSatisfied: false,
+      }),
+    ).toBe(false);
+    expect(
+      requiresExecApproval({
+        ask: "on-miss",
+        security: "allowlist",
+        analysisOk: true,
+        allowlistSatisfied: true,
+      }),
+    ).toBe(false);
+    expect(
+      requiresExecApproval({
+        ask: "on-miss",
+        security: "allowlist",
+        analysisOk: false,
+        allowlistSatisfied: false,
+      }),
+    ).toBe(true);
+    expect(
+      requiresExecApproval({
+        ask: "on-miss",
+        security: "full",
+        analysisOk: false,
+        allowlistSatisfied: false,
+      }),
+    ).toBe(false);
+  });
 });

 describe("exec approvals wildcard agent", () => {
@@ -141,3 +352,108 @@ describe("exec approvals wildcard agent", () => {
    }
  });
 });
+
+describe("exec approvals node host allowlist check", () => {
+  // These tests verify the allowlist satisfaction logic used by the node host path
+  // The node host checks: matchAllowlist() || isSafeBinUsage() for each command segment
+  // Using hardcoded resolution objects for cross-platform compatibility
+
+  it("satisfies allowlist when command matches exact path pattern", () => {
+    const resolution = {
+      rawExecutable: "python3",
+      resolvedPath: "/usr/bin/python3",
+      executableName: "python3",
+    };
+    const entries: ExecAllowlistEntry[] = [{ pattern: "/usr/bin/python3" }];
+    const match = matchAllowlist(entries, resolution);
+    expect(match).not.toBeNull();
+    expect(match?.pattern).toBe("/usr/bin/python3");
+  });
+
+  it("satisfies allowlist when command matches ** wildcard pattern", () => {
+    // Simulates symlink resolution: /opt/homebrew/bin/python3 -> /opt/homebrew/opt/python@3.14/bin/python3.14
+    const resolution = {
+      rawExecutable: "python3",
+      resolvedPath: "/opt/homebrew/opt/python@3.14/bin/python3.14",
+      executableName: "python3.14",
+    };
+    // Pattern with ** matches across multiple directories
+    const entries: ExecAllowlistEntry[] = [{ pattern: "/opt/**/python*" }];
+    const match = matchAllowlist(entries, resolution);
+    expect(match?.pattern).toBe("/opt/**/python*");
+  });
+
+  it("does not satisfy allowlist when command is not in allowlist", () => {
+    const resolution = {
+      rawExecutable: "unknown-tool",
+      resolvedPath: "/usr/local/bin/unknown-tool",
+      executableName: "unknown-tool",
+    };
+    // Allowlist has different commands
+    const entries: ExecAllowlistEntry[] = [
+      { pattern: "/usr/bin/python3" },
+      { pattern: "/opt/**/node" },
+    ];
+    const match = matchAllowlist(entries, resolution);
+    expect(match).toBeNull();
+
+    // Also not a safe bin
+    const safe = isSafeBinUsage({
+      argv: ["unknown-tool", "--help"],
+      resolution,
+      safeBins: normalizeSafeBins(["jq", "curl"]),
+      cwd: "/tmp",
+    });
+    expect(safe).toBe(false);
+  });
+
+  it("satisfies via safeBins even when not in allowlist", () => {
+    const resolution = {
+      rawExecutable: "jq",
+      resolvedPath: "/usr/bin/jq",
+      executableName: "jq",
+    };
+    // Not in allowlist
+    const entries: ExecAllowlistEntry[] = [{ pattern: "/usr/bin/python3" }];
+    const match = matchAllowlist(entries, resolution);
+    expect(match).toBeNull();
+
+    // But is a safe bin with non-file args
+    const safe = isSafeBinUsage({
+      argv: ["jq", ".foo"],
+      resolution,
+      safeBins: normalizeSafeBins(["jq"]),
+      cwd: "/tmp",
+    });
+    expect(safe).toBe(true);
+  });
+});
+
+describe("exec approvals default agent migration", () => {
+  it("migrates legacy default agent entries to main", () => {
+    const file = {
+      version: 1,
+      agents: {
+        default: { allowlist: [{ pattern: "/bin/legacy" }] },
+      },
+    };
+    const resolved = resolveExecApprovalsFromFile({ file });
+    expect(resolved.allowlist.map((entry) => entry.pattern)).toEqual(["/bin/legacy"]);
+    expect(resolved.file.agents?.default).toBeUndefined();
+    expect(resolved.file.agents?.main?.allowlist?.[0]?.pattern).toBe("/bin/legacy");
+  });
+
+  it("prefers main agent settings when both main and default exist", () => {
+    const file = {
+      version: 1,
+      agents: {
+        main: { ask: "always", allowlist: [{ pattern: "/bin/main" }] },
+        default: { ask: "off", allowlist: [{ pattern: "/bin/legacy" }] },
+      },
+    };
+    const resolved = resolveExecApprovalsFromFile({ file });
+    expect(resolved.agent.ask).toBe("always");
+    expect(resolved.allowlist.map((entry) => entry.pattern)).toEqual(["/bin/main", "/bin/legacy"]);
+    expect(resolved.file.agents?.default).toBeUndefined();
+  });
+});
--- a/src/infra/exec-approvals.ts
+++ b/src/infra/exec-approvals.ts
@@ -4,6 +4,8 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";

+import { DEFAULT_AGENT_ID } from "../routing/session-key.js";
+
 export type ExecHost = "sandbox" | "gateway" | "node";
 export type ExecSecurity = "deny" | "allowlist" | "full";
 export type ExecAsk = "off" | "on-miss" | "always";
@@ -60,6 +62,7 @@ const DEFAULT_ASK_FALLBACK: ExecSecurity = "deny";
 const DEFAULT_AUTO_ALLOW_SKILLS = false;
 const DEFAULT_SOCKET = "~/.clawdbot/exec-approvals.sock";
 const DEFAULT_FILE = "~/.clawdbot/exec-approvals.json";
+export const DEFAULT_SAFE_BINS = ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"];

 function hashExecApprovalsRaw(raw: string | null): string {
  return crypto
@@ -83,6 +86,35 @@ export function resolveExecApprovalsSocketPath(): string {
  return expandHome(DEFAULT_SOCKET);
 }

+function normalizeAllowlistPattern(value: string | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed ? trimmed.toLowerCase() : null;
+}
+
+function mergeLegacyAgent(
+  current: ExecApprovalsAgent,
+  legacy: ExecApprovalsAgent,
+): ExecApprovalsAgent {
+  const allowlist: ExecAllowlistEntry[] = [];
+  const seen = new Set<string>();
+  const pushEntry = (entry: ExecAllowlistEntry) => {
+    const key = normalizeAllowlistPattern(entry.pattern);
+    if (!key || seen.has(key)) return;
+    seen.add(key);
+    allowlist.push(entry);
+  };
+  for (const entry of current.allowlist ?? []) pushEntry(entry);
+  for (const entry of legacy.allowlist ?? []) pushEntry(entry);
+
+  return {
+    security: current.security ?? legacy.security,
+    ask: current.ask ?? legacy.ask,
+    askFallback: current.askFallback ?? legacy.askFallback,
+    autoAllowSkills: current.autoAllowSkills ?? legacy.autoAllowSkills,
+    allowlist: allowlist.length > 0 ? allowlist : undefined,
+  };
+}
+
 function ensureDir(filePath: string) {
  const dir = path.dirname(filePath);
  fs.mkdirSync(dir, { recursive: true });
@@ -91,6 +123,13 @@ function ensureDir(filePath: string) {
 export function normalizeExecApprovals(file: ExecApprovalsFile): ExecApprovalsFile {
  const socketPath = file.socket?.path?.trim();
  const token = file.socket?.token?.trim();
+  const agents = { ...file.agents };
+  const legacyDefault = agents.default;
+  if (legacyDefault) {
+    const main = agents[DEFAULT_AGENT_ID];
+    agents[DEFAULT_AGENT_ID] = main ? mergeLegacyAgent(main, legacyDefault) : legacyDefault;
+    delete agents.default;
+  }
  const normalized: ExecApprovalsFile = {
    version: 1,
    socket: {
@@ -103,7 +142,7 @@ export function normalizeExecApprovals(file: ExecApprovalsFile): ExecApprovalsFi
      askFallback: file.defaults?.askFallback,
      autoAllowSkills: file.defaults?.autoAllowSkills,
    },
-    agents: file.agents ?? {},
+    agents,
  };
  return normalized;
 }
@@ -210,14 +249,33 @@ export function resolveExecApprovals(
  overrides?: ExecApprovalsDefaultOverrides,
 ): ExecApprovalsResolved {
  const file = ensureExecApprovals();
+  return resolveExecApprovalsFromFile({
+    file,
+    agentId,
+    overrides,
+    path: resolveExecApprovalsPath(),
+    socketPath: expandHome(file.socket?.path ?? resolveExecApprovalsSocketPath()),
+    token: file.socket?.token ?? "",
+  });
+}
+
+export function resolveExecApprovalsFromFile(params: {
+  file: ExecApprovalsFile;
+  agentId?: string;
+  overrides?: ExecApprovalsDefaultOverrides;
+  path?: string;
+  socketPath?: string;
+  token?: string;
+}): ExecApprovalsResolved {
+  const file = normalizeExecApprovals(params.file);
  const defaults = file.defaults ?? {};
-  const agentKey = agentId ?? "default";
+  const agentKey = params.agentId ?? DEFAULT_AGENT_ID;
  const agent = file.agents?.[agentKey] ?? {};
  const wildcard = file.agents?.["*"] ?? {};
-  const fallbackSecurity = overrides?.security ?? DEFAULT_SECURITY;
-  const fallbackAsk = overrides?.ask ?? DEFAULT_ASK;
-  const fallbackAskFallback = overrides?.askFallback ?? DEFAULT_ASK_FALLBACK;
-  const fallbackAutoAllowSkills = overrides?.autoAllowSkills ?? DEFAULT_AUTO_ALLOW_SKILLS;
+  const fallbackSecurity = params.overrides?.security ?? DEFAULT_SECURITY;
+  const fallbackAsk = params.overrides?.ask ?? DEFAULT_ASK;
+  const fallbackAskFallback = params.overrides?.askFallback ?? DEFAULT_ASK_FALLBACK;
+  const fallbackAutoAllowSkills = params.overrides?.autoAllowSkills ?? DEFAULT_AUTO_ALLOW_SKILLS;
  const resolvedDefaults: Required<ExecApprovalsDefaults> = {
    security: normalizeSecurity(defaults.security, fallbackSecurity),
    ask: normalizeAsk(defaults.ask, fallbackAsk),
@@ -246,9 +304,11 @@ export function resolveExecApprovals(
    ...(Array.isArray(agent.allowlist) ? agent.allowlist : []),
  ];
  return {
-    path: resolveExecApprovalsPath(),
-    socketPath: expandHome(file.socket?.path ?? resolveExecApprovalsSocketPath()),
-    token: file.socket?.token ?? "",
+    path: params.path ?? resolveExecApprovalsPath(),
+    socketPath: expandHome(
+      params.socketPath ?? file.socket?.path ?? resolveExecApprovalsSocketPath(),
+    ),
+    token: params.token ?? file.socket?.token ?? "",
    defaults: resolvedDefaults,
    agent: resolvedAgent,
    allowlist,
@@ -262,6 +322,19 @@ type CommandResolution = {
  executableName: string;
 };

+function isExecutableFile(filePath: string): boolean {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) return false;
+    if (process.platform !== "win32") {
+      fs.accessSync(filePath, fs.constants.X_OK);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function parseFirstToken(command: string): string | null {
  const trimmed = command.trim();
  if (!trimmed) return null;
@@ -278,15 +351,26 @@ function parseFirstToken(command: string): string | null {
 function resolveExecutablePath(rawExecutable: string, cwd?: string, env?: NodeJS.ProcessEnv) {
  const expanded = rawExecutable.startsWith("~") ? expandHome(rawExecutable) : rawExecutable;
  if (expanded.includes("/") || expanded.includes("\\")) {
-    if (path.isAbsolute(expanded)) return expanded;
+    if (path.isAbsolute(expanded)) {
+      return isExecutableFile(expanded) ? expanded : undefined;
+    }
    const base = cwd && cwd.trim() ? cwd.trim() : process.cwd();
-    return path.resolve(base, expanded);
+    const candidate = path.resolve(base, expanded);
+    return isExecutableFile(candidate) ? candidate : undefined;
  }
  const envPath = env?.PATH ?? process.env.PATH ?? "";
  const entries = envPath.split(path.delimiter).filter(Boolean);
+  const extensions =
+    process.platform === "win32"
+      ? (env?.PATHEXT ?? process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+          .split(";")
+          .map((ext) => ext.toLowerCase())
+      : [""];
  for (const entry of entries) {
-    const candidate = path.join(entry, expanded);
-    if (fs.existsSync(candidate)) return candidate;
+    for (const ext of extensions) {
+      const candidate = path.join(entry, expanded + ext);
+      if (isExecutableFile(candidate)) return candidate;
+    }
  }
  return undefined;
 }
@@ -303,6 +387,18 @@ export function resolveCommandResolution(
  return { rawExecutable, resolvedPath, executableName };
 }

+export function resolveCommandResolutionFromArgv(
+  argv: string[],
+  cwd?: string,
+  env?: NodeJS.ProcessEnv,
+): CommandResolution | null {
+  const rawExecutable = argv[0]?.trim();
+  if (!rawExecutable) return null;
+  const resolvedPath = resolveExecutablePath(rawExecutable, cwd, env);
+  const executableName = resolvedPath ? path.basename(resolvedPath) : rawExecutable;
+  return { rawExecutable, resolvedPath, executableName };
+}
+
 function normalizeMatchTarget(value: string): string {
  return value.replace(/\\\\/g, "/").toLowerCase();
 }
@@ -349,24 +445,338 @@ export function matchAllowlist(
  entries: ExecAllowlistEntry[],
  resolution: CommandResolution | null,
 ): ExecAllowlistEntry | null {
-  if (!entries.length || !resolution) return null;
-  const rawExecutable = resolution.rawExecutable;
+  if (!entries.length || !resolution?.resolvedPath) return null;
  const resolvedPath = resolution.resolvedPath;
-  const executableName = resolution.executableName;
  for (const entry of entries) {
    const pattern = entry.pattern?.trim();
    if (!pattern) continue;
    const hasPath = pattern.includes("/") || pattern.includes("\\") || pattern.includes("~");
-    if (hasPath) {
-      const target = resolvedPath ?? rawExecutable;
-      if (target && matchesPattern(pattern, target)) return entry;
-      continue;
-    }
-    if (executableName && matchesPattern(pattern, executableName)) return entry;
+    if (!hasPath) continue;
+    if (matchesPattern(pattern, resolvedPath)) return entry;
  }
  return null;
 }

+export type ExecCommandSegment = {
+  raw: string;
+  argv: string[];
+  resolution: CommandResolution | null;
+};
+
+export type ExecCommandAnalysis = {
+  ok: boolean;
+  reason?: string;
+  segments: ExecCommandSegment[];
+};
+
+const DISALLOWED_TOKENS = new Set([";", "&", ">", "<", "`", "\n", "\r", "(", ")"]);
+
+function splitShellPipeline(command: string): { ok: boolean; reason?: string; segments: string[] } {
+  const segments: string[] = [];
+  let buf = "";
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  const pushSegment = () => {
+    const trimmed = buf.trim();
+    if (!trimmed) {
+      return false;
+    }
+    segments.push(trimmed);
+    buf = "";
+    return true;
+  };
+
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (escaped) {
+      buf += ch;
+      escaped = false;
+      continue;
+    }
+    if (!inSingle && ch === "\\") {
+      escaped = true;
+      buf += ch;
+      continue;
+    }
+    if (inSingle) {
+      if (ch === "'") inSingle = false;
+      buf += ch;
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') inDouble = false;
+      buf += ch;
+      continue;
+    }
+    if (ch === "'") {
+      inSingle = true;
+      buf += ch;
+      continue;
+    }
+    if (ch === '"') {
+      inDouble = true;
+      buf += ch;
+      continue;
+    }
+    if (ch === "|" && command[i + 1] === "|") {
+      return { ok: false, reason: "unsupported shell token: ||", segments: [] };
+    }
+    if (ch === "|" && command[i + 1] === "&") {
+      return { ok: false, reason: "unsupported shell token: |&", segments: [] };
+    }
+    if (ch === "|") {
+      if (!pushSegment()) {
+        return { ok: false, reason: "empty pipeline segment", segments: [] };
+      }
+      continue;
+    }
+    if (DISALLOWED_TOKENS.has(ch)) {
+      return { ok: false, reason: `unsupported shell token: ${ch}`, segments: [] };
+    }
+    if (ch === "$" && command[i + 1] === "(") {
+      return { ok: false, reason: "unsupported shell token: $()", segments: [] };
+    }
+    buf += ch;
+  }
+
+  if (escaped || inSingle || inDouble) {
+    return { ok: false, reason: "unterminated shell quote/escape", segments: [] };
+  }
+  if (!pushSegment()) {
+    return { ok: false, reason: "empty command", segments: [] };
+  }
+  return { ok: true, segments };
+}
+
+function tokenizeShellSegment(segment: string): string[] | null {
+  const tokens: string[] = [];
+  let buf = "";
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  const pushToken = () => {
+    if (buf.length > 0) {
+      tokens.push(buf);
+      buf = "";
+    }
+  };
+
+  for (let i = 0; i < segment.length; i += 1) {
+    const ch = segment[i];
+    if (escaped) {
+      buf += ch;
+      escaped = false;
+      continue;
+    }
+    if (!inSingle && ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (inSingle) {
+      if (ch === "'") {
+        inSingle = false;
+      } else {
+        buf += ch;
+      }
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') {
+        inDouble = false;
+      } else {
+        buf += ch;
+      }
+      continue;
+    }
+    if (ch === "'") {
+      inSingle = true;
+      continue;
+    }
+    if (ch === '"') {
+      inDouble = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      pushToken();
+      continue;
+    }
+    buf += ch;
+  }
+
+  if (escaped || inSingle || inDouble) {
+    return null;
+  }
+  pushToken();
+  return tokens;
+}
+
+export function analyzeShellCommand(params: {
+  command: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}): ExecCommandAnalysis {
+  const split = splitShellPipeline(params.command);
+  if (!split.ok) {
+    return { ok: false, reason: split.reason, segments: [] };
+  }
+  const segments: ExecCommandSegment[] = [];
+  for (const raw of split.segments) {
+    const argv = tokenizeShellSegment(raw);
+    if (!argv || argv.length === 0) {
+      return { ok: false, reason: "unable to parse shell segment", segments: [] };
+    }
+    segments.push({
+      raw,
+      argv,
+      resolution: resolveCommandResolutionFromArgv(argv, params.cwd, params.env),
+    });
+  }
+  return { ok: true, segments };
+}
+
+export function analyzeArgvCommand(params: {
+  argv: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}): ExecCommandAnalysis {
+  const argv = params.argv.filter((entry) => entry.trim().length > 0);
+  if (argv.length === 0) {
+    return { ok: false, reason: "empty argv", segments: [] };
+  }
+  return {
+    ok: true,
+    segments: [
+      {
+        raw: argv.join(" "),
+        argv,
+        resolution: resolveCommandResolutionFromArgv(argv, params.cwd, params.env),
+      },
+    ],
+  };
+}
+
+function isPathLikeToken(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  if (trimmed === "-") return false;
+  if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("~")) return true;
+  if (trimmed.startsWith("/")) return true;
+  return /^[A-Za-z]:[\\/]/.test(trimmed);
+}
+
+function defaultFileExists(filePath: string): boolean {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+export function normalizeSafeBins(entries?: string[]): Set<string> {
+  if (!Array.isArray(entries)) return new Set();
+  const normalized = entries
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0);
+  return new Set(normalized);
+}
+
+export function resolveSafeBins(entries?: string[] | null): Set<string> {
+  if (entries === undefined) return normalizeSafeBins(DEFAULT_SAFE_BINS);
+  return normalizeSafeBins(entries ?? []);
+}
+
+export function isSafeBinUsage(params: {
+  argv: string[];
+  resolution: CommandResolution | null;
+  safeBins: Set<string>;
+  cwd?: string;
+  fileExists?: (filePath: string) => boolean;
+}): boolean {
+  if (params.safeBins.size === 0) return false;
+  const resolution = params.resolution;
+  const execName = resolution?.executableName?.toLowerCase();
+  if (!execName) return false;
+  const matchesSafeBin =
+    params.safeBins.has(execName) ||
+    (process.platform === "win32" && params.safeBins.has(path.parse(execName).name));
+  if (!matchesSafeBin) return false;
+  if (!resolution?.resolvedPath) return false;
+  const cwd = params.cwd ?? process.cwd();
+  const exists = params.fileExists ?? defaultFileExists;
+  const argv = params.argv.slice(1);
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token) continue;
+    if (token === "-") continue;
+    if (token.startsWith("-")) {
+      const eqIndex = token.indexOf("=");
+      if (eqIndex > 0) {
+        const value = token.slice(eqIndex + 1);
+        if (value && (isPathLikeToken(value) || exists(path.resolve(cwd, value)))) {
+          return false;
+        }
+      }
+      continue;
+    }
+    if (isPathLikeToken(token)) return false;
+    if (exists(path.resolve(cwd, token))) return false;
+  }
+  return true;
+}
+
+export type ExecAllowlistEvaluation = {
+  allowlistSatisfied: boolean;
+  allowlistMatches: ExecAllowlistEntry[];
+};
+
+export function evaluateExecAllowlist(params: {
+  analysis: ExecCommandAnalysis;
+  allowlist: ExecAllowlistEntry[];
+  safeBins: Set<string>;
+  cwd?: string;
+  skillBins?: Set<string>;
+  autoAllowSkills?: boolean;
+}): ExecAllowlistEvaluation {
+  const allowlistMatches: ExecAllowlistEntry[] = [];
+  if (!params.analysis.ok || params.analysis.segments.length === 0) {
+    return { allowlistSatisfied: false, allowlistMatches };
+  }
+  const allowSkills = params.autoAllowSkills === true && (params.skillBins?.size ?? 0) > 0;
+  const allowlistSatisfied = params.analysis.segments.every((segment) => {
+    const match = matchAllowlist(params.allowlist, segment.resolution);
+    if (match) allowlistMatches.push(match);
+    const safe = isSafeBinUsage({
+      argv: segment.argv,
+      resolution: segment.resolution,
+      safeBins: params.safeBins,
+      cwd: params.cwd,
+    });
+    const skillAllow =
+      allowSkills && segment.resolution?.executableName
+        ? params.skillBins?.has(segment.resolution.executableName)
+        : false;
+    return Boolean(match || safe || skillAllow);
+  });
+  return { allowlistSatisfied, allowlistMatches };
+}
+
+export function requiresExecApproval(params: {
+  ask: ExecAsk;
+  security: ExecSecurity;
+  analysisOk: boolean;
+  allowlistSatisfied: boolean;
+}): boolean {
+  return (
+    params.ask === "always" ||
+    (params.ask === "on-miss" &&
+      params.security === "allowlist" &&
+      (!params.analysisOk || !params.allowlistSatisfied))
+  );
+}
+
 export function recordAllowlistUse(
  approvals: ExecApprovalsFile,
  agentId: string | undefined,
@@ -374,7 +784,7 @@ export function recordAllowlistUse(
  command: string,
  resolvedPath?: string,
 ) {
-  const target = agentId ?? "default";
+  const target = agentId ?? DEFAULT_AGENT_ID;
  const agents = approvals.agents ?? {};
  const existing = agents[target] ?? {};
  const allowlist = Array.isArray(existing.allowlist) ? existing.allowlist : [];
@@ -398,7 +808,7 @@ export function addAllowlistEntry(
  agentId: string | undefined,
  pattern: string,
 ) {
-  const target = agentId ?? "default";
+  const target = agentId ?? DEFAULT_AGENT_ID;
  const agents = approvals.agents ?? {};
  const existing = agents[target] ?? {};
  const allowlist = Array.isArray(existing.allowlist) ? existing.allowlist : [];
--- a/src/infra/fetch.test.ts
+++ b/src/infra/fetch.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { wrapFetchWithAbortSignal } from "./fetch.js";
+
+describe("wrapFetchWithAbortSignal", () => {
+  it("converts foreign abort signals to native controllers", async () => {
+    let seenSignal: AbortSignal | undefined;
+    const fetchImpl = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      seenSignal = init?.signal as AbortSignal | undefined;
+      return {} as Response;
+    });
+
+    const wrapped = wrapFetchWithAbortSignal(fetchImpl);
+
+    let abortHandler: (() => void) | null = null;
+    const fakeSignal = {
+      aborted: false,
+      addEventListener: (event: string, handler: () => void) => {
+        if (event === "abort") abortHandler = handler;
+      },
+      removeEventListener: (event: string, handler: () => void) => {
+        if (event === "abort" && abortHandler === handler) abortHandler = null;
+      },
+    } as AbortSignal;
+
+    const promise = wrapped("https://example.com", { signal: fakeSignal });
+    expect(fetchImpl).toHaveBeenCalledOnce();
+    expect(seenSignal).toBeInstanceOf(AbortSignal);
+    expect(seenSignal).not.toBe(fakeSignal);
+
+    abortHandler?.();
+    expect(seenSignal?.aborted).toBe(true);
+
+    await promise;
+  });
+});
--- a/src/infra/fetch.ts
+++ b/src/infra/fetch.ts
@@ -0,0 +1,47 @@
+type FetchWithPreconnect = typeof fetch & {
+  preconnect: (url: string, init?: { credentials?: RequestCredentials }) => void;
+};
+
+export function wrapFetchWithAbortSignal(fetchImpl: typeof fetch): typeof fetch {
+  const wrapped = ((input: RequestInfo | URL, init?: RequestInit) => {
+    const signal = init?.signal;
+    if (!signal) return fetchImpl(input, init);
+    if (typeof AbortSignal !== "undefined" && signal instanceof AbortSignal) {
+      return fetchImpl(input, init);
+    }
+    if (typeof AbortController === "undefined") {
+      return fetchImpl(input, init);
+    }
+    if (typeof signal.addEventListener !== "function") {
+      return fetchImpl(input, init);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const response = fetchImpl(input, { ...init, signal: controller.signal });
+    if (typeof signal.removeEventListener === "function") {
+      void response.finally(() => {
+        signal.removeEventListener("abort", onAbort);
+      });
+    }
+    return response;
+  }) as FetchWithPreconnect;
+
+  const fetchWithPreconnect = fetchImpl as FetchWithPreconnect;
+  wrapped.preconnect =
+    typeof fetchWithPreconnect.preconnect === "function"
+      ? fetchWithPreconnect.preconnect.bind(fetchWithPreconnect)
+      : () => {};
+
+  return Object.assign(wrapped, fetchImpl);
+}
+
+export function resolveFetch(fetchImpl?: typeof fetch): typeof fetch | undefined {
+  const resolved = fetchImpl ?? globalThis.fetch;
+  if (!resolved) return undefined;
+  return wrapFetchWithAbortSignal(resolved);
+}
--- a/src/infra/gateway-lock.test.ts
+++ b/src/infra/gateway-lock.test.ts
@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { acquireGatewayLock, GatewayLockError } from "./gateway-lock.js";
+
+async function makeEnv() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-gateway-lock-"));
+  const configPath = path.join(dir, "clawdbot.json");
+  await fs.writeFile(configPath, "{}", "utf8");
+  return {
+    env: {
+      ...process.env,
+      CLAWDBOT_STATE_DIR: dir,
+      CLAWDBOT_CONFIG_PATH: configPath,
+    },
+    cleanup: async () => {
+      await fs.rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("gateway lock", () => {
+  it("blocks concurrent acquisition until release", async () => {
+    const { env, cleanup } = await makeEnv();
+    const lock = await acquireGatewayLock({
+      env,
+      allowInTests: true,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    expect(lock).not.toBeNull();
+
+    await expect(
+      acquireGatewayLock({
+        env,
+        allowInTests: true,
+        timeoutMs: 200,
+        pollIntervalMs: 20,
+      }),
+    ).rejects.toBeInstanceOf(GatewayLockError);
+
+    await lock?.release();
+    const lock2 = await acquireGatewayLock({
+      env,
+      allowInTests: true,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    await lock2?.release();
+    await cleanup();
+  });
+});
--- a/src/infra/gateway-lock.ts
+++ b/src/infra/gateway-lock.ts
@@ -1,3 +1,33 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { resolveConfigPath, resolveStateDir } from "../config/paths.js";
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_STALE_MS = 30_000;
+
+type LockPayload = {
+  pid: number;
+  createdAt: string;
+  configPath: string;
+};
+
+export type GatewayLockHandle = {
+  lockPath: string;
+  configPath: string;
+  release: () => Promise<void>;
+};
+
+export type GatewayLockOptions = {
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  staleMs?: number;
+  allowInTests?: boolean;
+};
+
 export class GatewayLockError extends Error {
  constructor(
    message: string,
@@ -7,3 +37,117 @@ export class GatewayLockError extends Error {
    this.name = "GatewayLockError";
  }
 }
+
+function isAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readLockPayload(lockPath: string): Promise<LockPayload | null> {
+  try {
+    const raw = await fs.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<LockPayload>;
+    if (typeof parsed.pid !== "number") return null;
+    if (typeof parsed.createdAt !== "string") return null;
+    if (typeof parsed.configPath !== "string") return null;
+    return {
+      pid: parsed.pid,
+      createdAt: parsed.createdAt,
+      configPath: parsed.configPath,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveGatewayLockPath(env: NodeJS.ProcessEnv) {
+  const stateDir = resolveStateDir(env);
+  const configPath = resolveConfigPath(env, stateDir);
+  const hash = createHash("sha1").update(configPath).digest("hex").slice(0, 8);
+  const lockPath = path.join(stateDir, `gateway.${hash}.lock`);
+  return { lockPath, configPath };
+}
+
+export async function acquireGatewayLock(
+  opts: GatewayLockOptions = {},
+): Promise<GatewayLockHandle | null> {
+  const env = opts.env ?? process.env;
+  const allowInTests = opts.allowInTests === true;
+  if (
+    env.CLAWDBOT_ALLOW_MULTI_GATEWAY === "1" ||
+    (!allowInTests && (env.VITEST || env.NODE_ENV === "test"))
+  ) {
+    return null;
+  }
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+  const { lockPath, configPath } = resolveGatewayLockPath(env);
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+
+  const startedAt = Date.now();
+  let lastPayload: LockPayload | null = null;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      const payload: LockPayload = {
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        configPath,
+      };
+      await handle.writeFile(JSON.stringify(payload), "utf8");
+      return {
+        lockPath,
+        configPath,
+        release: async () => {
+          await handle.close().catch(() => undefined);
+          await fs.rm(lockPath, { force: true });
+        },
+      };
+    } catch (err) {
+      const code = (err as { code?: unknown }).code;
+      if (code !== "EEXIST") {
+        throw new GatewayLockError(`failed to acquire gateway lock at ${lockPath}`, err);
+      }
+
+      lastPayload = await readLockPayload(lockPath);
+      const ownerPid = lastPayload?.pid;
+      const ownerAlive = ownerPid ? isAlive(ownerPid) : false;
+      if (!ownerAlive && ownerPid) {
+        await fs.rm(lockPath, { force: true });
+        continue;
+      }
+      if (!ownerAlive) {
+        let stale = false;
+        if (lastPayload?.createdAt) {
+          const createdAt = Date.parse(lastPayload.createdAt);
+          stale = Number.isFinite(createdAt) ? Date.now() - createdAt > staleMs : false;
+        }
+        if (!stale) {
+          try {
+            const st = await fs.stat(lockPath);
+            stale = Date.now() - st.mtimeMs > staleMs;
+          } catch {
+            stale = true;
+          }
+        }
+        if (stale) {
+          await fs.rm(lockPath, { force: true });
+          continue;
+        }
+      }
+
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+
+  const owner = lastPayload?.pid ? ` (pid ${lastPayload.pid})` : "";
+  throw new GatewayLockError(`gateway already running${owner}; lock timeout after ${timeoutMs}ms`);
+}
--- a/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
+++ b/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
@@ -41,7 +41,6 @@ describe("resolveHeartbeatIntervalMs", () => {
            heartbeat: {
              every: "5m",
              target: "whatsapp",
-              to: "+1555",
              ackMaxChars: 0,
            },
          },
@@ -58,6 +57,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -102,7 +102,6 @@ describe("resolveHeartbeatIntervalMs", () => {
            heartbeat: {
              every: "5m",
              target: "whatsapp",
-              to: "+1555",
            },
          },
        },
@@ -118,6 +117,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -164,7 +164,6 @@ describe("resolveHeartbeatIntervalMs", () => {
            heartbeat: {
              every: "5m",
              target: "whatsapp",
-              to: "+1555",
            },
          },
        },
@@ -180,6 +179,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: originalUpdatedAt,
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -231,7 +231,7 @@ describe("resolveHeartbeatIntervalMs", () => {
      const cfg: ClawdbotConfig = {
        agents: {
          defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
          },
        },
        channels: { whatsapp: { allowFrom: ["*"] } },
@@ -246,6 +246,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -291,7 +292,7 @@ describe("resolveHeartbeatIntervalMs", () => {
      const cfg: ClawdbotConfig = {
        agents: {
          defaults: {
-            heartbeat: { every: "5m", target: "telegram", to: "123456" },
+            heartbeat: { every: "5m", target: "telegram" },
          },
        },
        channels: { telegram: { botToken: "test-bot-token-123" } },
@@ -306,6 +307,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "telegram",
              lastProvider: "telegram",
              lastTo: "123456",
            },
@@ -357,7 +359,7 @@ describe("resolveHeartbeatIntervalMs", () => {
      const cfg: ClawdbotConfig = {
        agents: {
          defaults: {
-            heartbeat: { every: "5m", target: "telegram", to: "123456" },
+            heartbeat: { every: "5m", target: "telegram" },
          },
        },
        channels: {
@@ -378,6 +380,7 @@ describe("resolveHeartbeatIntervalMs", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "telegram",
              lastProvider: "telegram",
              lastTo: "123456",
            },
--- a/src/infra/heartbeat-runner.returns-default-unset.test.ts
+++ b/src/infra/heartbeat-runner.returns-default-unset.test.ts
@@ -11,6 +11,7 @@ import {
  resolveMainSessionKey,
  resolveStorePath,
 } from "../config/sessions.js";
+import { buildAgentPeerSessionKey } from "../routing/session-key.js";
 import {
  isHeartbeatEnabledForAgent,
  resolveHeartbeatIntervalMs,
@@ -300,6 +301,30 @@ describe("runHeartbeatOnce", () => {
    }
  });

+  it("skips outside active hours", async () => {
+    const cfg: ClawdbotConfig = {
+      agents: {
+        defaults: {
+          userTimezone: "UTC",
+          heartbeat: {
+            every: "30m",
+            activeHours: { start: "08:00", end: "24:00", timezone: "user" },
+          },
+        },
+      },
+    };
+
+    const res = await runHeartbeatOnce({
+      cfg,
+      deps: { nowMs: () => Date.UTC(2025, 0, 1, 7, 0, 0) },
+    });
+
+    expect(res.status).toBe("skipped");
+    if (res.status === "skipped") {
+      expect(res.reason).toBe("quiet-hours");
+    }
+  });
+
  it("uses the last non-empty payload for delivery", async () => {
    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
    const storePath = path.join(tmpDir, "sessions.json");
@@ -308,7 +333,7 @@ describe("runHeartbeatOnce", () => {
      const cfg: ClawdbotConfig = {
        agents: {
          defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
          },
        },
        channels: { whatsapp: { allowFrom: ["*"] } },
@@ -371,7 +396,7 @@ describe("runHeartbeatOnce", () => {
            { id: "main", default: true },
            {
              id: "ops",
-              heartbeat: { every: "5m", target: "whatsapp", to: "+1555", prompt: "Ops check" },
+              heartbeat: { every: "5m", target: "whatsapp", prompt: "Ops check" },
            },
          ],
        },
@@ -427,6 +452,88 @@ describe("runHeartbeatOnce", () => {
    }
  });

+  it("runs heartbeats in the explicit session key when configured", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
+    const storePath = path.join(tmpDir, "sessions.json");
+    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
+    try {
+      const groupId = "120363401234567890@g.us";
+      const cfg: ClawdbotConfig = {
+        agents: {
+          defaults: {
+            heartbeat: {
+              every: "5m",
+              target: "last",
+            },
+          },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: storePath },
+      };
+      const mainSessionKey = resolveMainSessionKey(cfg);
+      const agentId = resolveAgentIdFromSessionKey(mainSessionKey);
+      const groupSessionKey = buildAgentPeerSessionKey({
+        agentId,
+        channel: "whatsapp",
+        peerKind: "group",
+        peerId: groupId,
+      });
+      if (cfg.agents?.defaults?.heartbeat) {
+        cfg.agents.defaults.heartbeat.session = groupSessionKey;
+      }
+
+      await fs.writeFile(
+        storePath,
+        JSON.stringify(
+          {
+            [mainSessionKey]: {
+              sessionId: "sid-main",
+              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
+              lastTo: "+1555",
+            },
+            [groupSessionKey]: {
+              sessionId: "sid-group",
+              updatedAt: Date.now() + 10_000,
+              lastChannel: "whatsapp",
+              lastTo: groupId,
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      replySpy.mockResolvedValue([{ text: "Group alert" }]);
+      const sendWhatsApp = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendWhatsApp,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+          webAuthExists: async () => true,
+          hasActiveWebListener: () => true,
+        },
+      });
+
+      expect(sendWhatsApp).toHaveBeenCalledTimes(1);
+      expect(sendWhatsApp).toHaveBeenCalledWith(groupId, "Group alert", expect.any(Object));
+      expect(replySpy).toHaveBeenCalledWith(
+        expect.objectContaining({ SessionKey: groupSessionKey }),
+        { isHeartbeat: true },
+        cfg,
+      );
+    } finally {
+      replySpy.mockRestore();
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
  it("suppresses duplicate heartbeat payloads within 24h", async () => {
    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
    const storePath = path.join(tmpDir, "sessions.json");
@@ -435,7 +542,7 @@ describe("runHeartbeatOnce", () => {
      const cfg: ClawdbotConfig = {
        agents: {
          defaults: {
-            heartbeat: { every: "5m", target: "whatsapp", to: "+1555" },
+            heartbeat: { every: "5m", target: "whatsapp" },
          },
        },
        channels: { whatsapp: { allowFrom: ["*"] } },
@@ -493,7 +600,6 @@ describe("runHeartbeatOnce", () => {
            heartbeat: {
              every: "5m",
              target: "whatsapp",
-              to: "+1555",
              includeReasoning: true,
            },
          },
@@ -510,6 +616,7 @@ describe("runHeartbeatOnce", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -564,7 +671,6 @@ describe("runHeartbeatOnce", () => {
            heartbeat: {
              every: "5m",
              target: "whatsapp",
-              to: "+1555",
              includeReasoning: true,
            },
          },
@@ -581,6 +687,7 @@ describe("runHeartbeatOnce", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
@@ -648,6 +755,7 @@ describe("runHeartbeatOnce", () => {
            [sessionKey]: {
              sessionId: "sid",
              updatedAt: Date.now(),
+              lastChannel: "whatsapp",
              lastProvider: "whatsapp",
              lastTo: "+1555",
            },
--- a/src/infra/heartbeat-runner.ts
+++ b/src/infra/heartbeat-runner.ts
@@ -1,4 +1,5 @@
 import { resolveAgentConfig, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { resolveUserTimezone } from "../agents/date-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import {
  DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
@@ -14,7 +15,9 @@ import { parseDurationMs } from "../cli/parse-duration.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import { loadConfig } from "../config/config.js";
 import {
+  canonicalizeMainSessionAlias,
  loadSessionStore,
+  resolveAgentIdFromSessionKey,
  resolveAgentMainSessionKey,
  resolveStorePath,
  saveSessionStore,
@@ -26,7 +29,7 @@ import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getQueueSize } from "../process/command-queue.js";
 import { CommandLane } from "../process/lanes.js";
 import { defaultRuntime, type RuntimeEnv } from "../runtime.js";
-import { normalizeAgentId } from "../routing/session-key.js";
+import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { emitHeartbeatEvent } from "./heartbeat-events.js";
 import {
  type HeartbeatRunResult,
@@ -69,6 +72,81 @@ export type HeartbeatSummary = {
 };

 const DEFAULT_HEARTBEAT_TARGET = "last";
+const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
+
+function resolveActiveHoursTimezone(cfg: ClawdbotConfig, raw?: string): string {
+  const trimmed = raw?.trim();
+  if (!trimmed || trimmed === "user") {
+    return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
+  }
+  if (trimmed === "local") {
+    const host = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return host?.trim() || "UTC";
+  }
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
+    return trimmed;
+  } catch {
+    return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
+  }
+}
+
+function parseActiveHoursTime(opts: { allow24: boolean }, raw?: string): number | null {
+  if (!raw || !ACTIVE_HOURS_TIME_PATTERN.test(raw)) return null;
+  const [hourStr, minuteStr] = raw.split(":");
+  const hour = Number(hourStr);
+  const minute = Number(minuteStr);
+  if (!Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+  if (hour === 24) {
+    if (!opts.allow24 || minute !== 0) return null;
+    return 24 * 60;
+  }
+  return hour * 60 + minute;
+}
+
+function resolveMinutesInTimeZone(nowMs: number, timeZone: string): number | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(new Date(nowMs));
+    const map: Record<string, string> = {};
+    for (const part of parts) {
+      if (part.type !== "literal") map[part.type] = part.value;
+    }
+    const hour = Number(map.hour);
+    const minute = Number(map.minute);
+    if (!Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+    return hour * 60 + minute;
+  } catch {
+    return null;
+  }
+}
+
+function isWithinActiveHours(
+  cfg: ClawdbotConfig,
+  heartbeat?: HeartbeatConfig,
+  nowMs?: number,
+): boolean {
+  const active = heartbeat?.activeHours;
+  if (!active) return true;
+
+  const startMin = parseActiveHoursTime({ allow24: false }, active.start);
+  const endMin = parseActiveHoursTime({ allow24: true }, active.end);
+  if (startMin === null || endMin === null) return true;
+  if (startMin === endMin) return true;
+
+  const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
+  const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);
+  if (currentMin === null) return true;
+
+  if (endMin > startMin) {
+    return currentMin >= startMin && currentMin < endMin;
+  }
+  return currentMin >= startMin || currentMin < endMin;
+}

 type HeartbeatAgentState = {
  agentId: string;
@@ -210,17 +288,53 @@ function resolveHeartbeatAckMaxChars(cfg: ClawdbotConfig, heartbeat?: HeartbeatC
  );
 }

-function resolveHeartbeatSession(cfg: ClawdbotConfig, agentId?: string) {
+function resolveHeartbeatSession(
+  cfg: ClawdbotConfig,
+  agentId?: string,
+  heartbeat?: HeartbeatConfig,
+) {
  const sessionCfg = cfg.session;
  const scope = sessionCfg?.scope ?? "per-sender";
  const resolvedAgentId = normalizeAgentId(agentId ?? resolveDefaultAgentId(cfg));
-  const sessionKey =
+  const mainSessionKey =
    scope === "global" ? "global" : resolveAgentMainSessionKey({ cfg, agentId: resolvedAgentId });
  const storeAgentId = scope === "global" ? resolveDefaultAgentId(cfg) : resolvedAgentId;
  const storePath = resolveStorePath(sessionCfg?.store, { agentId: storeAgentId });
  const store = loadSessionStore(storePath);
-  const entry = store[sessionKey];
-  return { sessionKey, storePath, store, entry };
+  const mainEntry = store[mainSessionKey];
+
+  if (scope === "global") {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const trimmed = heartbeat?.session?.trim() ?? "";
+  if (!trimmed) {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const normalized = trimmed.toLowerCase();
+  if (normalized === "main" || normalized === "global") {
+    return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
+  }
+
+  const candidate = toAgentStoreSessionKey({
+    agentId: resolvedAgentId,
+    requestKey: trimmed,
+    mainKey: cfg.session?.mainKey,
+  });
+  const canonical = canonicalizeMainSessionAlias({
+    cfg,
+    agentId: resolvedAgentId,
+    sessionKey: candidate,
+  });
+  if (canonical !== "global") {
+    const sessionAgentId = resolveAgentIdFromSessionKey(canonical);
+    if (sessionAgentId === normalizeAgentId(resolvedAgentId)) {
+      return { sessionKey: canonical, storePath, store, entry: store[canonical] };
+    }
+  }
+
+  return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
 }

 function resolveHeartbeatReplyPayload(
@@ -341,13 +455,17 @@ export async function runHeartbeatOnce(opts: {
    return { status: "skipped", reason: "disabled" };
  }

+  const startedAt = opts.deps?.nowMs?.() ?? Date.now();
+  if (!isWithinActiveHours(cfg, heartbeat, startedAt)) {
+    return { status: "skipped", reason: "quiet-hours" };
+  }
+
  const queueSize = (opts.deps?.getQueueSize ?? getQueueSize)(CommandLane.Main);
  if (queueSize > 0) {
    return { status: "skipped", reason: "requests-in-flight" };
  }

-  const startedAt = opts.deps?.nowMs?.() ?? Date.now();
-  const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId);
+  const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat);
  const previousUpdatedAt = entry?.updatedAt;
  const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
  const lastChannel = delivery.lastChannel;
--- a/src/infra/outbound/message-action-runner.ts
+++ b/src/infra/outbound/message-action-runner.ts
@@ -410,6 +410,21 @@ function parseButtonsParam(params: Record<string, unknown>): void {
  }
 }

+function parseCardParam(params: Record<string, unknown>): void {
+  const raw = params.card;
+  if (typeof raw !== "string") return;
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    delete params.card;
+    return;
+  }
+  try {
+    params.card = JSON.parse(trimmed) as unknown;
+  } catch {
+    throw new Error("--card must be valid JSON");
+  }
+}
+
 async function resolveChannel(cfg: ClawdbotConfig, params: Record<string, unknown>) {
  const channelHint = readStringParam(params, "channel");
  const selection = await resolveMessageChannelSelection({
@@ -558,10 +573,15 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
  const { cfg, params, channel, accountId, dryRun, gateway, input } = ctx;
  const action: ChannelMessageActionName = "send";
  const to = readStringParam(params, "to", { required: true });
-  const mediaHint = readStringParam(params, "media", { trim: false });
+  // Support media, path, and filePath parameters for attachments
+  const mediaHint =
+    readStringParam(params, "media", { trim: false }) ??
+    readStringParam(params, "path", { trim: false }) ??
+    readStringParam(params, "filePath", { trim: false });
+  const hasCard = params.card != null && typeof params.card === "object";
  let message =
    readStringParam(params, "message", {
-      required: !mediaHint,
+      required: !mediaHint && !hasCard,
      allowEmpty: true,
    }) ?? "";

@@ -570,7 +590,8 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
  params.message = message;
  if (!params.replyTo && parsed.replyToId) params.replyTo = parsed.replyToId;
  if (!params.media) {
-    params.media = parsed.mediaUrls?.[0] || parsed.mediaUrl || undefined;
+    // Use path/filePath if media not set, then fall back to parsed directives
+    params.media = mediaHint || parsed.mediaUrls?.[0] || parsed.mediaUrl || undefined;
  }

  message = await maybeApplyCrossContextMarker({
@@ -729,6 +750,7 @@ export async function runMessageAction(
  const cfg = input.cfg;
  const params = { ...input.params };
  parseButtonsParam(params);
+  parseCardParam(params);

  const action = input.action;
  if (action === "broadcast") {
--- a/src/infra/outbound/message-action-spec.ts
+++ b/src/infra/outbound/message-action-spec.ts
@@ -57,6 +57,7 @@ export const MESSAGE_ACTION_TARGET_MODE: Record<ChannelMessageActionName, Messag
 const ACTION_TARGET_ALIASES: Partial<Record<ChannelMessageActionName, string[]>> = {
  unsend: ["messageId"],
  edit: ["messageId"],
+  react: ["chatGuid", "chatIdentifier", "chatId"],
  renameGroup: ["chatGuid", "chatIdentifier", "chatId"],
  setGroupIcon: ["chatGuid", "chatIdentifier", "chatId"],
  addParticipant: ["chatGuid", "chatIdentifier", "chatId"],
--- a/src/infra/ports-format.ts
+++ b/src/infra/ports-format.ts
@@ -21,7 +21,7 @@ export function buildPortHints(listeners: PortListener[], port: number): string[
  const hints: string[] = [];
  if (kinds.has("gateway")) {
    hints.push(
-      `Gateway already running locally. Stop it (${formatCliCommand("clawdbot daemon stop")}) or use a different port.`,
+      `Gateway already running locally. Stop it (${formatCliCommand("clawdbot gateway stop")}) or use a different port.`,
    );
  }
  if (kinds.has("ssh")) {
--- a/src/infra/ports-inspect.test.ts
+++ b/src/infra/ports-inspect.test.ts
@@ -0,0 +1,35 @@
+import net from "node:net";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const runCommandWithTimeoutMock = vi.fn();
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+
+const describeUnix = process.platform === "win32" ? describe.skip : describe;
+
+describeUnix("inspectPortUsage", () => {
+  beforeEach(() => {
+    runCommandWithTimeoutMock.mockReset();
+  });
+
+  it("reports busy when lsof is missing but loopback listener exists", async () => {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = (server.address() as net.AddressInfo).port;
+
+    runCommandWithTimeoutMock.mockRejectedValueOnce(
+      Object.assign(new Error("spawn lsof ENOENT"), { code: "ENOENT" }),
+    );
+
+    try {
+      const { inspectPortUsage } = await import("./ports-inspect.js");
+      const result = await inspectPortUsage(port);
+      expect(result.status).toBe("busy");
+      expect(result.errors?.some((err) => err.includes("ENOENT"))).toBe(true);
+    } finally {
+      server.close();
+    }
+  });
+});
--- a/src/infra/ports-inspect.ts
+++ b/src/infra/ports-inspect.ts
@@ -1,5 +1,6 @@
 import net from "node:net";
 import { runCommandWithTimeout } from "../process/exec.js";
+import { resolveLsofCommand } from "./ports-lsof.js";
 import { buildPortHints } from "./ports-format.js";
 import type { PortListener, PortUsage, PortUsageStatus } from "./ports-types.js";

@@ -71,7 +72,8 @@ async function readUnixListeners(
  port: number,
 ): Promise<{ listeners: PortListener[]; detail?: string; errors: string[] }> {
  const errors: string[] = [];
-  const res = await runCommandSafe(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpFcn"]);
+  const lsof = await resolveLsofCommand();
+  const res = await runCommandSafe([lsof, "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpFcn"]);
  if (res.code === 0) {
    const listeners = parseLsofFieldOutput(res.stdout);
    await Promise.all(
@@ -87,11 +89,12 @@ async function readUnixListeners(
    );
    return { listeners, detail: res.stdout.trim() || undefined, errors };
  }
-  if (res.code === 1) {
+  const stderr = res.stderr.trim();
+  if (res.code === 1 && !res.error && !stderr) {
    return { listeners: [], detail: undefined, errors };
  }
  if (res.error) errors.push(res.error);
-  const detail = [res.stderr.trim(), res.stdout.trim()].filter(Boolean).join("\n");
+  const detail = [stderr, res.stdout.trim()].filter(Boolean).join("\n");
  if (detail) errors.push(detail);
  return { listeners: [], detail: undefined, errors };
 }
@@ -175,7 +178,7 @@ async function readWindowsListeners(
  return { listeners, detail: res.stdout.trim() || undefined, errors };
 }

-async function checkPortInUse(port: number): Promise<PortUsageStatus> {
+async function tryListenOnHost(port: number, host: string): Promise<PortUsageStatus | "skip"> {
  try {
    await new Promise<void>((resolve, reject) => {
      const tester = net
@@ -184,15 +187,29 @@ async function checkPortInUse(port: number): Promise<PortUsageStatus> {
        .once("listening", () => {
          tester.close(() => resolve());
        })
-        .listen(port);
+        .listen({ port, host, exclusive: true });
    });
    return "free";
  } catch (err) {
    if (isErrno(err) && err.code === "EADDRINUSE") return "busy";
+    if (isErrno(err) && (err.code === "EADDRNOTAVAIL" || err.code === "EAFNOSUPPORT")) {
+      return "skip";
+    }
    return "unknown";
  }
 }

+async function checkPortInUse(port: number): Promise<PortUsageStatus> {
+  const hosts = ["127.0.0.1", "0.0.0.0", "::1", "::"];
+  let sawUnknown = false;
+  for (const host of hosts) {
+    const result = await tryListenOnHost(port, host);
+    if (result === "busy") return "busy";
+    if (result === "unknown") sawUnknown = true;
+  }
+  return sawUnknown ? "unknown" : "free";
+}
+
 export async function inspectPortUsage(port: number): Promise<PortUsage> {
  const errors: string[] = [];
  const result =
--- a/src/infra/ports-lsof.ts
+++ b/src/infra/ports-lsof.ts
@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+
+const LSOF_CANDIDATES =
+  process.platform === "darwin"
+    ? ["/usr/sbin/lsof", "/usr/bin/lsof"]
+    : ["/usr/bin/lsof", "/usr/sbin/lsof"];
+
+async function canExecute(path: string): Promise<boolean> {
+  try {
+    await fsPromises.access(path, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveLsofCommand(): Promise<string> {
+  for (const candidate of LSOF_CANDIDATES) {
+    if (await canExecute(candidate)) return candidate;
+  }
+  return "lsof";
+}
+
+export function resolveLsofCommandSync(): string {
+  for (const candidate of LSOF_CANDIDATES) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // keep trying
+    }
+  }
+  return "lsof";
+}
--- a/src/infra/provider-usage.load.ts
+++ b/src/infra/provider-usage.load.ts
@@ -19,6 +19,7 @@ import type {
  UsageProviderId,
  UsageSummary,
 } from "./provider-usage.types.js";
+import { resolveFetch } from "./fetch.js";

 type UsageSummaryOptions = {
  now?: number;
@@ -34,7 +35,10 @@ export async function loadProviderUsageSummary(
 ): Promise<UsageSummary> {
  const now = opts.now ?? Date.now();
  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const fetchFn = opts.fetch ?? fetch;
+  const fetchFn = resolveFetch(opts.fetch);
+  if (!fetchFn) {
+    throw new Error("fetch is not available");
+  }

  const auths = await resolveProviderAuths({
    providers: opts.providers ?? usageProviders,
--- a/src/infra/update-check.test.ts
+++ b/src/infra/update-check.test.ts
@@ -28,20 +28,20 @@ describe("resolveNpmChannelTag", () => {
  });

  it("falls back to latest when beta is older", async () => {
-    versionByTag.beta = "2026.1.19-beta.1";
-    versionByTag.latest = "2026.1.20-1";
+    versionByTag.beta = "1.0.0-beta.1";
+    versionByTag.latest = "1.0.1-1";

    const resolved = await resolveNpmChannelTag({ channel: "beta", timeoutMs: 1000 });

-    expect(resolved).toEqual({ tag: "latest", version: "2026.1.20-1" });
+    expect(resolved).toEqual({ tag: "latest", version: "1.0.1-1" });
  });

  it("keeps beta when beta is not older", async () => {
-    versionByTag.beta = "2026.1.20-beta.1";
-    versionByTag.latest = "2026.1.20-1";
+    versionByTag.beta = "1.0.2-beta.1";
+    versionByTag.latest = "1.0.1-1";

    const resolved = await resolveNpmChannelTag({ channel: "beta", timeoutMs: 1000 });

-    expect(resolved).toEqual({ tag: "beta", version: "2026.1.20-beta.1" });
+    expect(resolved).toEqual({ tag: "beta", version: "1.0.2-beta.1" });
  });
 });
--- a/src/infra/update-runner.test.ts
+++ b/src/infra/update-runner.test.ts
@@ -74,7 +74,9 @@ describe("runGatewayUpdate", () => {
        stdout: "origin/main",
      },
      [`git -C ${tempDir} fetch --all --prune --tags`]: { stdout: "" },
-      [`git -C ${tempDir} rebase @{upstream}`]: { code: 1, stderr: "conflict" },
+      [`git -C ${tempDir} rev-parse @{upstream}`]: { stdout: "upstream123" },
+      [`git -C ${tempDir} rev-list --max-count=10 upstream123`]: { stdout: "upstream123\n" },
+      [`git -C ${tempDir} rebase upstream123`]: { code: 1, stderr: "conflict" },
      [`git -C ${tempDir} rebase --abort`]: { stdout: "" },
    });

@@ -96,8 +98,8 @@ describe("runGatewayUpdate", () => {
      JSON.stringify({ name: "clawdbot", version: "1.0.0", packageManager: "pnpm@8.0.0" }),
      "utf-8",
    );
-    const stableTag = "v2026.1.20-1";
-    const betaTag = "v2026.1.19-beta.2";
+    const stableTag = "v1.0.1-1";
+    const betaTag = "v1.0.0-beta.2";
    const { runner, calls } = createRunner({
      [`git -C ${tempDir} rev-parse --show-toplevel`]: { stdout: tempDir },
      [`git -C ${tempDir} rev-parse HEAD`]: { stdout: "abc123" },
--- a/src/infra/update-runner.ts
+++ b/src/infra/update-runner.ts
@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";

 import { type CommandOptions, runCommandWithTimeout } from "../process/exec.js";
@@ -63,6 +64,7 @@ type UpdateRunnerOptions = {

 const DEFAULT_TIMEOUT_MS = 20 * 60_000;
 const MAX_LOG_CHARS = 8000;
+const PREFLIGHT_MAX_COMMITS = 10;
 const START_DIRS = ["cwd", "argv1", "process"];

 function normalizeDir(value?: string | null) {
@@ -420,8 +422,152 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
      );
      steps.push(fetchStep);

+      const upstreamShaStep = await runStep(
+        step(
+          "git rev-parse @{upstream}",
+          ["git", "-C", gitRoot, "rev-parse", "@{upstream}"],
+          gitRoot,
+        ),
+      );
+      steps.push(upstreamShaStep);
+      const upstreamSha = upstreamShaStep.stdoutTail?.trim();
+      if (!upstreamShaStep.stdoutTail || !upstreamSha) {
+        return {
+          status: "error",
+          mode: "git",
+          root: gitRoot,
+          reason: "no-upstream-sha",
+          before: { sha: beforeSha, version: beforeVersion },
+          steps,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
+      const revListStep = await runStep(
+        step(
+          "git rev-list",
+          ["git", "-C", gitRoot, "rev-list", `--max-count=${PREFLIGHT_MAX_COMMITS}`, upstreamSha],
+          gitRoot,
+        ),
+      );
+      steps.push(revListStep);
+      if (revListStep.exitCode !== 0) {
+        return {
+          status: "error",
+          mode: "git",
+          root: gitRoot,
+          reason: "preflight-revlist-failed",
+          before: { sha: beforeSha, version: beforeVersion },
+          steps,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
+      const candidates = (revListStep.stdoutTail ?? "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+      if (candidates.length === 0) {
+        return {
+          status: "error",
+          mode: "git",
+          root: gitRoot,
+          reason: "preflight-no-candidates",
+          before: { sha: beforeSha, version: beforeVersion },
+          steps,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
+      const manager = await detectPackageManager(gitRoot);
+      const preflightRoot = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-update-preflight-"));
+      const worktreeDir = path.join(preflightRoot, "worktree");
+      const worktreeStep = await runStep(
+        step(
+          "preflight worktree",
+          ["git", "-C", gitRoot, "worktree", "add", "--detach", worktreeDir, upstreamSha],
+          gitRoot,
+        ),
+      );
+      steps.push(worktreeStep);
+      if (worktreeStep.exitCode !== 0) {
+        await fs.rm(preflightRoot, { recursive: true, force: true }).catch(() => {});
+        return {
+          status: "error",
+          mode: "git",
+          root: gitRoot,
+          reason: "preflight-worktree-failed",
+          before: { sha: beforeSha, version: beforeVersion },
+          steps,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
+      let selectedSha: string | null = null;
+      try {
+        for (const sha of candidates) {
+          const shortSha = sha.slice(0, 8);
+          const checkoutStep = await runStep(
+            step(
+              `preflight checkout (${shortSha})`,
+              ["git", "-C", worktreeDir, "checkout", "--detach", sha],
+              worktreeDir,
+            ),
+          );
+          steps.push(checkoutStep);
+          if (checkoutStep.exitCode !== 0) continue;
+
+          const depsStep = await runStep(
+            step(`preflight deps install (${shortSha})`, managerInstallArgs(manager), worktreeDir),
+          );
+          steps.push(depsStep);
+          if (depsStep.exitCode !== 0) continue;
+
+          const lintStep = await runStep(
+            step(`preflight lint (${shortSha})`, managerScriptArgs(manager, "lint"), worktreeDir),
+          );
+          steps.push(lintStep);
+          if (lintStep.exitCode !== 0) continue;
+
+          const buildStep = await runStep(
+            step(`preflight build (${shortSha})`, managerScriptArgs(manager, "build"), worktreeDir),
+          );
+          steps.push(buildStep);
+          if (buildStep.exitCode !== 0) continue;
+
+          selectedSha = sha;
+          break;
+        }
+      } finally {
+        const removeStep = await runStep(
+          step(
+            "preflight cleanup",
+            ["git", "-C", gitRoot, "worktree", "remove", "--force", worktreeDir],
+            gitRoot,
+          ),
+        );
+        steps.push(removeStep);
+        await runCommand(["git", "-C", gitRoot, "worktree", "prune"], {
+          cwd: gitRoot,
+          timeoutMs,
+        }).catch(() => null);
+        await fs.rm(preflightRoot, { recursive: true, force: true }).catch(() => {});
+      }
+
+      if (!selectedSha) {
+        return {
+          status: "error",
+          mode: "git",
+          root: gitRoot,
+          reason: "preflight-no-good-commit",
+          before: { sha: beforeSha, version: beforeVersion },
+          steps,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
      const rebaseStep = await runStep(
-        step("git rebase", ["git", "-C", gitRoot, "rebase", "@{upstream}"], gitRoot),
+        step("git rebase", ["git", "-C", gitRoot, "rebase", selectedSha], gitRoot),
      );
      steps.push(rebaseStep);
      if (rebaseStep.exitCode !== 0) {