u-foo 1.0.6 → 1.1.9

package/src/cli.js

@@ -3,6 +3,9 @@ const { spawnSync } = require("child_process");
 const net = require("net");
 const fs = require("fs");
 const { socketPath, isRunning } = require("./daemon");
+const { runBusCoreCommand } = require("./cli/busCoreCommands");
+const { runCtxCommand } = require("./cli/ctxCoreCommands");
+const { runOnlineCommand } = require("./cli/onlineCoreCommands");
 
 function getPackageRoot() {
   return path.resolve(__dirname, "..");
@@ -58,6 +61,7 @@ async function ensureDaemonRunning(projectRoot) {
     // eslint-disable-next-line no-await-in-loop
     await new Promise((r) => setTimeout(r, 200));
   }
+  throw new Error("Failed to start ufoo daemon");
 }
 
 async function sendDaemonRequest(projectRoot, payload) {
@@ -125,6 +129,70 @@ function requireOptional(name) {
   }
 }
 
+function collectOption(value, previous) {
+  const next = Array.isArray(previous) ? previous.slice() : [];
+  const parts = String(value || "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return next.concat(parts);
+}
+
+function collectOptionValues(argv, name) {
+  const values = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] !== name) continue;
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) continue;
+    values.push(value);
+    i += 1;
+  }
+  return values;
+}
+
+function parseJsonObject(text, fallback = {}) {
+  const raw = String(text || "").trim();
+  if (!raw) return fallback;
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Expected JSON object");
+  }
+  return parsed;
+}
+
+function normalizeReportPhase(action = "") {
+  const value = String(action || "").trim().toLowerCase();
+  if (value === "start") return "start";
+  if (value === "progress") return "progress";
+  if (value === "error" || value === "fail" || value === "failed") return "error";
+  if (value === "done" || value === "finish" || value === "finished") return "done";
+  return "";
+}
+
+function resolveOnlineAuthToken(opts) {
+  if (!opts) return "";
+  if (opts.authToken) return opts.authToken;
+  let tokens = null;
+  try {
+    // eslint-disable-next-line global-require
+    tokens = require("./online/tokens");
+  } catch {
+    return "";
+  }
+  const filePath = opts.tokenFile || tokens.defaultTokensPath();
+  let entry = null;
+  if (opts.subscriber) entry = tokens.getToken(filePath, opts.subscriber);
+  if (!entry && opts.nickname) entry = tokens.getTokenByNickname(filePath, opts.nickname);
+  if (!entry) return "";
+  return entry.token_hash || entry.token || "";
+}
+
+function onlineAuthHeaders(opts) {
+  const token = resolveOnlineAuthToken(opts);
+  if (!token) return {};
+  return { Authorization: `Bearer ${token}` };
+}
+
 async function runCli(argv) {
   const pkg = require(path.resolve(getPackageRoot(), "package.json"));
 
@@ -204,6 +272,208 @@ async function runCli(argv) {
           process.exitCode = 1;
         }
       });
+    program
+      .command("recover")
+      .description("List recoverable agents or recover a specific one")
+      .argument("[action]", "list|run", "list")
+      .argument("[target]", "Nickname or subscriber ID")
+      .option("--json", "Output recoverable list as JSON")
+      .action(async (action, target, opts) => {
+        try {
+          const projectRoot = process.cwd();
+          await ensureDaemonRunning(projectRoot);
+          const normalizedAction = (action || "list").toLowerCase();
+
+          if (normalizedAction === "list") {
+            const resp = await sendDaemonRequest(projectRoot, {
+              type: "list_recoverable_agents",
+              target: target || "",
+            });
+            const result = resp?.data?.recoverable || { recoverable: [], skipped: [] };
+            if (opts.json) {
+              console.log(JSON.stringify(result, null, 2));
+              return;
+            }
+
+            const recoverable = result.recoverable || [];
+            console.log(resp?.data?.reply || `Found ${recoverable.length} recoverable agent(s)`);
+            recoverable.forEach((item) => {
+              const nickname = item.nickname ? ` (${item.nickname})` : "";
+              const meta = item.launchMode ? ` [${item.agent}/${item.launchMode}]` : ` [${item.agent}]`;
+              console.log(`  - ${item.id}${nickname}${meta}`);
+            });
+            return;
+          }
+
+          if (normalizedAction === "run") {
+            if (!target) {
+              console.error("recover run requires <target>");
+              process.exitCode = 1;
+              return;
+            }
+            const resp = await sendDaemonRequest(projectRoot, {
+              type: "resume_agents",
+              target,
+            });
+            const reply = resp?.data?.reply || "Recover requested";
+            console.log(reply);
+            if (resp?.data?.resume?.resumed?.length) {
+              resp.data.resume.resumed.forEach((item) => {
+                const label = item.nickname ? ` (${item.nickname})` : "";
+                console.log(`  - ${item.id}${label}`);
+              });
+            }
+            return;
+          }
+
+          console.error("recover action must be list|run");
+          process.exitCode = 1;
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    program
+      .command("report")
+      .description("Report agent task status to daemon/ufoo-agent")
+      .argument("<action>", "start|progress|done|error|list")
+      .argument("[message...]", "Task message/summary")
+      .option("--task <id>", "Task ID (default: task-<timestamp>)")
+      .option("--agent <id>", "Agent ID (default: UFOO_SUBSCRIBER_ID)")
+      .option("--scope <scope>", "Report visibility: public|private", "public")
+      .option("--controller <id>", "Controller ID for private channel", "ufoo-agent")
+      .option("--summary <text>", "Summary text for done")
+      .option("--error <text>", "Error text for error")
+      .option("--meta <json>", "JSON metadata object")
+      .option("-n, --num <n>", "List count", "20")
+      .option("--json", "Output as JSON")
+      .action(async (action, messageParts, opts) => {
+        const normalized = normalizeReportPhase(action);
+        const text = Array.isArray(messageParts) ? messageParts.join(" ").trim() : String(messageParts || "").trim();
+        const projectRoot = process.cwd();
+        const { listReports } = require("./report/store");
+
+        if ((action || "").toLowerCase() === "list") {
+          try {
+            const rows = listReports(projectRoot, {
+              num: parseInt(opts.num, 10),
+              agent: opts.agent || "",
+            });
+            if (opts.json) {
+              console.log(JSON.stringify(rows, null, 2));
+              return;
+            }
+            console.log(`=== Reports (${rows.length} shown) ===`);
+            rows.forEach((row) => {
+              const detail = row.phase === "error"
+                ? (row.error || row.summary || row.message || row.task_id)
+                : (row.summary || row.message || row.task_id);
+              console.log(`${row.ts || "-"} [${row.phase}] ${row.agent_id || "unknown-agent"} ${row.task_id || ""} ${detail}`);
+            });
+            if (rows.length === 0) console.log("No reports found.");
+          } catch (err) {
+            console.error(err.message || String(err));
+            process.exitCode = 1;
+          }
+          return;
+        }
+
+        if (!normalized) {
+          console.error("report action must be start|progress|done|error|list");
+          process.exitCode = 1;
+          return;
+        }
+
+        let meta = {};
+        try {
+          meta = parseJsonObject(opts.meta, {});
+        } catch (err) {
+          console.error(`Invalid --meta: ${err.message}`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const agentId = String(opts.agent || process.env.UFOO_SUBSCRIBER_ID || "unknown-agent").trim() || "unknown-agent";
+        const taskId = String(opts.task || `task-${Date.now()}`).trim();
+        const summary = String(opts.summary || (normalized === "done" ? text : "")).trim();
+        const error = String(opts.error || (normalized === "error" ? text : "")).trim();
+        const report = {
+          phase: normalized,
+          task_id: taskId,
+          agent_id: agentId,
+          message: text,
+          summary,
+          error,
+          ok: normalized !== "error",
+          source: "cli",
+          scope: opts.scope || "public",
+          controller_id: opts.controller || "ufoo-agent",
+          meta,
+        };
+
+        try {
+          await ensureDaemonRunning(projectRoot);
+          const resp = await sendDaemonRequest(projectRoot, {
+            type: "agent_report",
+            report,
+          });
+          const out = resp?.data?.report || report;
+          if (opts.json) {
+            console.log(JSON.stringify(out, null, 2));
+            return;
+          }
+          const detail = out.phase === "error"
+            ? (out.error || out.summary || out.message || out.task_id)
+            : (out.summary || out.message || out.task_id);
+          console.log(`[report] ${out.phase} ${out.agent_id} ${out.task_id} ${detail}`);
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    program
+      .command("ucode")
+      .description("ucode core preparation helpers")
+      .argument("[action]", "doctor|prepare|build", "doctor")
+      .option("--skip-install", "Skip npm install even if node_modules is missing")
+      .action((action, opts) => {
+        const { inspectUcodeSetup, formatUcodeDoctor, prepareAndInspectUcode } = require("./agent/ucodeDoctor");
+        const { buildUcodeCore } = require("./agent/ucodeBuild");
+        const normalized = String(action || "doctor").trim().toLowerCase();
+        if (normalized !== "doctor" && normalized !== "prepare" && normalized !== "build") {
+          console.error("ucode action must be doctor|prepare|build");
+          process.exitCode = 1;
+          return;
+        }
+        if (normalized === "build") {
+          try {
+            const built = buildUcodeCore({
+              projectRoot: process.cwd(),
+              installIfMissing: !opts.skipInstall,
+              stdio: "inherit",
+            });
+            console.log("=== ucode build ===");
+            console.log(`workspace: ${built.workspaceRoot}`);
+            console.log(`core: ${built.coreRoot}`);
+            console.log(`dist: ${built.distCliPath}`);
+            console.log(`steps: ${built.steps.join(", ")}`);
+            return;
+          } catch (err) {
+            console.error(err.message || String(err));
+            process.exitCode = 1;
+            return;
+          }
+        }
+        const result = normalized === "prepare"
+          ? prepareAndInspectUcode({ projectRoot: process.cwd() })
+          : inspectUcodeSetup({ projectRoot: process.cwd() });
+        console.log(formatUcodeDoctor(result));
+        if (normalized === "prepare" && result.bootstrapPrepared && result.bootstrapPrepared.file) {
+          console.log(`prepared bootstrap: ${result.bootstrapPrepared.file}`);
+        }
+      });
 
     program
       .command("init")
@@ -252,6 +522,168 @@ async function runCli(argv) {
         }
       });
 
+    const online = program.command("online").description("ufoo online helpers");
+    online
+      .command("server")
+      .description("Start ufoo-online relay server")
+      .option("--port <port>", "Listen port", "8787")
+      .option("--host <host>", "Listen host", "127.0.0.1")
+      .option("--token-file <path>", "Token file for auth validation")
+      .option("--idle-timeout <ms>", "Idle timeout in ms", "30000")
+      .option("--insecure", "Allow any token (dev only)")
+      .option("--tls-cert <path>", "TLS certificate file")
+      .option("--tls-key <path>", "TLS private key file")
+      .action(async (opts) => {
+        try {
+          await runOnlineCommand("server", { opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+    online
+      .command("token")
+      .description("Generate and store a ufoo-online token")
+      .argument("<subscriber>", "Subscriber ID (e.g., claude-code:abc123)")
+      .option("--nickname <name>", "Nickname for this agent")
+      .option("--server <url>", "Online server URL")
+      .option("--file <path>", "Tokens file path")
+      .action(async (subscriber, opts) => {
+        try {
+          await runOnlineCommand("token", { subscriber, opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    online
+      .command("room")
+      .description("Manage online rooms (HTTP)")
+      .argument("<action>", "create|list")
+      .option("--server <url>", "Online server base URL (http://host:port)")
+      .option("--auth-token <token>", "Bearer token for HTTP auth (token or token_hash)")
+      .option("--token-file <path>", "Token file path for auth lookup")
+      .option("--subscriber <id>", "Subscriber ID to resolve token")
+      .option("--nickname <name>", "Nickname to resolve token")
+      .option("--name <room>", "Room name (optional)")
+      .option("--type <type>", "Room type (public|private)")
+      .option("--password <pwd>", "Room password (private only)")
+      .action(async (action, opts) => {
+        try {
+          await runOnlineCommand("room", { action, opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    online
+      .command("channel")
+      .description("Manage online channels (HTTP)")
+      .argument("<action>", "create|list")
+      .option("--server <url>", "Online server base URL (http://host:port)")
+      .option("--auth-token <token>", "Bearer token for HTTP auth (token or token_hash)")
+      .option("--token-file <path>", "Token file path for auth lookup")
+      .option("--subscriber <id>", "Subscriber ID to resolve token")
+      .option("--nickname <name>", "Nickname to resolve token")
+      .option("--name <name>", "Channel name (unique)")
+      .option("--type <type>", "Channel type (world|public)")
+      .action(async (action, opts) => {
+        try {
+          await runOnlineCommand("channel", { action, opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    online
+      .command("connect")
+      .description("Connect to ufoo-online relay (long-running)")
+      .requiredOption("--nickname <name>", "Agent nickname")
+      .option("--url <url>", "WebSocket URL", "ws://127.0.0.1:8787/ufoo/online")
+      .option("--subscriber <id>", "Subscriber ID (auto-generated if omitted)")
+      .option("--token <tok>", "Auth token")
+      .option("--token-hash <hash>", "Auth token hash")
+      .option("--token-file <path>", "Token file path")
+      .option("--world <name>", "World name", "default")
+      .option("--ping-ms <ms>", "Keepalive ping interval (ms)")
+      .option("--join <channel>", "Join channel after connect")
+      .option("--room <room>", "Join private room (enables bus/decisions/wake sync)")
+      .option("--room-password <pwd>", "Room password")
+      .option("--interval <ms>", "Bus sync poll interval in ms", "1500")
+      .option("--allow-insecure-ws", "Allow ws:// to non-localhost (insecure)")
+      .option("--trust-remote", "Trust all private-room members for bus/decisions/wake sync")
+      .option("--allow-from <subscriberId>", "Allow bus/decisions/wake from subscriber ID (repeatable)", collectOption)
+      .action(async (opts) => {
+        try {
+          await runOnlineCommand("connect", { opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    online
+      .command("send")
+      .description("Send a message to a channel or room via outbox")
+      .requiredOption("--nickname <name>", "Agent nickname (must match a running connect)")
+      .requiredOption("--text <message>", "Message text")
+      .option("--channel <name>", "Target channel")
+      .option("--room <id>", "Target room")
+      .action(async (opts) => {
+        try {
+          await runOnlineCommand("send", { opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
+    online
+      .command("inbox")
+      .description("View ufoo-online inbox for a nickname")
+      .argument("<nickname>", "Agent nickname")
+      .option("--clear", "Clear the inbox")
+      .option("--unread", "Show unread messages only")
+      .action(async (nickname, opts) => {
+        try {
+          await runOnlineCommand("inbox", { nickname, opts }, {
+            mode: "commander",
+            onlineAuthHeaders,
+            projectRoot: process.cwd(),
+          });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      });
+
     const bus = program.command("bus").description("Project bus commands");
     bus
       .command("alert")
@@ -330,7 +762,7 @@ async function runCli(argv) {
       });
     bus
       .command("inject")
-      .description("Inject /ubus command into agent's terminal (via PTY socket or tmux)")
+      .description("Inject /bus into a Terminal.app tab by subscriber ID")
       .argument("<subscriber>", "Subscriber ID to inject into")
       .action((subscriber) => {
         const EventBus = require("./bus");
@@ -344,6 +776,24 @@ async function runCli(argv) {
           }
         })();
       });
+    bus
+      .command("wake")
+      .description("Wake an agent (inject /ubus into its terminal)")
+      .argument("<target>", "Subscriber ID or nickname")
+      .option("--reason <reason>", "Wake reason")
+      .option("--no-shake", "Disable window shake")
+      .action((target, opts) => {
+        const EventBus = require("./bus");
+        const eventBus = new EventBus(process.cwd());
+        (async () => {
+          try {
+            await eventBus.wake(target, { reason: opts.reason || "remote", shake: opts.shake !== false });
+          } catch (err) {
+            console.error(err.message || String(err));
+            process.exitCode = 1;
+          }
+        })();
+      });
     bus
       .command("activate")
       .description("Activate (focus) the terminal/tmux window of an agent")
@@ -372,58 +822,8 @@ async function runCli(argv) {
         const cmdArgs = args.slice(1);
 
         try {
-          switch (cmd) {
-            case "init":
-              await eventBus.init();
-              break;
-            case "join":
-              {
-                const subscriber = await eventBus.join(cmdArgs[0], cmdArgs[1], cmdArgs[2]);
-                if (subscriber) console.log(subscriber);
-              }
-              break;
-            case "leave":
-              await eventBus.leave(cmdArgs[0]);
-              break;
-            case "send":
-              {
-                // 自动 join（如果还没有 join）并获取 subscriber ID
-                const publisher = await eventBus.ensureJoined();
-                await eventBus.send(cmdArgs[0], cmdArgs[1], publisher);
-              }
-              break;
-            case "broadcast":
-              {
-                // 自动 join（如果还没有 join）并获取 subscriber ID
-                const publisher = await eventBus.ensureJoined();
-                await eventBus.broadcast(cmdArgs[0], publisher);
-              }
-              break;
-            case "check":
-              await eventBus.check(cmdArgs[0]);
-              break;
-            case "ack":
-              await eventBus.ack(cmdArgs[0]);
-              break;
-            case "consume":
-              await eventBus.consume(cmdArgs[0], cmdArgs.includes("--from-beginning"));
-              break;
-            case "status":
-              await eventBus.status();
-              break;
-            case "resolve":
-              await eventBus.resolve(cmdArgs[0], cmdArgs[1]);
-              break;
-            case "rename":
-              await eventBus.rename(cmdArgs[0], cmdArgs[1]);
-              break;
-            case "whoami":
-              await eventBus.whoami();
-              break;
-            default:
-              console.error(`Unknown bus subcommand: ${sub}`);
-              process.exitCode = 1;
-          }
+          const result = await runBusCoreCommand(eventBus, cmd, cmdArgs);
+          if (result && result.subscriber) console.log(result.subscriber);
         } catch (err) {
           console.error(err.message);
           process.exitCode = 1;
@@ -432,98 +832,25 @@ async function runCli(argv) {
 
     program
       .command("ctx")
-      .description("Project context commands (doctor|lint|decisions)")
-      .argument("[subcmd]", "Subcommand (doctor|lint|decisions)", "doctor")
+      .description("Project context commands (doctor|lint|decisions|sync)")
+      .argument("[subcmd]", "Subcommand (doctor|lint|decisions|sync)", "doctor")
       .allowUnknownOption(true)
       .argument("[subargs...]", "Subcommand args")
       .action(async (subcmd, subargs = []) => {
-        const DecisionsManager = require("./context/decisions");
-        const ContextDoctor = require("./context/doctor");
         const cwd = process.cwd();
 
         try {
-          switch (subcmd) {
-            case "doctor": {
-              const doctor = new ContextDoctor(cwd);
-              const mode = subargs.includes("--project") ? "project" : "protocol";
-              const projectPath = mode === "project" ? subargs[subargs.indexOf("--project") + 1] : null;
-              await doctor.run({ mode, projectPath });
-              break;
-            }
-            case "lint": {
-              const doctor = new ContextDoctor(cwd);
-              const mode = subargs.includes("--project") ? "project" : "protocol";
-              const projectPath = mode === "project" ? subargs[subargs.indexOf("--project") + 1] : null;
-              if (mode === "project") {
-                doctor.lintProject(projectPath);
-              } else {
-                doctor.lintProtocol();
-              }
-              break;
-            }
-            case "decisions": {
-              const manager = new DecisionsManager(cwd);
-              const opts = {};
-
-              if (subargs[0] === "index" || subargs.includes("--index")) {
-                manager.writeIndex();
-                break;
-              }
-              if (subargs[0] === "new") {
-                const create = { title: "", author: "", status: "" };
-                for (let i = 1; i < subargs.length; i++) {
-                  const arg = subargs[i];
-                  if (arg === "--author") {
-                    create.author = subargs[++i] || "";
-                    continue;
-                  }
-                  if (arg === "--status") {
-                    create.status = subargs[++i] || "";
-                    continue;
-                  }
-                  if (!arg.startsWith("-")) {
-                    create.title = create.title ? `${create.title} ${arg}` : arg;
-                    continue;
-                  }
-                }
-                manager.createDecision(create);
-                break;
-              }
-
-              // Parse options
-              for (let i = 0; i < subargs.length; i++) {
-                if (subargs[i] === "-n") opts.num = parseInt(subargs[++i]);
-                if (subargs[i] === "-s") opts.status = subargs[++i];
-                if (subargs[i] === "-l") opts.listOnly = true;
-                if (subargs[i] === "-a") opts.all = true;
-                if (subargs[i] === "-d") {
-                  manager.decisionsDir = subargs[++i];
-                  manager.contextDir = path.dirname(manager.decisionsDir);
-                  manager.indexFile = path.join(manager.contextDir, "decisions.jsonl");
-                }
-              }
-
-              if (opts.listOnly) {
-                manager.list({ status: opts.status || "open" });
-              } else {
-                manager.show({
-                  status: opts.status || "open",
-                  num: opts.num || 1,
-                  all: opts.all || false,
-                });
-              }
-              break;
-            }
-            default:
-              console.error(
-                chalk.red(
-                  `Unknown ctx subcommand: ${subcmd}. Supported: doctor, lint, decisions`
-                )
-              );
-              process.exitCode = 1;
-          }
+          await runCtxCommand(subcmd, subargs, {
+            cwd,
+            allowIndexNew: true,
+            updateDecisionIndexPaths: true,
+          });
         } catch (err) {
-          console.error(chalk.red(`Error: ${err.message}`));
+          if (err && err.code === "UFOO_CTX_UNKNOWN") {
+            console.error(chalk.red(err.message));
+          } else {
+            console.error(chalk.red(`Error: ${err.message}`));
+          }
           process.exitCode = 1;
         }
       });
@@ -562,11 +889,24 @@ async function runCli(argv) {
     console.log("  ufoo daemon --start|--stop|--status");
     console.log("  ufoo chat");
     console.log("  ufoo resume [nickname]");
+    console.log("  ufoo recover [list [target] | run <target>] [--json]");
+    console.log("  ufoo report <start|progress|done|error|list> [message] [--task <id>] [--agent <id>]");
+    console.log("  ufoo ucode [doctor|prepare|build] [--skip-install]");
     console.log("  ufoo init [--modules <list>] [--project <dir>]");
     console.log("  ufoo skills list");
     console.log("  ufoo skills install <name|all> [--target <dir> | --codex | --agents]");
+    console.log("  ufoo online server [--port 8787] [--host 127.0.0.1] [--token-file <path>]");
+    console.log("  ufoo online token <subscriber> [--nickname <name>] [--server <url>] [--file <path>]");
+    console.log("  ufoo online room create [--name <room>] --type public|private [--password <pwd>] [--server <url>]");
+    console.log("  ufoo online room list [--server <url>]");
+    console.log("  ufoo online channel create --name <name> [--type world|public] [--server <url>]");
+    console.log("  ufoo online channel list [--server <url>]");
+    console.log("  ufoo online connect --nickname <name> [--join <ch>] [--room <id> --room-password <pwd>] [...]");
+    console.log("  ufoo online send --nickname <name> --text <msg> [--channel <ch>] [--room <id>]");
+    console.log("  ufoo online inbox <nickname> [--clear] [--unread]");
+    console.log("  ufoo bus wake <target> [--reason <reason>] [--no-shake]");
     console.log("  ufoo bus <args...>    (JS bus implementation)");
-    console.log("  ufoo ctx <subcmd> ... (doctor|lint|decisions)");
+    console.log("  ufoo ctx <subcmd> ... (doctor|lint|decisions|sync)");
     console.log("");
     console.log("Notes:");
     console.log("  - For Codex notifications, use ufoo bus alert / ufoo bus listen");
@@ -626,6 +966,214 @@ async function runCli(argv) {
     })();
     return;
   }
+  if (cmd === "recover") {
+    const first = rest[0] || "";
+    const action = first && !first.startsWith("--") ? first.toLowerCase() : "list";
+    const targetIdx = first && !first.startsWith("--") ? 1 : 0;
+    const target = rest[targetIdx] && !rest[targetIdx].startsWith("--") ? rest[targetIdx] : "";
+    const outputJson = rest.includes("--json");
+    (async () => {
+      try {
+        const projectRoot = process.cwd();
+        await ensureDaemonRunning(projectRoot);
+
+        if (action === "list") {
+          const resp = await sendDaemonRequest(projectRoot, {
+            type: "list_recoverable_agents",
+            target,
+          });
+          const result = resp?.data?.recoverable || { recoverable: [], skipped: [] };
+          if (outputJson) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+          }
+          const recoverable = result.recoverable || [];
+          console.log(resp?.data?.reply || `Found ${recoverable.length} recoverable agent(s)`);
+          recoverable.forEach((item) => {
+            const nickname = item.nickname ? ` (${item.nickname})` : "";
+            const meta = item.launchMode ? ` [${item.agent}/${item.launchMode}]` : ` [${item.agent}]`;
+            console.log(`  - ${item.id}${nickname}${meta}`);
+          });
+          return;
+        }
+
+        if (action === "run") {
+          if (!target) {
+            console.error("recover run requires <target>");
+            process.exitCode = 1;
+            return;
+          }
+          const resp = await sendDaemonRequest(projectRoot, {
+            type: "resume_agents",
+            target,
+          });
+          const reply = resp?.data?.reply || "Recover requested";
+          console.log(reply);
+          return;
+        }
+
+        console.error("recover action must be list|run");
+        process.exitCode = 1;
+      } catch (err) {
+        console.error(err.message || String(err));
+        process.exitCode = 1;
+      }
+    })();
+    return;
+  }
+  if (cmd === "report") {
+    const action = String(rest[0] || "").toLowerCase();
+    const normalized = normalizeReportPhase(action);
+    const { listReports } = require("./report/store");
+
+    if (action === "list") {
+      const agentIdx = rest.indexOf("--agent");
+      const numIdx = rest.indexOf("--num");
+      const nIdx = rest.indexOf("-n");
+      const json = rest.includes("--json");
+      const agent = agentIdx !== -1 ? (rest[agentIdx + 1] || "") : "";
+      const numRaw = numIdx !== -1
+        ? rest[numIdx + 1]
+        : (nIdx !== -1 ? rest[nIdx + 1] : "20");
+      try {
+        const rows = listReports(process.cwd(), { agent, num: parseInt(numRaw, 10) });
+        if (json) {
+          console.log(JSON.stringify(rows, null, 2));
+          return;
+        }
+        console.log(`=== Reports (${rows.length} shown) ===`);
+        rows.forEach((row) => {
+          const detail = row.phase === "error"
+            ? (row.error || row.summary || row.message || row.task_id)
+            : (row.summary || row.message || row.task_id);
+          console.log(`${row.ts || "-"} [${row.phase}] ${row.agent_id || "unknown-agent"} ${row.task_id || ""} ${detail}`);
+        });
+        if (rows.length === 0) console.log("No reports found.");
+      } catch (err) {
+        console.error(err.message || String(err));
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (!normalized) {
+      console.error("report action must be start|progress|done|error|list");
+      process.exitCode = 1;
+      return;
+    }
+
+    const getOpt = (name, fallback = "") => {
+      const idx = rest.indexOf(name);
+      if (idx === -1 || idx + 1 >= rest.length) return fallback;
+      const value = rest[idx + 1];
+      if (!value || value.startsWith("--")) return fallback;
+      return value;
+    };
+
+    const isValueToken = (token) =>
+      token && !token.startsWith("--") && token !== action;
+    const message = rest.slice(1).filter((token, idx, arr) => {
+      if (!isValueToken(token)) return false;
+      const prev = arr[idx - 1] || "";
+      if (
+        prev === "--task"
+        || prev === "--agent"
+        || prev === "--scope"
+        || prev === "--controller"
+        || prev === "--summary"
+        || prev === "--error"
+        || prev === "--meta"
+        || prev === "--num"
+        || prev === "-n"
+      ) {
+        return false;
+      }
+      return true;
+    }).join(" ").trim();
+
+    let meta = {};
+    try {
+      meta = parseJsonObject(getOpt("--meta", ""), {});
+    } catch (err) {
+      console.error(`Invalid --meta: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const report = {
+      phase: normalized,
+      task_id: getOpt("--task", `task-${Date.now()}`),
+      agent_id: getOpt("--agent", process.env.UFOO_SUBSCRIBER_ID || "unknown-agent"),
+      message,
+      summary: getOpt("--summary", normalized === "done" ? message : ""),
+      error: getOpt("--error", normalized === "error" ? message : ""),
+      ok: normalized !== "error",
+      source: "cli",
+      scope: getOpt("--scope", "public"),
+      controller_id: getOpt("--controller", "ufoo-agent"),
+      meta,
+    };
+
+    (async () => {
+      try {
+        await ensureDaemonRunning(process.cwd());
+        const resp = await sendDaemonRequest(process.cwd(), {
+          type: "agent_report",
+          report,
+        });
+        const out = resp?.data?.report || report;
+        if (rest.includes("--json")) {
+          console.log(JSON.stringify(out, null, 2));
+          return;
+        }
+        const detail = out.phase === "error"
+          ? (out.error || out.summary || out.message || out.task_id)
+          : (out.summary || out.message || out.task_id);
+        console.log(`[report] ${out.phase} ${out.agent_id} ${out.task_id} ${detail}`);
+      } catch (err) {
+        console.error(err.message || String(err));
+        process.exitCode = 1;
+      }
+    })();
+    return;
+  }
+  if (cmd === "ucode") {
+    const action = String(rest[0] || "doctor").trim().toLowerCase();
+    const { inspectUcodeSetup, formatUcodeDoctor, prepareAndInspectUcode } = require("./agent/ucodeDoctor");
+    const { buildUcodeCore } = require("./agent/ucodeBuild");
+    const skipInstall = rest.includes("--skip-install");
+    if (action !== "doctor" && action !== "prepare" && action !== "build") {
+      console.error("ucode action must be doctor|prepare|build");
+      process.exitCode = 1;
+      return;
+    }
+    if (action === "build") {
+      try {
+        const built = buildUcodeCore({
+          projectRoot: process.cwd(),
+          installIfMissing: !skipInstall,
+          stdio: "inherit",
+        });
+        console.log("=== ucode build ===");
+        console.log(`workspace: ${built.workspaceRoot}`);
+        console.log(`core: ${built.coreRoot}`);
+        console.log(`dist: ${built.distCliPath}`);
+        console.log(`steps: ${built.steps.join(", ")}`);
+      } catch (err) {
+        console.error(err.message || String(err));
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const result = action === "prepare"
+      ? prepareAndInspectUcode({ projectRoot: process.cwd() })
+      : inspectUcodeSetup({ projectRoot: process.cwd() });
+    console.log(formatUcodeDoctor(result));
+    if (action === "prepare" && result.bootstrapPrepared && result.bootstrapPrepared.file) {
+      console.log(`prepared bootstrap: ${result.bootstrapPrepared.file}`);
+    }
+    return;
+  }
   if (cmd === "init") {
     const UfooInit = require("./init");
     const init = new UfooInit(repoRoot);
@@ -684,6 +1232,35 @@ async function runCli(argv) {
     process.exitCode = 1;
     return;
   }
+  if (cmd === "online") {
+    const sub = rest[0] || "";
+    if (!sub) {
+      help();
+      process.exitCode = 1;
+      return;
+    }
+
+    (async () => {
+      try {
+        await runOnlineCommand(sub, { argv: rest }, {
+          mode: "fallback",
+          onlineAuthHeaders,
+          projectRoot: process.cwd(),
+          collectOptionValues,
+          collectOption,
+          defaultChannelType: "public",
+        });
+      } catch (err) {
+        if (err && err.code === "UFOO_ONLINE_UNKNOWN") {
+          help();
+        } else {
+          console.error(err.message || String(err));
+        }
+        process.exitCode = 1;
+      }
+    })();
+    return;
+  }
   if (cmd === "bus") {
     const sub = rest[0] || "";
     if (sub === "alert") {
@@ -776,6 +1353,24 @@ async function runCli(argv) {
       })();
       return;
     }
+    if (sub === "wake") {
+      const EventBus = require("./bus");
+      const eventBus = new EventBus(process.cwd());
+      (async () => {
+        try {
+          const target = rest[1];
+          if (!target) throw new Error("wake requires <subscriber-id|nickname>");
+          const reasonIdx = rest.indexOf("--reason");
+          const reason = reasonIdx !== -1 ? rest[reasonIdx + 1] : "remote";
+          const shake = !rest.includes("--no-shake");
+          await eventBus.wake(target, { reason, shake });
+        } catch (err) {
+          console.error(err.message || String(err));
+          process.exitCode = 1;
+        }
+      })();
+      return;
+    }
 
     // Use JavaScript EventBus module for core commands
     const EventBus = require("./bus");
@@ -784,58 +1379,8 @@ async function runCli(argv) {
     (async () => {
       try {
         const cmdArgs = rest.slice(1);
-        switch (sub) {
-          case "init":
-            await eventBus.init();
-            break;
-          case "join":
-            {
-              const subscriber = await eventBus.join(cmdArgs[0], cmdArgs[1], cmdArgs[2]);
-              if (subscriber) console.log(subscriber);
-            }
-            break;
-          case "leave":
-            await eventBus.leave(cmdArgs[0]);
-            break;
-          case "send":
-            {
-              // 自动 join（如果还没有 join）并获取 subscriber ID
-              const publisher = await eventBus.ensureJoined();
-              await eventBus.send(cmdArgs[0], cmdArgs[1], publisher);
-            }
-            break;
-          case "broadcast":
-            {
-              // 自动 join（如果还没有 join）并获取 subscriber ID
-              const publisher = await eventBus.ensureJoined();
-              await eventBus.broadcast(cmdArgs[0], publisher);
-            }
-            break;
-          case "check":
-            await eventBus.check(cmdArgs[0]);
-            break;
-          case "ack":
-            await eventBus.ack(cmdArgs[0]);
-            break;
-          case "consume":
-            await eventBus.consume(cmdArgs[0], cmdArgs.includes("--from-beginning"));
-            break;
-          case "status":
-            await eventBus.status();
-            break;
-          case "resolve":
-            await eventBus.resolve(cmdArgs[0], cmdArgs[1]);
-            break;
-          case "rename":
-            await eventBus.rename(cmdArgs[0], cmdArgs[1]);
-            break;
-          case "whoami":
-            await eventBus.whoami();
-            break;
-          default:
-            console.error(`Unknown bus subcommand: ${sub}`);
-            process.exitCode = 1;
-        }
+        const result = await runBusCoreCommand(eventBus, sub, cmdArgs);
+        if (result && result.subscriber) console.log(result.subscriber);
       } catch (err) {
         console.error(err.message);
         process.exitCode = 1;
@@ -846,57 +1391,15 @@ async function runCli(argv) {
   if (cmd === "ctx") {
     const sub = rest[0] || "doctor";
     const subargs = rest.slice(1);
-    const DecisionsManager = require("./context/decisions");
-    const ContextDoctor = require("./context/doctor");
     const cwd = process.cwd();
 
     (async () => {
       try {
-        switch (sub) {
-          case "doctor": {
-            const doctor = new ContextDoctor(cwd);
-            const mode = subargs.includes("--project") ? "project" : "protocol";
-            const projectPath = mode === "project" ? subargs[subargs.indexOf("--project") + 1] : null;
-            await doctor.run({ mode, projectPath });
-            break;
-          }
-          case "lint": {
-            const doctor = new ContextDoctor(cwd);
-            const mode = subargs.includes("--project") ? "project" : "protocol";
-            const projectPath = mode === "project" ? subargs[subargs.indexOf("--project") + 1] : null;
-            if (mode === "project") {
-              doctor.lintProject(projectPath);
-            } else {
-              doctor.lintProtocol();
-            }
-            break;
-          }
-          case "decisions": {
-            const manager = new DecisionsManager(cwd);
-            const opts = {};
-
-            for (let i = 0; i < subargs.length; i++) {
-              if (subargs[i] === "-n") opts.num = parseInt(subargs[++i]);
-              if (subargs[i] === "-s") opts.status = subargs[++i];
-              if (subargs[i] === "-l") opts.listOnly = true;
-              if (subargs[i] === "-a") opts.all = true;
-              if (subargs[i] === "-d") manager.decisionsDir = subargs[++i];
-            }
-
-            if (opts.listOnly) {
-              manager.list({ status: opts.status || "open" });
-            } else {
-              manager.show({
-                status: opts.status || "open",
-                num: opts.num || 1,
-                all: opts.all || false,
-              });
-            }
-            break;
-          }
-          default:
-            throw new Error(`Unknown ctx subcommand: ${sub}`);
-        }
+        await runCtxCommand(sub, subargs, {
+          cwd,
+          allowIndexNew: false,
+          updateDecisionIndexPaths: false,
+        });
       } catch (err) {
         console.error(`Error: ${err.message}`);
         process.exit(1);