From 9a7f2d2f1666c6f3105fac0d093ca263052115be Mon Sep 17 00:00:00 2001
From: "Doink (OpenClaw)" <charlie+doink@kindo.ai>
Date: Sat, 7 Mar 2026 16:21:58 -0800
Subject: [PATCH] feat: callback metadata, lifecycle webhooks, spawn ENOENT
 retry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- #104: Add --callback-session and --callback-agent CLI flags to launch.
  Stored in session.meta as openclaw_callback_session_key / openclaw_callback_agent_id.
  Propagated through daemon launch, multi-adapter orchestration, and surfaced in
  list/status --json output.

- #108: Native lifecycle webhook emission from daemon. Reads webhook_url and
  webhook_secret from config (~/.agentctl/config.json) or env vars
  (AGENTCTL_WEBHOOK_URL, AGENTCTL_WEBHOOK_SECRET). On running→stopped transitions
  POSTs {hook_type, session_id, cwd, adapter, duration_seconds, exit_status,
  summary, meta, timestamp} with HMAC-SHA256 signature. Fire-and-forget across
  all detection paths (session.stop, reconcile, PID liveness cleanup).

- #120: Spawn ENOENT retry. All adapter launch() methods now use spawnWithRetry()
  which on ENOENT waits 500ms, calls clearBinaryCache(), re-resolves the binary
  path, and retries once.

Fixes #104, Fixes #108, Fixes #120

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 src/adapters/claude-code.ts        |   9 +-
 src/adapters/codex.ts              |   8 +-
 src/adapters/opencode.ts           |   8 +-
 src/adapters/pi-rust.ts            |   8 +-
 src/adapters/pi.ts                 |   9 +-
 src/cli.ts                         |  20 ++++
 src/core/types.ts                  |   4 +
 src/daemon/server.ts               |  48 ++++++++-
 src/daemon/webhook.test.ts         | 166 +++++++++++++++++++++++++++++
 src/daemon/webhook.ts              | 102 ++++++++++++++++++
 src/launch-orchestrator.ts         |  14 +++
 src/utils/config.ts                |   2 +
 src/utils/spawn-with-retry.test.ts |  91 ++++++++++++++++
 src/utils/spawn-with-retry.ts      |  77 +++++++++++++
 14 files changed, 532 insertions(+), 34 deletions(-)
 create mode 100644 src/daemon/webhook.test.ts
 create mode 100644 src/daemon/webhook.ts
 create mode 100644 src/utils/spawn-with-retry.test.ts
 create mode 100644 src/utils/spawn-with-retry.ts

diff --git a/src/adapters/claude-code.ts b/src/adapters/claude-code.ts
index 5f1ceae..d0d6ee3 100644
--- a/src/adapters/claude-code.ts
+++ b/src/adapters/claude-code.ts
@@ -24,6 +24,7 @@ import {
   writePromptFile,
 } from "../utils/prompt-file.js";
 import { resolveBinaryPath } from "../utils/resolve-binary.js";
+import { spawnWithRetry } from "../utils/spawn-with-retry.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -480,19 +481,13 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     const logFd = await fs.open(logPath, "w");
 
     // Capture stderr to the same log file for debugging launch failures
-    const claudePath = await resolveBinaryPath("claude");
-    const child = spawn(claudePath, args, {
+    const child = await spawnWithRetry("claude", args, {
       cwd,
       env,
       stdio: [promptFd ? promptFd.fd : "ignore", logFd.fd, logFd.fd],
       detached: true,
     });
 
-    // Handle spawn errors (e.g. ENOENT) gracefully instead of crashing the daemon
-    child.on("error", (err) => {
-      console.error(`[claude-code] spawn error: ${err.message}`);
-    });
-
     // Fully detach: child runs in its own process group.
     // When the wrapper gets SIGTERM, the child keeps running.
     child.unref();
diff --git a/src/adapters/codex.ts b/src/adapters/codex.ts
index d713848..166ef8a 100644
--- a/src/adapters/codex.ts
+++ b/src/adapters/codex.ts
@@ -23,6 +23,7 @@ import {
   writePromptFile,
 } from "../utils/prompt-file.js";
 import { resolveBinaryPath } from "../utils/resolve-binary.js";
+import { spawnWithRetry } from "../utils/spawn-with-retry.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -280,18 +281,13 @@ export class CodexAdapter implements AgentAdapter {
     const logPath = path.join(this.sessionsMetaDir, `launch-${Date.now()}.log`);
     const logFd = await fs.open(logPath, "w");
 
-    const codexPath = await resolveBinaryPath("codex");
-    const child = spawn(codexPath, args, {
+    const child = await spawnWithRetry("codex", args, {
       cwd,
       env,
       stdio: [promptFd ? promptFd.fd : "ignore", logFd.fd, "ignore"],
       detached: true,
     });
 
-    child.on("error", (err) => {
-      console.error(`[codex] spawn error: ${err.message}`);
-    });
-
     child.unref();
 
     const pid = child.pid;
diff --git a/src/adapters/opencode.ts b/src/adapters/opencode.ts
index 1094653..e5dab0b 100644
--- a/src/adapters/opencode.ts
+++ b/src/adapters/opencode.ts
@@ -23,6 +23,7 @@ import {
   writePromptFile,
 } from "../utils/prompt-file.js";
 import { resolveBinaryPath } from "../utils/resolve-binary.js";
+import { spawnWithRetry } from "../utils/spawn-with-retry.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -372,18 +373,13 @@ export class OpenCodeAdapter implements AgentAdapter {
     const logPath = path.join(this.sessionsMetaDir, `launch-${Date.now()}.log`);
     const logFd = await fs.open(logPath, "w");
 
-    const opencodePath = await resolveBinaryPath("opencode");
-    const child = spawn(opencodePath, args, {
+    const child = await spawnWithRetry("opencode", args, {
       cwd,
       env,
       stdio: [promptFd ? promptFd.fd : "ignore", logFd.fd, logFd.fd],
       detached: true,
     });
 
-    child.on("error", (err) => {
-      console.error(`[opencode] spawn error: ${err.message}`);
-    });
-
     child.unref();
 
     const pid = child.pid;
diff --git a/src/adapters/pi-rust.ts b/src/adapters/pi-rust.ts
index e70d0ae..6c9ab92 100644
--- a/src/adapters/pi-rust.ts
+++ b/src/adapters/pi-rust.ts
@@ -23,6 +23,7 @@ import {
   writePromptFile,
 } from "../utils/prompt-file.js";
 import { resolveBinaryPath } from "../utils/resolve-binary.js";
+import { spawnWithRetry } from "../utils/spawn-with-retry.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -378,18 +379,13 @@ export class PiRustAdapter implements AgentAdapter {
     const logPath = path.join(this.sessionsMetaDir, `launch-${Date.now()}.log`);
     const logFd = await fs.open(logPath, "w");
 
-    const piRustPath = await resolveBinaryPath("pi-rust");
-    const child = spawn(piRustPath, args, {
+    const child = await spawnWithRetry("pi-rust", args, {
       cwd,
       env,
       stdio: [promptFd ? promptFd.fd : "ignore", logFd.fd, "ignore"],
       detached: true,
     });
 
-    child.on("error", (err) => {
-      console.error(`[pi-rust] spawn error: ${err.message}`);
-    });
-
     child.unref();
 
     const pid = child.pid;
diff --git a/src/adapters/pi.ts b/src/adapters/pi.ts
index 142a1d4..00b6ef9 100644
--- a/src/adapters/pi.ts
+++ b/src/adapters/pi.ts
@@ -23,6 +23,7 @@ import {
   writePromptFile,
 } from "../utils/prompt-file.js";
 import { resolveBinaryPath } from "../utils/resolve-binary.js";
+import { spawnWithRetry } from "../utils/spawn-with-retry.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -356,19 +357,13 @@ export class PiAdapter implements AgentAdapter {
     const logPath = path.join(this.sessionsMetaDir, `launch-${Date.now()}.log`);
     const logFd = await fs.open(logPath, "w");
 
-    const piPath = await resolveBinaryPath("pi");
-    const child = spawn(piPath, args, {
+    const child = await spawnWithRetry("pi", args, {
       cwd,
       env,
       stdio: [promptFd ? promptFd.fd : "ignore", logFd.fd, logFd.fd],
       detached: true,
     });
 
-    child.on("error", (err) => {
-      console.error(`[pi] spawn error: ${err.message}`);
-    });
-
-    // Fully detach: child runs in its own process group.
     child.unref();
 
     const pid = child.pid;
diff --git a/src/cli.ts b/src/cli.ts
index 437ca45..0f969ad 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -567,6 +567,8 @@ program
   .option("--matrix <file>", "YAML matrix file for advanced sweep launch")
   .option("--on-create <script>", "Hook: run after session is created")
   .option("--on-complete <script>", "Hook: run after session completes")
+  .option("--callback-session <key>", "Callback session key for orchestration")
+  .option("--callback-agent <id>", "Callback agent ID for orchestration")
   .allowUnknownOption() // Allow interleaved --adapter/--model for parseAdapterSlots
   .action(async (adapterName: string | undefined, opts) => {
     // Load persistent config defaults; CLI flags override config values
@@ -586,6 +588,10 @@ program
           }
         : undefined;
 
+    // Collect callback metadata
+    const callbackSessionKey = opts.callbackSession as string | undefined;
+    const callbackAgentId = opts.callbackAgent as string | undefined;
+
     // --- Multi-adapter / matrix detection ---
     let slots: AdapterSlot[] = [];
 
@@ -657,6 +663,8 @@ program
           cwd,
           hooks,
           adapters,
+          callbackSessionKey,
+          callbackAgentId,
           onSessionLaunched: (slotResult) => {
             // Track in daemon if available
             if (daemonRunning && !slotResult.error) {
@@ -740,6 +748,8 @@ program
             ? { repo: worktreeInfo.repo, branch: worktreeInfo.branch }
             : undefined,
           hooks,
+          callbackSessionKey,
+          callbackAgentId,
         });
         console.log(
           `Launched session ${shortId(session.id)} (PID: ${session.pid})`,
@@ -777,7 +787,17 @@ program
         cwd,
         model,
         hooks,
+        callbackSessionKey,
+        callbackAgentId,
       });
+
+      // Inject callback metadata into session meta
+      if (callbackSessionKey) {
+        session.meta.openclaw_callback_session_key = callbackSessionKey;
+      }
+      if (callbackAgentId) {
+        session.meta.openclaw_callback_agent_id = callbackAgentId;
+      }
       console.log(
         `Launched session ${shortId(session.id)} (PID: ${session.pid})`,
       );
diff --git a/src/core/types.ts b/src/core/types.ts
index c7f439b..8819ee3 100644
--- a/src/core/types.ts
+++ b/src/core/types.ts
@@ -102,6 +102,10 @@ export interface LaunchOpts {
   worktree?: { repo: string; branch: string };
   /** Lifecycle hooks — shell commands to run at various points */
   hooks?: LifecycleHooks;
+  /** Callback session key for orchestration (stored in meta) */
+  callbackSessionKey?: string;
+  /** Callback agent ID for orchestration (stored in meta) */
+  callbackAgentId?: string;
 }
 
 export interface LifecycleHooks {
diff --git a/src/daemon/server.ts b/src/daemon/server.ts
index 2c14aed..7890ccb 100644
--- a/src/daemon/server.ts
+++ b/src/daemon/server.ts
@@ -15,12 +15,20 @@ import { PiRustAdapter } from "../adapters/pi-rust.js";
 import type { AgentAdapter } from "../core/types.js";
 import { migrateLocks } from "../migration/migrate-locks.js";
 
+import { loadConfig } from "../utils/config.js";
 import { clearBinaryCache } from "../utils/resolve-binary.js";
 import { FuseEngine } from "./fuse-engine.js";
 import { LockManager } from "./lock-manager.js";
 import { MetricsRegistry } from "./metrics.js";
 import { SessionTracker } from "./session-tracker.js";
+import type { SessionRecord } from "./state.js";
 import { StateManager } from "./state.js";
+import {
+  buildWebhookPayload,
+  emitWebhook,
+  resolveWebhookConfig,
+  type WebhookConfig,
+} from "./webhook.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -98,6 +106,10 @@ export async function startDaemon(opts: DaemonStartOpts = {}): Promise<{
     "pi-rust": new PiRustAdapter(),
   };
 
+  // 7a. Resolve webhook config from config file + env
+  const config = await loadConfig(path.join(configDir, "config.json"));
+  const webhookConfig = resolveWebhookConfig(config);
+
   const lockManager = new LockManager(state);
   const emitter = new EventEmitter();
   const fuseEngine = new FuseEngine(state, {
@@ -112,11 +124,22 @@ export async function startDaemon(opts: DaemonStartOpts = {}): Promise<{
     metrics.recordFuseExpired();
   });
 
+  // Helper: emit webhook for a stopped session (fire-and-forget)
+  const emitSessionStoppedWebhook = (record: SessionRecord) => {
+    if (!webhookConfig) return;
+    const payload = buildWebhookPayload(record);
+    emitWebhook(webhookConfig, payload);
+  };
+
   // 8. Initial PID liveness cleanup for daemon-launched sessions
   //    (replaces the old validateAllSessions — much simpler, only checks launches)
   const initialDead = sessionTracker.cleanupDeadLaunches();
   if (initialDead.length > 0) {
-    for (const id of initialDead) lockManager.autoUnlock(id);
+    for (const id of initialDead) {
+      lockManager.autoUnlock(id);
+      const rec = state.getSession(id);
+      if (rec) emitSessionStoppedWebhook(rec);
+    }
     console.error(
       `Startup cleanup: marked ${initialDead.length} dead launches as stopped`,
     );
@@ -128,6 +151,8 @@ export async function startDaemon(opts: DaemonStartOpts = {}): Promise<{
   // 10. Start periodic PID liveness check for lock cleanup (30s interval)
   sessionTracker.startLaunchCleanup((deadId) => {
     lockManager.autoUnlock(deadId);
+    const rec = state.getSession(deadId);
+    if (rec) emitSessionStoppedWebhook(rec);
   });
 
   // 11. Create request handler
@@ -140,6 +165,8 @@ export async function startDaemon(opts: DaemonStartOpts = {}): Promise<{
     state,
     configDir,
     sockPath,
+    webhookConfig,
+    emitSessionStoppedWebhook,
   });
 
   // 12. Start Unix socket server
@@ -322,6 +349,8 @@ interface HandlerContext {
   state: StateManager;
   configDir: string;
   sockPath: string;
+  webhookConfig: WebhookConfig | null;
+  emitSessionStoppedWebhook: (record: SessionRecord) => void;
 }
 
 function createRequestHandler(ctx: HandlerContext) {
@@ -378,9 +407,11 @@ function createRequestHandler(ctx: HandlerContext) {
         const { sessions: allSessions, stoppedLaunchIds } =
           ctx.sessionTracker.reconcileAndEnrich(discovered, succeededAdapters);
 
-        // Release locks for sessions that disappeared from adapter results
+        // Release locks and emit webhooks for sessions that disappeared
         for (const id of stoppedLaunchIds) {
           ctx.lockManager.autoUnlock(id);
+          const rec = ctx.state.getSession(id);
+          if (rec) ctx.emitSessionStoppedWebhook(rec);
         }
 
         // Apply filters
@@ -522,6 +553,8 @@ function createRequestHandler(ctx: HandlerContext) {
           adapterOpts: params.adapterOpts as
             | Record<string, unknown>
             | undefined,
+          callbackSessionKey: params.callbackSessionKey as string | undefined,
+          callbackAgentId: params.callbackAgentId as string | undefined,
         });
 
         // Propagate group tag if provided
@@ -529,6 +562,16 @@ function createRequestHandler(ctx: HandlerContext) {
           session.group = params.group as string;
         }
 
+        // Propagate callback metadata
+        if (params.callbackSessionKey) {
+          session.meta.openclaw_callback_session_key =
+            params.callbackSessionKey as string;
+        }
+        if (params.callbackAgentId) {
+          session.meta.openclaw_callback_agent_id =
+            params.callbackAgentId as string;
+        }
+
         const record = ctx.sessionTracker.track(session, adapterName);
 
         // Auto-lock
@@ -576,6 +619,7 @@ function createRequestHandler(ctx: HandlerContext) {
         const stopped = ctx.sessionTracker.onSessionExit(sessionId);
         if (stopped) {
           ctx.metrics.recordSessionStopped();
+          ctx.emitSessionStoppedWebhook(stopped);
         }
 
         return null;
diff --git a/src/daemon/webhook.test.ts b/src/daemon/webhook.test.ts
new file mode 100644
index 0000000..e57365a
--- /dev/null
+++ b/src/daemon/webhook.test.ts
@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionRecord } from "./state.js";
+import {
+  buildWebhookPayload,
+  computeSignature,
+  emitWebhook,
+  resolveWebhookConfig,
+} from "./webhook.js";
+
+describe("resolveWebhookConfig", () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("returns null when no url configured", () => {
+    delete process.env.AGENTCTL_WEBHOOK_URL;
+    expect(resolveWebhookConfig()).toBeNull();
+    expect(resolveWebhookConfig({})).toBeNull();
+  });
+
+  it("reads from config object", () => {
+    delete process.env.AGENTCTL_WEBHOOK_URL;
+    delete process.env.AGENTCTL_WEBHOOK_SECRET;
+    const cfg = resolveWebhookConfig({
+      webhook_url: "https://example.com/hook",
+      webhook_secret: "s3cret",
+    });
+    expect(cfg).toEqual({
+      url: "https://example.com/hook",
+      secret: "s3cret",
+    });
+  });
+
+  it("env vars override config", () => {
+    process.env.AGENTCTL_WEBHOOK_URL = "https://env.example.com";
+    process.env.AGENTCTL_WEBHOOK_SECRET = "env-secret";
+    const cfg = resolveWebhookConfig({
+      webhook_url: "https://config.example.com",
+      webhook_secret: "config-secret",
+    });
+    expect(cfg).toEqual({
+      url: "https://env.example.com",
+      secret: "env-secret",
+    });
+  });
+
+  it("works with url only (no secret)", () => {
+    delete process.env.AGENTCTL_WEBHOOK_URL;
+    delete process.env.AGENTCTL_WEBHOOK_SECRET;
+    const cfg = resolveWebhookConfig({ webhook_url: "https://example.com" });
+    expect(cfg).toEqual({ url: "https://example.com", secret: undefined });
+  });
+});
+
+describe("buildWebhookPayload", () => {
+  it("builds correct payload from session record", () => {
+    const record: SessionRecord = {
+      id: "sess-123",
+      adapter: "claude-code",
+      status: "stopped",
+      startedAt: "2026-03-07T10:00:00.000Z",
+      stoppedAt: "2026-03-07T10:05:00.000Z",
+      cwd: "/home/user/project",
+      prompt: "Fix the bug",
+      meta: { openclaw_callback_session_key: "key-1" },
+    };
+
+    const payload = buildWebhookPayload(record);
+    expect(payload.hook_type).toBe("session.stopped");
+    expect(payload.session_id).toBe("sess-123");
+    expect(payload.adapter).toBe("claude-code");
+    expect(payload.cwd).toBe("/home/user/project");
+    expect(payload.duration_seconds).toBe(300);
+    expect(payload.exit_status).toBe("stopped");
+    expect(payload.summary).toBe("Fix the bug");
+    expect(payload.meta).toEqual({
+      openclaw_callback_session_key: "key-1",
+    });
+    expect(payload.timestamp).toBeTruthy();
+  });
+});
+
+describe("computeSignature", () => {
+  it("returns consistent HMAC-SHA256 hex", () => {
+    const sig1 = computeSignature('{"test":1}', "secret");
+    const sig2 = computeSignature('{"test":1}', "secret");
+    expect(sig1).toBe(sig2);
+    expect(sig1).toHaveLength(64); // SHA256 hex = 64 chars
+  });
+
+  it("different secrets produce different signatures", () => {
+    const sig1 = computeSignature("data", "secret1");
+    const sig2 = computeSignature("data", "secret2");
+    expect(sig1).not.toBe(sig2);
+  });
+});
+
+describe("emitWebhook", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("sends POST with JSON body", async () => {
+    const payload = buildWebhookPayload({
+      id: "s1",
+      adapter: "claude-code",
+      status: "stopped",
+      startedAt: "2026-03-07T10:00:00Z",
+      stoppedAt: "2026-03-07T10:01:00Z",
+      meta: {},
+    });
+
+    await emitWebhook({ url: "https://example.com/hook" }, payload);
+
+    expect(fetch).toHaveBeenCalledTimes(1);
+    const [url, opts] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe("https://example.com/hook");
+    expect(opts.method).toBe("POST");
+    expect(opts.headers["Content-Type"]).toBe("application/json");
+    expect(opts.headers["X-Agentctl-Signature"]).toBeUndefined();
+  });
+
+  it("includes HMAC signature when secret is provided", async () => {
+    const payload = buildWebhookPayload({
+      id: "s1",
+      adapter: "claude-code",
+      status: "stopped",
+      startedAt: "2026-03-07T10:00:00Z",
+      meta: {},
+    });
+
+    await emitWebhook(
+      { url: "https://example.com/hook", secret: "my-secret" },
+      payload,
+    );
+
+    const [, opts] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(opts.headers["X-Agentctl-Signature"]).toBeTruthy();
+    expect(opts.headers["X-Agentctl-Signature"]).toHaveLength(64);
+  });
+
+  it("does not throw on fetch failure", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new Error("network down")),
+    );
+
+    // Should not throw
+    await emitWebhook(
+      { url: "https://example.com/hook" },
+      buildWebhookPayload({
+        id: "s1",
+        adapter: "claude-code",
+        status: "stopped",
+        startedAt: "2026-03-07T10:00:00Z",
+        meta: {},
+      }),
+    );
+  });
+});
diff --git a/src/daemon/webhook.ts b/src/daemon/webhook.ts
new file mode 100644
index 0000000..c893122
--- /dev/null
+++ b/src/daemon/webhook.ts
@@ -0,0 +1,102 @@
+import crypto from "node:crypto";
+import type { SessionRecord } from "./state.js";
+
+export interface WebhookConfig {
+  url: string;
+  secret?: string;
+}
+
+export interface WebhookPayload {
+  hook_type: "session.stopped";
+  session_id: string;
+  cwd?: string;
+  adapter: string;
+  duration_seconds: number;
+  exit_status: string;
+  summary?: string;
+  meta: Record<string, unknown>;
+  timestamp: string;
+}
+
+/**
+ * Resolve webhook config from environment variables and/or config object.
+ * Env vars take precedence over config file values.
+ */
+export function resolveWebhookConfig(config?: {
+  webhook_url?: string;
+  webhook_secret?: string;
+}): WebhookConfig | null {
+  const url = process.env.AGENTCTL_WEBHOOK_URL || config?.webhook_url;
+  if (!url) return null;
+
+  const secret = process.env.AGENTCTL_WEBHOOK_SECRET || config?.webhook_secret;
+
+  return { url, secret };
+}
+
+/**
+ * Build a webhook payload from a stopped session record.
+ */
+export function buildWebhookPayload(session: SessionRecord): WebhookPayload {
+  const startedAt = new Date(session.startedAt).getTime();
+  const stoppedAt = session.stoppedAt
+    ? new Date(session.stoppedAt).getTime()
+    : Date.now();
+  const durationSeconds = Math.max(
+    0,
+    Math.round((stoppedAt - startedAt) / 1000),
+  );
+
+  return {
+    hook_type: "session.stopped",
+    session_id: session.id,
+    cwd: session.cwd,
+    adapter: session.adapter,
+    duration_seconds: durationSeconds,
+    exit_status: session.status,
+    summary: session.prompt?.slice(0, 200),
+    meta: session.meta ?? {},
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Compute HMAC-SHA256 signature for a payload.
+ */
+export function computeSignature(body: string, secret: string): string {
+  return crypto.createHmac("sha256", secret).update(body).digest("hex");
+}
+
+/**
+ * Fire-and-forget webhook POST. Logs errors but never throws.
+ */
+export async function emitWebhook(
+  webhookConfig: WebhookConfig,
+  payload: WebhookPayload,
+): Promise<void> {
+  try {
+    const body = JSON.stringify(payload);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (webhookConfig.secret) {
+      headers["X-Agentctl-Signature"] = computeSignature(
+        body,
+        webhookConfig.secret,
+      );
+    }
+
+    // Use global fetch (available in Node 18+)
+    await fetch(webhookConfig.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    console.error(
+      `[webhook] Failed to emit to ${webhookConfig.url}: ${(err as Error).message}`,
+    );
+  }
+}
diff --git a/src/launch-orchestrator.ts b/src/launch-orchestrator.ts
index 4b14a53..a520a7e 100644
--- a/src/launch-orchestrator.ts
+++ b/src/launch-orchestrator.ts
@@ -35,6 +35,10 @@ export interface OrchestrateOpts {
   cwd: string;
   hooks?: LifecycleHooks;
   adapters: Record<string, AgentAdapter>;
+  /** Callback session key for orchestration */
+  callbackSessionKey?: string;
+  /** Callback agent ID for orchestration */
+  callbackAgentId?: string;
   /** Optional: callback when daemon is available for lock/track */
   onSessionLaunched?: (result: SlotLaunchResult) => void;
   /** Optional: callback when group ID is generated (before launches) */
@@ -220,6 +224,8 @@ export async function orchestrateLaunch(
         model: slot.model,
         worktree: { repo: worktree.repo, branch },
         hooks,
+        callbackSessionKey: opts.callbackSessionKey,
+        callbackAgentId: opts.callbackAgentId,
       };
 
       const session = await adapter.launch(launchOpts);
@@ -227,6 +233,14 @@ export async function orchestrateLaunch(
       // Tag the session with the group
       session.group = groupId;
 
+      // Inject callback metadata
+      if (opts.callbackSessionKey) {
+        session.meta.openclaw_callback_session_key = opts.callbackSessionKey;
+      }
+      if (opts.callbackAgentId) {
+        session.meta.openclaw_callback_agent_id = opts.callbackAgentId;
+      }
+
       const result: SlotLaunchResult = {
         slot,
         sessionId: session.id,
diff --git a/src/utils/config.ts b/src/utils/config.ts
index 5052a3a..afe96f5 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -8,6 +8,8 @@ export interface AgentCtlConfig {
   model?: string;
   cwd?: string;
   timeout?: number;
+  webhook_url?: string;
+  webhook_secret?: string;
 }
 
 export const DEFAULT_CONFIG_PATH = path.join(
diff --git a/src/utils/spawn-with-retry.test.ts b/src/utils/spawn-with-retry.test.ts
new file mode 100644
index 0000000..aba4c7d
--- /dev/null
+++ b/src/utils/spawn-with-retry.test.ts
@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock child_process.spawn
+const spawnCalls: Array<{ cmd: string; args: string[]; opts: unknown }> = [];
+let spawnErrorToEmit: NodeJS.ErrnoException | null = null;
+let spawnCallCount = 0;
+
+vi.mock("node:child_process", () => {
+  const { EventEmitter } = require("node:events");
+  return {
+    spawn: (cmd: string, args: string[], opts: unknown) => {
+      spawnCalls.push({ cmd, args: [...args], opts });
+      spawnCallCount++;
+      const child = new EventEmitter();
+      child.pid = 12345;
+      child.unref = vi.fn();
+
+      // Emit error on the first call if configured
+      if (spawnErrorToEmit && spawnCallCount === 1) {
+        const err = spawnErrorToEmit;
+        setImmediate(() => child.emit("error", err));
+      }
+
+      return child;
+    },
+  };
+});
+
+// Mock resolve-binary
+let resolveCallCount = 0;
+vi.mock("./resolve-binary.js", () => ({
+  resolveBinaryPath: async (name: string) => {
+    resolveCallCount++;
+    return `/usr/local/bin/${name}`;
+  },
+  clearBinaryCache: vi.fn(),
+}));
+
+import { clearBinaryCache } from "./resolve-binary.js";
+import { spawnWithRetry } from "./spawn-with-retry.js";
+
+beforeEach(() => {
+  spawnCalls.length = 0;
+  spawnCallCount = 0;
+  spawnErrorToEmit = null;
+  resolveCallCount = 0;
+  vi.clearAllMocks();
+});
+
+describe("spawnWithRetry", () => {
+  it("resolves with child on successful spawn", async () => {
+    const child = await spawnWithRetry("claude", ["--print"], { cwd: "/tmp" });
+    expect(child.pid).toBe(12345);
+    expect(spawnCalls).toHaveLength(1);
+    expect(spawnCalls[0].cmd).toBe("/usr/local/bin/claude");
+  });
+
+  it("retries once on ENOENT, clearing binary cache", async () => {
+    const err = new Error("spawn ENOENT") as NodeJS.ErrnoException;
+    err.code = "ENOENT";
+    spawnErrorToEmit = err;
+
+    const child = await spawnWithRetry("claude", ["--print"], { cwd: "/tmp" });
+
+    // Should have spawned twice (original + retry)
+    expect(spawnCalls).toHaveLength(2);
+    expect(spawnCalls[0].cmd).toBe("/usr/local/bin/claude");
+    expect(spawnCalls[1].cmd).toBe("/usr/local/bin/claude");
+
+    // Should have cleared the binary cache
+    expect(clearBinaryCache).toHaveBeenCalledTimes(1);
+
+    // Should have resolved binary path twice
+    expect(resolveCallCount).toBe(2);
+
+    expect(child.pid).toBe(12345);
+  });
+
+  it("does not retry on non-ENOENT errors", async () => {
+    const err = new Error("EACCES") as NodeJS.ErrnoException;
+    err.code = "EACCES";
+    spawnErrorToEmit = err;
+
+    const child = await spawnWithRetry("claude", ["--print"], { cwd: "/tmp" });
+
+    // Should have spawned only once
+    expect(spawnCalls).toHaveLength(1);
+    expect(clearBinaryCache).not.toHaveBeenCalled();
+    expect(child.pid).toBe(12345);
+  });
+});
diff --git a/src/utils/spawn-with-retry.ts b/src/utils/spawn-with-retry.ts
new file mode 100644
index 0000000..71d4f42
--- /dev/null
+++ b/src/utils/spawn-with-retry.ts
@@ -0,0 +1,77 @@
+import {
+  type ChildProcess,
+  type SpawnOptions,
+  spawn,
+} from "node:child_process";
+import { clearBinaryCache, resolveBinaryPath } from "./resolve-binary.js";
+
+/**
+ * Spawn a binary with ENOENT retry.
+ *
+ * On ENOENT, waits 500ms, clears the binary path cache, re-resolves
+ * the binary, and retries once. This handles transient cases where
+ * binaries are being installed/updated during daemon operation.
+ */
+export async function spawnWithRetry(
+  binaryName: string,
+  args: string[],
+  opts: SpawnOptions,
+  knownLocations?: string[],
+): Promise<ChildProcess> {
+  const binaryPath = await resolveBinaryPath(binaryName, knownLocations);
+
+  try {
+    return await spawnAndCheck(binaryPath, args, opts);
+  } catch (err) {
+    const errno = err as NodeJS.ErrnoException;
+    if (errno.code !== "ENOENT") throw err;
+
+    // ENOENT: wait 500ms, clear cache, retry once
+    await new Promise((r) => setTimeout(r, 500));
+    clearBinaryCache();
+
+    const retryPath = await resolveBinaryPath(binaryName, knownLocations);
+    return spawnAndCheck(retryPath, args, opts);
+  }
+}
+
+/**
+ * Spawn a child and wait briefly for an error event.
+ * If no error fires within a microtask cycle, resolve with the child.
+ * If ENOENT fires, reject so the caller can retry.
+ */
+function spawnAndCheck(
+  binaryPath: string,
+  args: string[],
+  opts: SpawnOptions,
+): Promise<ChildProcess> {
+  const child = spawn(binaryPath, args, opts);
+
+  return new Promise<ChildProcess>((resolve, reject) => {
+    let settled = false;
+
+    const onError = (err: NodeJS.ErrnoException) => {
+      if (settled) return;
+      settled = true;
+      child.removeListener("error", onError);
+      if (err.code === "ENOENT") {
+        reject(err);
+      } else {
+        // Non-ENOENT: resolve with the child (caller may still get error events)
+        resolve(child);
+      }
+    };
+
+    child.on("error", onError);
+
+    // Spawn errors (ENOENT) fire synchronously on the next tick.
+    // Give one event-loop cycle for the error to arrive, then resolve.
+    setImmediate(() => {
+      if (!settled) {
+        settled = true;
+        child.removeListener("error", onError);
+        resolve(child);
+      }
+    });
+  });
+}