agents-pod 0.2.0 → 0.3.1

package/examples/feishu/feishu_deliver.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Feishu reply deliverer — the single agents-pod delivery command (ADR 0025).
+
+The wrapper invokes this once per outbox entry, at wake-up exit. The entry
+arrives verbatim on stdin:
+
+    {"to": "chat=<chat_id>;affinity=<root_id>[;thread=<thread_id>]", "text": "…"}
+
+`to` is the Delivery Address rendered by `{{reply_to}}` (ADR 0026). A reply goes
+to the affinity message — inside its thread when `thread` is present — so the
+human's answer inherits `root_id` and the next turn routes back to the same
+Conversation. `AGENTS_POD_OUTBOX_UUID` is Feishu's one-hour reply idempotency
+key: the same value is sent on every retry of the same entry.
+
+Exit 0 acknowledges delivery (core deletes the entry); anything else leaves the
+file for the next pass. `--check` (ADR 0027) prints a self-check instead, and
+exits 0 healthy or 1 not.
+"""
+
+import json
+import os
+import sys
+
+import feishu_client as fc
+
+# Feishu text messages cap at 150 KB; a chat reply has no business being long.
+TEXT_CAP = 30000
+
+
+def parse_address(raw):
+    """`chat=…;affinity=…[;thread=…]` → dict, tolerating spaces and order."""
+    fields = {}
+    for part in (raw or "").split(";"):
+        key, _, value = part.partition("=")
+        key = key.strip().lower()
+        if key:
+            fields[key] = value.strip()
+    return fields
+
+
+def reply(token, fields, text, uuid):
+    chat_id = fields.get("chat", "")
+    affinity = fields.get("affinity", "")
+    thread_id = fields.get("thread", "")
+    content = json.dumps({"text": text}, ensure_ascii=False)
+    body = {"msg_type": "text", "content": content}
+    if uuid:
+        body["uuid"] = uuid
+
+    if affinity:
+        try:
+            payload = dict(body)
+            if thread_id:
+                payload["reply_in_thread"] = True
+            fc.api("POST", "/im/v1/messages/%s/reply" % affinity, token=token, body=payload)
+            return "reply:%s%s" % (affinity, ":thread" if thread_id else "")
+        except fc.FeishuError as err:
+            sys.stderr.write("[feishu-deliver] reply to %s failed (%s); trying the chat\n"
+                             % (affinity, err))
+            if not chat_id:
+                raise
+    if not chat_id:
+        raise fc.FeishuError("/im/v1/messages", "no-address", "neither affinity nor chat")
+    fc.api("POST", "/im/v1/messages", token=token,
+           params={"receive_id_type": "chat_id"},
+           body={"receive_id": chat_id, **body})
+    return "chat:%s" % chat_id
+
+
+def self_check():
+    """`--check`: the operator command's own report (ADR 0027). Exit 0 healthy, 1 not."""
+    fc.load_env()
+    try:
+        fc.tenant_token()
+    except fc.FeishuError as err:
+        print("no tenant token: %s" % err)
+        print("  credentials live in .env beside this file: cp .env.example .env, then fill")
+        return 1
+    print("token ok (tenant_access_token)")
+
+    address = "chat=oc_x;affinity=om_x;thread=t_x"
+    parsed = parse_address(address)
+    if parsed != {"chat": "oc_x", "affinity": "om_x", "thread": "t_x"}:
+        print("Delivery Address parser broken: %r -> %r" % (address, parsed))
+        return 1
+    print("Delivery Address parser ok: chat=…;affinity=…[;thread=…]")
+
+    # No scope-check endpoint exists: `im:message:send_as_bot` is proven by a
+    # real send, and a probe must not post into someone's chat.
+    print("send scope is only proven by a real send; the first reply verifies it")
+    return 0
+
+
+def main():
+    if "--check" in sys.argv[1:]:
+        return self_check()
+    fc.load_env()
+    raw = sys.stdin.read()
+    try:
+        entry = json.loads(raw)
+    except ValueError:
+        sys.stderr.write("[feishu-deliver] entry is not JSON\n")
+        return 1
+    if not isinstance(entry, dict):
+        sys.stderr.write("[feishu-deliver] entry is not a JSON object\n")
+        return 1
+
+    text = entry.get("text")
+    address = entry.get("to")
+    if not isinstance(text, str) or not text.strip():
+        sys.stderr.write("[feishu-deliver] entry has no text\n")
+        return 1
+    if not isinstance(address, str) or not address.strip():
+        sys.stderr.write("[feishu-deliver] entry has no Delivery Address\n")
+        return 1
+    if len(text) > TEXT_CAP:
+        text = text[:TEXT_CAP] + "\n…(truncated)"
+
+    fields = parse_address(address)
+    if not fields.get("chat") and not fields.get("affinity"):
+        sys.stderr.write("[feishu-deliver] unusable Delivery Address %r\n" % address)
+        return 1
+
+    uuid = (os.environ.get("AGENTS_POD_OUTBOX_UUID") or "").strip()
+    try:
+        token = fc.tenant_token()
+        where = reply(token, fields, text, uuid)
+    except fc.FeishuError as err:
+        sys.stderr.write("[feishu-deliver] %s\n" % err)
+        return 1
+    sys.stdout.write("[feishu-deliver] delivered to %s\n" % where)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/examples/feishu/feishu_drain.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""Feishu pull drain — an agents-pod Source command (ADR 0024).
+
+One invocation = one reconcile pass. Reads every group chat the bot is in
+(plus the thread containers those chats reveal) from the committed cursor,
+prints one JSONL item per human message, then the new cursor.
+
+Environment (all optional, read from `~/.agents/pods/adapters/.env` too):
+  FEISHU_APP_ID / FEISHU_APP_SECRET   the bot app credentials
+  FEISHU_CHATS                        comma-separated chat_id allowlist (empty: all)
+  FEISHU_REQUIRE_MENTION              1 = only messages that @-mention the bot
+  FEISHU_LOOKBACK_SECONDS             read this far back when there is no cursor (3600)
+  FEISHU_OVERLAP_SECONDS              re-read overlap behind the cursor (60)
+  FEISHU_MAX_ITEMS                    at most this many items per drain (40)
+  --check                             print a self-check instead of draining (ADR 0027):
+                                      exit 0 healthy, 1 not; `agents-pod doctor --probe`
+                                      runs it and quotes these lines
+
+The cursor never advances past an item this drain did not print, so a burst
+bigger than FEISHU_MAX_ITEMS simply arrives over several passes. p2p chats are
+not enumerable (ADR 0024), so only group conversations are read.
+"""
+
+import json
+import os
+import re
+import sys
+import time
+
+import feishu_client as fc
+
+PAGE_SIZE = 50
+THREAD_PAGE_CEILING = 6
+THREAD_KEEP_SECONDS = 7 * 24 * 3600
+
+
+def env_int(name, default):
+    try:
+        return int(str(os.environ.get(name, "")).strip() or default)
+    except ValueError:
+        return default
+
+
+def env_flag(name):
+    return str(os.environ.get(name, "")).strip().lower() in ("1", "true", "yes", "on")
+
+
+def warn(message):
+    sys.stderr.write("[feishu-drain] %s\n" % message)
+
+
+def list_chats(token):
+    """Every chat the bot can see; the chat list itself excludes p2p (ADR 0024)."""
+    chats, page_token = [], ""
+    while True:
+        data = fc.api("GET", "/im/v1/chats", token=token,
+                      params={"page_size": 100, "page_token": page_token})
+        chats.extend(data.get("items") or [])
+        page_token = data.get("page_token") or ""
+        if not data.get("has_more") or not page_token:
+            return chats
+
+
+def iter_messages(token, container_type, container_id, since=None):
+    """Pages one container in ascending create-time order."""
+    page_token, pages = "", 0
+    while True:
+        params = {
+            "container_id_type": container_type,
+            "container_id": container_id,
+            "sort_type": "ByCreateTimeAsc",
+            "page_size": PAGE_SIZE,
+            "page_token": page_token,
+            "start_time": since if since else None,
+        }
+        data = fc.api("GET", "/im/v1/messages", token=token, params=params)
+        for msg in data.get("items") or []:
+            yield msg
+        page_token = data.get("page_token") or ""
+        pages += 1
+        if not data.get("has_more") or not page_token:
+            return
+        if container_type == "thread" and pages >= THREAD_PAGE_CEILING:
+            warn("thread %s: stopped after %d pages (ceiling)" % (container_id, pages))
+            return
+
+
+def created_at(msg):
+    try:
+        return int(msg.get("create_time") or 0) // 1000
+    except (TypeError, ValueError):
+        return 0
+
+
+def is_bot(msg):
+    return ((msg.get("sender") or {}).get("sender_type") or "") == "app"
+
+
+def mentions_bot(msg, open_id):
+    if not open_id:
+        return True
+    for mention in msg.get("mentions") or []:
+        if (mention.get("id") or {}).get("open_id") == open_id:
+            return True
+    return False
+
+
+def main():
+    if "--check" in sys.argv[1:]:
+        return self_check()
+    fc.load_env()
+    try:
+        token = fc.tenant_token()
+    except fc.FeishuError as err:
+        warn("no tenant token: %s" % err)
+        return 1
+
+    cursor_raw = (os.environ.get("AGENTS_POD_CURSOR") or "").strip()
+    now = int(time.time())
+    overlap = env_int("FEISHU_OVERLAP_SECONDS", 60)
+    lookback = env_int("FEISHU_LOOKBACK_SECONDS", 3600)
+    max_items = max(1, env_int("FEISHU_MAX_ITEMS", 40))
+    allowlist = {c.strip() for c in (os.environ.get("FEISHU_CHATS") or "").split(",") if c.strip()}
+    require_mention = env_flag("FEISHU_REQUIRE_MENTION")
+
+    cursor = int(cursor_raw) if cursor_raw.isdigit() else None
+    floor = (cursor if cursor is not None else now - lookback) - overlap
+    since = max(0, floor)
+
+    state = fc.load_state()
+    known_chats = set(state["known_chats"])
+    threads = state["threads"]
+
+    try:
+        open_id = fc.bot_open_id(token) if require_mention else None
+        chats = list_chats(token)
+    except fc.FeishuError as err:
+        warn("chat enumeration failed: %s" % err)
+        return 1
+
+    chats = [c for c in chats if not allowlist or c.get("chat_id") in allowlist]
+    chat_names = {c.get("chat_id"): (c.get("name") or c.get("chat_id")) for c in chats}
+
+    collected, seen = [], set()
+
+    def absorb(chat_id, msg):
+        msg_id = msg.get("message_id")
+        if not msg_id or msg_id in seen or is_bot(msg):
+            return
+        if require_mention and not mentions_bot(msg, open_id):
+            return
+        body = fc.flatten_message(msg)
+        if not body:
+            return
+        seen.add(msg_id)
+        thread_id = msg.get("thread_id") or ""
+        collected.append({
+            "id": msg_id,
+            "title": "%s: %s" % (chat_names.get(chat_id, chat_id or "chat"),
+                                 body.splitlines()[0][:60]),
+            "body": body,
+            "chat_id": chat_id,
+            "root_id": msg.get("root_id") or msg.get("parent_id") or msg_id,
+            "thread_id": thread_id,
+            "at": created_at(msg),
+        })
+        # A thread container is the only place its replies appear (ADR 0024).
+        if thread_id and thread_id not in threads:
+            threads[thread_id] = {"chat_id": chat_id, "seen_at": created_at(msg) or now}
+
+    for chat in chats:
+        chat_id = chat.get("chat_id")
+        if not chat_id:
+            continue
+        # A chat the bot just joined has no cursor of its own; read a lookback.
+        chat_since = since if chat_id in known_chats else max(0, now - lookback)
+        try:
+            for msg in iter_messages(token, "chat", chat_id, chat_since):
+                absorb(chat_id, msg)
+        except fc.FeishuError as err:
+            warn("chat %s: %s" % (chat_id, err))
+            return 1
+        known_chats.add(chat_id)
+        chat_names.setdefault(chat_id, chat.get("name") or chat_id)
+
+    for thread_id in list(threads.keys()):
+        info = threads[thread_id] or {}
+        chat_id = info.get("chat_id") or ""
+        if allowlist and chat_id not in allowlist:
+            continue
+        try:
+            for msg in iter_messages(token, "thread", thread_id):
+                if created_at(msg) < since:
+                    continue
+                absorb(chat_id or msg.get("chat_id") or "", msg)
+        except fc.FeishuError as err:
+            warn("thread %s: %s" % (thread_id, err))
+            continue
+        if now - (info.get("seen_at") or now) > THREAD_KEEP_SECONDS:
+            del threads[thread_id]
+
+    state["known_chats"] = sorted(known_chats)
+    state["threads"] = threads
+    try:
+        fc.save_state(state)
+    except OSError as err:
+        warn("state write failed: %s" % err)
+
+    collected.sort(key=lambda item: item["at"])
+    emitted = collected[:max_items]
+    # The cursor stops at the last item printed: the rest must not be skipped.
+    next_cursor = max(cursor or 0, emitted[-1]["at"] if emitted else 0)
+
+    for item in emitted:
+        item.pop("at", None)
+        sys.stdout.write(json.dumps(item, ensure_ascii=False) + "\n")
+
+    if len(collected) > len(emitted):
+        warn("%d more messages wait for the next pass" % (len(collected) - len(emitted)))
+    if emitted and next_cursor:
+        sys.stdout.write(json.dumps({"cursor": str(next_cursor)}) + "\n")
+    sys.stdout.flush()
+    return 0
+
+
+def scope_hint(err):
+    """A missing scope names its console link inside the error - or we build one."""
+    hint = ["grant it in the app console, then publish a new version (权限管理 → 版本管理与发布)"]
+    text = " ".join([err.msg or "", getattr(err, "ext", "") or ""])
+    url = None
+    for word in re.split(r"[：\s]+", text):
+        if word.startswith("https://open.feishu.cn/"):
+            url = word
+            break
+    scopes = re.findall(r"need scope: ([a-z:._]+)", text)
+    app_id = (os.environ.get("FEISHU_APP_ID") or "").strip()
+    if url is None and scopes and app_id:
+        url = ("https://open.feishu.cn/app/%s/auth?q=%s&op_from=openapi&token_type=tenant"
+               % (app_id, ",".join(scopes)))
+    if url:
+        hint.insert(0, url)
+    return hint
+
+
+def self_check():
+    """`--check`: the operator command's own report (ADR 0027). Exit 0 healthy, 1 not."""
+    fc.load_env()
+    failures = 0
+    try:
+        token = fc.tenant_token()
+    except fc.FeishuError as err:
+        print("no tenant token: %s" % err)
+        print("  credentials live in .env beside this file: cp .env.example .env, then fill")
+        print("  FEISHU_APP_ID / FEISHU_APP_SECRET from https://open.feishu.cn/app")
+        return 1
+    print("token ok (tenant_access_token, cached in .token.json for its 2 h)")
+
+    try:
+        bot = fc.api("GET", "/bot/v3/info", token=token).get("bot") or {}
+        print("bot %s (%s)" % (bot.get("app_name") or "?", bot.get("open_id") or "?"))
+    except fc.FeishuError as err:
+        print("bot info failed: %s" % err)
+        failures += 1
+
+    allowlist = {c.strip() for c in (os.environ.get("FEISHU_CHATS") or "").split(",") if c.strip()}
+    try:
+        visible = list_chats(token)
+    except fc.FeishuError as err:
+        print("chat list failed: %s" % err)
+        for line in scope_hint(err):
+            print("  " + line)
+        return 1
+    chats = [c for c in visible if not allowlist or c.get("chat_id") in allowlist]
+    if not chats:
+        print("no readable chat: this app is in no group chat%s"
+              % (" (or FEISHU_CHATS excludes every one)" if allowlist else ""))
+        print("  add it: 群设置 → 群机器人 → 添加机器人 %s" % (bot.get("app_name") or ""))
+        print("  a p2p chat cannot be enumerated by a pull drain (ADR 0024)")
+        return 1
+    print("%d chat(s) visible%s" % (len(chats), ", %d allowed by FEISHU_CHATS" % len(allowlist)
+                                    if allowlist else ""))
+
+    chat = chats[0]
+    name = chat.get("name") or chat.get("chat_id")
+    try:
+        fc.api("GET", "/im/v1/messages", token=token, params={
+            "container_id_type": "chat", "container_id": chat.get("chat_id"),
+            "sort_type": "ByCreateTimeAsc", "page_size": 1})
+        print("read ok in %s" % name)
+    except fc.FeishuError as err:
+        print("read failed in %s: %s" % (name, err))
+        for line in scope_hint(err):
+            print("  " + line)
+        failures += 1
+    state = fc.load_state()
+    print("state: %d known chat(s), %d known thread(s)"
+          % (len(state["known_chats"]), len(state["threads"])))
+    if env_flag("FEISHU_REQUIRE_MENTION") and not fc.bot_open_id(token):
+        print("FEISHU_REQUIRE_MENTION is on but the bot's open_id is unknown")
+        failures += 1
+    return 0 if failures == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Supervision for long-running coding agents: detached pods, heartbeat liveness, cron-ticked reconcile, and a Pi extension for spawning and handoff",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -13,6 +13,7 @@
     ]
   },
   "files": [
+    "examples",
     "bin",
     "src",
     "index.mjs",

package/src/cli.ts

@@ -22,6 +22,11 @@ import {
   writeAgents,
 } from "./agents-store.ts";
 import { renderTemplate, scanInbox, type InboxItem } from "./inbox.ts";
+import {
+  doctor,
+  type DoctorMark,
+  type DoctorReport,
+} from "./doctor.ts";
 import {
   claimKey,
   newListenerId,
@@ -33,7 +38,7 @@ import { acquireLock, readLock, releaseLock, sleep } from "./locks.ts";
 import { loadNotifyConfig } from "./notify/config.ts";
 import { dispatchNotification, shouldNotify } from "./notify/dispatch.ts";
 import type { NotificationsConfig, PodNotification } from "./notify/types.ts";
-import { cronLogPath, delivererFile, podDir, reconcileLockPath } from "./paths.ts";
+import { cronLogPath, delivererFile, lastPassFile, podDir, reconcileLockPath } from "./paths.ts";
 import { readDeliverer, retryOutbox, writeDeliverer } from "./outbox.ts";
 import {
   projectHasCapacity,
@@ -48,6 +53,7 @@ import {
   drainSources,
   pruneSourceClaims,
   readSources,
+  recordSourceFailure,
   writeSources,
   type SourceDrain,
 } from "./sources.ts";
@@ -257,6 +263,9 @@ async function reconcileCmd(deps: CliDeps = {}): Promise<number> {
         await appendCronLog(
           `source ${result.name}: drain failed (${result.error}); no items, cursor unchanged`,
         );
+        // The failure is also a record fact, so `doctor` can report it without
+        // tailing cron.log (ADR 0027).
+        await recordSourceFailure(result.name, result.error);
       }
       for (const bad of result.bad) {
         await appendCronLog(
@@ -278,6 +287,9 @@ async function reconcileCmd(deps: CliDeps = {}): Promise<number> {
       (await withRegistryLock(() => reconcilePass(notify, project, drained))) ?? [];
   } finally {
     await releaseLock(reconcileLockPath());
+    // The pass marker (ADR 0027): without it, "cron is not installed" and
+    // "cron runs and finds nothing" are the same silence in every report.
+    await writeFile(lastPassFile(), `${JSON.stringify({ at: Date.now() })}\n`).catch(() => undefined);
   }
   // A bad config degrades, it never kills the pass (ADR 0021): the warnings
   // and any delivery failure are cron.log lines, and nothing is retried.
@@ -430,6 +442,14 @@ async function reconcilePass(
         pod.policy.failureStreak = 0;
         delete pod.policy.nextWakeAt;
       }
+      // A clean exit served the batch it was woken for, so the debt is paid
+      // (ADR 0026 amendment). `failed` and `lost` leave it standing: the next
+      // admitted wake-up is the retry, and it is bounded by backoff and park
+      // exactly like any other failure. `cancelled` leaves it too — a human
+      // stopped a window, not the work.
+      if (wake.outcome === "more" || wake.outcome === "done") {
+        delete pod.policy.intakePending;
+      }
       pod.policy.appliedOutcomes += 1;
       changed = true;
     }
@@ -490,13 +510,26 @@ async function reconcilePass(
  * woken. It runs after intake so an item that just landed in a pod's `## Inbox`
  * is served by the same pass's wake (ADR 0014), and the read is the registry's
  * current state — the same compare-and-swap ADR 0018 relies on, one write.
+ *
+ * One gate sits in front of it (ADR 0026 amendment): a pod **bound by a
+ * listener** is intake-driven, so it is admitted only while it owes a batch
+ * (`policy.intakePending`). Without the gate a standing router with an empty
+ * inbox burned one whole agent run per tick — the shape that got the first
+ * router pod cancelled. An unbound pod has no inbox to check, so ADR 0011's
+ * optimistic rule stays its whole policy.
  */
 async function wakeDuePods(now: number): Promise<void> {
   const pods = await readPods();
   const projects = await readProjects();
+  const intakeBound = new Set(
+    (await readListeners()).flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
   let changed = false;
   for (const pod of pods) {
     if (pod.state !== "idle" || pod.policy?.parked) continue;
+    if (intakeBound.has(pod.id) && !pod.policy?.intakePending) continue;
     if (pod.policy?.nextWakeAt !== undefined && pod.policy.nextWakeAt > now) continue;
     if (pod.after !== undefined) {
       const upstream = pods.find((candidate) => candidate.id === pod.after);
@@ -761,6 +794,14 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
       const claim = waiting.find((candidate) => candidate.item === item.id);
       if (claim !== undefined) claim.appended = true;
     }
+    // The batch is in the document, so the pod owes a wake-up it did not owe
+    // before (ADR 0026 amendment). Written here — inside the same registry lock
+    // as the append — because the wake phase reads this field as the pod's only
+    // admission: idle + owed batch, never the tick. A capacity-blocked launch
+    // leaves the count standing, so the next pass is the retry.
+    pod.policy ??= { failureStreak: 0, appliedOutcomes: 0 };
+    pod.policy.intakePending = (pod.policy.intakePending ?? 0) + batch.length;
+    await writePods(pods);
     appended = true;
   }
   // Append first, then mark: the marker is on disk before the wake phase can
@@ -1827,11 +1868,70 @@ async function listenerCmd(
   }
 }
 
+const MARKS: Record<DoctorMark, string> = { ok: "✓", bad: "✗", note: "?" };
+
+/** One line per finding, then the first run only when it is what is missing (ADR 0027). */
+function printDoctor(report: DoctorReport, out: (line: string) => void): void {
+  out(`agents-pod doctor  ${report.store}`);
+  if (report.sections.length > 0) out("");
+  for (const section of report.sections) {
+    section.lines.forEach((line, index) => {
+      const head = index === 0 ? section.title.padEnd(10) : " ".repeat(10);
+      out(`${head}${MARKS[line.mark]} ${line.text}`);
+      for (const detail of line.detail ?? []) out(`${" ".repeat(12)}${detail}`);
+    });
+  }
+  if (report.recipe.length > 0) {
+    out("");
+    out(
+      report.sections.length === 0
+        ? "nothing is configured yet — the first run, in order:"
+        : "still missing:",
+    );
+    for (const step of report.recipe) out(`  ${step}`);
+  }
+}
+
+/**
+ * `doctor` is read-only, and `--probe` is its only mode that runs operator code
+ * (ADR 0027). Exit 0 healthy, 1 something blocks a channel, 2 bad usage.
+ */
+async function doctorCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const unknown = words.filter((word) => word !== "--probe" && word !== "--json");
+  if (unknown.length > 0) {
+    err(`Unknown doctor argument: ${unknown[0]}. Usage: agents-pod doctor [--probe] [--json]`);
+    return 2;
+  }
+  const report = await doctor({
+    probe: words.includes("--probe"),
+    ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+  });
+  if (words.includes("--json")) out(JSON.stringify(report));
+  else printDoctor(report, out);
+  return report.healthy ? 0 : 1;
+}
+
 export async function main(argv: string[], deps: CliDeps = {}): Promise<number> {
   const out = deps.stdout ?? ((line: string) => console.log(line));
   const err = deps.stderr ?? ((line: string) => console.error(line));
   const [cmd, ...rest] = argv;
 
+  // The bare invocation is where a first run happens, so it points at the
+  // report that says what is missing (ADR 0027).
+  if (cmd === undefined) {
+    out("agents-pod — standing Pods across days, one cron-ticked pass");
+    out("");
+    out("start here  agents-pod doctor   what is missing on this machine, and the command that fixes it");
+    out("pods        spawn | list | status <id> | logs <id> | wake <id> | cancel <id>");
+    out("records     agent | listener | source | deliver | project | reconcile");
+    return 0;
+  }
+
   switch (cmd) {
     case "spawn":
       return spawnCmd(rest, deps, out, err);
@@ -1857,8 +1957,10 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
       return deliverCmd(rest, deps, out, err);
     case "project":
       return projectCmd(rest, deps, out, err);
+    case "doctor":
+      return doctorCmd(rest, deps, out, err);
     default:
-      err(`Unknown command: ${cmd ?? "(none)"}. Try: spawn | list | status | logs | wake | cancel | reconcile | agent | listener | source | deliver | project`);
+      err(`Unknown command: ${cmd ?? "(none)"}. Try: doctor | spawn | list | status | logs | wake | cancel | reconcile | agent | listener | source | deliver | project`);
       return 2;
   }
 }