@dadado/agent-kit-cli 5.3.0 → 5.5.0

package/README.md

@@ -63,7 +63,8 @@ On an interactive TTY, long-running commands (`init`, `install`, `doctor`, `upda
 |---------|---------|
 | `agent-kit install` | Bootstrap L0 (+ optional packs) and write `agent-kit.json` |
 | `agent-kit status` | Show installed kit version and profile |
-| `agent-kit doctor` | Diagnose repository readiness |
+| `agent-kit doctor` | Diagnose repository readiness (`--json` includes an `env` pillar: bin-on-PATH, npm prefix writability, Node version, shell profile) |
+| `agent-kit setup-global` | Self-heal a root-owned npm global prefix (relocate to `~/.npm-global`, fix `PATH`, reinstall) |
 | `agent-kit update` | Re-apply L0/packs/skills from the registry |
 | `agent-kit dashboard` | Start Mission Control for this workspace |
 | `agent-kit add <id>` | Install a skill or L1 pack |

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/dashboard-data.mjs

@@ -111,7 +111,7 @@ const SNAPSHOT = {
       dashboardDataVersion: "Semantic version of the data model schema",
       plans: "Active plans from .cursor/plans/*.plan.md with frontmatter parsing",
       system:
-        "System metadata: repoRoot, listen port, handoff state, allowlisted config summary, package info, version, name, contextPacks",
+        "System metadata: repoRoot, listen port, handoff state, allowlisted config summary, package info, version, name, contextPacks, detachedAuditSessions ({count, oldestAgeSeconds}|null; host-wide detached agent-kit-audit-* PTYs)",
       agents: "Agent definitions from .cursor/agents/*.md",
       commands: "Slash commands from .cursor/commands/*.md",
       memory:
@@ -641,6 +641,77 @@ try {
   SNAPSHOT.processes = [];
 }
 
+// 13b. Detached audit-session visibility (plan phase3-visibility).
+// Mirrors the sessionStart hook semantics (packages/cli/src/hooks/session-start.ts):
+// whole agent-kit-audit- namespace (any token, legacy unscoped names included),
+// detached sessions only; attached sessions are operator work and never counted.
+// Fail-open: null when zero sessions or tmux/screen is missing/errors.
+SNAPSHOT.system.detachedAuditSessions = null;
+try {
+  if (withinSnapshotBudget(400)) {
+    const auditAges = [];
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    try {
+      const tmuxOut = execSync(
+        "tmux list-sessions -F '#{session_name} #{session_attached} #{session_created}'",
+        { encoding: "utf-8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] },
+      );
+      for (const line of tmuxOut.split("\n")) {
+        const m = line.trim().match(/^(\S+)\s+(\d+)\s+(\d+)$/);
+        if (!m) continue;
+        if (!m[1].startsWith("agent-kit-audit-")) continue;
+        if (Number(m[2]) > 0) continue;
+        const created = Number(m[3]);
+        auditAges.push(nowEpoch >= created ? nowEpoch - created : -1);
+      }
+    } catch {
+      // tmux missing or no server: fail-open
+    }
+    try {
+      // `screen -ls` exits 1 while successfully listing, so soften the exit code.
+      const screenOut = execSync("screen -ls || true", {
+        encoding: "utf-8",
+        timeout: 2000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      // The "N Sockets in <dir>." line trails the session list; socket mtime ~ start time.
+      let sockdir = null;
+      for (const line of screenOut.split("\n")) {
+        const dirMatch = line.match(/^\d+\s+Sockets?\s+in\s+(.+)\.$/);
+        if (dirMatch) sockdir = dirMatch[1];
+      }
+      for (const line of screenOut.split("\n")) {
+        const m = line.match(/^\s+(\d+)\.(\S+)\s+\((.*)\)/);
+        if (!m) continue;
+        if (!m[2].startsWith("agent-kit-audit-")) continue;
+        // "Detached" has a single t before "ached", so it never matches [Aa]ttached.
+        if (/[Aa]ttached/.test(m[3])) continue;
+        let age = -1;
+        if (sockdir) {
+          try {
+            const mtimeMs = statSync(join(sockdir, `${m[1]}.${m[2]}`)).mtimeMs;
+            if (Date.now() >= mtimeMs) age = Math.floor((Date.now() - mtimeMs) / 1000);
+          } catch {
+            // socket not stat-able: age stays unknown, session still counted
+          }
+        }
+        auditAges.push(age);
+      }
+    } catch {
+      // screen missing: fail-open
+    }
+    if (auditAges.length > 0) {
+      const known = auditAges.filter((a) => a >= 0);
+      SNAPSHOT.system.detachedAuditSessions = {
+        count: auditAges.length,
+        oldestAgeSeconds: known.length ? Math.max(...known) : null,
+      };
+    }
+  }
+} catch {
+  SNAPSHOT.system.detachedAuditSessions = null;
+}
+
 // 10. Health checks (originally)
 const checks = [
   { id: "plans", label: "Plans directory", ok: existsSync(plansDir) && SNAPSHOT.plans.length > 0 },

package/dashboard/dashboard.html

@@ -4270,6 +4270,16 @@ function fmtDate(iso) {
   return d.toLocaleString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
 }
 
+// Humanize a duration in seconds (mirrors formatSessionAge in the sessionStart hook).
+function formatDuration(seconds) {
+  const s = Number(seconds);
+  if (!Number.isFinite(s) || s < 0) return 'unknown';
+  if (s >= 86400) return Math.floor(s / 86400) + 'd';
+  if (s >= 3600) return Math.floor(s / 3600) + 'h';
+  if (s >= 60) return Math.floor(s / 60) + 'm';
+  return Math.floor(s) + 's';
+}
+
 // Presentation contract (Phase 2): progress is never an error signal. Any
 // in-flight percentage (0-99) renders the neutral accent; 100% renders green
 // (lifecycle completed with total > 0 implies 100 per the Phase 0 contract).
@@ -8289,6 +8299,14 @@ function renderUnsafe() {
 
   // ===== Processes =====
   const processes = d.processes || [];
+  // Detached audit-session visibility (phase3): host-wide agent-kit-audit-* PTYs.
+  const auditSessions = d.system?.detachedAuditSessions || null;
+  const auditSessionsNote = auditSessions && auditSessions.count > 0
+    ? `
+      <div class="processes-note">
+        <span><strong>${auditSessions.count} detached audit ${auditSessions.count === 1 ? 'session' : 'sessions'}.</strong> Host-wide <code>agent-kit-audit-*</code> plan-review ${auditSessions.count === 1 ? 'PTY is' : 'PTYs are'} still alive (${auditSessions.oldestAgeSeconds != null ? `oldest ~${formatDuration(auditSessions.oldestAgeSeconds)}` : 'oldest age unknown'}). Inspect with <code>tmux attach -t &lt;name&gt;</code> / <code>screen -r &lt;name&gt;</code>, or let the audit launcher's session GC dispose of them on the next spawn.</span>
+      </div>`
+    : '';
   parts.push(`
     <div class="content-section" id="section-processes">
       <div class="section-title">
@@ -8297,7 +8315,7 @@ function renderUnsafe() {
       </div>
       <div class="processes-note">
         <span><strong>Live ps snapshot.</strong> Agent chats spawned inside the IDE do not appear here; the Crew monitor on the Overview tab tracks that activity.</span>
-      </div>
+      </div>${auditSessionsNote}
       ${processes.length === 0
         ? renderEmptyStateCta({
             headline: 'All quiet',

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());
   }
@@ -400,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) {