@dadado/agent-kit-cli 4.8.2 → 4.8.3

package/dashboard/dashboard.html

@@ -5582,7 +5582,7 @@ function renderFlightLogWarningCard(warning, idx) {
 /**
  * Quiet-state open-triage row (untriaged external review). Prompt chrome;
  * per-row Copy triage + path only. No Review all / Resolve all.
- * Cap mirrors FLIGHT_LOG_QUIET_OPEN_TRIAGES_CAP in semantic-model.mjs.
+ * Kind class from flightLogKindClassName('prompt') (SoT map; not a literal).
  * @param {{ id?: string, label?: string, sourcePath?: string, action?: { target?: string, label?: string, subject?: string } }} item
  * @param {number} idx
  */
@@ -5603,8 +5603,9 @@ function renderFlightLogQuietOpenTriageCard(item, idx) {
   const copyTriageHandler = copyForPasteHandler(triageCmd, 'triage command', 'chatInput');
   const copyPathHandler = copyRepoPathHandler(sourcePath);
   const aria = `Review: ${label}`;
+  const kindClass = flightLogKindClassName('prompt');
   return `
-    <div class="flight-log-card flight-log-card-current flight-log-kind-advice" role="listitem" tabindex="0" data-focus-key="flight-log-open-triage-${idx}" data-flight-log-kind="prompt" aria-label="${escapeAttr(aria)}">
+    <div class="flight-log-card flight-log-card-current ${kindClass}" role="listitem" tabindex="0" data-focus-key="flight-log-open-triage-${idx}" data-flight-log-kind="prompt" aria-label="${escapeAttr(aria)}">
       <span class="flight-log-card-label">Review</span>
       <div class="flight-log-card-text">${escapeHtml(label)}</div>
       <div class="flight-log-card-meta">${escapeHtml(sourcePath)}</div>
@@ -5616,6 +5617,43 @@ function renderFlightLogQuietOpenTriageCard(item, idx) {
   `;
 }
 
+/**
+ * Resolve Live Gaps text for Flight Log render + fingerprint (same fallback chain).
+ * Prefer fl.current; with Plan:none, fall back to now.gaps then system.handoff.gaps.
+ */
+function resolveFlightLogCurrent(d) {
+  const fl = d?.missionControl?.flightLog ?? d?.flightLog ?? null;
+  if (typeof fl?.current === 'string' && fl.current.trim()) return fl.current.trim();
+  const nowGaps = d?.missionControl?.now?.gaps ?? d?.now?.gaps;
+  if (typeof nowGaps === 'string' && nowGaps.trim()) return nowGaps.trim();
+  const handoffGaps = d?.system?.handoff?.gaps;
+  if (typeof handoffGaps === 'string' && handoffGaps.trim()) return handoffGaps.trim();
+  return null;
+}
+
+function flightLogHasPastEntries(fl) {
+  if (!fl || !Array.isArray(fl.past)) return false;
+  return fl.past.some((e) => {
+    if (typeof e === 'string') return Boolean(e.trim());
+    return Boolean(e && typeof e.text === 'string' && e.text.trim());
+  });
+}
+
+/** Match renderFlightLogWarningCard: text-less warnings do not count. */
+function flightLogHasWarningEntries(fl) {
+  if (!fl || !Array.isArray(fl.warnings)) return false;
+  return fl.warnings.some((w) => {
+    if (typeof w === 'string') return Boolean(w.trim());
+    return Boolean(w && typeof w.text === 'string' && w.text.trim());
+  });
+}
+
+/** Shared quiet gate for renderAttentionPanel + flightLogFingerprint. */
+function isFlightLogQuiet(d) {
+  const fl = d?.missionControl?.flightLog ?? d?.flightLog ?? null;
+  return !resolveFlightLogCurrent(d) && !flightLogHasPastEntries(fl) && !flightLogHasWarningEntries(fl);
+}
+
 /**
  * Flight Log panel: HANDOFF Gaps log (live large + earlier smaller) + Warnings lane.
  * When Gaps + Warnings are empty, may show bounded quiet open-triage rows.
@@ -5626,22 +5664,22 @@ function renderAttentionPanel(d, attentionChanged) {
   const sourcePath =
     (typeof fl?.sourcePath === 'string' && fl.sourcePath.trim()) ||
     '.cursor/HANDOFF.md';
-  const current =
-    typeof fl?.current === 'string' && fl.current.trim()
-      ? fl.current.trim()
-      : typeof d.missionControl?.now?.gaps === 'string' && d.missionControl.now.gaps.trim()
-        ? d.missionControl.now.gaps.trim()
-        : typeof d.system?.handoff?.gaps === 'string' && d.system.handoff.gaps.trim()
-          ? d.system.handoff.gaps.trim()
-          : null;
+  const current = resolveFlightLogCurrent(d);
   const past = Array.isArray(fl?.past) ? fl.past : [];
   const warnings = Array.isArray(fl?.warnings) ? fl.warnings : [];
+  const quietCap =
+    typeof d.missionControl?.flightLogQuietOpenTriagesCap === 'number' &&
+    d.missionControl.flightLogQuietOpenTriagesCap > 0
+      ? Math.floor(d.missionControl.flightLogQuietOpenTriagesCap)
+      : 0;
   const quietOpenTriages = Array.isArray(fl?.quietOpenTriages)
     ? fl.quietOpenTriages
     : Array.isArray(d.missionControl?.attention)
-      ? d.missionControl.attention.filter(
-          (i) => i && i.kind === 'report' && typeof i.sourcePath === 'string' && i.sourcePath.trim(),
-        ).slice(0, 5)
+      ? d.missionControl.attention
+          .filter(
+            (i) => i && i.kind === 'report' && typeof i.sourcePath === 'string' && i.sourcePath.trim(),
+          )
+          .slice(0, quietCap)
       : [];
   const pastCards = past
     .filter((e) => e && typeof e.text === 'string' && e.text.trim())
@@ -5675,6 +5713,7 @@ function renderAttentionPanel(d, attentionChanged) {
   const hasCurrent = Boolean(current);
   const hasPast = pastCards.length > 0;
   const hasWarnings = warningCards.length > 0;
+  // Keep local flags aligned with isFlightLogQuiet(d) for the quiet branch.
   if (!hasCurrent && !hasPast && !hasWarnings) {
     if (hasOpenTriages) {
       body = `<div class="flight-log-stack" role="list" aria-label="Reviews awaiting triage">${openTriageCards}</div>`;
@@ -5780,18 +5819,48 @@ function previousStageElapsedTitle(now) {
   return `Previous step elapsed ${formatElapsedPlain(row.elapsedMs)}`;
 }
 
-function flightLogFingerprint(fl) {
+/**
+ * Fingerprint Flight Log for SSE re-render. Accepts full dashboard `d` or a
+ * slim prev snapshot `{ flightLog, now, system }` so quiet-gate matches render.
+ */
+function flightLogFingerprint(d) {
+  if (!d || typeof d !== 'object') return '';
+  const fl = d.missionControl?.flightLog ?? d.flightLog ?? null;
   if (!fl || typeof fl !== 'object') return '';
-  const current = typeof fl.current === 'string' ? fl.current : '';
+  const current = resolveFlightLogCurrent(d) || '';
   const past = Array.isArray(fl.past)
-    ? fl.past.map((e) => (e && typeof e.text === 'string' ? e.text : '')).join('\n')
+    ? fl.past
+        .map((e) =>
+          typeof e === 'string' ? e : e && typeof e.text === 'string' ? e.text : '',
+        )
+        .join('\n')
     : '';
   const warnings = Array.isArray(fl.warnings)
-    ? fl.warnings.map((w) => (w && (w.id || w.text) ? String(w.id || w.text) : '')).join('\n')
-    : '';
-  const openTriages = Array.isArray(fl.quietOpenTriages)
-    ? fl.quietOpenTriages.map((i) => (i && (i.id || i.sourcePath) ? String(i.id || i.sourcePath) : '')).join('\n')
+    ? fl.warnings
+        .map((w) =>
+          typeof w === 'string'
+            ? w
+            : w && (w.id || w.text)
+              ? String(w.id || w.text)
+              : '',
+        )
+        .join('\n')
     : '';
+  // Quiet-only: include open-triage ids when Gaps + Warnings are empty so a new
+  // monitor does not flash the non-quiet Flight Log card with no visible change.
+  // Must use the same gate as renderAttentionPanel (Plan:none Gaps fallback).
+  const openTriages =
+    isFlightLogQuiet(d) && Array.isArray(fl.quietOpenTriages)
+      ? fl.quietOpenTriages
+          .map((i) =>
+            typeof i === 'string'
+              ? i
+              : i && (i.id || i.sourcePath)
+                ? String(i.id || i.sourcePath)
+                : '',
+          )
+          .join('\n')
+      : '';
   return `${current}\0${past}\0${warnings}\0${openTriages}`;
 }
 
@@ -6085,8 +6154,12 @@ function renderUnsafe() {
   const nowChanged = prevData && nowFingerprint(d.missionControl?.now) !== nowFingerprint(prevData.now);
   const attentionChanged =
     prevData &&
-    flightLogFingerprint(d.missionControl?.flightLog) !==
-      flightLogFingerprint(prevData.flightLog);
+    flightLogFingerprint(d) !==
+      flightLogFingerprint({
+        flightLog: prevData.flightLog,
+        now: prevData.now,
+        system: prevData.system,
+      });
   prevData = snapshotPrevData(d);
 
   dataLoading = false;

package/dashboard/lib/guards.mjs

@@ -29,6 +29,22 @@ export const DEFAULT_PORT_BASE = 3333;
  */
 export const DEFAULT_PORT_RANGE = 256;
 
+/**
+ * Escape a path/string for embedding in a Perl double-quoted literal.
+ * Scoped npm package paths contain `@` (e.g. `node_modules/@dadado/...`);
+ * unescaped `@name` is array interpolation in Perl and strips the scope segment,
+ * so macOS detach-start via `perl -e` cannot exec `dashboard/serve.mjs`.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapePerlDoubleQuoted(value) {
+  return String(value)
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, "\\$")
+    .replace(/@/g, "\\@");
+}
+
 /**
  * Resolve the repository root Mission Control should snapshot.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
@@ -141,7 +157,9 @@ export function sameRepoRoot(a, b) {
 export function resolveMissionControlPort({ repoRoot, envPort, probe, opts = {} }) {
   const root = resolve(String(repoRoot || "").trim() || ".");
   const raw =
-    envPort != null && String(envPort).trim() !== "" ? Number.parseInt(String(envPort), 10) : NaN;
+    envPort != null && String(envPort).trim() !== ""
+      ? Number.parseInt(String(envPort), 10)
+      : Number.NaN;
 
   if (Number.isFinite(raw) && raw > 0) {
     const info = probe(raw);

package/dashboard/lib/semantic-model.mjs

@@ -2,6 +2,10 @@
 // Pure Mission Control view-model helpers (testable; no fs/git I/O).
 
 import { truncateStr } from "./guards.mjs";
+import { TRIAGE_HEADING_RE, hasTriageHeading } from "./triage-heading.mjs";
+
+/** Durable triage heading SoT (shared with CLI `monitors --untriaged`). */
+export { TRIAGE_HEADING_RE, hasTriageHeading };
 
 export const MAX_ACTIVITY = 28;
 export const MAX_ATTENTION = 15;
@@ -62,15 +66,6 @@ export const MAX_CHECKLIST_NOTES = 15;
  * External review reports are `.cursor/memory/plan-monitor-<slug>.md`. */
 export const EXTERNAL_REPORT_FILE_RE = /^plan-monitor-(.+)\.md$/;
 
-/**
- * A heading the triage step leaves behind in the report itself. Confirmed
- * against the local reports: `## Triage note - residual (A) verified` and
- * `## Follow-up plan - hitl_ask_questions_residuals_2026_07_20.plan.md`.
- * `/plan-review-triage` must write one of these for every outcome, including
- * Ack and stop, so Field Report can clear the untriaged row.
- */
-export const TRIAGE_HEADING_RE = /^#{2,6}\s+.*\b(triage|follow-?up plan|residuals plan)\b/im;
-
 /**
  * Local Field Report dismissals store (IDs only). Valid attention ids that
  * `/field-report-resolve` may append: External reviews, agent prompts, and
@@ -576,21 +571,23 @@ export function buildFlightLogWarnings(handoff, opts = {}) {
 
 /**
  * Bounded untriaged external-review rows for Flight Log quiet state.
- * Filters attention to `kind === "report"` only (no cadence, prompts, readiness,
- * or bulk FR CTAs). Used when Gaps + Warnings are empty; callers must not mix
- * these rows into a non-quiet Gaps/Warnings stack.
- * @param {object[]|null|undefined} attention - buildAttentionItems output
+ * Filters to `kind === "report"` with a non-empty `sourcePath` (no cadence,
+ * prompts, readiness, or bulk FR CTAs). Prefer calling with
+ * `buildExternalReportItems(...)` output so the quiet lane is not starved by
+ * the shared `buildAttentionItems` cap. Callers must not mix these rows into a
+ * non-quiet Gaps/Warnings stack.
+ * @param {object[]|null|undefined} reportOrAttentionItems
  * @param {{ limit?: number }} [opts]
  * @returns {object[]}
  */
-export function listFlightLogQuietOpenTriages(attention, opts = {}) {
+export function listFlightLogQuietOpenTriages(reportOrAttentionItems, opts = {}) {
   const limit =
     typeof opts.limit === "number" && opts.limit > 0
       ? Math.floor(opts.limit)
       : FLIGHT_LOG_QUIET_OPEN_TRIAGES_CAP;
-  if (!Array.isArray(attention) || attention.length === 0) return [];
+  if (!Array.isArray(reportOrAttentionItems) || reportOrAttentionItems.length === 0) return [];
   const out = [];
-  for (const item of attention) {
+  for (const item of reportOrAttentionItems) {
     if (!item || item.kind !== "report") continue;
     if (typeof item.sourcePath !== "string" || !item.sourcePath.trim()) continue;
     out.push(item);
@@ -1369,26 +1366,33 @@ export function normalizeHandoffGaps(raw) {
 
 /**
  * Classify a Flight Log Gaps/Warning body for palette chrome.
+ * Runs heuristics on whitespace-collapsed text **before** display truncation so
+ * long Gaps whose only warning/prompt/advice keyword sits past MAX_SEMANTIC_LABEL
+ * still match the inline dashboard.html classifier (which does not truncate).
  * @param {string | null | undefined} text
  * @param {{ lane?: 'gaps' | 'warning' }} [opts]
  * @returns {FlightLogMessageKind}
  */
 export function classifyFlightLogMessageKind(text, opts = {}) {
   if (opts.lane === "warning") return "warning";
-  const normalized = typeof text === "string" ? normalizeHandoffGaps(text) : null;
-  if (normalized == null) return "ok";
+  if (!text || typeof text !== "string") return "ok";
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  if (!collapsed) return "ok";
+  if (/^(none|n\/a)$/i.test(collapsed)) return "ok";
+  if (/^(none|n\/a)\s*[.:,;\/(\-–—…]/i.test(collapsed)) return "ok";
+  if (/^([-–—.…]|empty|no gaps?|cleared|all clear|ok)$/i.test(collapsed)) return "ok";
   if (
-    /\bAPI\s*\/\s*usage\s+limit\b|\bAPI\s+usage\s+limit\b|\bSTOPPED:\s*API\b/i.test(normalized) ||
-    /\b(hard.?stop|quota\s+pause)\b/i.test(normalized)
+    /\bAPI\s*\/\s*usage\s+limit\b|\bAPI\s+usage\s+limit\b|\bSTOPPED:\s*API\b/i.test(collapsed) ||
+    /\b(hard.?stop|quota\s+pause)\b/i.test(collapsed)
   ) {
     return "warning";
   }
   if (
-    /\b(confirm|ask questions|hitl|\bpaste\b|choose\b|approve\b|operator yes)\b/i.test(normalized)
+    /\b(confirm|ask questions|hitl|\bpaste\b|choose\b|approve\b|operator yes)\b/i.test(collapsed)
   ) {
     return "prompt";
   }
-  if (/\b(tip:|advice:|consider\b|recommends?\b|recommended\b|prefer\b)/i.test(normalized)) {
+  if (/\b(tip:|advice:|consider\b|recommends?\b|recommended\b|prefer\b)/i.test(collapsed)) {
     return "advice";
   }
   return "residual";
@@ -3544,6 +3548,15 @@ export function buildMissionControlView({
   // Field Report attention inbox left the Flight Log card; builders stay
   // exported for /field-report-resolve + cadence scripts (ADR keep).
   // Quiet Gaps+Warnings: bounded report rows may surface on Flight Log.
+  // Build quiet lane from external reports directly (not capped attention) so
+  // prompt/readiness pressure cannot starve Reviews awaiting triage to All clear.
+  const dismissedForQuiet = new Set(
+    (dismissedIds || []).filter((id) => typeof id === "string" && id.length > 0),
+  );
+  const quietReportItems = buildExternalReportItems(externalReports, plans, {
+    handoff,
+    archivedPlanFiles,
+  }).filter((item) => item && !dismissedForQuiet.has(item.id));
   const attention = buildAttentionItems({
     plans,
     handoff,
@@ -3556,7 +3569,7 @@ export function buildMissionControlView({
     cadenceLedger,
     cadenceConfig,
   });
-  flightLog.quietOpenTriages = listFlightLogQuietOpenTriages(attention);
+  flightLog.quietOpenTriages = listFlightLogQuietOpenTriages(quietReportItems);
   // Deprecated: attention owns Field Report rows. Kept empty so older panel
   // code that still reads the field does not double-render.
   const checklistNotes = [];
@@ -3571,6 +3584,8 @@ export function buildMissionControlView({
     plans: classifiedPlans,
     // Crew Monitor hero display cap (SoT for dashboard.html; no HTML literal).
     monitorFeedCap: MONITOR_FEED_CAP,
+    // Quiet open-triage fallback cap for dashboard.html attention mirror.
+    flightLogQuietOpenTriagesCap: FLIGHT_LOG_QUIET_OPEN_TRIAGES_CAP,
     // /run-plan-all queue slice (null outside queue mode). Copy-only data:
     // display order and roles; the panel never writes the queue back.
     runQueue: buildRunQueueView(handoff),

package/dashboard/lib/triage-heading.mjs

@@ -0,0 +1,20 @@
+/**
+ * Durable triage headings written by `/plan-review-triage` (L0).
+ *
+ * Shared SoT for Mission Control (`isReportTriaged`) and
+ * `agent-kit monitors --untriaged`. Match ONLY these heading titles, not tick
+ * headings that merely name a `triage-*` to-do id (hyphens are word boundaries,
+ * so `\btriage\b` falsely matched those).
+ *
+ * Allowed forms (case-insensitive; optional suffix after the title):
+ *   ## Triage note
+ *   ## 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;
+
+/** True when markdown carries a durable triage heading. */
+export function hasTriageHeading(text) {
+  return TRIAGE_HEADING_RE.test(String(text ?? ""));
+}

package/dashboard/start-broadcast.mjs

@@ -7,13 +7,14 @@
  * prints LAN URL(s) with token. Does not weaken loopback `/dashboard`.
  */
 
-import { spawn, execFileSync, execSync } from "node:child_process";
+import { execFileSync, execSync, spawn } from "node:child_process";
 import { existsSync, openSync } from "node:fs";
+import { platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { platform } from "node:os";
 import {
   BROADCAST_TOKEN_ENV,
+  escapePerlDoubleQuoted,
   generateBroadcastToken,
   isLoopbackBindHost,
   isValidBroadcastToken,
@@ -26,7 +27,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const SERVE = join(__dirname, "serve.mjs");
 const LOG = process.env.MISSION_CONTROL_LOG || "/tmp/mission-control-broadcast.log";
-const PORT = parseInt(process.env.PORT || "3333", 10);
+const PORT = Number.parseInt(process.env.PORT || "3333", 10);
 const READY_TIMEOUT_MS = 20_000;
 const READY_POLL_MS = 250;
 
@@ -57,11 +58,10 @@ function urlsForProbe(token) {
 
 function probeHttp(url) {
   try {
-    const code = execFileSync(
-      "curl",
-      ["-sf", "-o", "/dev/null", "-w", "%{http_code}", url],
-      { encoding: "utf8", timeout: 3000 },
-    ).trim();
+    const code = execFileSync("curl", ["-sf", "-o", "/dev/null", "-w", "%{http_code}", url], {
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
     return code === "200";
   } catch {
     return false;
@@ -70,11 +70,10 @@ function probeHttp(url) {
 
 function listeningPids() {
   try {
-    const out = execFileSync(
-      "lsof",
-      ["-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN", "-t"],
-      { encoding: "utf8", timeout: 3000 },
-    ).trim();
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
     return out ? out.split(/\n+/).filter(Boolean) : [];
   } catch {
     return [];
@@ -107,12 +106,13 @@ function detachStart(env) {
     return;
   }
 
-  const rootEsc = ROOT.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const serveEsc = SERVE.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const logEsc = LOG.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const hostEsc = String(env.HOST).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const tokenEsc = String(env[BROADCAST_TOKEN_ENV]).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const portEsc = String(PORT);
+  // Escape @/$ so scoped package paths (node_modules/@scope/...) survive Perl qq.
+  const rootEsc = escapePerlDoubleQuoted(ROOT);
+  const serveEsc = escapePerlDoubleQuoted(SERVE);
+  const logEsc = escapePerlDoubleQuoted(LOG);
+  const hostEsc = escapePerlDoubleQuoted(String(env.HOST));
+  const tokenEsc = escapePerlDoubleQuoted(String(env[BROADCAST_TOKEN_ENV]));
+  const portEsc = escapePerlDoubleQuoted(String(PORT));
   const perl = [
     "use POSIX qw(setsid);",
     "exit if fork;",
@@ -169,7 +169,9 @@ function openBrowser(url) {
 async function main() {
   const { env, host, token } = resolveBroadcastEnv();
   if (isLoopbackBindHost(host)) {
-    console.error("Broadcast refused: bind host resolved to loopback. Set HOST to a non-loopback address.");
+    console.error(
+      "Broadcast refused: bind host resolved to loopback. Set HOST to a non-loopback address.",
+    );
     process.exit(1);
   }
 
@@ -193,9 +195,7 @@ async function main() {
     detachStart(env);
     const ready = await waitReady(urls);
     if (!ready) {
-      console.error(
-        `Mission Control broadcast did not answer within ${READY_TIMEOUT_MS}ms.`,
-      );
+      console.error(`Mission Control broadcast did not answer within ${READY_TIMEOUT_MS}ms.`);
       console.error(`Check the log: ${LOG}`);
       process.exit(1);
     }

package/dashboard/start.mjs

@@ -15,17 +15,18 @@
  * Foreground serve for debugging remains: `npm run start:dashboard`.
  */
 
-import { spawn, execFileSync, execSync } from "node:child_process";
+import { execFileSync, execSync, spawn } from "node:child_process";
 import { existsSync, openSync } from "node:fs";
+import { platform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { platform } from "node:os";
 import {
   REPO_ROOT_ENV,
-  resolveSnapshotRepoRoot,
+  escapePerlDoubleQuoted,
+  repoRootLogId,
   resolveMissionControlPort,
+  resolveSnapshotRepoRoot,
   sameRepoRoot,
-  repoRootLogId,
 } from "./lib/guards.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -50,18 +51,15 @@ function setPort(port) {
   PORT = port;
   URL = `http://${DISPLAY_HOST}:${PORT}/`;
   DATA_URL = `http://${DISPLAY_HOST}:${PORT}/dashboard-data.json`;
-  LOG =
-    process.env.MISSION_CONTROL_LOG ||
-    `/tmp/mission-control-${repoRootLogId(ROOT)}.log`;
+  LOG = process.env.MISSION_CONTROL_LOG || `/tmp/mission-control-${repoRootLogId(ROOT)}.log`;
 }
 
 function probeHttp(url = URL) {
   try {
-    const code = execFileSync(
-      "curl",
-      ["-sf", "-o", "/dev/null", "-w", "%{http_code}", url],
-      { encoding: "utf8", timeout: 3000 },
-    ).trim();
+    const code = execFileSync("curl", ["-sf", "-o", "/dev/null", "-w", "%{http_code}", url], {
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
     return code === "200";
   } catch {
     return false;
@@ -70,11 +68,10 @@ function probeHttp(url = URL) {
 
 function listeningPids(port = PORT) {
   try {
-    const out = execFileSync(
-      "lsof",
-      ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"],
-      { encoding: "utf8", timeout: 3000 },
-    ).trim();
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
     return out ? out.split(/\n+/).filter(Boolean) : [];
   } catch {
     return [];
@@ -153,11 +150,12 @@ function detachStart() {
   }
 
   // macOS and other hosts without setsid: Perl double-fork + setsid().
-  const rootEsc = KIT_ROOT.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const serveEsc = SERVE.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const logEsc = LOG.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  const portEsc = String(PORT);
-  const snapEsc = ROOT.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  // Escape @/$ so scoped package paths (node_modules/@scope/...) survive Perl qq.
+  const rootEsc = escapePerlDoubleQuoted(KIT_ROOT);
+  const serveEsc = escapePerlDoubleQuoted(SERVE);
+  const logEsc = escapePerlDoubleQuoted(LOG);
+  const portEsc = escapePerlDoubleQuoted(String(PORT));
+  const snapEsc = escapePerlDoubleQuoted(ROOT);
   const perl = [
     "use POSIX qw(setsid);",
     "exit if fork;",
@@ -258,9 +256,7 @@ async function ensureServer() {
   detachStart();
   const ready = await waitReady();
   if (!ready) {
-    console.error(
-      `Mission Control did not answer ${URL} within ${READY_TIMEOUT_MS}ms.`,
-    );
+    console.error(`Mission Control did not answer ${URL} within ${READY_TIMEOUT_MS}ms.`);
     console.error(`Check the log: ${LOG}`);
     process.exit(1);
   }
@@ -280,9 +276,7 @@ async function main() {
       "Opened in the default browser. In Cursor, Simple Browser or /dashboard also works.",
     );
   } else {
-    console.log(
-      "Open that URL in a browser (Cursor: Simple Browser, or run /dashboard in chat).",
-    );
+    console.log("Open that URL in a browser (Cursor: Simple Browser, or run /dashboard in chat).");
   }
 }
 

package/dist/index.js

@@ -1767,8 +1767,11 @@ import path22 from "path";
 import { defineCommand as defineCommand6 } from "citty";
 
 // src/invariants/hooks-health.ts
-import { access as access4, readFile as readFile6 } from "fs/promises";
+import { execFile as execFile2 } from "child_process";
+import { constants as constants2, access as access4, readFile as readFile6, stat } from "fs/promises";
 import path12 from "path";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 var EXPECTED_EVENTS = [
   "sessionStart",
   "preCompact",
@@ -1784,6 +1787,37 @@ async function exists(p) {
     return false;
   }
 }
+async function isExecutable(p) {
+  try {
+    await access4(p, constants2.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveAgentKitCli(rootDir) {
+  const root = path12.resolve(rootDir);
+  const candidates = [
+    path12.join(root, "node_modules", ".bin", "agent-kit"),
+    path12.join(root, "packages", "cli", "dist", "index.js")
+  ];
+  for (const c of candidates) {
+    if (await exists(c)) return c;
+  }
+  try {
+    const { stdout } = await execFileAsync2("which", ["agent-kit"], { encoding: "utf8" });
+    const hit = stdout.trim().split("\n")[0]?.trim();
+    if (hit) return hit;
+  } catch {
+  }
+  return null;
+}
+function commandLooksLikeAdapter(command) {
+  const trimmed = command.trim();
+  if (!trimmed) return null;
+  const m = trimmed.match(/(\.cursor\/hooks\/agent\/[A-Za-z0-9._-]+\.sh)\b/);
+  return m?.[1] ?? null;
+}
 async function assessHooksHealth(rootDir) {
   const root = path12.resolve(rootDir);
   const hooksJsonPath = ".cursor/hooks.json";
@@ -1812,6 +1846,7 @@ async function assessHooksHealth(rootDir) {
     };
   }
   const hooks = parsed.hooks ?? {};
+  const adapterRels = /* @__PURE__ */ new Set();
   for (const event of EXPECTED_EVENTS) {
     const list = hooks[event];
     if (Array.isArray(list) && list.length > 0) {
@@ -1822,6 +1857,8 @@ async function assessHooksHealth(rootDir) {
         if (command.endsWith(".py") || command.includes("python")) {
           reasons.push(`${event} still points at a Python script (${command})`);
         }
+        const rel = commandLooksLikeAdapter(command);
+        if (rel) adapterRels.add(rel);
       }
     } else {
       reasons.push(`missing hook event: ${event}`);
@@ -1830,6 +1867,34 @@ async function assessHooksHealth(rootDir) {
   const resolveLib = path12.join(root, ".cursor", "hooks", "agent", "resolve-agent-kit.sh");
   if (!await exists(resolveLib)) {
     reasons.push("missing `.cursor/hooks/agent/resolve-agent-kit.sh` (thin adapter resolver)");
+  } else if (!await isExecutable(resolveLib)) {
+    reasons.push("`.cursor/hooks/agent/resolve-agent-kit.sh` is not executable (chmod +x)");
+  }
+  for (const rel of adapterRels) {
+    const abs = path12.join(root, rel);
+    if (!await exists(abs)) {
+      reasons.push(`missing adapter script: \`${rel}\``);
+      continue;
+    }
+    try {
+      const st = await stat(abs);
+      if (!st.isFile()) {
+        reasons.push(`adapter path is not a file: \`${rel}\``);
+        continue;
+      }
+    } catch {
+      reasons.push(`unreadable adapter script: \`${rel}\``);
+      continue;
+    }
+    if (!await isExecutable(abs)) {
+      reasons.push(`adapter not executable: \`${rel}\` (chmod +x)`);
+    }
+  }
+  const cli = await resolveAgentKitCli(root);
+  if (!cli) {
+    reasons.push(
+      "agent-kit CLI not resolvable (PATH, node_modules/.bin/agent-kit, or packages/cli/dist)"
+    );
   }
   if (Array.isArray(hooks.stop) && hooks.stop.length > 0) {
     reasons.push("`stop` hook is registered (forbidden; remove it)");
@@ -2240,10 +2305,10 @@ async function detectSafety(rootDir, trackedFiles) {
 import path19 from "path";
 
 // src/scanner/detect-git.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import path14 from "path";
-import { promisify as promisify2 } from "util";
-var exec = promisify2(execFile2);
+import { promisify as promisify3 } from "util";
+var exec = promisify3(execFile3);
 function remoteHostname(remoteUrl) {
   const scpMatch = remoteUrl.match(/^[^@]+@([^:]+):/);
   if (scpMatch?.[1]) return scpMatch[1].toLowerCase();
@@ -3034,6 +3099,8 @@ var doctorCommand = defineCommand6({
 });
 
 // src/commands/guard.ts
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
 import { defineCommand as defineCommand7 } from "citty";
 
 // src/hooks/read-stdin-json.ts
@@ -3075,10 +3142,21 @@ var SECRET_PATTERNS2 = [
     re: /\bsk-[A-Za-z0-9]{20,}\b/
   }
 ];
+function maskSecretExcerpt(raw) {
+  return raw.replace(/\b(ghp_|sk-|AKIA)([A-Za-z0-9_]{4,})/g, (_m, p1, p2) => {
+    return `${p1}${"*".repeat(Math.min(8, p2.length))}`;
+  }).replace(
+    /(=\s*['"]?)([^\s'"]{4,})/g,
+    (_m, p1, p2) => `${p1}${"*".repeat(Math.min(8, p2.length))}`
+  ).replace(
+    /("(?:password|apiKey|api_key|secret|token|auth)"\s*:\s*")([^"]{4,})(")/gi,
+    (_m, p1, p2, p3) => `${p1}${"*".repeat(Math.min(8, p2.length))}${p3}`
+  );
+}
 function excerptAround(text, index, len) {
   const start = Math.max(0, index - 8);
   const end = Math.min(text.length, index + len + 8);
-  return text.slice(start, end).replace(/\s+/g, " ");
+  return maskSecretExcerpt(text.slice(start, end).replace(/\s+/g, " "));
 }
 function scanTextForSecrets(text) {
   if (!text) return [];
@@ -3105,6 +3183,7 @@ function secretsAdviseMessage(hits) {
 
 // src/invariants/shell-guard.ts
 var CITE2 = "agent-kit guard shell (ADR 2026-07-29_cli-invariants-thin-hook-adapters)";
+var PROTECTED_BRANCH_RE = /^(?:main|master|prod)$/;
 function normalizeShellCommand(command) {
   return command.replace(/\s+/g, " ").trim();
 }
@@ -3116,11 +3195,61 @@ function shellInvocationHeads(command) {
 function anyHeadMatches(command, re) {
   return shellInvocationHeads(command).some((head) => re.test(head));
 }
+function isProtectedBranch(name) {
+  return typeof name === "string" && PROTECTED_BRANCH_RE.test(name.trim());
+}
+function normalizePushRefspecToken(token) {
+  let t = token.trim();
+  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2 || t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+    t = t.slice(1, -1).trim();
+  }
+  if (t.startsWith("+")) t = t.slice(1);
+  if (t.startsWith("refs/heads/")) t = t.slice("refs/heads/".length);
+  if (t.startsWith("origin/")) t = t.slice("origin/".length);
+  return t;
+}
+function pushHeadHasProtectedDest(head) {
+  if (/HEAD:(?:refs\/heads\/)?(?:main|master|prod)\b/.test(head)) return true;
+  if (/(?:^|\s)-(?:u|--set-upstream)\s+\S+\s+(?:main|master|prod)(?:\s|$)/.test(head)) {
+    return true;
+  }
+  const after = head.replace(/^(?:[\w./-]+\/)?git\s+push\b/, "");
+  for (const raw of after.split(/\s+/).filter(Boolean)) {
+    if (raw.startsWith("-")) continue;
+    const dest = raw.includes(":") ? raw.slice(raw.lastIndexOf(":") + 1) : raw;
+    if (PROTECTED_BRANCH_RE.test(normalizePushRefspecToken(dest))) return true;
+  }
+  return false;
+}
+function isBareOrHeadPushToCurrent(head) {
+  if (!/^(?:[\w./-]+\/)?git\s+push\b/.test(head)) return false;
+  if (pushHeadHasProtectedDest(head)) {
+    return false;
+  }
+  if (/(?:^|\s)\+?(?:refs\/heads\/)?(?:origin\/)?(?:staging|develop|homologacao)(?:\s|$|:)/.test(
+    head
+  ) || /HEAD:(?:refs\/heads\/)?(?!main|master|prod)[A-Za-z0-9._/-]+/.test(head)) {
+    return false;
+  }
+  const after = head.replace(/^(?:[\w./-]+\/)?git\s+push\b/, "").trim();
+  const withoutFlags = after.replace(/(?:^|\s)(?:--force|-f|-u|--set-upstream|--tags|--all|--prune)(?=\s|$)/g, " ").replace(/(?:^|\s)--\w[\w-]*(?:=\S+)?/g, " ").replace(/\s+/g, " ").trim();
+  if (!withoutFlags) return true;
+  const tokens = withoutFlags.split(/\s+/);
+  if (tokens.length === 1) return true;
+  if (tokens.length >= 2 && tokens[1] === "HEAD") return true;
+  if (/\bHEAD\b/.test(withoutFlags) && !/HEAD:/.test(withoutFlags)) return true;
+  return false;
+}
 var SHELL_DENY_RULES = [
   {
     id: "git-checkout-path",
-    description: "git checkout -- <paths> discards working-tree edits",
-    test: (cmd) => anyHeadMatches(cmd, /^(?:[\w./-]+\/)?git\s+checkout\s+--(?:\s|$)/)
+    description: "git checkout -- / HEAD -- / . discards working-tree edits",
+    test: (cmd) => shellInvocationHeads(cmd).some((head) => {
+      if (!/^(?:[\w./-]+\/)?git\s+checkout\b/.test(head)) return false;
+      if (/\s--(?:\s|$)/.test(head)) return true;
+      if (/\scheckout\s+\.(?:\s|$)/.test(head)) return true;
+      return false;
+    })
   },
   {
     id: "git-restore",
@@ -3142,19 +3271,25 @@ var SHELL_DENY_RULES = [
   {
     id: "git-push-main",
     description: "direct push to main/master/prod bypasses staging",
-    test: (cmd) => shellInvocationHeads(cmd).some((head) => {
+    test: (cmd, opts) => shellInvocationHeads(cmd).some((head) => {
       if (!/^(?:[\w./-]+\/)?git\s+push\b/.test(head)) return false;
-      return /(?:^|\s)(?:origin\/)?(?:main|master|prod)(?:\s|$|:)/.test(head) || /HEAD:(?:refs\/heads\/)?(?:main|master|prod)\b/.test(head) || /(?:^|\s)-(?:u|--set-upstream)\s+\S+\s+(?:main|master|prod)(?:\s|$)/.test(head);
+      if (pushHeadHasProtectedDest(head)) {
+        return true;
+      }
+      if (isProtectedBranch(opts?.currentBranch) && isBareOrHeadPushToCurrent(head)) {
+        return true;
+      }
+      return false;
     })
   }
 ];
-function evaluateShellCommand(command) {
+function evaluateShellCommand(command, opts = {}) {
   const normalized = normalizeShellCommand(command);
   if (!normalized) {
     return { permission: "allow" };
   }
   for (const rule of SHELL_DENY_RULES) {
-    if (rule.test(normalized)) {
+    if (rule.test(normalized, opts)) {
       const agent_message = `Denied by ${CITE2}: ${rule.description} (rule \`${rule.id}\`). Use /git-staging; never discard human hunks or push protected branches from the agent.`;
       return {
         permission: "deny",
@@ -3168,6 +3303,18 @@ function evaluateShellCommand(command) {
 }
 
 // src/commands/guard.ts
+var execFileAsync3 = promisify4(execFile4);
+async function detectCurrentBranch() {
+  try {
+    const { stdout } = await execFileAsync3("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf8"
+    });
+    const branch = stdout.trim();
+    return branch && branch !== "HEAD" ? branch : void 0;
+  } catch {
+    return void 0;
+  }
+}
 var guardCommand = defineCommand7({
   meta: {
     name: "guard",
@@ -3196,7 +3343,8 @@ var guardCommand = defineCommand7({
           const payload = await readStdinJson();
           command = typeof payload.command === "string" ? payload.command : "";
         }
-        const result = evaluateShellCommand(command);
+        const currentBranch = await detectCurrentBranch();
+        const result = evaluateShellCommand(command, { currentBranch });
         console.log(JSON.stringify(result));
       }
     }),
@@ -3224,7 +3372,7 @@ var guardCommand = defineCommand7({
             continue: true,
             user_message: secretsAdviseMessage(hits),
             agent_message: secretsAdviseMessage(hits),
-            hits
+            hits: hits.map((h) => ({ patternId: h.patternId }))
           })
         );
       }
@@ -4299,12 +4447,16 @@ import path30 from "path";
 import { defineCommand as defineCommand12 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
-import { execFile as execFile3 } from "child_process";
-import { readFile as readFile14, readdir as readdir3, stat } from "fs/promises";
+import { execFile as execFile5 } from "child_process";
+import { readFile as readFile14, readdir as readdir3, stat as stat2 } from "fs/promises";
 import path29 from "path";
-import { promisify as promisify3 } from "util";
-var execFileAsync2 = promisify3(execFile3);
-var TRIAGE_HEADING_RE = /^#{2,6}\s+.*\b(triage|follow-?up plan|residuals plan)\b/im;
+import { promisify as promisify5 } from "util";
+
+// src/invariants/triage-heading.ts
+var TRIAGE_HEADING_RE = /^#{2,6}\s+(?:Triage note|Follow-?up plan|Residuals plan)\b/im;
+
+// src/invariants/monitors-untriaged.ts
+var execFileAsync4 = promisify5(execFile5);
 var CITE4 = "agent-kit monitors --untriaged (ADR 2026-07-27_plan-review-triage-untriaged-not-mtime; never newest-mtime-wins)";
 function hasOpenGaps(content) {
   if (/###\s+Still open[^\n]*\n+(?:\s*\n)*(?:None\.|none\.|\*None\*)/i.test(content)) {
@@ -4330,7 +4482,7 @@ async function listMonitorFiles(memoryDir) {
 async function gitFreshMonitorNames(rootDir) {
   const names = /* @__PURE__ */ new Set();
   try {
-    const { stdout } = await execFileAsync2(
+    const { stdout } = await execFileAsync4(
       "git",
       ["status", "--porcelain", "--", ".cursor/memory"],
       { cwd: rootDir, maxBuffer: 2 * 1024 * 1024 }
@@ -4369,7 +4521,7 @@ async function selectUntriagedMonitors(rootDir) {
   for (const name of allNames) {
     const abs = path29.join(memoryDir, name);
     try {
-      const [content, st] = await Promise.all([readFile14(abs, "utf8"), stat(abs)]);
+      const [content, st] = await Promise.all([readFile14(abs, "utf8"), stat2(abs)]);
       byName.set(name, { content, mtimeMs: st.mtimeMs });
     } catch {
     }
@@ -5176,10 +5328,10 @@ var statusCommand = defineCommand15({
 import { defineCommand as defineCommand16 } from "citty";
 
 // src/lifecycle/check-updates.ts
-import { execFile as execFile4 } from "child_process";
+import { execFile as execFile6 } from "child_process";
 import path37 from "path";
-import { promisify as promisify4 } from "util";
-var execFileAsync3 = promisify4(execFile4);
+import { promisify as promisify6 } from "util";
+var execFileAsync5 = promisify6(execFile6);
 var SEMVER_CORE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i;
 var FACTORY_URL_MARKERS = ["agent-kit-dev"];
 var FACTORY_REFS = /* @__PURE__ */ new Set(["staging", "homologacao", "develop", "dev"]);
@@ -5238,7 +5390,7 @@ function pickLatestSemverTag(lsRemoteStdout) {
 }
 async function fetchLatestPublicVersion(registryUrl = DEFAULT_REGISTRY_URL) {
   assertSafeRegistrySource(registryUrl, "main");
-  const { stdout } = await execFileAsync3("git", ["ls-remote", "--tags", "--", registryUrl], {
+  const { stdout } = await execFileAsync5("git", ["ls-remote", "--tags", "--", registryUrl], {
     env: gitEnv2(),
     timeout: 2e4
   });

package/package.json

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