@theagenthub/cli 0.3.0 → 0.3.1

package/README.md

@@ -1,9 +1,9 @@
-# agenthub
+# @theagenthub/cli
 
 The [Agent Hub](https://theagenthub.app) CLI. It signs you in to a hub and runs the hooks that bring teammates' agents' messages into your coding agent.
 
 ```sh
-npm install -g @theagenthub/cli          # needs Node 22; without Node: curl -fsSL https://get.theagenthub.app | sh
+npm install -g @theagenthub/cli  # needs Node 22; without Node: curl -fsSL https://get.theagenthub.app | sh
 agenthub login --hub https://hub.theagenthub.app
 agenthub hooks install claude-code   # or codex, copilot, opencode
 ```

package/bin/agenthub.cjs

@@ -276,6 +276,15 @@ function writeSettings(s, env = process.env) {
   (0, import_node_fs4.mkdirSync)(dir, { recursive: true, mode: 448 });
   (0, import_node_fs4.writeFileSync)((0, import_node_path5.join)(dir, "config.json"), JSON.stringify(s, null, 2) + "\n");
 }
+function projectKey(origin) {
+  try {
+    const { host, path } = parseRemote(origin);
+    const p = path.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "").toLowerCase();
+    return p ? `${host}/${p}` : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function hubUrl(env = process.env) {
   const raw = env.AGENTHUB_URL ?? readSettings(env).hub;
   return raw?.replace(/\/+$/, "");
@@ -286,6 +295,7 @@ var init_settings = __esm({
     "use strict";
     import_node_fs4 = require("node:fs");
     import_node_path5 = require("node:path");
+    init_registry();
     init_paths();
   }
 });
@@ -453,12 +463,349 @@ var init_update = __esm({
   }
 });
 
+// src/cli/watch.ts
+var watch_exports = {};
+__export(watch_exports, {
+  readEvents: () => readEvents,
+  watch: () => watch
+});
+async function watch(opts, deps) {
+  const env = deps.env ?? process.env;
+  const fetchFn = deps.fetch ?? fetch;
+  const sleep = deps.sleep ?? defaultSleep;
+  const hub = hubUrl(env);
+  if (!hub) {
+    deps.write("No hub configured. Run agenthub login --hub <url>.");
+    return 1;
+  }
+  const { origin, upstream } = (deps.remotes ?? gitRemotes)(deps.cwd ?? process.cwd());
+  if (!origin) {
+    deps.write("Not in a git repo with an origin remote.");
+    return 1;
+  }
+  const agentName = opts.agentName ?? env.AGENTHUB_AGENT_NAME;
+  const query = new URLSearchParams({ project: origin, ...upstream ? { upstream } : {}, ...agentName ? { agent_name: agentName } : {} });
+  let backoff = 1e3;
+  let saidWaiting = false;
+  let waitingApproval = false;
+  while (!opts.signal?.aborted) {
+    const token = await accessToken(hub, { store: deps.store, fetch: fetchFn, env });
+    if (!token) {
+      deps.write("Not signed in. Run agenthub login.");
+      return 1;
+    }
+    let res;
+    try {
+      res = await fetchFn(`${hub}/api/stream?${query}`, {
+        headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
+        ...opts.signal ? { signal: opts.signal } : {}
+      });
+    } catch {
+      if (opts.signal?.aborted) break;
+      await sleep(backoff, opts.signal);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+      continue;
+    }
+    if (res.status === 404) {
+      const { membership } = await res.json().catch(() => ({}));
+      if (membership === "pending") {
+        if (!waitingApproval) deps.write(opts.json ? JSON.stringify({ membership: "pending" }) : "Your request to join is waiting for a project admin's approval.");
+        waitingApproval = true;
+      } else {
+        if (waitingApproval) {
+          if (membership === "active") deps.write(opts.json ? JSON.stringify({ membership: "approved" }) : "A project admin approved you: ask your agent to call join_project.");
+          else deps.write(opts.json ? JSON.stringify({ membership: "declined" }) : "A project admin turned down your request to join.");
+          waitingApproval = false;
+          saidWaiting = true;
+        }
+        if (!saidWaiting) deps.write("No agent of yours has joined this project yet; waiting.");
+        saidWaiting = true;
+      }
+      await sleep(backoff, opts.signal);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+      continue;
+    }
+    if (res.status === 403 || res.status === 409 || res.status === 410) {
+      const body = await res.json().catch(() => ({}));
+      deps.write(body.message ?? `The hub refused the stream (${res.status}).`);
+      return 1;
+    }
+    if (!res.ok || !res.body) {
+      await res.body?.cancel();
+      await sleep(backoff, opts.signal);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+      continue;
+    }
+    backoff = 1e3;
+    saidWaiting = false;
+    let stop;
+    try {
+      for await (const ev of readEvents(res.body)) {
+        if (ev.event === "inbox") {
+          const data = JSON.parse(ev.data);
+          if (opts.json) deps.write(JSON.stringify(data));
+          else {
+            const text = formatInbox(data);
+            if (text) deps.write(text);
+          }
+        } else if (ev.event === "end") {
+          const { reason } = JSON.parse(ev.data);
+          if (reason === "replaced") {
+            deps.write("Another session joined with this agent name; stopping.");
+            stop = 1;
+          } else if (reason === "revoked") {
+            deps.write("This agent lost access to the project; stopping.");
+            stop = 1;
+          } else if (reason === "left") {
+            if (opts.json) deps.write(JSON.stringify({ left: true }));
+            else deps.write("The agent left the project; waiting for it to join again.");
+          }
+        }
+      }
+    } catch {
+    }
+    if (stop !== void 0) return stop;
+  }
+  return 0;
+}
+async function* readEvents(body) {
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of body) {
+    buf += decoder.decode(chunk, { stream: true });
+    let i;
+    while ((i = buf.indexOf("\n\n")) >= 0) {
+      const block = buf.slice(0, i);
+      buf = buf.slice(i + 2);
+      let event = "message";
+      const data = [];
+      for (const line of block.split("\n")) {
+        if (line.startsWith("event:")) event = line.slice(6).trim();
+        else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
+      }
+      if (data.length) yield { event, data: data.join("\n") };
+    }
+  }
+}
+function defaultSleep(ms, signal) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(t);
+      resolve();
+    }, { once: true });
+  });
+}
+var MAX_BACKOFF_MS;
+var init_watch = __esm({
+  "src/cli/watch.ts"() {
+    "use strict";
+    init_notify();
+    init_session();
+    init_settings();
+    MAX_BACKOFF_MS = 3e4;
+  }
+});
+
+// src/cli/wait.ts
+var wait_exports = {};
+__export(wait_exports, {
+  DEFAULT_WAIT_MS: () => DEFAULT_WAIT_MS,
+  addPending: () => addPending,
+  claimFile: () => claimFile,
+  mergeInbox: () => mergeInbox,
+  pendingFile: () => pendingFile,
+  releaseWaiter: () => releaseWaiter,
+  takePending: () => takePending,
+  wait: () => wait,
+  wakeMode: () => wakeMode,
+  wakeSetting: () => wakeSetting
+});
+function wakeSetting(env, origin) {
+  const settings = readSettings(env);
+  const key = origin ? projectKey(origin) : void 0;
+  const project = key ? settings.wake_projects?.[key] : void 0;
+  const [raw, from] = env.AGENTHUB_WAKE !== void 0 ? [env.AGENTHUB_WAKE, "env"] : project ? [project, "project"] : settings.wake ? [settings.wake, "user"] : ["", "default"];
+  const v = raw.trim().toLowerCase();
+  const mode = ["0", "false", "off", "no"].includes(v) ? "off" : v === "all" ? "all" : "requests";
+  return { mode, from };
+}
+function wakeMode(env, origin) {
+  return wakeSetting(env, origin).mode;
+}
+function claimFile(env, key) {
+  return (0, import_node_path7.join)(cacheDir(env), `wait-${key}.json`);
+}
+function pendingFile(env, key) {
+  return (0, import_node_path7.join)(cacheDir(env), `pending-${key}.json`);
+}
+function releaseWaiter(env, key) {
+  (0, import_node_fs6.rmSync)(claimFile(env, key), { force: true });
+}
+function takePending(env, key) {
+  const file2 = pendingFile(env, key);
+  try {
+    const pending = JSON.parse((0, import_node_fs6.readFileSync)(file2, "utf8"));
+    (0, import_node_fs6.rmSync)(file2, { force: true });
+    return pending;
+  } catch {
+    return void 0;
+  }
+}
+function addPending(env, key, inbox) {
+  if (!inbox.messages.length && !inbox.events.length) return;
+  const file2 = pendingFile(env, key);
+  let before;
+  try {
+    before = JSON.parse((0, import_node_fs6.readFileSync)(file2, "utf8"));
+  } catch {
+    before = void 0;
+  }
+  (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(file2, ".."), { recursive: true, mode: 448 });
+  (0, import_node_fs6.writeFileSync)(file2, JSON.stringify(mergeInbox(before, inbox)), { mode: 384 });
+}
+function mergeInbox(earlier, later) {
+  if (!earlier) return later;
+  return {
+    ...later,
+    messages: [...earlier.messages, ...later.messages],
+    events: [...earlier.events, ...later.events]
+  };
+}
+async function wait(opts, deps) {
+  const env = deps.env ?? process.env;
+  const fetchFn = deps.fetch ?? fetch;
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? defaultSleep2;
+  const cwd = typeof opts.payload?.cwd === "string" ? opts.payload.cwd : deps.cwd ?? process.cwd();
+  const hub = hubUrl(env);
+  if (!hub) return NOTHING;
+  const { origin, upstream } = (deps.remotes ?? gitRemotes)(cwd);
+  if (!origin) return NOTHING;
+  const mode = wakeMode(env, origin);
+  if (mode === "off") return NOTHING;
+  if (!await onHub(hub, [origin, upstream], fetchFn, env, now).catch(() => false)) return NOTHING;
+  const agentName = hookAgentName(opts.payload, env);
+  const key = sessionKey(hub, origin, agentName);
+  const id = (0, import_node_crypto2.randomBytes)(8).toString("hex");
+  const claim2 = claimFile(env, key);
+  (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(claim2, ".."), { recursive: true, mode: 448 });
+  (0, import_node_fs6.writeFileSync)(claim2, JSON.stringify({ id, pid: process.pid, at: now() }));
+  const holds = () => {
+    try {
+      return JSON.parse((0, import_node_fs6.readFileSync)(claim2, "utf8")).id === id;
+    } catch {
+      return false;
+    }
+  };
+  const ac = new AbortController();
+  const stop = () => ac.abort();
+  opts.signal?.addEventListener("abort", stop, { once: true });
+  const deadline = setTimeout(stop, opts.maxMs ?? DEFAULT_WAIT_MS);
+  const check2 = setInterval(() => {
+    if (!holds()) stop();
+  }, deps.claimCheckMs ?? 1e3);
+  const query = new URLSearchParams({ project: origin, ...upstream ? { upstream } : {}, ...agentName ? { agent_name: agentName } : {}, idle: "1" });
+  let backoff = 1e3;
+  try {
+    while (!ac.signal.aborted) {
+      const token = await accessToken(hub, { store: deps.store, fetch: fetchFn, env, now });
+      if (!token) return NOTHING;
+      let res;
+      try {
+        res = await fetchFn(`${hub}/api/stream?${query}`, {
+          headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
+          signal: ac.signal
+        });
+      } catch {
+        if (ac.signal.aborted) break;
+        await sleep(backoff, ac.signal);
+        backoff = Math.min(backoff * 2, MAX_BACKOFF_MS2);
+        continue;
+      }
+      if ([401, 403, 404, 409, 410].includes(res.status)) {
+        await res.body?.cancel();
+        return NOTHING;
+      }
+      if (!res.ok || !res.body) {
+        await res.body?.cancel();
+        await sleep(res.status === 429 ? MAX_BACKOFF_MS2 : backoff, ac.signal);
+        backoff = Math.min(backoff * 2, MAX_BACKOFF_MS2);
+        continue;
+      }
+      backoff = 1e3;
+      try {
+        for await (const ev of readEvents(res.body)) {
+          if (ev.event === "inbox") {
+            const data = JSON.parse(ev.data);
+            const wakes = data.messages.some((m) => m.new && (mode === "all" || m.type !== "fyi"));
+            if (wakes && holds()) return { code: 2, text: `${formatInbox(mergeInbox(takePending(env, key), data))}
+${WOKEN}` };
+            addPending(env, key, data);
+          } else if (ev.event === "end") {
+            const { reason } = JSON.parse(ev.data);
+            if (reason === "left" || reason === "replaced" || reason === "revoked") return NOTHING;
+          }
+        }
+      } catch {
+      }
+    }
+    return NOTHING;
+  } finally {
+    clearTimeout(deadline);
+    clearInterval(check2);
+    opts.signal?.removeEventListener("abort", stop);
+    ac.abort();
+    if (holds()) (0, import_node_fs6.rmSync)(claim2, { force: true });
+  }
+}
+function defaultSleep2(ms, signal) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(t);
+      resolve();
+    }, { once: true });
+  });
+}
+var import_node_crypto2, import_node_fs6, import_node_path7, DEFAULT_WAIT_MS, MAX_BACKOFF_MS2, NOTHING, WOKEN;
+var init_wait = __esm({
+  "src/cli/wait.ts"() {
+    "use strict";
+    import_node_crypto2 = require("node:crypto");
+    import_node_fs6 = require("node:fs");
+    import_node_path7 = require("node:path");
+    init_paths();
+    init_notify();
+    init_session();
+    init_settings();
+    init_watch();
+    DEFAULT_WAIT_MS = 12 * 36e5;
+    MAX_BACKOFF_MS2 = 6e4;
+    NOTHING = { code: 0, text: "" };
+    WOKEN = "Agent Hub woke this session while it was idle, so the user may be away. Handle these as the Agent Hub rules say: answer questions and do reviews read-only, and complete them; leave a handoff, or anything that would run commands, push, merge or touch secrets, for the user and say so.";
+  }
+});
+
 // src/cli/notify.ts
+var notify_exports = {};
+__export(notify_exports, {
+  CARD_NUDGE_MS: () => CARD_NUDGE_MS,
+  TASK_CHECK_MS: () => TASK_CHECK_MS,
+  formatInbox: () => formatInbox,
+  gitBranch: () => gitBranch,
+  gitRemotes: () => gitRemotes,
+  hookAgentName: () => hookAgentName,
+  notify: () => notify,
+  onHub: () => onHub,
+  sessionKey: () => sessionKey
+});
 async function notify(opts, deps) {
   try {
     const event = opts.event ?? HOOK_EVENTS[String(opts.payload?.hook_event_name ?? "")] ?? "post-tool";
     const update = event === "session-start" && deps.version ? updateNotice(deps.version, { env: deps.env ?? process.env, fetch: deps.fetch ?? fetch, ...deps.now ? { now: deps.now } : {} }) : Promise.resolve("");
     const [text, notice] = await Promise.all([run(opts, event, deps).catch(() => ""), update.catch(() => "")]);
+    if (typeof text === "object") return text.raw;
     return render(opts.format, event, [text, notice].filter(Boolean).join("\n"));
   } catch {
     return "";
@@ -476,14 +823,27 @@ async function run(opts, event, deps) {
   if (!origin) return "";
   if (!await onHub(hub, [origin, upstream], fetchFn, env, now)) return "";
   const agentName = hookAgentName(opts.payload, env);
-  const throttleKey = (0, import_node_crypto2.createHash)("sha256").update(`${hub}|${origin}|${agentName ?? ""}`).digest("hex").slice(0, 24);
-  const wait = THROTTLE_MS[event];
-  if (wait && !throttle((0, import_node_path7.join)(cacheDir(env), `notify-${throttleKey}.json`), wait, now())) return "";
+  const throttleKey = sessionKey(hub, origin, agentName);
+  if (event !== "stop") releaseWaiter(env, throttleKey);
+  const wait2 = THROTTLE_MS[event];
+  if (wait2 && !throttle((0, import_node_path8.join)(cacheDir(env), `notify-${throttleKey}.json`), wait2, now())) return "";
   const token = await accessToken(hub, { store: deps.store, fetch: fetchFn, env, now });
   if (!token) return event === "session-start" ? out(`Agent Hub: not signed in. Ask the user to run \`agenthub login --hub ${hub}\` to get teammates' messages here.`) : "";
   const who = { project: origin, ...upstream ? { upstream } : {}, ...agentName ? { agent_name: agentName } : {} };
   const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
   const signal = AbortSignal.timeout(3e3);
+  if (event === "stop" && opts.format === "codex" && wakeMode(env, origin) !== "off") {
+    const res2 = await fetchFn(`${hub}/api/inbox?${new URLSearchParams(who)}`, { headers, signal });
+    if (res2.ok) {
+      const inbox2 = mergeInbox(takePending(env, throttleKey), await res2.json());
+      const mode = wakeMode(env, origin);
+      if (inbox2.messages.some((m) => m.new && (mode === "all" || m.type !== "fyi"))) {
+        return { raw: JSON.stringify({ decision: "block", reason: `${formatInbox(inbox2)}
+Handle these as the Agent Hub rules say before you finish.` }) };
+      }
+      addPending(env, throttleKey, inbox2);
+    }
+  }
   if (event === "stop" || event === "session-end") {
     await fetchFn(`${hub}/api/presence`, {
       method: "POST",
@@ -498,28 +858,81 @@ async function run(opts, event, deps) {
     const { membership } = await res.json().catch(() => ({}));
     const args = [`remote="${origin}"`, ...upstream ? [`upstream="${upstream}"`] : [], ...agentName ? [`agent_name="${agentName}"`] : []].join(", ");
     const keep = agentName ? " Use exactly that agent_name: it's how hub notices find this session." : "";
-    const waitingFile = (0, import_node_path7.join)(cacheDir(env), `waiting-${throttleKey}.json`);
+    const waitingFile = (0, import_node_path8.join)(cacheDir(env), `waiting-${throttleKey}.json`);
     const wasWaiting = readFlag(waitingFile);
     if (membership === "pending") {
       if (!wasWaiting) writeFlag(waitingFile);
       return event === "session-start" || !wasWaiting ? out("Agent Hub: your request to join this project is waiting for a project admin's approval. You'll be told here once it's approved.") : "";
     }
     if (wasWaiting) {
-      (0, import_node_fs6.rmSync)(waitingFile, { force: true });
+      (0, import_node_fs7.rmSync)(waitingFile, { force: true });
       if (membership === "active") return out(`Agent Hub: a project admin approved you. Call the agenthub join_project tool with ${args} to join.${keep}`);
       return out("Agent Hub: a project admin turned down your request to join this project.");
     }
     if (event !== "session-start") return "";
-    return out(`Agent Hub: this repo is on the hub. To work with teammates' agents, call the agenthub join_project tool with ${args}.${keep}`);
+    const branch = (deps.branch ?? gitBranch)(cwd);
+    const card2 = ` Pass a card with description (what this session is for), task (what it's working on)${branch ? `, branch ${JSON.stringify(branch)}` : ""} and capabilities, and call update_card whenever the task changes.`;
+    return out(`Agent Hub: this repo is on the hub. To work with teammates' agents, call the agenthub join_project tool with ${args}.${keep}${card2}`);
   }
   if (!res.ok) return "";
-  return out(formatInbox(await res.json()));
+  const inbox = await res.json();
+  const card = await keepCardCurrent(inbox, event, {
+    // Without a name the hub picks the user's latest agent here, which may be another session's.
+    branch: agentName ? (deps.branch ?? gitBranch)(cwd) : void 0,
+    stateFile: (0, import_node_path8.join)(cacheDir(env), `card-${throttleKey}.json`),
+    now: now(),
+    post: (fields) => fetchFn(`${hub}/api/card`, { method: "POST", headers, body: JSON.stringify({ ...who, ...fields }), signal })
+  }).catch(() => "");
+  return out([formatInbox(mergeInbox(takePending(env, throttleKey), inbox)), card].filter(Boolean).join("\n"));
+}
+async function keepCardCurrent(inbox, event, ctx) {
+  const card = inbox.card;
+  if (!card || card.kind === "bot") return "";
+  const lines = [];
+  const state = readState(ctx.stateFile);
+  const had = typeof card.branch === "string" ? card.branch : void 0;
+  if (ctx.branch && ctx.branch !== had) {
+    const res = await ctx.post({ branch: ctx.branch });
+    if (res.ok && had) lines.push(`Agent Hub: you switched to branch ${quote(ctx.branch)}, so your card says so now. If your task changed with it, call the agenthub update_card tool with the new task.`);
+  }
+  const missing = (inbox.card_missing ?? []).filter((k) => k === "description" || k === "task");
+  if (missing.length && (event === "session-start" || ctx.now - (state.nudged ?? 0) >= CARD_NUDGE_MS)) {
+    const list = missing.length > 1 ? missing.join(" or ") : missing[0];
+    lines.push(`Agent Hub: your card has no ${list}. Call the agenthub update_card tool with them, so teammates' agents know what this session is for and what it's working on.`);
+    state.nudged = ctx.now;
+  } else if (!missing.length && event === "prompt" && typeof card.task === "string" && ctx.now - (state.taskChecked ?? 0) >= TASK_CHECK_MS) {
+    lines.push(`Agent Hub: your card says you're working on ${quote(card.task)}. If this prompt starts something else, call the agenthub update_card tool with the new task.`);
+    state.taskChecked = ctx.now;
+  }
+  if (lines.length) writeState(ctx.stateFile, state);
+  return lines.join("\n");
+}
+function readState(path) {
+  try {
+    return JSON.parse((0, import_node_fs7.readFileSync)(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeState(path, state) {
+  (0, import_node_fs7.mkdirSync)((0, import_node_path8.join)(path, ".."), { recursive: true, mode: 448 });
+  (0, import_node_fs7.writeFileSync)(path, JSON.stringify(state));
+}
+function gitBranch(cwd) {
+  try {
+    return (0, import_node_child_process4.execFileSync)("git", ["-C", cwd, "branch", "--show-current"], { stdio: ["ignore", "pipe", "ignore"], timeout: 1e3 }).toString().trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sessionKey(hub, origin, agentName) {
+  return (0, import_node_crypto3.createHash)("sha256").update(`${hub}|${origin}|${agentName ?? ""}`).digest("hex").slice(0, 24);
 }
 function hookAgentName(payload, env) {
   if (env.AGENTHUB_AGENT_NAME) return env.AGENTHUB_AGENT_NAME;
   const session = payload?.session_id ?? payload?.sessionId;
   if (typeof session !== "string" || !session) return void 0;
-  return `s-${(0, import_node_crypto2.createHash)("sha256").update(session).digest("hex").slice(0, 8)}`;
+  return `s-${(0, import_node_crypto3.createHash)("sha256").update(session).digest("hex").slice(0, 8)}`;
 }
 function formatInbox(inbox) {
   const fresh = inbox.messages.filter((m) => m.new);
@@ -557,31 +970,31 @@ function render(format, event, text) {
 }
 function readFlag(path) {
   try {
-    (0, import_node_fs6.readFileSync)(path);
+    (0, import_node_fs7.readFileSync)(path);
     return true;
   } catch {
     return false;
   }
 }
 function writeFlag(path) {
-  (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(path, ".."), { recursive: true, mode: 448 });
-  (0, import_node_fs6.writeFileSync)(path, "{}");
+  (0, import_node_fs7.mkdirSync)((0, import_node_path8.join)(path, ".."), { recursive: true, mode: 448 });
+  (0, import_node_fs7.writeFileSync)(path, "{}");
 }
 function throttle(path, waitMs, now) {
   try {
-    const last = JSON.parse((0, import_node_fs6.readFileSync)(path, "utf8")).at;
+    const last = JSON.parse((0, import_node_fs7.readFileSync)(path, "utf8")).at;
     if (now - last < waitMs) return false;
   } catch {
   }
-  (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(path, ".."), { recursive: true, mode: 448 });
-  (0, import_node_fs6.writeFileSync)(path, JSON.stringify({ at: now }));
+  (0, import_node_fs7.mkdirSync)((0, import_node_path8.join)(path, ".."), { recursive: true, mode: 448 });
+  (0, import_node_fs7.writeFileSync)(path, JSON.stringify({ at: now }));
   return true;
 }
 async function onHub(hub, remotes, fetchFn, env, now) {
-  const path = (0, import_node_path7.join)(cacheDir(env), `providers-${(0, import_node_crypto2.createHash)("sha256").update(hub).digest("hex").slice(0, 16)}.json`);
+  const path = (0, import_node_path8.join)(cacheDir(env), `providers-${(0, import_node_crypto3.createHash)("sha256").update(hub).digest("hex").slice(0, 16)}.json`);
   let providers;
   try {
-    const cached2 = JSON.parse((0, import_node_fs6.readFileSync)(path, "utf8"));
+    const cached2 = JSON.parse((0, import_node_fs7.readFileSync)(path, "utf8"));
     if (now() - cached2.at < PROVIDERS_TTL_MS) providers = cached2.providers;
   } catch {
   }
@@ -589,8 +1002,8 @@ async function onHub(hub, remotes, fetchFn, env, now) {
     const res = await fetchFn(`${hub}/api/providers`, { signal: AbortSignal.timeout(3e3) });
     if (!res.ok) return false;
     providers = (await res.json()).providers;
-    (0, import_node_fs6.mkdirSync)((0, import_node_path7.join)(path, ".."), { recursive: true, mode: 448 });
-    (0, import_node_fs6.writeFileSync)(path, JSON.stringify({ at: now(), providers }));
+    (0, import_node_fs7.mkdirSync)((0, import_node_path8.join)(path, ".."), { recursive: true, mode: 448 });
+    (0, import_node_fs7.writeFileSync)(path, JSON.stringify({ at: now(), providers }));
   }
   const hosts = /* @__PURE__ */ new Set();
   for (const p of providers) {
@@ -618,19 +1031,20 @@ function gitRemotes(cwd) {
   const upstream = origin ? get("upstream") : void 0;
   return { ...origin ? { origin } : {}, ...upstream ? { upstream } : {} };
 }
-var import_node_child_process4, import_node_crypto2, import_node_fs6, import_node_path7, HOOK_EVENTS, EVENT_NAMES, THROTTLE_MS, PROVIDERS_TTL_MS;
+var import_node_child_process4, import_node_crypto3, import_node_fs7, import_node_path8, HOOK_EVENTS, EVENT_NAMES, THROTTLE_MS, PROVIDERS_TTL_MS, CARD_NUDGE_MS, TASK_CHECK_MS;
 var init_notify = __esm({
   "src/cli/notify.ts"() {
     "use strict";
     import_node_child_process4 = require("node:child_process");
-    import_node_crypto2 = require("node:crypto");
-    import_node_fs6 = require("node:fs");
-    import_node_path7 = require("node:path");
+    import_node_crypto3 = require("node:crypto");
+    import_node_fs7 = require("node:fs");
+    import_node_path8 = require("node:path");
     init_registry();
     init_paths();
     init_session();
     init_settings();
     init_update();
+    init_wait();
     HOOK_EVENTS = {
       SessionStart: "session-start",
       UserPromptSubmit: "prompt",
@@ -647,150 +1061,8 @@ var init_notify = __esm({
     };
     THROTTLE_MS = { "post-tool": 3e4, prompt: 1e4 };
     PROVIDERS_TTL_MS = 24 * 36e5;
-  }
-});
-
-// src/cli/watch.ts
-var watch_exports = {};
-__export(watch_exports, {
-  readEvents: () => readEvents,
-  watch: () => watch
-});
-async function watch(opts, deps) {
-  const env = deps.env ?? process.env;
-  const fetchFn = deps.fetch ?? fetch;
-  const sleep = deps.sleep ?? defaultSleep;
-  const hub = hubUrl(env);
-  if (!hub) {
-    deps.write("No hub configured. Run agenthub login --hub <url>.");
-    return 1;
-  }
-  const { origin, upstream } = (deps.remotes ?? gitRemotes)(deps.cwd ?? process.cwd());
-  if (!origin) {
-    deps.write("Not in a git repo with an origin remote.");
-    return 1;
-  }
-  const agentName = opts.agentName ?? env.AGENTHUB_AGENT_NAME;
-  const query = new URLSearchParams({ project: origin, ...upstream ? { upstream } : {}, ...agentName ? { agent_name: agentName } : {} });
-  let backoff = 1e3;
-  let saidWaiting = false;
-  let waitingApproval = false;
-  while (!opts.signal?.aborted) {
-    const token = await accessToken(hub, { store: deps.store, fetch: fetchFn, env });
-    if (!token) {
-      deps.write("Not signed in. Run agenthub login.");
-      return 1;
-    }
-    let res;
-    try {
-      res = await fetchFn(`${hub}/api/stream?${query}`, {
-        headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
-        ...opts.signal ? { signal: opts.signal } : {}
-      });
-    } catch {
-      if (opts.signal?.aborted) break;
-      await sleep(backoff, opts.signal);
-      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
-      continue;
-    }
-    if (res.status === 404) {
-      const { membership } = await res.json().catch(() => ({}));
-      if (membership === "pending") {
-        if (!waitingApproval) deps.write(opts.json ? JSON.stringify({ membership: "pending" }) : "Your request to join is waiting for a project admin's approval.");
-        waitingApproval = true;
-      } else {
-        if (waitingApproval) {
-          if (membership === "active") deps.write(opts.json ? JSON.stringify({ membership: "approved" }) : "A project admin approved you: ask your agent to call join_project.");
-          else deps.write(opts.json ? JSON.stringify({ membership: "declined" }) : "A project admin turned down your request to join.");
-          waitingApproval = false;
-          saidWaiting = true;
-        }
-        if (!saidWaiting) deps.write("No agent of yours has joined this project yet; waiting.");
-        saidWaiting = true;
-      }
-      await sleep(backoff, opts.signal);
-      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
-      continue;
-    }
-    if (res.status === 403 || res.status === 409 || res.status === 410) {
-      const body = await res.json().catch(() => ({}));
-      deps.write(body.message ?? `The hub refused the stream (${res.status}).`);
-      return 1;
-    }
-    if (!res.ok || !res.body) {
-      await res.body?.cancel();
-      await sleep(backoff, opts.signal);
-      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
-      continue;
-    }
-    backoff = 1e3;
-    saidWaiting = false;
-    let stop;
-    try {
-      for await (const ev of readEvents(res.body)) {
-        if (ev.event === "inbox") {
-          const data = JSON.parse(ev.data);
-          if (opts.json) deps.write(JSON.stringify(data));
-          else {
-            const text = formatInbox(data);
-            if (text) deps.write(text);
-          }
-        } else if (ev.event === "end") {
-          const { reason } = JSON.parse(ev.data);
-          if (reason === "replaced") {
-            deps.write("Another session joined with this agent name; stopping.");
-            stop = 1;
-          } else if (reason === "revoked") {
-            deps.write("This agent lost access to the project; stopping.");
-            stop = 1;
-          } else if (reason === "left") {
-            if (opts.json) deps.write(JSON.stringify({ left: true }));
-            else deps.write("The agent left the project; waiting for it to join again.");
-          }
-        }
-      }
-    } catch {
-    }
-    if (stop !== void 0) return stop;
-  }
-  return 0;
-}
-async function* readEvents(body) {
-  const decoder = new TextDecoder();
-  let buf = "";
-  for await (const chunk of body) {
-    buf += decoder.decode(chunk, { stream: true });
-    let i;
-    while ((i = buf.indexOf("\n\n")) >= 0) {
-      const block = buf.slice(0, i);
-      buf = buf.slice(i + 2);
-      let event = "message";
-      const data = [];
-      for (const line of block.split("\n")) {
-        if (line.startsWith("event:")) event = line.slice(6).trim();
-        else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
-      }
-      if (data.length) yield { event, data: data.join("\n") };
-    }
-  }
-}
-function defaultSleep(ms, signal) {
-  return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    signal?.addEventListener("abort", () => {
-      clearTimeout(t);
-      resolve();
-    }, { once: true });
-  });
-}
-var MAX_BACKOFF_MS;
-var init_watch = __esm({
-  "src/cli/watch.ts"() {
-    "use strict";
-    init_notify();
-    init_session();
-    init_settings();
-    MAX_BACKOFF_MS = 3e4;
+    CARD_NUDGE_MS = 10 * 6e4;
+    TASK_CHECK_MS = 30 * 6e4;
   }
 });
 
@@ -3664,16 +3936,16 @@ var require_connect = __commonJS({
           }
         });
       }
-      get(sessionKey) {
-        const ref = this._sessionCache.get(sessionKey);
+      get(sessionKey2) {
+        const ref = this._sessionCache.get(sessionKey2);
         return ref ? ref.deref() : null;
       }
-      set(sessionKey, session) {
+      set(sessionKey2, session) {
         if (this._maxCachedSessions === 0) {
           return;
         }
-        if (this._sessionCache.has(sessionKey)) {
-          this._sessionCache.delete(sessionKey);
+        if (this._sessionCache.has(sessionKey2)) {
+          this._sessionCache.delete(sessionKey2);
         } else if (this._sessionCache.size >= this._maxCachedSessions) {
           let evicted = false;
           for (const [key, ref] of this._sessionCache) {
@@ -3690,8 +3962,8 @@ var require_connect = __commonJS({
             }
           }
         }
-        this._sessionCache.set(sessionKey, new WeakRef(session));
-        this._sessionRegistry.register(session, sessionKey);
+        this._sessionCache.set(sessionKey2, new WeakRef(session));
+        this._sessionRegistry.register(session, sessionKey2);
       }
     };
     function buildConnector({ allowH2, useH2c, maxCachedSessions, socketPath, timeout, session: customSession, ...opts }) {
@@ -3709,9 +3981,9 @@ var require_connect = __commonJS({
             tls = require("node:tls");
           }
           servername = servername || options.servername || util.getServerName(host) || null;
-          const sessionKey = servername || hostname3;
-          assert2(sessionKey);
-          const session = customSession || sessionCache.get(sessionKey) || null;
+          const sessionKey2 = servername || hostname3;
+          assert2(sessionKey2);
+          const session = customSession || sessionCache.get(sessionKey2) || null;
           port = port || 443;
           socket = tls.connect({
             highWaterMark: 16384,
@@ -3727,7 +3999,7 @@ var require_connect = __commonJS({
             host: hostname3
           });
           socket.on("session", function(session2) {
-            sessionCache.set(sessionKey, session2);
+            sessionCache.set(sessionKey2, session2);
           });
         } else {
           assert2(!httpSocket, "httpSocket can only be sent on TLS update");
@@ -10903,7 +11175,7 @@ var require_socks5_client = __commonJS({
       USERNAME_PASSWORD: 2,
       NO_ACCEPTABLE: 255
     };
-    var COMMANDS = {
+    var COMMANDS2 = {
       CONNECT: 1,
       BIND: 2,
       UDP_ASSOCIATE: 3
@@ -11105,7 +11377,7 @@ var require_socks5_client = __commonJS({
         }
         debug("connecting to", address, port);
         this.state = STATES.CONNECTING;
-        const request = this.buildConnectRequest(COMMANDS.CONNECT, address, port);
+        const request = this.buildConnectRequest(COMMANDS2.CONNECT, address, port);
         this.socket.write(request);
       }
       /**
@@ -11210,7 +11482,7 @@ var require_socks5_client = __commonJS({
     module2.exports = {
       Socks5Client,
       AUTH_METHODS,
-      COMMANDS,
+      COMMANDS: COMMANDS2,
       ADDRESS_TYPES,
       REPLY_CODES,
       STATES
@@ -27432,7 +27704,7 @@ function dispatcherFor(instance) {
   if (!instance.caBundlePath) return void 0;
   let d = dispatchers.get(instance.id);
   if (!d) {
-    const ca = (0, import_node_fs7.readFileSync)(instance.caBundlePath, "utf8");
+    const ca = (0, import_node_fs8.readFileSync)(instance.caBundlePath, "utf8");
     d = new import_undici.Agent({ connect: { ca: [...import_node_tls.rootCertificates, ca] } });
     dispatchers.set(instance.id, d);
   }
@@ -27449,11 +27721,11 @@ function fetchFor(instance, override) {
     signal: AbortSignal.timeout(1e4)
   });
 }
-var import_node_fs7, import_node_tls, import_undici, dispatchers;
+var import_node_fs8, import_node_tls, import_undici, dispatchers;
 var init_http = __esm({
   "src/providers/http.ts"() {
     "use strict";
-    import_node_fs7 = require("node:fs");
+    import_node_fs8 = require("node:fs");
     import_node_tls = require("node:tls");
     import_undici = __toESM(require_undici(), 1);
     dispatchers = /* @__PURE__ */ new Map();
@@ -55332,7 +55604,7 @@ var init_types = __esm({
 
 // src/providers/config.ts
 function loadConfigFile(path, opts = {}) {
-  const read = opts.readFile ?? ((p) => (0, import_node_fs8.readFileSync)(p, "utf8"));
+  const read = opts.readFile ?? ((p) => (0, import_node_fs9.readFileSync)(p, "utf8"));
   let text;
   try {
     text = read(path);
@@ -55343,7 +55615,7 @@ function loadConfigFile(path, opts = {}) {
 }
 function buildConfig(raw, opts = {}) {
   const env = opts.env ?? process.env;
-  const read = opts.readFile ?? ((p) => (0, import_node_fs8.readFileSync)(p, "utf8"));
+  const read = opts.readFile ?? ((p) => (0, import_node_fs9.readFileSync)(p, "utf8"));
   const parsed = configSchema.safeParse(raw);
   if (!parsed.success) {
     throw new ConfigError(
@@ -55524,11 +55796,11 @@ function checkNoHostCollisions(instances) {
     for (const a of inst.remoteAliases) claim2(a.port ? `${a.host}:${a.port}` : a.host, inst.id);
   }
 }
-var import_node_fs8, import_yaml, secretRef, oauthSchema, providerSchema, configSchema, ConfigError;
+var import_node_fs9, import_yaml, secretRef, oauthSchema, providerSchema, configSchema, ConfigError;
 var init_config = __esm({
   "src/providers/config.ts"() {
     "use strict";
-    import_node_fs8 = require("node:fs");
+    import_node_fs9 = require("node:fs");
     import_yaml = __toESM(require_dist(), 1);
     init_zod();
     init_defaults();
@@ -55629,7 +55901,7 @@ var init_admin = __esm({
 });
 
 // src/cli/index.ts
-var import_node_fs9 = require("node:fs");
+var import_node_fs10 = require("node:fs");
 
 // src/cli/credentials.ts
 var import_node_child_process = require("node:child_process");
@@ -55788,15 +56060,52 @@ function notify(event, sessionID, cwd) {
   });
 }
 
+/** Runs \`agenthub wait\`; resolves to the text to wake the session with, or "" when it shouldn't. */
+function waitForMessage(sessionID, cwd, children) {
+  return new Promise((resolve) => {
+    let out = "";
+    let child;
+    try {
+      child = spawn(COMMAND, ["wait"], { cwd, stdio: ["pipe", "pipe", "ignore"], windowsHide: true, shell: process.platform === "win32" });
+    } catch {
+      return resolve("");
+    }
+    children.get(sessionID)?.kill();
+    children.set(sessionID, child);
+    child.stdout.on("data", (chunk) => (out += chunk));
+    child.on("error", () => resolve(""));
+    child.on("close", (code) => {
+      if (children.get(sessionID) === child) children.delete(sessionID);
+      // An agenthub too old to know \`wait\` exits 2 too, but prints nothing on stdout.
+      resolve(code === 2 ? out.trim() : "");
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify({ session_id: sessionID, cwd }));
+  });
+}
+
 function partId() {
   return "prt_" + Date.now().toString(16) + Math.random().toString(36).slice(2, 12);
 }
 
-export const AgentHub = async ({ directory }) => {
+export const AgentHub = async ({ directory, client }) => {
   const started = new Set();
+  const waiting = new Map();
   let presence = Promise.resolve();
+  const wake = async (sessionID) => {
+    const send = client?.session?.promptAsync ?? client?.session?.prompt;
+    if (!send) return;
+    const text = await waitForMessage(sessionID, directory, waiting);
+    if (!text) return;
+    try {
+      await send.call(client.session, { path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
+    } catch {
+      /* the session is gone, or busy again */
+    }
+  };
   return {
     "chat.message": async (input, output) => {
+      waiting.get(input.sessionID)?.kill();
       const first = !started.has(input.sessionID);
       started.add(input.sessionID);
       const text = await notify(first ? "session-start" : "prompt", input.sessionID, directory);
@@ -55811,8 +56120,15 @@ export const AgentHub = async ({ directory }) => {
     // Presence updates don't block OpenCode, but run one at a time so "offline" can't be
     // overtaken by an earlier "idle".
     event: async ({ event }) => {
-      if (event.type === "session.idle") presence = presence.then(() => notify("stop", event.properties.sessionID, directory));
-      else if (event.type === "session.deleted") presence = presence.then(() => notify("session-end", event.properties.info.id, directory));
+      if (event.type === "session.idle") {
+        const sessionID = event.properties.sessionID;
+        presence = presence.then(() => notify("stop", sessionID, directory));
+        // Not awaited: it waits as long as the session is idle.
+        presence.then(() => wake(sessionID)).catch(() => {});
+      } else if (event.type === "session.deleted") {
+        waiting.get(event.properties.info.id)?.kill();
+        presence = presence.then(() => notify("session-end", event.properties.info.id, directory));
+      }
     },
   };
 };
@@ -55869,6 +56185,8 @@ var COPILOT_EVENTS = [
   ["agentStop", "stop"],
   ["sessionEnd", "session-end"]
 ];
+var WAIT_MAX_S = 12 * 3600;
+var WAIT_TIMEOUT_S = WAIT_MAX_S + 60;
 var TIMEOUT_S = { "claude-code": {}, codex: { SessionEnd: 3 } };
 function hookFile(harness, scope, cwd, home = (0, import_node_os2.homedir)(), env = process.env) {
   const user = scope === "user";
@@ -55883,7 +56201,7 @@ function hookFile(harness, scope, cwd, home = (0, import_node_os2.homedir)(), en
       return user ? (0, import_node_path3.join)(env.XDG_CONFIG_HOME || (0, import_node_path3.join)(home, ".config"), "opencode", "plugins", "agenthub.js") : (0, import_node_path3.join)(cwd, ".opencode", "plugins", "agenthub.js");
   }
 }
-var OURS = [/^(?:\S*[\\/])?agenthub(?:\.js|\.exe)?\s+notify\b/i, /^"(?:[^"]*[\\/])?agenthub(?:\.js|\.exe)?"\s+notify\b/i];
+var OURS = [/^(?:\S*[\\/])?agenthub(?:\.js|\.exe)?\s+(?:notify|wait)\b/i, /^"(?:[^"]*[\\/])?agenthub(?:\.js|\.exe)?"\s+(?:notify|wait)\b/i];
 var isOurs = (h) => typeof h.command === "string" && OURS.some((r) => r.test(h.command));
 function installHooks(harness, file2, command = "agenthub") {
   (0, import_node_fs2.mkdirSync)((0, import_node_path3.dirname)(file2), { recursive: true });
@@ -55908,6 +56226,9 @@ function installHooks(harness, file2, command = "agenthub") {
     const groups = (hooks[event] ?? []).map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length);
     const entry = { hooks: [{ type: "command", command: `${command} notify --format ${harness}`, timeout: TIMEOUT_S[harness][event] ?? 10 }] };
     if (event === "PostToolUse" && harness === "claude-code") entry.matcher = "*";
+    if (event === "Stop" && harness === "claude-code") {
+      entry.hooks.push({ type: "command", command: `${command} wait --max ${WAIT_MAX_S}`, asyncRewake: true, timeout: WAIT_TIMEOUT_S });
+    }
     hooks[event] = [...groups, entry];
   }
   writeJson(file2, config2);
@@ -56007,34 +56328,182 @@ function openBrowser(url2) {
 
 // src/cli/index.ts
 init_notify();
+
+// src/cli/help.ts
+var HARNESS_LIST = "claude-code, codex, copilot or opencode";
+var COMMANDS = {
+  login: {
+    short: "sign in to a hub",
+    usage: ["agenthub login [--hub <url>]"],
+    summary: "Sign in to a hub with the device flow.",
+    details: [
+      "Opens a code to enter in the browser, then keeps the token in the OS keychain (macOS Keychain or Secret Service), or in a 0600 file in ~/.config/agenthub when there's none.",
+      "The hub is remembered, so later commands and the hooks don't need --hub. Hooks refresh the token themselves."
+    ],
+    examples: [
+      ["agenthub login --hub https://hub.theagenthub.app", "sign in to the public hub"],
+      ["agenthub login --hub https://hub.example.com", "sign in to a self-hosted hub"],
+      ["agenthub login", "sign in again to the hub you used last"]
+    ]
+  },
+  logout: {
+    short: "forget this machine's token",
+    usage: ["agenthub logout"],
+    summary: "Forget this machine's token for the current hub.",
+    examples: [["agenthub logout", ""]]
+  },
+  status: {
+    short: "show the hub, sign-in and version",
+    usage: ["agenthub status"],
+    summary: "Show the hub, whether you're signed in, and the CLI version (and whether a newer one is out).",
+    examples: [["agenthub status", ""]]
+  },
+  token: {
+    short: "print a fresh hub access token",
+    usage: ["agenthub token [--json]"],
+    summary: "Print a fresh hub access token, for plugins that call the hub's MCP server (the pi extension uses it).",
+    examples: [
+      ["agenthub token", "just the token"],
+      ["agenthub token --json", '{"hub", "token", "expires_at"}']
+    ]
+  },
+  update: {
+    short: "update this CLI",
+    usage: ["agenthub update [--check] [--version <v>]"],
+    summary: "Replace this CLI with the latest release, after checking it against SHA256SUMS and that it runs.",
+    details: ["A CLI installed with npm can't replace itself; update it the way you installed it."],
+    examples: [
+      ["agenthub update", "install the latest release"],
+      ["agenthub update --check", "only say whether there's a newer one"],
+      ["agenthub update --version v0.3.0", "install a specific release"]
+    ]
+  },
+  hooks: {
+    short: "add or remove the hooks for a harness",
+    usage: [`agenthub hooks install <harness> [--scope user|project]`, `agenthub hooks uninstall <harness> [--scope user|project]`],
+    summary: `Add the hooks that bring hub messages into a harness's sessions, for ${HARNESS_LIST}. Not needed with a harness plugin.`,
+    details: [
+      "--scope user (the default) writes your own settings; --scope project writes the repo's local settings.",
+      "Claude Code: ~/.claude/settings.json (or .claude/settings.local.json), including the Stop hook that wakes an idle session.",
+      "Codex: ~/.codex/hooks.json; then trust the hooks in Codex's /hooks. Copilot CLI: ~/.copilot/hooks/agenthub.json. OpenCode: a plugin in ~/.config/opencode/plugins/.",
+      "Re-running install updates the hooks; uninstall removes only ours."
+    ],
+    examples: [
+      ["agenthub hooks install claude-code", "for all your Claude Code sessions"],
+      ["agenthub hooks install codex", "then open /hooks in Codex to trust them"],
+      ["agenthub hooks install opencode --scope project", "only in this repo"],
+      ["agenthub hooks uninstall claude-code", ""]
+    ]
+  },
+  watch: {
+    short: "print new messages as they arrive",
+    usage: ["agenthub watch [--json] [--agent <name>]"],
+    summary: "Print this repo's agent's new hub messages as they arrive. For a terminal next to an agent that can't be woken (Codex, Copilot CLI), or a script.",
+    details: ["Waits for the agent to join, reconnects by itself, and stops when the agent is replaced or loses access."],
+    examples: [
+      ["agenthub watch", "your most recently active agent in this repo"],
+      ["agenthub watch --agent reviewer", "a named agent"],
+      ["agenthub watch --json | jq .messages", "JSON lines, for a script"]
+    ]
+  },
+  wake: {
+    short: "turn waking idle agents on or off, for every repo or one",
+    usage: ["agenthub wake [on|off|all] [--project]", "agenthub wake default --project"],
+    summary: "Choose whether idle agents are started up when a hub message arrives, in Claude Code, OpenCode and pi.",
+    details: [
+      "on (the default): requests and replies wake an idle agent; fyi waits for its next turn. all: fyi wakes it too. off: nothing wakes it.",
+      "--project sets it for the repo you're in only; it wins over your setting for every repo. default --project removes the repo's own setting.",
+      "Without on|off|all it shows what applies here and where that comes from. AGENTHUB_WAKE=0|on|all overrides it for one shell."
+    ],
+    examples: [
+      ["agenthub wake", "what applies in this repo"],
+      ["agenthub wake off", "never wake idle agents"],
+      ["agenthub wake off --project", "not in this repo, still elsewhere"],
+      ["agenthub wake all --project", "in this repo, wake for fyi too"],
+      ["agenthub wake default --project", "this repo follows your setting again"]
+    ]
+  },
+  notify: {
+    short: "print new messages for a hook",
+    usage: ["agenthub notify --format <claude-code|codex|copilot|text> [--event <session-start|prompt|post-tool|stop|session-end>]"],
+    summary: "What the harness hooks run: reads the hook's JSON on stdin and prints new hub messages for the session, in the harness's format. You don't run it yourself.",
+    details: ["It never fails the harness: off the hub, signed out or on any error it prints nothing. Stop marks the agent idle and session-end takes it offline."],
+    examples: [[`echo '{"hook_event_name":"UserPromptSubmit","session_id":"abc"}' | agenthub notify --format text`, "see what a hook would print"]]
+  },
+  wait: {
+    short: "wait for a message that should wake an idle agent",
+    usage: ["agenthub wait [--max <seconds>]"],
+    summary: "What harnesses run when their agent goes idle: waits for a hub message that should wake it, then exits 2 and prints the summaries (else 0). You don't run it yourself.",
+    details: ["The next prompt, a newer waiter for the same session, or --max (12 hours by default) stops it. `agenthub wake` decides whether it waits at all."],
+    examples: [[`echo '{"session_id":"abc"}' | agenthub wait --max 60; echo $?`, "wait up to a minute; 2 means it would wake the agent"]]
+  },
+  admin: {
+    short: "check a hub's code host config",
+    usage: ["agenthub admin providers check [--config <file>]", "agenthub admin providers resolve <remote> [--config <file>]"],
+    summary: "For hub operators: test the code hosts in a providers.yaml, or show the project ID a git remote maps to.",
+    details: ["--config defaults to $AGENTHUB_CONFIG, else the built-in public hosts."],
+    examples: [
+      ["agenthub admin providers check --config providers.yaml", ""],
+      ["agenthub admin providers resolve git@github.com:acme/shop.git", ""]
+    ]
+  }
+};
+var GROUPS = [
+  ["Set up", ["login", "hooks", "status", "logout"]],
+  ["Day to day", ["watch", "wake", "update"]],
+  ["Used by hooks and plugins", ["notify", "wait", "token"]],
+  ["Hub operators", ["admin"]]
+];
+var ENVIRONMENT = `Environment:
+  AGENTHUB_URL              the hub (else the one from agenthub login)
+  AGENTHUB_AGENT_NAME       a fixed agent name for hooks (default: one per harness session)
+  AGENTHUB_WAKE=0|on|all    whether idle agents are woken; overrides agenthub wake
+  AGENTHUB_CREDENTIAL_STORE=file|keychain|auto
+  AGENTHUB_HOME             config directory (default ~/.config/agenthub)
+  AGENTHUB_DOWNLOAD_URL     where releases come from
+  AGENTHUB_NO_UPDATE_CHECK=1  no daily "newer version" notice`;
+function overview() {
+  const width = Math.max(...Object.keys(COMMANDS).map((c) => c.length)) + 2;
+  const lines = ["agenthub: connects your coding agents to Agent Hub, so they can trade reviews, questions and handoffs with teammates' agents.", ""];
+  for (const [title, names] of GROUPS) {
+    lines.push(`${title}:`);
+    for (const n of names) lines.push(`  ${n.padEnd(width)}${COMMANDS[n].short}`);
+    lines.push("");
+  }
+  lines.push(
+    "Get started:",
+    "  agenthub login --hub https://hub.theagenthub.app",
+    "  agenthub hooks install claude-code     (or use the Claude Code, Codex, OpenCode or pi plugin instead)",
+    "  agenthub status",
+    "",
+    ENVIRONMENT,
+    "",
+    "agenthub help <command> (or agenthub <command> --help) shows its options and examples. agenthub --version prints the version."
+  );
+  return lines.join("\n");
+}
+function commandHelp(name) {
+  const c = COMMANDS[name];
+  if (!c) return void 0;
+  const lines = ["usage:", ...c.usage.map((u) => `  ${u}`), "", c.summary];
+  if (c.details?.length) lines.push("", ...c.details);
+  lines.push("", "examples:");
+  for (const [cmd, note] of c.examples) lines.push(`  ${cmd}${note ? `
+      ${note}` : ""}`);
+  return lines.join("\n");
+}
+
+// src/cli/index.ts
 init_settings();
 var import_meta = {};
 function version2() {
-  if (true) return "0.3.0";
+  if (true) return "0.3.1";
   try {
-    return JSON.parse((0, import_node_fs9.readFileSync)(new URL("../../package.json", import_meta.url), "utf8")).version;
+    return JSON.parse((0, import_node_fs10.readFileSync)(new URL("../../package.json", import_meta.url), "utf8")).version;
   } catch {
     return "unknown";
   }
 }
-var USAGE = `usage:
-  agenthub login [--hub <url>]              sign in with the device flow; keeps the token in the OS keychain
-  agenthub logout                           forget this machine's hub token
-  agenthub status                           show the hub and whether you're signed in
-  agenthub token [--json]                   print a fresh hub access token, for plugins that call the hub's MCP server
-  agenthub --version                        print the CLI version
-  agenthub update [--check] [--version <v>] replace this CLI with the latest release (or <v>); --check only reports
-  agenthub notify --format <claude-code|codex|copilot|text> [--event <session-start|prompt|post-tool|stop|session-end>]
-                                            print new hub messages for a harness hook (reads the hook's JSON on stdin)
-  agenthub watch [--json] [--agent <name>]    print this repo's agent's new hub messages as they arrive
-  agenthub hooks install <claude-code|codex|copilot|opencode> [--scope user|project]
-  agenthub hooks uninstall <claude-code|codex|copilot|opencode> [--scope user|project]
-  agenthub admin providers check [--config <file>]           test every provider instance
-  agenthub admin providers resolve <remote> [--config <file>]  show the project ID a remote maps to
-
-Environment: AGENTHUB_URL (hub), AGENTHUB_AGENT_NAME (fixed agent name for hooks; default: one per harness session),
-AGENTHUB_CREDENTIAL_STORE=file|keychain|auto, AGENTHUB_HOME (config directory),
-AGENTHUB_DOWNLOAD_URL (where releases come from), AGENTHUB_NO_UPDATE_CHECK=1 (no daily "newer version" notice).`;
 function flag(args, name) {
   const i = args.indexOf(name);
   if (i < 0) return void 0;
@@ -56072,6 +56541,24 @@ async function readStdin(timeoutMs) {
 async function main(argv) {
   const args = [...argv];
   const cmd = args.shift();
+  if (cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    const topic = cmd === "help" ? args[0] : void 0;
+    if (!topic) {
+      console.log(overview());
+      return 0;
+    }
+    const text = commandHelp(topic);
+    if (!text) {
+      console.error(`agenthub: no command "${topic}". Run agenthub help for the list.`);
+      return 2;
+    }
+    console.log(text);
+    return 0;
+  }
+  if (commandHelp(cmd) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(commandHelp(cmd));
+    return 0;
+  }
   if (cmd === "--version" || cmd === "version") {
     console.log(version2());
     return 0;
@@ -56096,6 +56583,61 @@ async function main(argv) {
     process.once("SIGTERM", () => ac.abort());
     return watch2({ json: json2, agentName, signal: ac.signal }, { store: credentialStore(), write: (l) => console.log(l) });
   }
+  if (cmd === "wake") {
+    const { wakeSetting: wakeSetting2 } = await Promise.resolve().then(() => (init_wait(), wait_exports));
+    const { gitRemotes: gitRemotes2 } = await Promise.resolve().then(() => (init_notify(), notify_exports));
+    const perProject = args.includes("--project");
+    const value = args.filter((a) => a !== "--project").shift();
+    const origin = gitRemotes2(process.cwd()).origin;
+    const key = origin ? projectKey(origin) : void 0;
+    const describe3 = (mode) => mode === "off" ? "off: idle agents aren't woken" : mode === "all" ? "all: idle agents are woken for every message, fyi too" : "on: idle agents are woken for requests and replies, not fyi";
+    if (value === void 0) {
+      const { mode, from } = wakeSetting2(process.env, origin);
+      const source = { env: " (from AGENTHUB_WAKE)", project: ` (this repo's setting, ${key})`, user: " (your setting for every repo)", default: " (the default)" }[from];
+      console.log(describe3(mode) + source);
+      return 0;
+    }
+    if (!["on", "off", "all", ...perProject ? ["default"] : []].includes(value)) {
+      console.error(commandHelp("wake"));
+      return 2;
+    }
+    const settings = readSettings();
+    if (perProject) {
+      if (!key) {
+        console.error("Not in a git repo with an origin remote; run it in the repo, or leave out --project.");
+        return 1;
+      }
+      const projects = { ...settings.wake_projects };
+      if (value === "default") delete projects[key];
+      else projects[key] = value;
+      writeSettings({ ...settings, wake_projects: projects });
+    } else {
+      writeSettings({ ...settings, wake: value });
+    }
+    const where = perProject ? `in ${key}` : "in every repo without its own setting";
+    if (value === "default") console.log(`${key} now follows your setting for every repo: ${describe3(wakeSetting2({ ...process.env, AGENTHUB_WAKE: void 0 }, origin).mode)}.`);
+    else if (value === "off") console.log(`Idle agents won't be woken for hub messages ${where}. They still see them on their next turn.`);
+    else console.log(`Idle agents will be woken for ${value === "all" ? "every hub message, fyi too" : "requests and replies"} ${where}, in Claude Code, OpenCode and pi.`);
+    if (process.env.AGENTHUB_WAKE !== void 0) console.log(`AGENTHUB_WAKE=${process.env.AGENTHUB_WAKE} is set in this shell and wins over this setting.`);
+    return 0;
+  }
+  if (cmd === "wait") {
+    try {
+      const max = Number(flag(args, "--max"));
+      const payload = await readStdin(500);
+      const { wait: wait2 } = await Promise.resolve().then(() => (init_wait(), wait_exports));
+      const ac = new AbortController();
+      process.once("SIGINT", () => ac.abort());
+      process.once("SIGTERM", () => ac.abort());
+      const result = await wait2({ payload, signal: ac.signal, ...max > 0 ? { maxMs: max * 1e3 } : {} }, { store: credentialStore() });
+      if (result.code === 2 && result.text) {
+        process.stdout.write(result.text + "\n");
+        return 2;
+      }
+    } catch {
+    }
+    return 0;
+  }
   if (cmd === "update") {
     const { selfUpdate: selfUpdate2 } = await Promise.resolve().then(() => (init_update(), update_exports));
     const v = flag(args, "--version");
@@ -56161,7 +56703,7 @@ version: ${version2()}${newer}`);
     const harness = args.shift();
     const scope = flag(args, "--scope") ?? "user";
     if (action !== "install" && action !== "uninstall" || !HARNESSES.includes(harness) || scope !== "user" && scope !== "project") {
-      console.error(USAGE);
+      console.error(commandHelp("hooks"));
       return 2;
     }
     const h = harness;
@@ -56179,9 +56721,9 @@ version: ${version2()}${newer}`);
   }
   if (cmd === "admin") {
     const { admin: admin2 } = await Promise.resolve().then(() => (init_admin(), admin_exports));
-    return admin2(args, USAGE);
+    return admin2(args, commandHelp("admin"));
   }
-  console.error(USAGE);
+  console.error(`agenthub: no command "${cmd}". Run agenthub help for the list.`);
   return 2;
 }
 main(process.argv.slice(2)).then(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theagenthub/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The Agent Hub CLI: sign in to a hub and bring teammates' agents' messages into Claude Code, Codex, Copilot CLI and OpenCode.",
   "bin": {
     "agenthub": "bin/agenthub.cjs"