@indigoai-us/hq-cli 5.117.2 → 5.118.0

package/dist/lib/agent-kit/inbox-state.js

@@ -0,0 +1,86 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DONE_IDS_NAME = "done-ids.json";
+export const MAX_DONE_IDS = 5000;
+const INBOX_JSONL = "inbox.jsonl";
+export function readDoneIds(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), "utf8"));
+        return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === "string") : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+export function markInboxDone(paths, ids) {
+    const done = readDoneIds(paths);
+    const added = [];
+    for (const id of ids) {
+        if (!done.has(id)) {
+            done.add(id);
+            added.push(id);
+        }
+    }
+    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), JSON.stringify([...done].slice(-MAX_DONE_IDS)), { mode: 0o600 });
+    return added;
+}
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export function readMirroredInbox(paths) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(paths.inboxDir, INBOX_JSONL), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.id === "string" && entry.id) {
+                byId.delete(entry.id);
+                byId.set(entry.id, entry);
+            }
+        }
+        catch {
+            /* skip a torn line */
+        }
+    }
+    return [...byId.values()];
+}
+export function pendingInbox(paths) {
+    const done = readDoneIds(paths);
+    return readMirroredInbox(paths).filter((e) => !done.has(e.id));
+}
+/** Compact view for bots: who, when, which channel, and the text. */
+export function summarizeInboxEntry(e, done) {
+    const pick = (...keys) => {
+        for (const k of keys)
+            if (typeof e[k] === "string" && e[k])
+                return e[k];
+        return undefined;
+    };
+    return {
+        id: e.id,
+        channel: pick("channel"),
+        from: pick("fromDisplayName", "fromEmail", "fromPersonUid") ?? "unknown",
+        fromUid: pick("fromPersonUid"),
+        at: pick("receivedAt", "createdAt", "mirroredAt"),
+        text: pick("text", "body"),
+        done,
+    };
+}
+//# sourceMappingURL=inbox-state.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -16,6 +16,7 @@
  * tool result.
  */
 import type { ExternalMachineCreds } from "../creds.js";
+import type { AgentKitPaths } from "../paths.js";
 import { type McpTool } from "./jsonrpc.js";
 export interface HqRunResult {
     code: number;
@@ -24,6 +25,8 @@ export interface HqRunResult {
 }
 export interface McpToolClients {
     creds: ExternalMachineCreds;
+    /** Kit layout; the inbox tools read the mirror and done-state here. */
+    paths: Pick<AgentKitPaths, "inboxDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
     getToken: () => Promise<string>;

package/dist/lib/agent-kit/mcp/tools.js

@@ -17,6 +17,7 @@
  */
 import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
+import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../inbox-state.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
 function str(args, key, opts = {}) {
@@ -226,37 +227,87 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_inbox_read",
-            description: "Read this agent's recent incoming direct messages (newest first). Optionally only unread.",
+            description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
+                "marked handled. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {
                     limit: { type: "integer", minimum: 1, maximum: 100 },
-                    unread_only: { type: "boolean" },
+                    include_done: { type: "boolean", description: "Also return items already marked handled" },
+                    unread_only: { type: "boolean", description: "Deprecated alias: true is the default behaviour" },
                 },
                 additionalProperties: false,
             },
             handler: async (args) => {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
-                const unreadOnly = args.unread_only === true;
-                const token = await clients.getToken();
-                const res = await clients.apiJson(token, "/v1/notify/inbox", { query: { limit: String(limit) } });
-                if (res.status !== 200)
-                    return errorResult(`inbox read failed (${res.status}): ${describeError(res.body)}`);
-                const events = Array.isArray(res.body?.events)
-                    ? (res.body.events)
-                    : [];
-                const rows = events
-                    .filter((e) => !unreadOnly || !e.acknowledgedAt)
-                    .map((e) => ({
-                    eventId: e.eventId,
-                    from: e.fromDisplayName ?? e.fromEmail ?? e.fromPersonUid ?? "unknown",
-                    fromUid: e.fromPersonUid,
-                    at: e.createdAt,
-                    unread: !e.acknowledgedAt,
-                    body: e.body,
-                    ...(e.prompt ? { prompt: e.prompt } : {}),
-                }));
-                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows }, null, 2)));
+                const includeDone = args.include_done === true;
+                const done = readDoneIds(clients.paths);
+                // The kit mirror is the source of truth; merge the agent's own server
+                // inbox so items the poller has not mirrored yet are not missed.
+                const byId = new Map();
+                for (const e of readMirroredInbox(clients.paths))
+                    byId.set(e.id, e);
+                let serverNote;
+                try {
+                    const token = await clients.getToken();
+                    const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                    if (res.status === 200) {
+                        const messages = res.body?.messages;
+                        for (const m of Array.isArray(messages) ? messages : []) {
+                            if (!m || typeof m !== "object")
+                                continue;
+                            const raw = m;
+                            const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
+                            if (id && !byId.has(id))
+                                byId.set(id, { ...raw, id });
+                        }
+                    }
+                    else {
+                        serverNote = `server inbox answered ${res.status}: ${describeError(res.body)}; showing the local mirror only`;
+                    }
+                }
+                catch (err) {
+                    serverNote = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only`;
+                }
+                const rows = [...byId.values()]
+                    .filter((e) => includeDone || !done.has(e.id))
+                    .slice(0, limit)
+                    .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows, ...(serverNote ? { note: serverNote } : {}) }, null, 2)));
+            },
+        },
+        {
+            name: "hq_inbox_done",
+            description: "Mark inbox items handled (after replying) so they stop showing as pending and the wake hook stops retrying.",
+            inputSchema: {
+                type: "object",
+                properties: { ids: { type: "array", items: { type: "string" }, description: "Item ids from hq_inbox_read" } },
+                required: ["ids"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const ids = strList(args, "ids");
+                for (const id of ids) {
+                    if (!/^[A-Za-z0-9._:-]{1,200}$/.test(id))
+                        throw new McpToolInputError(`invalid id ${JSON.stringify(id)}`);
+                }
+                const added = markInboxDone(clients.paths, ids);
+                const acked = [];
+                const failed = [];
+                try {
+                    const token = await clients.getToken();
+                    for (const id of ids) {
+                        const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`, { method: "POST" });
+                        if (res.status >= 200 && res.status < 300)
+                            acked.push(id);
+                        else
+                            failed.push(`${id} (${res.status})`);
+                    }
+                }
+                catch (err) {
+                    failed.push(`ack skipped: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return textResult(JSON.stringify({ marked: added.length, alreadyDone: ids.length - added.length, serverAcked: acked.length, ...(failed.length ? { ackFailures: failed } : {}) }, null, 2));
             },
         },
         {

package/dist/lib/agent-kit/run/inbox.d.ts

@@ -17,6 +17,7 @@
  */
 import type { KitLogger } from "../log.js";
 import type { AgentKitPaths } from "../paths.js";
+import { type WakeConfig, type WakeDeps, type WakeNotice, type WakeResult } from "../wake.js";
 export declare const SEEN_IDS_NAME = "seen-ids.json";
 export declare const INBOX_JSONL_NAME = "inbox.jsonl";
 export declare const MAX_SEEN_IDS = 5000;
@@ -42,6 +43,10 @@ export interface InboxDeps {
     warmCache?: (token: string, agentUid: string) => Promise<unknown>;
     sleep?: (ms: number) => Promise<void>;
     maxPolls?: number;
+    /** Override wake config lookup (tests). `null` disables the wake. */
+    wakeConfig?: WakeConfig | null;
+    fireWake?: (config: WakeConfig, notice: WakeNotice, deps: WakeDeps) => Promise<WakeResult>;
+    now?: () => Date;
 }
 export declare const INBOX_ERROR_BODY_MAX = 300;
 export interface InboxFetchResult {

package/dist/lib/agent-kit/run/inbox.js

@@ -19,6 +19,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { writeComponentStatus } from "../creds.js";
+import { pendingInbox } from "../inbox-state.js";
+import { buildWakeNotice, currentWakeState, fireWake, readWakeConfig, shouldWake, } from "../wake.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
 export const MAX_SEEN_IDS = 5000;
@@ -168,8 +170,27 @@ export async function pollInboxOnce(deps) {
             deps.log("warn", `cache refresh failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    await maybeWake(deps, fresh.length);
     return { ok: true, mirrored: fresh.length };
 }
+/** Poke the bot's framework when mail is new, or still pending past the retry window. */
+async function maybeWake(deps, freshCount) {
+    const config = deps.wakeConfig !== undefined ? deps.wakeConfig : readWakeConfig(deps.paths);
+    if (!config)
+        return;
+    const now = (deps.now ?? (() => new Date()))();
+    const pending = pendingInbox(deps.paths);
+    const reason = shouldWake(config, currentWakeState(deps.paths), freshCount, pending.length, now);
+    if (!reason)
+        return;
+    const notice = buildWakeNotice(deps.agentUid, reason, pending.map((e) => e.id), now);
+    try {
+        await (deps.fireWake ?? fireWake)(config, notice, { paths: deps.paths, agentUid: deps.agentUid, log: deps.log, now: deps.now });
+    }
+    catch (err) {
+        deps.log("warn", `wake failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export async function runInboxLoop(deps) {
     const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     let polls = 0;

package/dist/lib/agent-kit/skills.js

@@ -25,18 +25,21 @@ hq dm <uid1>,<uid2> "message text"         # group DM
 hq dm '#channel-name' "message text"       # channel
 \`\`\`
 
-## Read
+## Read and handle incoming messages
+
+The kit's inbox poller mirrors every message addressed to you (DMs, channel
+mentions, jobs). Work through them like this:
 
 \`\`\`bash
-hq dm inbox --unread            # unread DMs addressed to you
-hq dm thread <email-or-uid>     # the 1:1 conversation
-hq dm inbox --mark-read         # mark what you have read
-hq dm channel <name>            # read a channel
+hq agent inbox                  # pending messages, oldest first (id, sender uid, text)
+hq dm <sender-uid> "reply"      # answer each one
+hq agent inbox done <id> [id…]  # mark handled so it is never answered twice
 \`\`\`
 
-New inbound messages are also mirrored by the kit's inbox poller to
-\`~/.hq-agent/inbox/<id>.json\` (and \`inbox.jsonl\`) — check there when
-you are asked whether anyone has messaged you.
+The MCP equivalents are \`hq_inbox_read\`, \`hq_dm_send\` and \`hq_inbox_done\`.
+If the kit has a wake configured (\`hq agent kit wake show\`), HQ pokes your
+framework whenever something is pending, so always drain the whole list and
+mark each item done.
 
 ## Rules
 

package/dist/lib/agent-kit/wake.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Wake hook: tell the bot's own framework that HQ mail is waiting.
+ *
+ * Hosted agents are woken by the box watcher, which runs the model per inbox
+ * item. An external bot brings its own brain, so the kit cannot run it, but
+ * it can poke it. Two kinds, stored in ~/.hq-agent/wake.json (0600):
+ *
+ *   url      POST a small JSON notice to a URL the framework gives you, such
+ *            as a Grok Bot routine webhook. The URL is treated as a secret:
+ *            it is never logged or printed in full.
+ *   command  Run a local command (argv, no shell) for frameworks with a CLI
+ *            (such as OpenClaw). The notice is written to its stdin. One run
+ *            at a time; mail that arrives mid-run triggers one more run after.
+ *
+ * The notice never carries message text. It only says how many items are
+ * pending and their ids; the bot reads them through HQ (`hq agent inbox`).
+ *
+ * The inbox poller fires the wake when new items are mirrored, and re-fires
+ * every `retryMs` while items stay pending, so a missed webhook heals.
+ */
+import { spawn } from "node:child_process";
+import type { KitLogger } from "./log.js";
+import type { AgentKitPaths } from "./paths.js";
+export declare const WAKE_FILE_NAME = "wake.json";
+export declare const WAKE_STATE_NAME = "wake-state.json";
+export declare const DEFAULT_WAKE_RETRY_MS: number;
+export declare const WAKE_URL_TIMEOUT_MS = 15000;
+export declare const DEFAULT_WAKE_COMMAND_TIMEOUT_MS: number;
+export type WakeConfig = {
+    kind: "url";
+    url: string;
+    retryMs: number;
+} | {
+    kind: "command";
+    command: string[];
+    timeoutMs: number;
+    retryMs: number;
+};
+export interface WakeNotice {
+    event: "hq.inbox.pending";
+    agentUid: string;
+    reason: "new" | "retry" | "test";
+    pending: number;
+    messageIds: string[];
+    at: string;
+    instructions: string;
+}
+export declare const WAKE_INSTRUCTIONS: string;
+export declare function wakePath(paths: Pick<AgentKitPaths, "agentDir">): string;
+export declare function validateWakeUrl(raw: string): string;
+/** Origin plus a masked path: enough to recognise, not enough to call. */
+export declare function redactWakeUrl(url: string): string;
+export declare function describeWake(config: WakeConfig | null): string;
+export declare function readWakeConfig(paths: Pick<AgentKitPaths, "agentDir">): WakeConfig | null;
+export declare function writeWakeConfig(paths: Pick<AgentKitPaths, "agentDir">, config: WakeConfig): void;
+export declare function clearWakeConfig(paths: Pick<AgentKitPaths, "agentDir">): boolean;
+export interface WakeDeps {
+    paths: Pick<AgentKitPaths, "agentDir" | "stateDir" | "logsDir">;
+    agentUid: string;
+    log: KitLogger;
+    now?: () => Date;
+    fetchImpl?: typeof fetch;
+    spawnImpl?: typeof spawn;
+    pidAlive?: (pid: number | undefined) => boolean;
+}
+export declare function buildWakeNotice(agentUid: string, reason: WakeNotice["reason"], ids: string[], now: Date): WakeNotice;
+/**
+ * Decide whether to wake now: always on new mail, otherwise only when items
+ * are still pending and the last wake is older than retryMs.
+ */
+export declare function shouldWake(config: WakeConfig, state: {
+    lastWakeAt?: string;
+}, freshCount: number, pendingCount: number, now: Date): WakeNotice["reason"] | null;
+export interface WakeResult {
+    fired: boolean;
+    ok: boolean;
+    detail: string;
+}
+export declare function fireWake(config: WakeConfig, notice: WakeNotice, deps: WakeDeps): Promise<WakeResult>;
+export declare function currentWakeState(paths: Pick<AgentKitPaths, "stateDir">): {
+    lastWakeAt?: string;
+};
+//# sourceMappingURL=wake.d.ts.map

package/dist/lib/agent-kit/wake.js

@@ -0,0 +1,236 @@
+/**
+ * Wake hook: tell the bot's own framework that HQ mail is waiting.
+ *
+ * Hosted agents are woken by the box watcher, which runs the model per inbox
+ * item. An external bot brings its own brain, so the kit cannot run it, but
+ * it can poke it. Two kinds, stored in ~/.hq-agent/wake.json (0600):
+ *
+ *   url      POST a small JSON notice to a URL the framework gives you, such
+ *            as a Grok Bot routine webhook. The URL is treated as a secret:
+ *            it is never logged or printed in full.
+ *   command  Run a local command (argv, no shell) for frameworks with a CLI
+ *            (such as OpenClaw). The notice is written to its stdin. One run
+ *            at a time; mail that arrives mid-run triggers one more run after.
+ *
+ * The notice never carries message text. It only says how many items are
+ * pending and their ids; the bot reads them through HQ (`hq agent inbox`).
+ *
+ * The inbox poller fires the wake when new items are mirrored, and re-fires
+ * every `retryMs` while items stay pending, so a missed webhook heals.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const WAKE_FILE_NAME = "wake.json";
+export const WAKE_STATE_NAME = "wake-state.json";
+export const DEFAULT_WAKE_RETRY_MS = 10 * 60_000;
+export const WAKE_URL_TIMEOUT_MS = 15_000;
+export const DEFAULT_WAKE_COMMAND_TIMEOUT_MS = 10 * 60_000;
+export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool), reply to each " +
+    "with `hq dm <sender-uid> \"…\"` (or hq_dm_send), then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
+export function wakePath(paths) {
+    return path.join(paths.agentDir, WAKE_FILE_NAME);
+}
+function wakeStatePath(paths) {
+    return path.join(paths.stateDir, WAKE_STATE_NAME);
+}
+export function validateWakeUrl(raw) {
+    const url = raw.trim();
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error("wake URL is not a valid URL");
+    }
+    const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "::1";
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local)) {
+        throw new Error("wake URL must use https (http is allowed only for localhost)");
+    }
+    if (parsed.username || parsed.password)
+        throw new Error("wake URL must not embed a username or password");
+    return url;
+}
+/** Origin plus a masked path: enough to recognise, not enough to call. */
+export function redactWakeUrl(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}/…`;
+    }
+    catch {
+        return "(invalid url)";
+    }
+}
+export function describeWake(config) {
+    if (!config)
+        return "not configured";
+    return config.kind === "url"
+        ? `url ${redactWakeUrl(config.url)}`
+        : `command ${config.command[0]}${config.command.length > 1 ? " …" : ""}`;
+}
+export function readWakeConfig(paths) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(wakePath(paths), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const retryMs = typeof raw.retryMs === "number" && raw.retryMs >= 60_000 ? raw.retryMs : DEFAULT_WAKE_RETRY_MS;
+    if (raw.kind === "url" && typeof raw.url === "string") {
+        try {
+            return { kind: "url", url: validateWakeUrl(raw.url), retryMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (raw.kind === "command" && Array.isArray(raw.command) && raw.command.length > 0 && raw.command.every((x) => typeof x === "string" && x)) {
+        const timeoutMs = typeof raw.timeoutMs === "number" && raw.timeoutMs > 0 ? raw.timeoutMs : DEFAULT_WAKE_COMMAND_TIMEOUT_MS;
+        return { kind: "command", command: raw.command, timeoutMs, retryMs };
+    }
+    return null;
+}
+export function writeWakeConfig(paths, config) {
+    fs.mkdirSync(paths.agentDir, { recursive: true, mode: 0o700 });
+    const file = wakePath(paths);
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+export function clearWakeConfig(paths) {
+    try {
+        fs.unlinkSync(wakePath(paths));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readWakeState(paths) {
+    try {
+        return JSON.parse(fs.readFileSync(wakeStatePath(paths), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeWakeState(paths, state) {
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(wakeStatePath(paths), JSON.stringify(state), { mode: 0o600 });
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function buildWakeNotice(agentUid, reason, ids, now) {
+    return {
+        event: "hq.inbox.pending",
+        agentUid,
+        reason,
+        pending: ids.length,
+        messageIds: ids.slice(0, 50),
+        at: now.toISOString(),
+        instructions: WAKE_INSTRUCTIONS,
+    };
+}
+/**
+ * Decide whether to wake now: always on new mail, otherwise only when items
+ * are still pending and the last wake is older than retryMs.
+ */
+export function shouldWake(config, state, freshCount, pendingCount, now) {
+    if (pendingCount === 0)
+        return null;
+    if (freshCount > 0)
+        return "new";
+    const last = state.lastWakeAt ? Date.parse(state.lastWakeAt) : NaN;
+    if (Number.isNaN(last) || now.getTime() - last >= config.retryMs)
+        return "retry";
+    return null;
+}
+export async function fireWake(config, notice, deps) {
+    const now = deps.now ?? (() => new Date());
+    const state = readWakeState(deps.paths);
+    const alive = deps.pidAlive ?? pidAlive;
+    if (config.kind === "url") {
+        const doFetch = deps.fetchImpl ?? fetch;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WAKE_URL_TIMEOUT_MS);
+        const target = redactWakeUrl(config.url);
+        try {
+            const res = await doFetch(config.url, {
+                method: "POST",
+                headers: { "content-type": "application/json", "user-agent": "hq-agent-kit" },
+                body: JSON.stringify(notice),
+                signal: controller.signal,
+            });
+            writeWakeState(deps.paths, { ...state, lastWakeAt: now().toISOString() });
+            const ok = res.status >= 200 && res.status < 300;
+            const detail = `wake url ${target} → ${res.status} (${notice.reason}, ${notice.pending} pending)`;
+            deps.log(ok ? "info" : "warn", detail);
+            return { fired: true, ok, detail };
+        }
+        catch (err) {
+            const detail = `wake url ${target} failed: ${err instanceof Error ? err.name === "AbortError" ? "timeout" : err.message : String(err)}`;
+            deps.log("warn", detail);
+            return { fired: true, ok: false, detail };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    if (alive(state.runningPid)) {
+        writeWakeState(deps.paths, { ...state, rerun: true });
+        const detail = `wake command still running (pid ${state.runningPid}); will run again after it exits`;
+        deps.log("info", detail);
+        return { fired: false, ok: true, detail };
+    }
+    const doSpawn = deps.spawnImpl ?? spawn;
+    const logFd = fs.openSync(path.join(deps.paths.logsDir, "wake.log"), "a", 0o600);
+    let child;
+    try {
+        child = doSpawn(config.command[0], config.command.slice(1), {
+            stdio: ["pipe", logFd, logFd],
+            env: {
+                ...process.env,
+                HQ_WAKE_EVENT: notice.event,
+                HQ_WAKE_REASON: notice.reason,
+                HQ_WAKE_PENDING: String(notice.pending),
+                HQ_AGENT_UID: notice.agentUid,
+            },
+        });
+    }
+    catch (err) {
+        fs.closeSync(logFd);
+        const detail = `wake command failed to start: ${err instanceof Error ? err.message : String(err)}`;
+        deps.log("warn", detail);
+        return { fired: false, ok: false, detail };
+    }
+    fs.closeSync(logFd);
+    child.stdin?.end(`${JSON.stringify(notice)}\n`);
+    writeWakeState(deps.paths, { lastWakeAt: now().toISOString(), runningPid: child.pid, rerun: false });
+    const timer = setTimeout(() => child.kill("SIGTERM"), config.timeoutMs);
+    const detail = `wake command started pid ${child.pid} (${notice.reason}, ${notice.pending} pending)`;
+    deps.log("info", detail);
+    child.on("error", (err) => deps.log("warn", `wake command error: ${err.message}`));
+    child.on("exit", (code, signal) => {
+        clearTimeout(timer);
+        const after = readWakeState(deps.paths);
+        writeWakeState(deps.paths, { lastWakeAt: after.lastWakeAt, rerun: false });
+        deps.log(code === 0 ? "info" : "warn", `wake command exited ${signal ?? code}`);
+        if (after.rerun) {
+            void fireWake(config, { ...notice, reason: "new", at: now().toISOString() }, deps);
+        }
+    });
+    return { fired: true, ok: true, detail };
+}
+export function currentWakeState(paths) {
+    return { lastWakeAt: readWakeState(paths).lastWakeAt };
+}
+//# sourceMappingURL=wake.js.map

package/dist/lib/doctor/__testing__/fake-hq-tree.d.ts

@@ -74,7 +74,7 @@ export interface FakeHookSpec {
     mode?: number;
     /** Whether the hook is registered in `.claude/settings.json`. Default: true. */
     registered?: boolean;
-    /** Events the hook registers against. Default: ["PreToolUse"]. */
+    /** Events the hook registers against. Default: SessionStart and PreToolUse. */
     events?: HookEventName[];
     /** Optional settings matcher (e.g. "Bash", "Glob"). */
     matcher?: string;

package/dist/lib/doctor/__testing__/fake-hq-tree.js

@@ -166,7 +166,7 @@ function writeHook(claudeHooksDir, codexHooksDir, hook, defaultMirror) {
     const claudeBody = hook.body ?? DEFAULT_HOOK_BODY;
     const present = hook.present !== false;
     const registered = hook.registered !== false;
-    const events = hook.events ?? ["PreToolUse"];
+    const events = hook.events ?? ["SessionStart", "PreToolUse"];
     const profiles = hook.profiles ?? [...GATE_PROFILES];
     const scriptPath = path.join(claudeHooksDir, `${hook.id}.sh`);
     let mode = null;