feat(hooks): run boot.md on gateway startup

src/gateway/boot.test.ts

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const agentCommand = vi.fn();
+
+vi.mock("../commands/agent.js", () => ({ agentCommand }));
+
+const { runBootOnce } = await import("./boot.js");
+const { resolveMainSessionKey } = await import("../config/sessions/main-session.js");
+
+describe("runBootOnce", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const makeDeps = () => ({
+    sendMessageWhatsApp: vi.fn(),
+    sendMessageTelegram: vi.fn(),
+    sendMessageDiscord: vi.fn(),
+    sendMessageSlack: vi.fn(),
+    sendMessageSignal: vi.fn(),
+    sendMessageIMessage: vi.fn(),
+  });
+
+  it("skips when BOOT.md is missing", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-boot-"));
+    await expect(
+      runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir }),
+    ).resolves.toEqual({ status: "skipped", reason: "missing" });
+    expect(agentCommand).not.toHaveBeenCalled();
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it("skips when BOOT.md is empty", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-boot-"));
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), "   \n", "utf-8");
+    await expect(
+      runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir }),
+    ).resolves.toEqual({ status: "skipped", reason: "empty" });
+    expect(agentCommand).not.toHaveBeenCalled();
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it("runs agent command when BOOT.md exists", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-boot-"));
+    const content = "Say hello when you wake up.";
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), content, "utf-8");
+
+    agentCommand.mockResolvedValue(undefined);
+    await expect(
+      runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir }),
+    ).resolves.toEqual({ status: "ran" });
+
+    expect(agentCommand).toHaveBeenCalledTimes(1);
+    const call = agentCommand.mock.calls[0]?.[0];
+    expect(call).toEqual(
+      expect.objectContaining({
+        deliver: false,
+        sessionKey: resolveMainSessionKey({}),
+      }),
+    );
+    expect(call?.message).toContain("BOOT.md:");
+    expect(call?.message).toContain(content);
+    expect(call?.message).toContain("NO_REPLY");
+
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+});

src/gateway/boot.ts

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
+import type { CliDeps } from "../cli/deps.js";
+import type { ClawdbotConfig } from "../config/config.js";
+import { resolveMainSessionKey } from "../config/sessions/main-session.js";
+import { agentCommand } from "../commands/agent.js";
+import { createSubsystemLogger } from "../logging.js";
+import { type RuntimeEnv, defaultRuntime } from "../runtime.js";
+
+const log = createSubsystemLogger("gateway/boot");
+const BOOT_FILENAME = "BOOT.md";
+
+export type BootRunResult =
+  | { status: "skipped"; reason: "missing" | "empty" }
+  | { status: "ran" }
+  | { status: "failed"; reason: string };
+
+function buildBootPrompt(content: string) {
+  return [
+    "You are running a boot check. Follow BOOT.md instructions exactly.",
+    "",
+    "BOOT.md:",
+    content,
+    "",
+    "If BOOT.md asks you to send a message, use the message tool (action=send with channel + target).",
+    "Use the `target` field (not `to`) for message tool destinations.",
+    `After sending with the message tool, reply with ONLY: ${SILENT_REPLY_TOKEN}.`,
+    `If nothing needs attention, reply with ONLY: ${SILENT_REPLY_TOKEN}.`,
+  ].join("\n");
+}
+
+async function loadBootFile(
+  workspaceDir: string,
+): Promise<{ content?: string; status: "ok" | "missing" | "empty" }> {
+  const bootPath = path.join(workspaceDir, BOOT_FILENAME);
+  try {
+    const content = await fs.readFile(bootPath, "utf-8");
+    const trimmed = content.trim();
+    if (!trimmed) return { status: "empty" };
+    return { status: "ok", content: trimmed };
+  } catch (err) {
+    const anyErr = err as { code?: string };
+    if (anyErr.code === "ENOENT") return { status: "missing" };
+    throw err;
+  }
+}
+
+export async function runBootOnce(params: {
+  cfg: ClawdbotConfig;
+  deps: CliDeps;
+  workspaceDir: string;
+}): Promise<BootRunResult> {
+  const bootRuntime: RuntimeEnv = {
+    log: () => {},
+    error: (message) => log.error(String(message)),
+    exit: defaultRuntime.exit,
+  };
+  let result: Awaited<ReturnType<typeof loadBootFile>>;
+  try {
+    result = await loadBootFile(params.workspaceDir);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`boot: failed to read ${BOOT_FILENAME}: ${message}`);
+    return { status: "failed", reason: message };
+  }
+
+  if (result.status === "missing" || result.status === "empty") {
+    return { status: "skipped", reason: result.status };
+  }
+
+  const sessionKey = resolveMainSessionKey(params.cfg);
+  const message = buildBootPrompt(result.content ?? "");
+
+  try {
+    await agentCommand(
+      {
+        message,
+        sessionKey,
+        deliver: false,
+      },
+      bootRuntime,
+      params.deps,
+    );
+    return { status: "ran" };
+  } catch (err) {
+    const messageText = err instanceof Error ? err.message : String(err);
+    log.error(`boot: agent run failed: ${messageText}`);
+    return { status: "failed", reason: messageText };
+  }
+}

src/gateway/server-startup.ts

@@ -8,7 +8,11 @@ import {
 import type { CliDeps } from "../cli/deps.js";
 import type { loadConfig } from "../config/config.js";
 import { startGmailWatcher } from "../hooks/gmail-watcher.js";
-import { clearInternalHooks } from "../hooks/internal-hooks.js";
+import {
+  clearInternalHooks,
+  createInternalHookEvent,
+  triggerInternalHook,
+} from "../hooks/internal-hooks.js";
 import { loadInternalHooks } from "../hooks/loader.js";
 import type { loadClawdbotPlugins } from "../plugins/loader.js";
 import { type PluginServicesHandle, startPluginServices } from "../plugins/services.js";
@@ -122,6 +126,17 @@ export async function startGatewaySidecars(params: {
     );
   }
 
+  if (params.cfg.hooks?.internal?.enabled) {
+    setTimeout(() => {
+      const hookEvent = createInternalHookEvent("gateway", "startup", "gateway:startup", {
+        cfg: params.cfg,
+        deps: params.deps,
+        workspaceDir: params.defaultWorkspaceDir,
+      });
+      void triggerInternalHook(hookEvent);
+    }, 250);
+  }
+
   let pluginServices: PluginServicesHandle | null = null;
   try {
     pluginServices = await startPluginServices({