cmdr-mcp 0.1.1 → 0.2.0

package/plugins/cmdr/README.md

@@ -2,15 +2,15 @@
 
 Connect local Claude Code, Codex, ZCode and other MCP-capable sessions as a squad. Requires macOS/Linux and Node.js ≥22.5 (24 recommended); npm distribution packages include all runtime dependencies. A source checkout requires `npm ci && npm run build` at the repository root before installation; generated `dist` files are not tracked by Git.
 
-In each session enter `/cmdr my-project`. The first becomes commander; others join as executors. Without slash commands, ask the Agent to call `join(squad_name="my-project")`.
+In each session enter `/cmdr my-project`. Joining defaults to executor, even for a new channel. Explicitly use role="commander" to claim command; no commander is required to retain a channel. Without slash commands, ask the Agent to call `join(squad_name="my-project")`.
 
-Tools: `join`, `list`, `send`, `report`, `ask`, `read`, `leave`. Executors report ready with capabilities/cwd, then read tasks, report results and ask when blocked. Commanders dispatch verifiable tasks and answer questions with `reply_to`. Use each result's `me.recommended_wait` for long polling; the skills limit standby to 40 rounds.
+Tools: `join`, `list`, `send`, `report`, `ask`, `read`, `leave`. Executors report ready with capabilities/cwd, then read tasks, report results and ask when blocked. Commanders dispatch verifiable tasks and answer questions with `reply_to`. Acknowledge each command with working + reply_to before executing it. Use read(recover=true) to find unfinished commands after interruptions. Offline never means stopped. Use join(standby="auto") and check listener health; with a healthy listener, end the idle turn. Manual fallback is limited to two recommended waits.
 
-Install a built checkout or the unpacked/installed npm package root as a marketplace in Claude Code/Codex, or use ZCode Settings → Plugins → Create → Add plugin marketplace. Codex needs hooks enabled and five hook approvals; start a new session after installation. ZCode uses its native manifest and four supported hooks; MCP EOF handles offline state. Generic hosts can configure the absolute `bin/cmdr-mcp` executable and `CMDR_AGENT=<host>` with optional `CMDR_SESSION_ID=<unique native session>`.
+Install a built checkout or the unpacked/installed npm package root as a marketplace in Claude Code/Codex, or use ZCode Settings → Plugins → Create → Add plugin marketplace. Codex needs hooks enabled and five hook approvals; start a new session after installation. For ZCode, use the published `njugray/cmdr#marketplace` source to install without a local build or global npm package. ZCode uses its native manifest and four supported hooks; MCP EOF handles offline state. Generic hosts can configure the absolute `bin/cmdr-mcp` executable and `CMDR_AGENT=<host>` with optional `CMDR_SESSION_ID=<unique native session>`.
 
 `bin/cmdr config --agent zcode` prints native ZCode configuration; `bin/cmdr config --agent my-agent` prints generic MCP configuration. `bin/cmdr doctor` checks installation health. `bin/cmdr daemon restart` reloads same-version code changes. State lives in `~/.cmdr/` (override `CMDR_HOME`), shared by all sessions.
 
-No active wakeups, Agent launching, remote transport or execution of message contents. Read marks delivery; use history if a host loses a previously delivered result. Idle recipients may need the user to say “continue”.
+The daemon can wake existing Codex sessions through the shared public app-server transport; other hosts explicitly remain manual. It never creates agents or provides remote transport. Read marks delivery; report(working/done/failed/cancelled, reply_to) tracks work separately. cmdr standby manages listeners, and tail --after/--for supports non-consuming event replay. See [long-running collaboration](https://github.com/njugray/cmdr/blob/main/docs/long-running-collaboration.md).
 
 [Installation and usage](https://github.com/njugray/cmdr#readme) · [Host integration](https://github.com/njugray/cmdr/blob/main/docs/agent-integration.md) · [Verification scope](https://github.com/njugray/cmdr/blob/main/docs/implementation.md)
 

package/plugins/cmdr/bin/cmdr-node

@@ -37,13 +37,13 @@ if [ -z "$CMDR_NODE" ]; then
 fi
 if [ -z "$CMDR_NODE" ]; then
   cmdr_failure node
-  [ "$CMDR_ENTRY" = hook ] && exit 0
+  [ "$CMDR_ENTRY" = hook ] && { echo "cmdr hook unavailable: Node >=22.5 required; run cmdr doctor." >&2; exit 0; }
   echo 'cmdr requires Node.js >=22.5 (24 recommended). Install Node and retry.' >&2
   exit 1
 fi
 if [ ! -f "$CMDR_BIN_DIR/../dist/$CMDR_ENTRY.mjs" ]; then
   cmdr_failure runtime
-  [ "$CMDR_ENTRY" = hook ] && exit 0
+  [ "$CMDR_ENTRY" = hook ] && { echo "cmdr hook unavailable: missing dist runtime; build or reinstall the plugin and run cmdr doctor --plugin-root PATH." >&2; exit 0; }
   if [ "$CMDR_ENTRY" = cli ] && [ "$1" = doctor ] && [ -f "$CMDR_BIN_DIR/cmdr-check.mjs" ]; then
     exec "$CMDR_NODE" "$CMDR_BIN_DIR/cmdr-check.mjs" "$CMDR_BIN_DIR/.."
   fi

package/plugins/cmdr/commands/cmdr.md

@@ -1,9 +1,7 @@
 ---
-description: Create or join a named local agent squad.
+description: Create or join a persistent local agent channel.
 argument-hint: <name>
 ---
-Call the cmdr join tool with squad_name="$ARGUMENTS". This is an atomic find-or-create operation; do not list then create. If no name was provided, ask for one. Do not invent a name.
-If the squad is orphaned, ask whether to take over as commander or join as executor and then use explicit role and squad ID.
-Follow the returned protocol_hint. An executor reports ready with cwd, capabilities and context before replying. Translate user_reply into the user's language, keep the join line unchanged, and reply with only that text. Then use read(wait=me.recommended_wait) to participate.
-
-If cmdr tools are unavailable, follow the using-cmdr installation diagnostics and member CLI fallback. Do not invent native session IDs or access raw sockets.
+Call join(squad_name="$ARGUMENTS", standby="auto") for atomic find-or-create. If no name was provided, ask for one; do not invent it. Joining defaults to executor, including a channel without a commander. Add role="commander" if the user explicitly requested command; use takeover=true only for requested handover.
+Follow protocol_hint and the role skill. Executors report ready with cwd and capabilities. Give a brief translated user_reply preserving the join line. Check listener health: end the idle turn when can_auto_respond=true; otherwise use at most two recommended waits and explain manual continuation. Do not create a private wake script.
+If tools are unavailable, follow using-cmdr diagnostics and member CLI fallback. Use the real host session ID, never an invented identity or raw socket workaround.

package/plugins/cmdr/dist/cli.mjs

@@ -6,9 +6,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/cli/session.ts
-import { parseArgs } from "node:util";
-
 // src/shared/diagnostics.ts
 import { mkdirSync as mkdirSync2, readFileSync, writeFileSync, renameSync, rmSync } from "node:fs";
 import { join as join2 } from "node:path";
@@ -115,7 +112,18 @@ import { connect } from "node:net";
 import { spawn } from "node:child_process";
 import { dirname, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
-import { mkdirSync as mkdirSync3, rmSync as rmSync2, statSync } from "node:fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync2, rmSync as rmSync2, statSync } from "node:fs";
+
+// src/daemon/lock.ts
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
 
 // src/shared/rpc.ts
 import { EventEmitter } from "node:events";
@@ -260,7 +268,7 @@ var Rpc = class extends EventEmitter {
 };
 
 // src/shared/version.ts
-var VERSION = true ? "0.1.1" : "0.1.0";
+var VERSION = true ? "0.2.0" : MIN_CLIENT_VERSION;
 var PROTOCOL = 1;
 function newer(a, b) {
   const x = a.split(".").map(Number), y = b.split(".").map(Number);
@@ -306,15 +314,16 @@ async function daemonConnection(options = {}) {
             { from: hello.version, to: VERSION, protocol: hello.protocol },
             options.home
           );
-          await rpc.request("admin.shutdown", { reason: "upgrade", version: VERSION }, timeout);
-          rpc.close();
-          await sleep(100);
-          continue;
+          throw new CmdrError(
+            "UPGRADE_REQUIRED",
+            `Daemon ${hello.version} is older than client ${VERSION}. Run cmdr daemon restart from this installation; automatic replacement is disabled to protect live sessions.`
+          );
         }
         return rpc;
       } catch (e) {
         rpc?.close();
-        if (e.code === "PROTOCOL_MISMATCH" || !options.start) throw e;
+        if (e.code === "PROTOCOL_MISMATCH" || e.code === "UPGRADE_REQUIRED" || !options.start)
+          throw e;
       }
       if (!owner) {
         try {
@@ -328,7 +337,12 @@ async function daemonConnection(options = {}) {
           }
         }
       }
-      if (owner) {
+      let daemonOwnsLock = false;
+      try {
+        daemonOwnsLock = alive(Number(readFileSync2(p.lock, "utf8")));
+      } catch {
+      }
+      if (owner && !daemonOwnsLock) {
         if (attempt === 0 || !spawned) {
           const child = spawn(
             process.execPath,
@@ -439,6 +453,81 @@ var DaemonClient = class {
   }
 };
 
+// src/cli/tail.ts
+async function tail(options) {
+  let after = options.after, stopped = false;
+  let connection;
+  const stop = () => {
+    stopped = true;
+    connection?.close();
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  const show = (event) => {
+    if (after !== void 0 && event.event_seq <= after) return;
+    process.stdout.write(
+      options.json ? JSON.stringify(event) + "\n" : `${event.event_seq} ${new Date(event.at).toISOString()} ${event.channel || "-"} ${event.kind} ${event.from_sid || "-"} \u2192 ${event.to_sid || "-"} ${event.message_id || ""}${event.reply_to ? ` reply_to=${event.reply_to}` : ""}${event.reason ? ` ${event.reason}` : ""}${event.message ? ` ${event.message.body.replace(/\s+/g, " ")}` : ""}
+`
+    );
+    after = event.event_seq;
+  };
+  try {
+    do {
+      try {
+        const rpc = connection = await daemonConnection();
+        const closed = new Promise((resolve3) => rpc.once("close", resolve3));
+        await rpc.request("session.register", { kind: "cli" });
+        let replaying = true;
+        const buffer = [];
+        rpc.on("notification", (method, value) => {
+          if (method === "lifecycle.event") replaying ? buffer.push(value) : show(value);
+        });
+        let result = await rpc.request(options.follow ? "admin.tail" : "admin.events", {
+          ...options,
+          after
+        });
+        if (result.gap) {
+          const gap = { kind: "retention.gap", after, retained_after: result.retained_after };
+          if (options.json) process.stdout.write(JSON.stringify(gap) + "\n");
+          else
+            process.stderr.write(
+              `cmdr: event retention gap; events through ${result.retained_after} expired
+`
+            );
+        }
+        for (; ; ) {
+          for (const event of result.events) show(event);
+          after = Math.max(after || 0, result.next);
+          if (result.next >= result.high) break;
+          result = await rpc.request("admin.events", { ...options, after });
+        }
+        replaying = false;
+        for (const event of buffer.sort((a, b) => a.event_seq - b.event_seq)) show(event);
+        if (!options.follow) rpc.close();
+        else await closed;
+      } catch (e) {
+        if (!options.follow || stopped) {
+          if (!stopped) throw e;
+        } else
+          process.stderr.write(
+            `cmdr tail: ${String(e)}; reconnecting after ${after ?? "latest"}
+`
+          );
+      } finally {
+        connection?.close();
+        connection = void 0;
+      }
+      if (options.follow && !stopped) await new Promise((r) => setTimeout(r, 1e3));
+    } while (options.follow && !stopped);
+  } finally {
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+  }
+}
+
+// src/cli/session.ts
+import { parseArgs } from "node:util";
+
 // node_modules/zod/v3/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -4492,16 +4581,20 @@ var schemas = {
     squad: external_exports.string().optional(),
     name: external_exports.string().trim().min(1).max(64).optional(),
     note: text.optional(),
-    squad_name: external_exports.string().trim().min(1).max(64).optional()
+    squad_name: external_exports.string().trim().min(1).max(64).optional(),
+    takeover: external_exports.boolean().default(false),
+    standby: external_exports.enum(["auto", "manual"]).optional(),
+    rebind: external_exports.string().optional()
   }).strict(),
   list: external_exports.object({
     ...identity,
+    full: external_exports.boolean().default(false),
     scope: external_exports.enum(["squad", "all"]).optional(),
     squad: external_exports.string().optional()
   }).strict(),
   report: external_exports.object({
     ...identity,
-    status: external_exports.enum(["ready", "working", "blocked", "done", "failed"]),
+    status: external_exports.enum(["ready", "working", "blocked", "done", "failed", "cancelled"]),
     message: text,
     reply_to: external_exports.string().optional(),
     data
@@ -4511,7 +4604,10 @@ var schemas = {
     ...identity,
     to: external_exports.union([external_exports.string().min(1), external_exports.array(external_exports.string().min(1)).min(1).max(1e3)]),
     message: text,
-    type: external_exports.enum(["command", "answer", "info"]).default("command"),
+    type: external_exports.enum(["command", "cancel", "answer", "info"]).default("command"),
+    task_key: external_exports.string().min(1).max(128).optional(),
+    reassign: external_exports.string().optional(),
+    attention: external_exports.boolean().optional(),
     priority: external_exports.enum(["high", "normal", "low"]).optional(),
     reply_to: external_exports.string().optional(),
     data
@@ -4522,7 +4618,10 @@ var schemas = {
     limit: external_exports.number().int().min(1).max(100).default(20),
     peek: external_exports.boolean().default(false),
     history: external_exports.boolean().default(false),
-    since: external_exports.string().optional()
+    since: external_exports.string().optional(),
+    id: external_exports.string().optional(),
+    recover: external_exports.boolean().default(false),
+    full: external_exports.boolean().default(false)
   }).strict(),
   leave: external_exports.object({ ...identity, dissolve: external_exports.boolean().default(false), message: text.optional() }).strict()
 };
@@ -4591,6 +4690,16 @@ async function runSession(argv) {
         to: { type: "string" },
         type: { type: "string" },
         "reply-to": { type: "string" },
+        priority: { type: "string" },
+        "task-key": { type: "string" },
+        reassign: { type: "string" },
+        rebind: { type: "string" },
+        takeover: { type: "boolean" },
+        standby: { type: "string" },
+        full: { type: "boolean" },
+        recover: { type: "boolean" },
+        id: { type: "string" },
+        limit: { type: "string" },
         peek: { type: "boolean" },
         history: { type: "boolean" },
         dissolve: { type: "boolean" },
@@ -4600,7 +4709,7 @@ async function runSession(argv) {
     });
     if (v.help) {
       console.log(
-        "cmdr session join|list|send|report|ask|read|leave --agent HOST --native-id ID [--input JSON] [--timeout SECONDS]\nUse --squad-name for join; --status and text for report; --to and text for send; text for ask. read supports --wait/--peek/--history. IDs must match the host session; commands do not wake agents."
+        "cmdr session join|list|send|report|ask|read|leave --agent HOST --native-id ID [--input JSON] [--timeout SECONDS]\nUse --squad-name for join; --status and text for report; --to and text for send; text for ask. read supports --wait/--peek/--history. IDs must match the host session; read also supports --recover/--id/--full/--limit. Configure automatic wake with cmdr standby start --session SID; unsupported hosts remain manual."
       );
       return;
     }
@@ -4631,12 +4740,22 @@ async function runSession(argv) {
       to: "to",
       type: "type",
       "reply-to": "reply_to",
+      priority: "priority",
+      "task-key": "task_key",
+      reassign: "reassign",
+      rebind: "rebind",
+      takeover: "takeover",
+      standby: "standby",
+      full: "full",
+      recover: "recover",
+      id: "id",
       peek: "peek",
       history: "history",
       dissolve: "dissolve"
     };
     for (const [flag, field] of Object.entries(mapping))
       if (v[flag] !== void 0) input[field] = v[flag];
+    if (v.limit !== void 0) input.limit = Number(v.limit);
     if (v.all) input.scope = "all";
     if (v.wait !== void 0) input.wait = Number(v.wait);
     if (args.length > 1) input[action === "ask" ? "question" : "message"] = args.slice(1).join(" ");
@@ -4646,6 +4765,7 @@ async function runSession(argv) {
       throw new Error("--timeout must be >0 and <=3600 seconds");
     client = new DaemonClient({
       kind: "mcp",
+      transport: "cli",
       agent,
       native_id: native,
       cwd: process.cwd(),
@@ -4794,7 +4914,7 @@ async function probeMcp(root) {
 }
 
 // src/cli/main.ts
-import { readFileSync as readFileSync2, existsSync } from "node:fs";
+import { readFileSync as readFileSync3, existsSync } from "node:fs";
 import { dirname as dirname2, join as join5, resolve as resolve2 } from "node:path";
 import { homedir as homedir2 } from "node:os";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
@@ -4814,6 +4934,19 @@ if (process.argv[2] === "session") {
       to: { type: "string" },
       type: { type: "string" },
       "reply-to": { type: "string" },
+      priority: { type: "string" },
+      "task-key": { type: "string" },
+      reassign: { type: "string" },
+      after: { type: "string" },
+      for: { type: "string" },
+      adapter: { type: "string" },
+      executable: { type: "string" },
+      socket: { type: "string" },
+      resolve: { type: "string" },
+      recover: { type: "boolean" },
+      history: { type: "boolean" },
+      id: { type: "string" },
+      limit: { type: "string" },
       session: { type: "string" },
       peek: { type: "boolean" },
       follow: { type: "boolean" },
@@ -4864,7 +4997,7 @@ if (process.argv[2] === "session") {
       checks.daemon = "not running";
     }
     try {
-      const conf = readFileSync2(
+      const conf = readFileSync3(
         join5(process.env.CODEX_HOME || join5(homedir2(), ".codex"), "config.toml"),
         "utf8"
       );
@@ -4899,7 +5032,7 @@ if (process.argv[2] === "session") {
     } else
       checks.zcode = "Desktop app not found in /Applications; generic MCP configuration is available.";
     try {
-      const zconfig = JSON.parse(readFileSync2(join5(homedir2(), ".zcode/cli/config.json"), "utf8"));
+      const zconfig = JSON.parse(readFileSync3(join5(homedir2(), ".zcode/cli/config.json"), "utf8"));
       checks.zcode_user_hooks = zconfig.hooks?.enabled === true;
     } catch {
       checks.zcode_user_hooks = "No user hook config; installed plugin hooks follow plugin enablement.";
@@ -4909,7 +5042,7 @@ if (process.argv[2] === "session") {
   try {
     if (v.help)
       process.stdout.write(
-        "cmdr status | list [--all] [--squad ID] | tail [--follow] [--full] | send --squad ID [--to MEMBER] [--type command|info|answer] TEXT | read --session SID [--peek] | daemon start|stop|restart|status|logs | config [--agent HOST] [--session ID] | doctor [--plugin-root PATH] [--deep] | session --help | purge [--all]\n"
+        "cmdr status | list [--all] [--squad ID] | tail [--follow] [--full] [--json] [--after EVENT_SEQ] [--for SID] | standby start|status|stop|resume --session SID [--adapter codex|manual] | send --squad ID [--to MEMBER] [--type command|cancel|info|answer] TEXT | read --session SID [--peek] | daemon start|stop|restart|status|logs | config [--agent HOST] [--session ID] | doctor [--plugin-root PATH] [--deep] | session --help | purge [--all]\n"
       );
     else if (cmd === "config") {
       const agent = v.agent || "generic";
@@ -4933,7 +5066,8 @@ if (process.argv[2] === "session") {
     else if (cmd === "list") {
       const result = await call("session.list", {
         scope: v.all ? "all" : void 0,
-        squad: v.squad
+        squad: v.squad,
+        full: !!v.full
       });
       if (v.json) print(result);
       else {
@@ -4945,11 +5079,16 @@ if (process.argv[2] === "session") {
             title: s.title,
             role: s.role,
             squad: s.squad,
-            presence: s.presence,
+            work: s.commands.map((m) => `${m.id}:${m.state}${m.cancel_requested_at ? ":cancelling" : ""}`).join(", "),
+            unacked: s.unacked,
+            in_progress: s.in_progress,
             activity: s.activity,
+            progress_seconds_ago: s.last_progress_at ? Math.floor((Date.now() - s.last_progress_at) / 1e3) : "unknown",
+            connection: s.presence,
             pending: s.pending,
+            wake: `${s.listener.wake_mode}/${s.listener.health}`,
             identity: s.native_id ? "confirmed" : "provisional",
-            age_ms: Date.now() - s.created_at,
+            seen_seconds_ago: Math.floor((Date.now() - s.last_seen) / 1e3),
             cwd: s.cwd,
             terminal: s.terminal?.program
           }))
@@ -4972,6 +5111,9 @@ if (process.argv[2] === "session") {
             to: v.to || "all",
             type: v.type || "command",
             reply_to: v["reply-to"],
+            priority: v.priority,
+            reassign: v.reassign,
+            task_key: v["task-key"],
             message: args.slice(1).join(" ")
           },
           true
@@ -4979,26 +5121,64 @@ if (process.argv[2] === "session") {
       );
     else if (cmd === "read") {
       if (!v.session) throw new Error("--session SID is required");
-      print(await call("admin.read", { sid: v.session, options: { peek: !!v.peek } }));
+      print(
+        await call("admin.read", {
+          sid: v.session,
+          options: {
+            peek: !!v.peek,
+            history: !!v.history,
+            full: !!v.full,
+            recover: !!v.recover,
+            id: v.id,
+            limit: v.limit ? Number(v.limit) : void 0
+          }
+        })
+      );
     } else if (cmd === "purge") print(await call("admin.purge", { all: !!v.all }));
-    else if (cmd === "tail") {
-      const rpc = await daemonConnection();
-      await rpc.request("session.register", { kind: "cli" });
-      if (v.follow) {
-        rpc.on("notification", (method, value) => {
-          if (method === "msg.event") print(value);
-        });
-        await rpc.request("admin.tail", { squad: v.squad, full: !!v.full });
-      }
-      print(await rpc.request("admin.recent", { squad: v.squad, full: !!v.full }));
-      if (!v.follow) rpc.close();
-      else process.on("SIGINT", () => rpc.close());
+    else if (cmd === "standby") {
+      if (!v.session) throw new Error("--session SID is required");
+      print(
+        await call(
+          "admin.standby",
+          {
+            sid: v.session,
+            action: args[1] || "status",
+            adapter: v.adapter,
+            executable: v.executable,
+            socket: v.socket,
+            resolve: v.resolve
+          },
+          true
+        )
+      );
+    } else if (cmd === "tail") {
+      const after = v.after === void 0 ? void 0 : Number(v.after);
+      if (after !== void 0 && (!Number.isSafeInteger(after) || after < 0))
+        throw new Error("--after requires a nonnegative event_seq");
+      await tail({
+        squad: v.squad,
+        for: v.for,
+        after,
+        full: !!v.full,
+        json: !!v.json,
+        follow: !!v.follow
+      });
     } else if (cmd === "daemon") {
       const action = args[1] || "status";
       if (action === "logs")
-        process.stdout.write(existsSync(p.log) ? readFileSync2(p.log, "utf8") : "No daemon logs.\n");
+        process.stdout.write(existsSync(p.log) ? readFileSync3(p.log, "utf8") : "No daemon logs.\n");
       else if (action === "status") print(await call("admin.status"));
       else if (action === "stop" || action === "restart") {
+        if (action === "restart")
+          execFileSync(
+            process.execPath,
+            [
+              "--experimental-sqlite",
+              join5(dirname2(fileURLToPath3(import.meta.url)), "daemon.mjs"),
+              "--preflight"
+            ],
+            { timeout: 15e3, stdio: ["ignore", "pipe", "pipe"] }
+          );
         try {
           print(await call("admin.shutdown", { reason: action }));
         } catch (e) {