@dadado/agent-kit-cli 5.2.1 → 5.3.0

package/dashboard/lib/guards.d.mts

@@ -52,6 +52,39 @@ export function resolveMissionControlPort(args: {
   probe: (port: number) => { listening: boolean; repoRoot: string | null };
   opts?: PortOpts;
 }): { port: number; reuse: boolean; explicit: boolean };
+type BroadcastProbe = {
+  listening: boolean;
+  repoRoot?: string | null;
+  acceptsToken?: boolean;
+  tokenGated?: boolean;
+  lanReachable?: boolean | null;
+};
+type BroadcastListenerKind =
+  | "free"
+  | "self-broadcast"
+  | "self-other-mode"
+  | "foreign"
+  | "token-gated"
+  | "unknown";
+export function classifyBroadcastListener(
+  info: BroadcastProbe,
+  repoRoot: string,
+): BroadcastListenerKind;
+export function describeBroadcastListener(
+  kind: string,
+  info?: { port?: number | null; repoRoot?: string | null },
+): string;
+export function resolveBroadcastPort(args: {
+  repoRoot: string;
+  envPort?: string | number | null;
+  probe: (port: number) => BroadcastProbe;
+  opts?: PortOpts;
+}): {
+  port: number;
+  reuse: boolean;
+  explicit: boolean;
+  skipped: Array<{ port: number; kind: string; repoRoot: string | null }>;
+};
 export function isSafeRepoRelativePath(relPath: unknown): boolean;
 export function resolveBindHost(envHost?: string | null): string;
 export function isLoopbackBindHost(host: string | undefined | null): boolean;

package/dashboard/lib/guards.mjs

@@ -194,6 +194,134 @@ export function resolveMissionControlPort({ repoRoot, envPort, probe, opts = {}
   );
 }
 
+/**
+ * Classify what holds a candidate Mission Control port, from the point of view
+ * of a **broadcast** (LAN) start.
+ *
+ * Broadcast needs a non-loopback, token-gated listener of its own. A loopback
+ * `/dashboard` for this same workspace answers `?token=…` with 200 (the query is
+ * ignored when no token is required), so "same repoRoot + accepts our token" is
+ * not sufficient: reuse also requires the listener to answer on a LAN address.
+ * `lanReachable` may be `null`/omitted when the host has no LAN IPv4 to probe —
+ * then a root + token match is accepted.
+ *
+ * `token-gated` means: something Mission-Control-shaped is listening but refuses
+ * our token, so its owner cannot be confirmed. Like `foreign` and `unknown` it is
+ * never killed and never reused.
+ *
+ * @param {{ listening: boolean, repoRoot?: string|null, acceptsToken?: boolean, tokenGated?: boolean, lanReachable?: boolean|null }} info
+ * @param {string} repoRoot
+ * @returns {"free"|"self-broadcast"|"self-other-mode"|"foreign"|"token-gated"|"unknown"}
+ */
+export function classifyBroadcastListener(info, repoRoot) {
+  if (!info || info.listening !== true) return "free";
+  const mine = sameRepoRoot(info.repoRoot, repoRoot);
+  if (mine && info.acceptsToken === true) {
+    return info.lanReachable === false ? "self-other-mode" : "self-broadcast";
+  }
+  if (mine) return "self-other-mode";
+  if (info.repoRoot != null) return "foreign";
+  return info.tokenGated === true ? "token-gated" : "unknown";
+}
+
+/** Operator-facing wording for each {@link classifyBroadcastListener} kind. */
+const BROADCAST_LISTENER_LABELS = {
+  free: "free",
+  "self-broadcast": "this workspace's broadcast",
+  "self-other-mode":
+    "this workspace, but not a broadcast listener (loopback /dashboard, or another token)",
+  foreign: "another workspace",
+  "token-gated": "a token-gated Mission Control whose owner this token cannot confirm",
+  unknown: "an unidentified process",
+  exhausted: "no free port in this workspace's range",
+};
+
+/**
+ * One honest line about who holds a port. Used by the broadcast preflight so the
+ * operator is told *which* instance is in the way instead of a blind kill recipe.
+ *
+ * @param {string} kind
+ * @param {{ port?: number | null, repoRoot?: string | null }} [info]
+ * @returns {string}
+ */
+export function describeBroadcastListener(kind, info = {}) {
+  const label = BROADCAST_LISTENER_LABELS[kind] || BROADCAST_LISTENER_LABELS.unknown;
+  const owner =
+    kind === "foreign" && info.repoRoot ? `another workspace (${info.repoRoot})` : label;
+  return info.port == null ? owner : `${info.port}: ${owner}`;
+}
+
+/**
+ * Pick a listen port for a broadcast (LAN) Mission Control instance.
+ *
+ * Same per-workspace candidate walk as {@link resolveMissionControlPort}, with
+ * broadcast-aware reuse: only this workspace's own broadcast listener is reused.
+ * Anything else on a candidate port (our loopback panel, another workspace, an
+ * unidentified process) is **skipped, never killed** — that is what allows more
+ * than one Mission Control instance to run at once.
+ *
+ * Explicit `PORT` still refuses rather than walking, so an operator who pinned a
+ * port is told the truth instead of silently landing somewhere else.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string | number | undefined | null} [args.envPort] - raw `PORT` env
+ * @param {(port: number) => { listening: boolean, repoRoot?: string|null, acceptsToken?: boolean, tokenGated?: boolean, lanReachable?: boolean|null }} args.probe
+ * @param {{ base?: number, range?: number }} [args.opts]
+ * @returns {{ port: number, reuse: boolean, explicit: boolean, skipped: Array<{ port: number, kind: string, repoRoot: string | null }> }}
+ */
+export function resolveBroadcastPort({ repoRoot, envPort, probe, opts = {} }) {
+  const root = resolve(String(repoRoot || "").trim() || ".");
+  const raw =
+    envPort != null && String(envPort).trim() !== ""
+      ? Number.parseInt(String(envPort), 10)
+      : Number.NaN;
+  /** @type {Array<{ port: number, kind: string, repoRoot: string | null }>} */
+  const skipped = [];
+
+  if (Number.isFinite(raw) && raw > 0) {
+    const info = probe(raw) || { listening: false };
+    const kind = classifyBroadcastListener(info, root);
+    if (kind === "free") return { port: raw, reuse: false, explicit: true, skipped };
+    if (kind === "self-broadcast") return { port: raw, reuse: true, explicit: true, skipped };
+    const owner = info.repoRoot ? String(info.repoRoot) : null;
+    skipped.push({ port: raw, kind, repoRoot: owner });
+    const detail =
+      kind === "self-other-mode"
+        ? "it is this workspace's Mission Control but not a broadcast listener (loopback /dashboard, or a different MISSION_CONTROL_TOKEN)"
+        : kind === "foreign"
+          ? `it is Mission Control for ${owner}, and broadcast never touches another workspace`
+          : kind === "token-gated"
+            ? "a token-gated Mission Control is there whose owner this token cannot confirm, so it is left alone"
+            : "an unidentified process is there, so it is left alone";
+    const err = new Error(
+      `PORT ${raw} is not available for broadcast: ${detail}. Unset PORT to let broadcast pick a free per-workspace port instead.`,
+    );
+    Object.assign(err, {
+      broadcast: { port: raw, kind, repoRoot: owner, explicit: true, skipped },
+    });
+    throw err;
+  }
+
+  for (const port of portCandidatesForRepoRoot(root, opts)) {
+    const info = probe(port) || { listening: false };
+    const kind = classifyBroadcastListener(info, root);
+    if (kind === "free") return { port, reuse: false, explicit: false, skipped };
+    if (kind === "self-broadcast") return { port, reuse: true, explicit: false, skipped };
+    skipped.push({ port, kind, repoRoot: info.repoRoot ? String(info.repoRoot) : null });
+  }
+
+  const base = Number.isFinite(opts.base) ? opts.base : DEFAULT_PORT_BASE;
+  const range = Number.isFinite(opts.range) && opts.range > 0 ? opts.range : DEFAULT_PORT_RANGE;
+  const err = new Error(
+    `No free Mission Control broadcast port in ${base}-${base + range - 1} for ${root}. Stop one of your own unused instances, or set PORT to a free port.`,
+  );
+  Object.assign(err, {
+    broadcast: { port: null, kind: "exhausted", repoRoot: null, explicit: false, skipped },
+  });
+  throw err;
+}
+
 export const MAX_STRING = {
   branch: 64,
   lastCommit: 120,

package/dashboard/start-broadcast.mjs

@@ -5,11 +5,17 @@
  * Opt-in LAN bind: HOST=0.0.0.0 (or explicit non-loopback), requires
  * MISSION_CONTROL_TOKEN (generated when unset), detach-starts serve.mjs,
  * prints LAN URL(s) with token. Does not weaken loopback `/dashboard`.
+ *
+ * Multi-instance: the listen port is the same per-workspace allocation the
+ * loopback starter uses (hash of the snapshot root in the 3333-3588 range unless
+ * PORT is set). Candidate ports held by this workspace's loopback panel, another
+ * workspace, or an unidentified process are skipped - never killed - so a
+ * broadcast can come up beside an already-running Mission Control.
  */
 
 import { execFileSync, execSync, spawn } from "node:child_process";
 import { existsSync, openSync, realpathSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   buildBroadcastShareUrl,
@@ -19,13 +25,17 @@ import {
 } from "./lib/broadcast-share.mjs";
 import {
   BROADCAST_TOKEN_ENV,
+  REPO_ROOT_ENV,
+  describeBroadcastListener,
   escapePerlDoubleQuoted,
   generateBroadcastToken,
   isLoopbackBindHost,
   isValidBroadcastToken,
   listLanIPv4Addresses,
   normalizeAuthToken,
+  repoRootLogId,
   resolveBindHost,
+  resolveBroadcastPort,
   resolveContextConfigPath,
   resolveSnapshotRepoRoot,
 } from "./lib/guards.mjs";
@@ -37,11 +47,14 @@ const KIT_ROOT = join(__dirname, "..");
 const ROOT = resolveSnapshotRepoRoot(process.env, KIT_ROOT);
 process.title = `Mission Control · ${basename(ROOT) || "workspace"}`;
 const SERVE = join(__dirname, "serve.mjs");
-const LOG = process.env.MISSION_CONTROL_LOG || "/tmp/mission-control-broadcast.log";
-const PORT = Number.parseInt(process.env.PORT || "3333", 10);
+const LOG =
+  process.env.MISSION_CONTROL_LOG || `/tmp/mission-control-broadcast-${repoRootLogId(ROOT)}.log`;
 const READY_TIMEOUT_MS = 20_000;
 const READY_POLL_MS = 250;
 
+/** Allocated listen port for this run (see resolveBroadcastPort in main). */
+let PORT = 0;
+
 function resolveBroadcastEnv() {
   const env = { ...process.env };
   let host = resolveBindHost(env.HOST);
@@ -58,30 +71,84 @@ function resolveBroadcastEnv() {
   return { env, host, token };
 }
 
-function urlsForProbe(token) {
+function urlsForProbe(token, port = PORT) {
   const q = `?token=${encodeURIComponent(token)}`;
-  const urls = [`http://127.0.0.1:${PORT}/${q}`];
+  const urls = [`http://127.0.0.1:${port}/${q}`];
   for (const ip of listLanIPv4Addresses()) {
-    urls.push(`http://${ip}:${PORT}/${q}`);
+    urls.push(`http://${ip}:${port}/${q}`);
   }
   return urls;
 }
 
+/** HTTP status code as a string; "000" when the connection failed. */
+function httpStatus(url) {
+  try {
+    return execFileSync(
+      "curl",
+      ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "3", url],
+      { encoding: "utf8", timeout: 5000 },
+    ).trim();
+  } catch {
+    return "000";
+  }
+}
+
 function probeHttp(url) {
+  return httpStatus(url) === "200";
+}
+
+/** Snapshot root reported by a listener that accepts our token, else null. */
+function snapshotRootAt(port, token) {
+  const url = `http://127.0.0.1:${port}/dashboard-data.json?token=${encodeURIComponent(token)}`;
   try {
-    const code = execFileSync("curl", ["-sf", "-o", "/dev/null", "-w", "%{http_code}", url], {
+    const raw = execFileSync("curl", ["-sf", url], {
       encoding: "utf8",
-      timeout: 3000,
-    }).trim();
-    return code === "200";
+      timeout: 8000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    const root = JSON.parse(raw)?.system?.repoRoot;
+    return typeof root === "string" && root.trim() ? resolve(root.trim()) : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
-function listeningPids() {
+/**
+ * Probe one candidate port for `resolveBroadcastPort`.
+ *
+ * `lanReachable` is what separates our own broadcast (reusable) from our own
+ * loopback panel: a loopback listener needs no token, so it answers `?token=…`
+ * with 200 on 127.0.0.1 while staying unreachable on every LAN address.
+ */
+function probeBroadcastPort(port, token) {
+  const q = `?token=${encodeURIComponent(token)}`;
+  const loopbackStatus = httpStatus(`http://127.0.0.1:${port}/${q}`);
+  const listening = loopbackStatus !== "000" || listeningPids(port).length > 0;
+  if (!listening) {
+    return { listening: false, repoRoot: null, acceptsToken: false, tokenGated: false };
+  }
+  const acceptsToken = loopbackStatus === "200";
+  if (!acceptsToken) {
+    return {
+      listening: true,
+      repoRoot: null,
+      acceptsToken: false,
+      tokenGated: loopbackStatus === "401" || loopbackStatus === "403",
+    };
+  }
+  const ips = listLanIPv4Addresses();
+  return {
+    listening: true,
+    repoRoot: snapshotRootAt(port, token),
+    acceptsToken: true,
+    tokenGated: false,
+    lanReachable: ips.length > 0 ? ips.some((ip) => probeHttp(`http://${ip}:${port}/${q}`)) : null,
+  };
+}
+
+function listeningPids(port = PORT) {
   try {
-    const out = execFileSync("lsof", ["-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN", "-t"], {
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
       encoding: "utf8",
       timeout: 3000,
     }).trim();
@@ -124,6 +191,7 @@ function detachStart(env) {
   const hostEsc = escapePerlDoubleQuoted(String(env.HOST));
   const tokenEsc = escapePerlDoubleQuoted(String(env[BROADCAST_TOKEN_ENV]));
   const portEsc = escapePerlDoubleQuoted(String(PORT));
+  const snapEsc = escapePerlDoubleQuoted(ROOT);
   const perl = [
     "use POSIX qw(setsid);",
     "exit if fork;",
@@ -136,6 +204,7 @@ function detachStart(env) {
     `$ENV{HOST}="${hostEsc}";`,
     `$ENV{${BROADCAST_TOKEN_ENV}}="${tokenEsc}";`,
     `$ENV{PORT}="${portEsc}";`,
+    `$ENV{${REPO_ROOT_ENV}}="${snapEsc}";`,
     `exec("node","${serveEsc}");`,
   ].join(" ");
 
@@ -159,6 +228,68 @@ async function waitReady(urls) {
   return null;
 }
 
+/**
+ * Preflight: name every candidate port we walked past. Nothing here is killed —
+ * a busy port means another Mission Control (ours or someone else's) keeps
+ * running and broadcast lands on the next free per-workspace port.
+ */
+function reportSkipped(skipped) {
+  if (!skipped || skipped.length === 0) return;
+  console.log("Ports already held (left running):");
+  for (const entry of skipped) {
+    console.log(`  ${describeBroadcastListener(entry.kind, entry)}`);
+  }
+  if (skipped.some((entry) => entry.kind === "token-gated")) {
+    console.log(
+      `  Export ${BROADCAST_TOKEN_ENV} with an existing broadcast's token to reuse it instead of starting another.`,
+    );
+  }
+}
+
+/** Recovery text for a port we may not take. Never a blind kill of a foreign listener. */
+function recoveryLines(kind, port) {
+  switch (kind) {
+    case "self-other-mode":
+      return [
+        `  That listener is this workspace (${ROOT}). Stop it yourself if you want this exact port:`,
+        `    kill "$(lsof -nP -iTCP:${port} -sTCP:LISTEN -t)"`,
+        "  Or retry with PORT unset: broadcast will take a free per-workspace port and leave it running.",
+      ];
+    case "foreign":
+      return [
+        "  Leave that workspace's Mission Control running. Retry with PORT unset to take a free per-workspace port.",
+      ];
+    case "token-gated":
+      return [
+        `  Export ${BROADCAST_TOKEN_ENV} with that instance's token to reuse it, or retry with PORT unset.`,
+      ];
+    case "exhausted":
+      return [
+        "  Every candidate port in this workspace's range is held by an instance that is not ours to stop.",
+        "  Stop one of your own Mission Control instances, or set PORT to a port you know is free.",
+      ];
+    default:
+      return [
+        "  Leave that process alone. Retry with PORT unset to take a free per-workspace port.",
+      ];
+  }
+}
+
+function reportRefusal(err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  const info = err?.broadcast;
+  if (!info) return;
+  if (info.kind === "exhausted" && info.skipped?.length) {
+    console.error("Ports checked (all left running):");
+    for (const entry of info.skipped.slice(0, 8)) {
+      console.error(`  ${describeBroadcastListener(entry.kind, entry)}`);
+    }
+  }
+  for (const line of recoveryLines(info.kind, info.port)) {
+    console.error(line);
+  }
+}
+
 async function main() {
   const { env, host, token } = resolveBroadcastEnv();
   if (isLoopbackBindHost(host)) {
@@ -168,6 +299,26 @@ async function main() {
     process.exit(1);
   }
 
+  let allocation;
+  try {
+    allocation = resolveBroadcastPort({
+      repoRoot: ROOT,
+      envPort: process.env.PORT,
+      probe: (port) => probeBroadcastPort(port, token),
+    });
+  } catch (err) {
+    reportRefusal(err);
+    process.exit(1);
+  }
+
+  reportSkipped(allocation.skipped);
+
+  PORT = allocation.port;
+  // Pin the allocation for this process and the detached server.
+  process.env.PORT = String(PORT);
+  env.PORT = String(PORT);
+  env[REPO_ROOT_ENV] = ROOT;
+
   const urls = urlsForProbe(token);
   const primaryLan = listLanIPv4Addresses()[0];
   const displayUrl =
@@ -175,15 +326,9 @@ async function main() {
       ? `http://${primaryLan}:${PORT}/?token=${encodeURIComponent(token)}`
       : urls[0];
 
-  const already = listeningPids().length > 0 && urls.some((u) => probeHttp(u));
-  if (!already) {
-    if (listeningPids().length > 0) {
-      console.error(
-        `Port ${PORT} is listening but did not accept the broadcast token. Stop the existing Mission Control instance (loopback /dashboard) first, then retry.`,
-      );
-      console.error(`  kill "$(lsof -nP -iTCP:${PORT} -sTCP:LISTEN -t)"`);
-      process.exit(1);
-    }
+  if (allocation.reuse) {
+    console.log(`Mission Control broadcast already listening on port ${PORT} for ${ROOT}`);
+  } else {
     console.log(`Starting Mission Control broadcast on ${host}:${PORT}…`);
     detachStart(env);
     const ready = await waitReady(urls);
@@ -192,8 +337,6 @@ async function main() {
       console.error(`Check the log: ${LOG}`);
       process.exit(1);
     }
-  } else {
-    console.log(`Mission Control broadcast already listening on port ${PORT}`);
   }
 
   const shareBase = resolveShareBase(process.env);
@@ -233,7 +376,10 @@ async function main() {
       "  Share is a cosmetic Mission Kit (or BYO) link; phone must still reach this LAN.",
     );
   }
-  console.log("  Config writes stay loopback-only. Stop: kill the LISTEN pid on this port.");
+  console.log(`  Root:  ${ROOT}`);
+  console.log(
+    "  Config writes stay loopback-only. Stop this workspace only: kill the LISTEN pid on this port.",
+  );
   console.log("  Firewall: allow inbound TCP on this port for your LAN profile if needed.");
   console.log("");
 

package/dist/index.js

@@ -198,7 +198,23 @@ var KNOWN_SHIPPED_OVERLAY_HASHES = /* @__PURE__ */ new Set([
   "a8756742197c3a2e1a6d64f4bde2a88db48abb66a0f449d625cd2e1c7b8d0cb4",
   "6a5f8795a4a26b419f167e249576b798781c95308dc1ea50958351de713231d4",
   "4009c5e2faf9775d5708cdff0b5f9da80fd3ce390cc42aed0bb94272f6b05b1b",
-  "a8e070fae187908ef7b2cf2a41605e3079329403b1802b5fc67e83294c96a070"
+  "a8e070fae187908ef7b2cf2a41605e3079329403b1802b5fc67e83294c96a070",
+  "81186b528105f2873818ea91f51d20c95a68c0c4b3d128aa8896dd38a1bb3159",
+  "b2c7db73a0e18bd475651001722aa34b39276af9f73f0921102b680eb42bea0e",
+  "d03445b726cb6afe2ff37a936de97605cc60e441896e06385abfc15a127e2f45",
+  "f5ef970adaf4cfa7af551e35cb41b4052576109f5444a280b1e26562338b39e8",
+  "fe3f8e2339a7f183545f2aad6b7f02d3687277ca67597fa7620bfee269392bcd",
+  "b2489e381ea7daaef7299e5aede437a8baaa39baaddaac849efbf0a6ccb84a2b",
+  "0ae7d076904fd342de3ba38745f38fed8ca5c1f02d7b099d27deeb0a9be79740",
+  "15ca459811f0f050f4eeff77d4567b45c0790beb77904ecf37e145d65a858c77",
+  "1dc329c0c0695a4395bb7c30db0fb7b6fb06bcf5fdc1d6a475656ac6a525aa5f",
+  "35bb0008ef52af147a45fba667f7dceb841d537ad5e185317672577afbcbc189",
+  "42b701d224f4e690dc027d66fcc1214bab31a0ae0c50ef982124f57d4dae4982",
+  "65272f85a32f8fe95ed19d0823fa9d1d6dee5bc18a0244f7b553ea5162ba9b36",
+  "73cd50bac290b84df6245d3647e686dee8ec3b0434736d08fdba6e30d342ef0a",
+  "61b635ea8a08171062bd329a4615d7426eb787eb796271aa882f55f39db56810",
+  "86afbea8f64de68a79ad5e374f3132bdbe2582b94321fb3d438314838e36c776",
+  "65cc1c0293b145e48ed73ad0ca9ab33cbba5ed834a5bfb31f195ed30c2f143df"
 ]);
 
 // src/lifecycle/paths.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dadado/agent-kit-cli",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Agent Kit CLI: HITL framework install and tooling for AI-assisted IDEs (rules, skills, plan/handoff, context).",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",