@dadado/agent-kit-cli 5.2.1 → 5.4.0

package/dashboard/README.md

@@ -0,0 +1,25 @@
+# Mission Control runtime
+
+The dashboard the CLI serves. Plain ES modules, no build step: `serve.mjs` reads this directory
+directly, and `packages/cli/dashboard/` is a generated copy (gitignored, produced by
+`scripts/sync-cli-dashboard.mjs` at build/prepack time so the npm tarball can ship it).
+
+| Path | Role |
+| --- | --- |
+| `serve.mjs` | HTTP server, auth gate, SSE |
+| `start.mjs` / `start-broadcast.mjs` | loopback and LAN entry points, per-workspace port allocation |
+| `dashboard-data.mjs` | snapshot builder for the panel |
+| `dashboard.html`, `open.html` | panel and share shell |
+| `lib/*.mjs` | guards, semantic model, live refresh, browser open, terminal snapshot |
+| `lib/guards.d.mts` | hand-written types consumed by the CLI package (parity is pinned by a test) |
+
+## Where the tests live
+
+Tests for these modules are in `packages/cli/src/dashboard/*.test.ts`, not next to the source. The
+CLI package owns the only test runner in the workspace (vitest), and those suites import the `.mjs`
+files directly (`../../../../dashboard/lib/...`) so there is one implementation under test rather
+than a copy. Lint and format are covered from the repository root (`pnpm lint` checks `dashboard/**`
+before it fans out to the workspace packages).
+
+`dashboard.html` is outside Biome's scope; CSS/HTML-only changes are covered by
+`packages/cli/src/dashboard/plugin-ux-validation.test.ts` instead.

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

@@ -47,12 +47,12 @@ export function escapePerlDoubleQuoted(value) {
 
 /**
  * Resolve the repository root Mission Control should snapshot.
- * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined> | undefined} env - `undefined` falls back to `process.env`
  * @param {string} kitRoot - absolute path to the kit tree (parent of `dashboard/`)
  * @returns {string} absolute snapshot root
  */
-export function resolveSnapshotRepoRoot(env = process.env, kitRoot) {
-  const raw = env?.[REPO_ROOT_ENV];
+export function resolveSnapshotRepoRoot(env, kitRoot) {
+  const raw = (env ?? process.env)?.[REPO_ROOT_ENV];
   if (typeof raw === "string" && raw.trim()) {
     return resolve(raw.trim());
   }
@@ -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,
@@ -272,7 +400,7 @@ export function tokensMatch(a, b) {
 /**
  * Resolve bind + token gate for Mission Control serve.
  * Non-loopback bind requires a valid MISSION_CONTROL_TOKEN (no warn-only 0.0.0.0).
- * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined> | undefined} env - `undefined` falls back to `process.env`
  * @returns
  *   | { ok: true, host: string, tokenRequired: boolean, token: string | null, broadcast: boolean }
  *   | { ok: false, error: string }

package/dashboard/lib/triage-heading.mjs

@@ -11,8 +11,7 @@
  *   ## Follow-up plan  (also "Followup plan")
  *   ## Residuals plan
  */
-export const TRIAGE_HEADING_RE =
-  /^#{2,6}\s+(?:Triage note|Follow-?up plan|Residuals plan)\b/im;
+export const TRIAGE_HEADING_RE = /^#{2,6}\s+(?:Triage note|Follow-?up plan|Residuals plan)\b/im;
 
 /** True when markdown carries a durable triage heading. */
 export function hasTriageHeading(text) {

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,25 @@ 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",
+  "f04fcfe31354d1b09aeb256a17e4aab91c98ea48a5cff25e4a0281af3cfb289f",
+  "34e559ad9036d93d9cbc96d394bc2bbeb10ce50ead00d58a914158ae19daa76c"
 ]);
 
 // src/lifecycle/paths.ts
@@ -1072,17 +1090,38 @@ async function findPack(rootDir, packId) {
 }
 
 // src/registry/install.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile5, readdir as readdir3 } from "fs/promises";
 import path8 from "path";
+function skillTargetDir(skillPath, skillId) {
+  const category = skillPath.includes("/core/") ? "core" : "community";
+  return path8.posix.join(".cursor", "skills", category, skillId);
+}
+async function skillFileTargets(registryRoot, skillPath, skillId) {
+  const targetDir = skillTargetDir(skillPath, skillId);
+  const pair = (rel) => ({
+    sourceRel: path8.posix.join(skillPath, rel),
+    targetRel: path8.posix.join(targetDir, rel)
+  });
+  let companions = [];
+  try {
+    const dirAbs = resolveContained(registryRoot, skillPath);
+    const entries = await readdir3(dirAbs, { withFileTypes: true, recursive: true });
+    companions = entries.filter((entry) => entry.isFile()).map((entry) => {
+      const parent = path8.relative(dirAbs, entry.parentPath ?? dirAbs);
+      return path8.join(parent, entry.name).split(path8.sep).join("/");
+    }).filter((rel) => rel !== "SKILL.md" && !rel.split("/").some((seg) => seg.startsWith("."))).sort();
+  } catch {
+    companions = [];
+  }
+  return [pair("SKILL.md"), ...companions.map(pair)];
+}
 function targetForMember(member) {
   switch (member.kind) {
-    case "skill": {
-      const category = member.source.includes("/core/") ? "core" : "community";
+    case "skill":
       return {
         sourceRel: path8.posix.join(member.source, "SKILL.md"),
-        targetRel: path8.posix.join(".cursor", "skills", category, member.id, "SKILL.md")
+        targetRel: path8.posix.join(skillTargetDir(member.source, member.id), "SKILL.md")
       };
-    }
     case "rule":
       return {
         sourceRel: member.source,
@@ -1123,19 +1162,22 @@ function targetForMember(member) {
 }
 async function installSkill(registryRoot, projectRoot, skill, options = {}) {
   const stats = emptyStats();
-  const category = skill.path.includes("/core/") ? "core" : "community";
-  const sourceRel = path8.posix.join(skill.path, "SKILL.md");
-  const targetRel = path8.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
   const managedHashes = await loadManagedHashLedger(projectRoot);
-  const outcome = await copyRegistryFile(
+  for (const { sourceRel, targetRel } of await skillFileTargets(
     registryRoot,
-    projectRoot,
-    sourceRel,
-    targetRel,
-    options.protectedGlobs ?? [],
-    { managedHashes, persistManagedHashes: false }
-  );
-  recordOutcome(stats, targetRel, outcome);
+    skill.path,
+    skill.id
+  )) {
+    const outcome = await copyRegistryFile(
+      registryRoot,
+      projectRoot,
+      sourceRel,
+      targetRel,
+      options.protectedGlobs ?? [],
+      { managedHashes, persistManagedHashes: false }
+    );
+    recordOutcome(stats, targetRel, outcome);
+  }
   await saveManagedHashLedger(projectRoot, managedHashes);
   return stats;
 }
@@ -1169,16 +1211,18 @@ async function installPack(registryRoot, projectRoot, packId, options = {}) {
   const managedHashes = await loadManagedHashLedger(projectRoot);
   const copyOpts = { managedHashes, persistManagedHashes: false };
   for (const member of packManifest.members) {
-    const { sourceRel, targetRel } = targetForMember(member);
-    const outcome = await copyRegistryFile(
-      registryRoot,
-      projectRoot,
-      sourceRel,
-      targetRel,
-      protectedGlobs,
-      copyOpts
-    );
-    recordOutcome(stats, targetRel, outcome);
+    const pairs = member.kind === "skill" ? await skillFileTargets(registryRoot, member.source, member.id) : [targetForMember(member)];
+    for (const { sourceRel, targetRel } of pairs) {
+      const outcome = await copyRegistryFile(
+        registryRoot,
+        projectRoot,
+        sourceRel,
+        targetRel,
+        protectedGlobs,
+        copyOpts
+      );
+      recordOutcome(stats, targetRel, outcome);
+    }
   }
   await saveManagedHashLedger(projectRoot, managedHashes);
   return stats;
@@ -1604,8 +1648,10 @@ async function buildRegistryPathMap(registryRoot, manifest) {
   for (const packId of manifest.packs ?? []) {
     const pack = await loadPackManifest(registryRoot, packId);
     for (const member of pack.members) {
-      const { sourceRel, targetRel } = packMemberTargets(member);
-      map.set(targetRel.split(path9.sep).join("/"), sourceRel.split(path9.sep).join("/"));
+      const pairs = member.kind === "skill" ? await skillFileTargets(registryRoot, member.source, member.id) : [packMemberTargets(member)];
+      for (const { sourceRel, targetRel } of pairs) {
+        map.set(targetRel.split(path9.sep).join("/"), sourceRel.split(path9.sep).join("/"));
+      }
     }
   }
   if ((manifest.skills ?? []).length > 0) {
@@ -1614,25 +1660,28 @@ async function buildRegistryPathMap(registryRoot, manifest) {
     for (const id of manifest.skills ?? []) {
       const skill = pool.find((s) => s.id === id);
       if (!skill) continue;
-      const category = skill.path.includes("/core/") ? "core" : "community";
-      const sourceRel = path9.posix.join(skill.path, "SKILL.md");
-      const targetRel = path9.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
-      map.set(targetRel, sourceRel);
+      for (const { sourceRel, targetRel } of await skillFileTargets(
+        registryRoot,
+        skill.path,
+        skill.id
+      )) {
+        map.set(targetRel, sourceRel);
+      }
     }
   }
   return map;
 }
 function guessRegistryPath(projectRel) {
   const p = projectRel.split(path9.sep).join("/");
-  if (p.startsWith(".cursor/skills/") && p.endsWith("/SKILL.md")) {
+  if (p.startsWith(".cursor/skills/")) {
     const rest = p.slice(".cursor/skills/".length);
     const parts = rest.split("/");
-    if (parts.length === 3 && (parts[0] === "core" || parts[0] === "community")) {
+    if (parts.length >= 3 && (parts[0] === "core" || parts[0] === "community")) {
       return path9.posix.join("registry/skills", rest);
     }
     const skillId = parts[0];
-    if (parts.length === 2 && skillId) {
-      return path9.posix.join("registry/skills", "community", skillId, "SKILL.md");
+    if (parts.length >= 2 && skillId) {
+      return path9.posix.join("registry/skills", "community", rest);
     }
   }
   if (p.startsWith(".cursor/rules/")) {
@@ -2735,8 +2784,10 @@ async function diffAgainstRegistry(registryRoot, projectRoot, manifest) {
   for (const packId of manifest.packs ?? []) {
     const pack = await loadPackManifest(registryRoot, packId);
     for (const member of pack.members) {
-      const { sourceRel, targetRel } = packMemberTargets(member);
-      await pushUnique(sourceRel, targetRel);
+      const pairs = member.kind === "skill" ? await skillFileTargets(registryRoot, member.source, member.id) : [packMemberTargets(member)];
+      for (const { sourceRel, targetRel } of pairs) {
+        await pushUnique(sourceRel, targetRel);
+      }
     }
   }
   if ((manifest.skills ?? []).length > 0) {
@@ -2748,10 +2799,13 @@ async function diffAgainstRegistry(registryRoot, projectRoot, manifest) {
         entries.push({ path: `skill:${id}`, status: "missing-registry" });
         continue;
       }
-      const category = skill.path.includes("/core/") ? "core" : "community";
-      const sourceRel = path13.posix.join(skill.path, "SKILL.md");
-      const targetRel = path13.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
-      await pushUnique(sourceRel, targetRel);
+      for (const { sourceRel, targetRel } of await skillFileTargets(
+        registryRoot,
+        skill.path,
+        skill.id
+      )) {
+        await pushUnique(sourceRel, targetRel);
+      }
     }
   }
   return entries;
@@ -2827,7 +2881,7 @@ import { defineCommand as defineCommand7 } from "citty";
 
 // src/invariants/hooks-health.ts
 import { execFile as execFile2 } from "child_process";
-import { constants as constants2, access as access5, readFile as readFile9, readdir as readdir3, stat as stat2 } from "fs/promises";
+import { constants as constants2, access as access5, readFile as readFile9, readdir as readdir4, stat as stat2 } from "fs/promises";
 import path14 from "path";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
@@ -2911,7 +2965,7 @@ async function assessGitHooksInstallDrift(rootDir) {
   const installHint = "Install or refresh with: `cp git-hooks/<name> .git/hooks/<name> && chmod +x .git/hooks/<name>` (see git-hooks/README.md)";
   let names = [...GIT_HOOK_CANONICAL_NAMES];
   try {
-    const listed = await readdir3(canonicalDir);
+    const listed = await readdir4(canonicalDir);
     const fromDisk = listed.filter(
       (n) => GIT_HOOK_CANONICAL_NAMES.includes(n)
     );
@@ -4756,7 +4810,7 @@ var guardCommand = defineCommand8({
 
 // src/commands/handoff.ts
 import { spawn as spawn4 } from "child_process";
-import { readFile as readFile13, readdir as readdir4, writeFile as writeFile6 } from "fs/promises";
+import { readFile as readFile13, readdir as readdir5, writeFile as writeFile6 } from "fs/promises";
 import path25 from "path";
 import { defineCommand as defineCommand9 } from "citty";
 function parsePlanFrontmatter(raw) {
@@ -4775,7 +4829,7 @@ function parsePlanFrontmatter(raw) {
 }
 async function findActivePlan(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir4(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
+  const files = (await readdir5(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
   for (const file of files) {
     const raw = await readFile13(path25.join(plansDir, file), "utf8");
     const fm = parsePlanFrontmatter(raw);
@@ -6409,7 +6463,7 @@ import { defineCommand as defineCommand13 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
 import { execFile as execFile5 } from "child_process";
-import { readFile as readFile17, readdir as readdir5, stat as stat3 } from "fs/promises";
+import { readFile as readFile17, readdir as readdir6, stat as stat3 } from "fs/promises";
 import path34 from "path";
 import { promisify as promisify5 } from "util";
 
@@ -6434,7 +6488,7 @@ function hasOpenGaps(content) {
 }
 async function listMonitorFiles(memoryDir) {
   try {
-    const names = await readdir5(memoryDir);
+    const names = await readdir6(memoryDir);
     return names.filter((n) => n.startsWith("plan-monitor-") && n.endsWith(".md")).sort();
   } catch {
     return [];
@@ -6842,7 +6896,7 @@ function createPersonaBannerPrinter(persona) {
 }
 
 // src/plan-loop/plan-state.ts
-import { readFile as readFile18, readdir as readdir6 } from "fs/promises";
+import { readFile as readFile18, readdir as readdir7 } from "fs/promises";
 import path38 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
@@ -6870,7 +6924,7 @@ function countPendingTodos(raw) {
 }
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir6(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
+  const files = (await readdir7(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
   return files[0] ? path38.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dadado/agent-kit-cli",
-  "version": "5.2.1",
+  "version": "5.4.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",