@dadado/agent-kit-cli 5.15.1 → 5.17.0

package/dist/hook-DYIMKJYL.js

@@ -0,0 +1,1074 @@
+import {
+  validateHandoffText
+} from "./chunk-2YU2H7I6.js";
+import {
+  readStdinJson
+} from "./chunk-DE3LQFSJ.js";
+import {
+  CHANGELOG_FETCH_TIMEOUT_MS,
+  resolveInventoryRoot,
+  stampCursorUpdateCheck
+} from "./chunk-CBCW5R5J.js";
+import {
+  shouldEmitPublicInboundNudge,
+  stampPublicInboundCheck
+} from "./chunk-2IPXQFJE.js";
+import {
+  formatPlanIndexSection,
+  writePlanIndex
+} from "./chunk-KD2MYBB6.js";
+import {
+  READINESS_SNAPSHOT_RELATIVE_PATH
+} from "./chunk-ZXKZBTXE.js";
+import {
+  stampLastCheckedAt
+} from "./chunk-SMGFN3Z4.js";
+import {
+  loadContextConfig
+} from "./chunk-NQ7IQ5XT.js";
+import "./chunk-2RDRMGD3.js";
+import "./chunk-N3HTJVBR.js";
+import {
+  MANIFEST_RELATIVE_PATH
+} from "./chunk-AW74INUW.js";
+import {
+  HANDOFF_REL
+} from "./chunk-5VCOWTTP.js";
+import "./chunk-7HDQEK6T.js";
+import {
+  fileExists
+} from "./chunk-77V75A7O.js";
+
+// src/commands/hook.ts
+import path2 from "path";
+import { defineCommand } from "citty";
+
+// src/hooks/format-session-start.ts
+function resolveSessionStartFormat(value) {
+  return value === "claude" ? "claude" : "cursor";
+}
+function formatSessionStartOutput(additionalContext, format) {
+  if (format === "claude") return additionalContext;
+  return JSON.stringify({ additional_context: additionalContext });
+}
+var SESSION_START_DEGRADED_MESSAGE = "Agent Kit session-start context is unavailable this session (internal error, fail-open mode). Nothing else is affected; retry next session.";
+
+// src/hooks/pre-compact.ts
+var CONTEXT_USAGE_CAP_PERCENT = 50;
+function buildPreCompactUserMessage(payload = {}) {
+  const pct = payload.context_usage_percent;
+  const trigger = payload.trigger || "auto";
+  const pctTxt = pct !== void 0 && pct !== null ? `~${pct}%` : "high";
+  const overCap = pct === void 0 || pct === null || pct >= CONTEXT_USAGE_CAP_PERCENT;
+  const msg = overCap ? `Context compacting (${trigger}, usage ${pctTxt}) \u2014 over the ${CONTEXT_USAGE_CAP_PERCENT}% per-agent context-usage cap. Update \`.cursor/HANDOFF.md\` now (forced checkpoint) and open a new chat with \`/continue-plan\` so the next agent starts fresh.` : `Context compacting (${trigger}, usage ${pctTxt}). Update \`.cursor/HANDOFF.md\` and open a new chat with \`/continue-plan\` so the next agent starts fresh.`;
+  return { user_message: msg };
+}
+
+// src/hooks/session-start.ts
+import { spawn } from "child_process";
+import { readFile, stat } from "fs/promises";
+import path from "path";
+
+// src/hooks/handoff-excerpt.ts
+var HANDOFF_EXCERPT_MAX_LINES = 60;
+var HANDOFF_EXCERPT_MAX_BYTES = 12 * 1024;
+var HANDOFF_PROSE_LINE_MIN_BYTES = 160;
+var HANDOFF_MACHINE_FIELDS = /* @__PURE__ */ new Set([
+  "Plan",
+  "Last updated",
+  "Mode",
+  "In progress",
+  "Next",
+  "Next phase",
+  "Next to-dos",
+  "Backlog",
+  "Backlog plans",
+  "Parked plans",
+  "Run queue",
+  "Queue cursor",
+  "Queue status",
+  "Queue outcomes"
+]);
+var FIELD_BULLET = /^- \*\*([^*\n]+?):\*\*/;
+function byteLength(s) {
+  return Buffer.byteLength(s, "utf8");
+}
+function classify(lines) {
+  const entries = [];
+  let lastBullet = "structural";
+  for (const text of lines) {
+    let kind;
+    if (!text.trim() || /^#{1,6}\s/.test(text)) {
+      kind = "structural";
+    } else if (/^\s+\S/.test(text)) {
+      kind = lastBullet;
+    } else {
+      const m = FIELD_BULLET.exec(text);
+      kind = m?.[1] && HANDOFF_MACHINE_FIELDS.has(m[1].trim()) ? "machine" : "prose";
+      lastBullet = kind;
+    }
+    entries.push({ text, kind, bytes: byteLength(text) });
+  }
+  return entries;
+}
+function selectByFieldPriority(entries, maxLines) {
+  if (entries.length <= maxLines) return entries;
+  const mustKeep = /* @__PURE__ */ new Set();
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (!e) continue;
+    if (e.kind === "machine") mustKeep.add(i);
+  }
+  if (entries[0] && /^#\s/.test(entries[0].text)) mustKeep.add(0);
+  const selected = new Set(mustKeep);
+  for (let i = 0; i < entries.length && selected.size < maxLines; i++) {
+    selected.add(i);
+  }
+  if (mustKeep.size > maxLines) {
+    const ordered = [...mustKeep].sort((a, b) => a - b).slice(0, maxLines);
+    return ordered.flatMap((i) => {
+      const e = entries[i];
+      return e ? [e] : [];
+    });
+  }
+  return [...selected].sort((a, b) => a - b).flatMap((i) => {
+    const e = entries[i];
+    return e ? [e] : [];
+  });
+}
+function truncateToBytes(text, maxBytes) {
+  let used = 0;
+  let kept = "";
+  let keptChars = 0;
+  const total = Array.from(text).length;
+  for (const ch of text) {
+    const b = byteLength(ch);
+    if (used + b > maxBytes) break;
+    used += b;
+    kept += ch;
+    keptChars += 1;
+  }
+  return { kept: kept.trimEnd(), removedChars: total - keptChars };
+}
+var MARKER_RESERVE_BYTES = 32;
+function truncationMarker(removedChars) {
+  return ` \u2026[truncated ${removedChars} chars]`;
+}
+function jsonValue(text) {
+  const head = (FIELD_BULLET.exec(text) ?? /^\s*(?:[-*]\s+)?/.exec(text))?.[0] ?? "";
+  const value = text.slice(head.length).trimStart();
+  if (!value.startsWith("{") && !value.startsWith("[")) return null;
+  if (/^\[[ xX]\](\s|$)|^\[[^\]\n]*\]\(/.test(value)) return null;
+  return { prefix: head.trimEnd(), value };
+}
+function countJsonEntries(value) {
+  let depth = 0;
+  let entries = 0;
+  let inString = false;
+  let seenValue = false;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i] ?? "";
+    if (inString) {
+      if (ch === "\\") i += 1;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      depth += 1;
+      if (depth === 1) continue;
+    } else if (ch === "}" || ch === "]") {
+      depth -= 1;
+      if (depth === 0) break;
+    } else if (ch === "," && depth === 1) {
+      entries += 1;
+      seenValue = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    if (depth >= 1 && ch.trim()) seenValue = true;
+  }
+  return entries + (seenValue ? 1 : 0);
+}
+function jsonMarker(entries) {
+  return `(JSON, ${entries} ${entries === 1 ? "entry" : "entries"}; read HANDOFF)`;
+}
+function capMachineLines(items, maxBytes, floor, join) {
+  const out = [...items];
+  const touched = /* @__PURE__ */ new Set();
+  let over = byteLength(join(out)) - maxBytes;
+  while (over > 0) {
+    let idx = -1;
+    for (let i = 0; i < out.length; i++) {
+      const e2 = out[i];
+      if (e2?.kind === "machine" && (idx < 0 || e2.bytes > (out[idx]?.bytes ?? 0))) idx = i;
+    }
+    const e = out[idx];
+    if (!e || e.bytes <= floor) break;
+    const target = Math.max(floor, e.bytes - over);
+    const { kept, removedChars } = truncateToBytes(e.text, target - MARKER_RESERVE_BYTES);
+    const text = kept + truncationMarker(removedChars);
+    const bytes = byteLength(text);
+    if (bytes >= e.bytes) break;
+    out[idx] = { text, kind: e.kind, bytes };
+    touched.add(idx);
+    over = byteLength(join(out)) - maxBytes;
+  }
+  return { items: out, machineTruncated: touched.size };
+}
+function droppedMarker(dropped) {
+  return `\u2026[${dropped} prose ${dropped === 1 ? "line" : "lines"} omitted by the excerpt byte cap; read .cursor/HANDOFF.md]`;
+}
+function proseShare(proseBytes, budget, floor) {
+  const n = proseBytes.length;
+  if (n === 0) return budget;
+  let share = Math.floor(budget / n);
+  for (let i = 0; i < 8; i++) {
+    const longer = proseBytes.filter((b) => b > share);
+    if (longer.length === 0) break;
+    const used = proseBytes.reduce((sum, b) => sum + Math.min(b, share), 0);
+    const slack = budget - used;
+    const step = Math.floor(slack / longer.length);
+    if (step <= 0) break;
+    share += step;
+  }
+  return Math.max(floor, share);
+}
+function capHandoffExcerpt(content, options = {}) {
+  const maxLines = options.maxLines ?? HANDOFF_EXCERPT_MAX_LINES;
+  const maxBytes = options.maxBytes ?? HANDOFF_EXCERPT_MAX_BYTES;
+  const floor = options.proseLineMinBytes ?? HANDOFF_PROSE_LINE_MIN_BYTES;
+  const allEntries = classify(content.split(/\r?\n/));
+  const entries = selectByFieldPriority(allEntries, maxLines);
+  const join = (items) => items.map((e) => e.text).join("\n").trim();
+  const untouched = join(entries);
+  const untouchedBytes = byteLength(untouched);
+  if (untouchedBytes <= maxBytes) {
+    return {
+      text: untouched,
+      bytes: untouchedBytes,
+      lines: entries.length,
+      truncatedLines: 0,
+      droppedLines: 0,
+      machineTruncated: 0
+    };
+  }
+  const fixedBytes = entries.reduce((sum, e) => sum + (e.kind === "prose" ? 0 : e.bytes) + 1, 0);
+  const proseBudget = Math.max(0, maxBytes - fixedBytes);
+  const share = proseShare(
+    entries.filter((e) => e.kind === "prose").map((e) => e.bytes),
+    proseBudget,
+    floor
+  );
+  let truncatedLines = 0;
+  const shaped = entries.map((e) => {
+    if (e.kind !== "prose" || e.bytes <= share) return e;
+    const json = jsonValue(e.text);
+    if (json) {
+      const marker = jsonMarker(countJsonEntries(json.value));
+      const text3 = json.prefix ? `${json.prefix} ${marker}` : marker;
+      truncatedLines += 1;
+      return { text: text3, kind: e.kind, bytes: byteLength(text3) };
+    }
+    const { kept, removedChars } = truncateToBytes(e.text, share - MARKER_RESERVE_BYTES);
+    const text2 = kept + truncationMarker(removedChars);
+    truncatedLines += 1;
+    return { text: text2, kind: e.kind, bytes: byteLength(text2) };
+  });
+  let total = shaped.reduce((sum, e) => sum + e.bytes + 1, 0) - 1;
+  let droppedLines = 0;
+  if (total > maxBytes) {
+    const keep = new Set(shaped.map((_, i) => i));
+    const noteBytes = byteLength(droppedMarker(99)) + 1;
+    for (let i = shaped.length - 1; i >= 0 && total + noteBytes > maxBytes; i--) {
+      const e = shaped[i];
+      if (!e || e.kind !== "prose") continue;
+      keep.delete(i);
+      total -= e.bytes + 1;
+      droppedLines += 1;
+    }
+    const remaining = shaped.filter((_, i) => keep.has(i));
+    remaining.push({ text: droppedMarker(droppedLines), kind: "structural", bytes: 0 });
+    const capped2 = capMachineLines(remaining, maxBytes, floor, join);
+    const text2 = join(capped2.items);
+    return {
+      text: text2,
+      bytes: byteLength(text2),
+      lines: entries.length,
+      truncatedLines,
+      droppedLines,
+      machineTruncated: capped2.machineTruncated
+    };
+  }
+  const capped = capMachineLines(shaped, maxBytes, floor, join);
+  const text = join(capped.items);
+  return {
+    text,
+    bytes: byteLength(text),
+    lines: entries.length,
+    truncatedLines,
+    droppedLines,
+    machineTruncated: capped.machineTruncated
+  };
+}
+
+// src/hooks/hard-rules.ts
+var HARD_RULES = `# Agent Kit session hard rules (manual mode default)
+
+1. **One phase per chat.** Finish the current phase (or one to-do if the phase is huge), update \`.cursor/HANDOFF.md\`, then STOP and ask the user before starting the next phase.
+2. **Do not burn the window.** Never run an entire multi-phase plan in one conversation unless the user explicitly ran \`/run-plan\` (or a deprecated alias \`/run-plan-loop\` / \`/run-plan-orchestrated\`).
+3. **Context questions are not optional.** If the user asks about context / contexto / window size, run the context-guardian protocol: warn, offer handoff, do NOT dismiss with "it's fine" and keep coding.
+4. **Read HANDOFF first** when resuming. Do not restart the plan from scratch.
+5. **Git:** suggest \`/git-staging\` after a phase with a diff; never \`/git-prod\` without explicit confirmation. A \`/run-plan-all\` queue confirm with Ship auth \`per-plan-release\` is that confirmation for one ship per completed plan.
+6. **HITL slash commands win.** When waiting for confirmation on \`/git-staging\` or \`/git-prod\` (or similar), do not divert to continue-plan / phase-boundary chatter; stay on that routine until the user answers.
+7. **\`/start-project\` is plan bootstrap, not execute.** Broad Intake Review first, then two gates: (A) single composite question (with active plan: backlog+write / park+write / modify / cancel; without: write / write+backlog (\`Write plan and add to backlog\`) / modify / cancel): approve/write the plan file only, (B) approve the first unit. Goal text in the same message is NOT permission to edit product files. Never "create plan and start Phase 1" in one turn. If HANDOFF already has an active plan, disposition is merged into Gate A composite options; never park silently. Gates use Ask questions per \`.cursor/skills/core/hitl-gates/SKILL.md\` and \`.cursor/rules/hitl-ask-questions.mdc\`. Fallback: numbered list is path 1.
+8. **\`/continue-plan\` waits for yes.** Summarize next \`[to-do-id]\`, then stop until the user confirms before editing.
+9. **\`/run-plan-all\` is a pure orchestrator.** After the confirm queue Ask, dispatch one Task subagent per plan (run the \`/run-plan\` tick contract inside it). Do not implement that plan's to-dos in the orchestrator window. When Ship auth is \`per-plan-release\`, this window ships one release after each completed plan and waits until it is Done before the next plan. \`Run plans only\` does not ship. A red public sync stops the queue.
+10. **Backlog CRUD never activates.** \`/backlog-add\` enqueues (Broad Intake + write Ask + plan file + HANDOFF Backlog) without park, activate, or Gate B. \`/backlog-edit\` / \`/backlog-delete\` / \`/backlog-cancel\` require Ask confirm before mutate; delete archives from Backlog, cancel is soft in place. No Field Report cards for routine backlog CRUD.
+11. **HANDOFF machine fields are bullet fields, not \`##\` headings.** Mission Control parses \`- **Plan:**\`, \`- **Backlog plans:**\`, \`- **Parked plans:**\`, \`- **Run queue:**\` (etc.). Canonical Plan: \`- **Plan:** \\\`name.plan.md\\\`\` or \`none\`. Nested backlog/parked rows: \`- \\\`other.plan.md\\\`\`. Never invent \`## Backlog plans\` / \`## Parked plans\` / \`## Run queue\` headings in place of those fields (Checklist / Current mission go empty or idle).
+12. **Plans inventory is index + HANDOFF.** \`/continue-plan\`, \`/run-plan-all\`, and Broad Intake read \`.cursor/context/plan-index.json\` and \`.cursor/HANDOFF.md\` only. Do not glob \`.cursor/plans/*.plan.md\`. Named single-file reads of a known basename remain OK. Delegation stays (ADR \`decisions/2026-07-26_command-orchestration-delegation-pattern.md\`).`;
+var DOGFOOD_INBOX_HINT = `## Dogfood inbox
+
+Unprocessed files are listed under \`dogfood/README.md\` (factory) or \`.cursor/dogfood/README.md\` (consumer). To file a new note, use \`/dogfood <topic> [summary]\`. Follow the ingest ritual (detect \u2192 analyze \u2192 memory WRITE \u2192 triage). Do not auto-start analysis unless the user asks.`;
+var UPDATE_CHECK_NUDGE = `## Agent Kit update available
+
+Installed **v{installed}**; latest public **v{latest}**.
+
+This is an advisory only (no files were changed). To apply, run \`/update\` and confirm via Ask questions. Bare \`agent-kit update\` is an explicit operator invoke, not a background job.`;
+var CURSOR_AWARENESS_NUDGE = `## Cursor product-update awareness
+
+Advisory gaps vs \`docs/cursor-native-audit.md\` (check-only; no apply; no Field Reports).
+
+Run \`/cursor-update-awareness\` (or \`agent-kit cursor-awareness --check\`) and confirm routing via Ask \u2192 \`/backlog-add\` or \`/dogfood\`.`;
+var PUBLIC_INBOUND_NUDGE = `## Public inbound radar
+
+Open issues or pull requests on \`agent-kit-startup/agent-kit\` (inspect-only; no merge/close).
+
+Run \`/public-inbound-radar\` (or \`agent-kit public-inbound-radar --json\`) and confirm routing via Ask \u2192 \`/backlog-add\`, Memory WRITE, \`/dogfood\`, \`/public-issue-triage\`, or Dismiss. Dependabot is one batch.`;
+
+// src/hooks/session-start.ts
+var NONE_PLACEHOLDERS = /* @__PURE__ */ new Set(["none", "n/a", "empty", "nil"]);
+var CURSOR_AWARENESS_SPAWN_TIMEOUT_MS = CHANGELOG_FETCH_TIMEOUT_MS + 3e3;
+async function readFull(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+function isMarkdownTableSeparator(line) {
+  const stripped = line.trim();
+  if (!stripped.startsWith("|")) return false;
+  const parts = stripped.replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+  return parts.length > 0 && parts.every((cell) => /^:?-+:?$/.test(cell));
+}
+function parseUnprocessedDogfoodItems(readmeText) {
+  const items = [];
+  let inSection = false;
+  let sectionLevel = 0;
+  const lines = readmeText.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const unprocessedMatch = /^(#{2,3})\s+Unprocessed Files\b/.exec(line);
+    if (unprocessedMatch) {
+      const hashes = unprocessedMatch[1];
+      if (!hashes) continue;
+      inSection = true;
+      sectionLevel = hashes.length;
+      continue;
+    }
+    if (!inSection) continue;
+    const headingMatch = /^(#{1,6})\s+/.exec(line);
+    if (headingMatch) {
+      if (/^#{1,6}\s+Processed(?:\s+Files)?\b/.test(line)) break;
+      const hashes = headingMatch[1];
+      if (hashes && hashes.length <= sectionLevel) break;
+      continue;
+    }
+    if (line.trim().startsWith("|") && isMarkdownTableSeparator(lines[i + 1] ?? "")) {
+      continue;
+    }
+    const body = extractUnprocessedDogfoodLine(line);
+    if (!body) continue;
+    items.push(body);
+  }
+  return items;
+}
+function extractUnprocessedDogfoodLine(line) {
+  const stripped = line.trim();
+  if (!stripped) return null;
+  let raw = null;
+  if (stripped.startsWith("- ")) {
+    raw = stripped.slice(2).trim();
+  } else {
+    const numbered = /^(\d+)[.)]\s+(.+)$/.exec(stripped);
+    if (numbered?.[2]) {
+      raw = numbered[2].trim();
+    } else if (stripped.startsWith("|")) {
+      if (isMarkdownTableSeparator(stripped)) return null;
+      const parts = stripped.replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+      if (parts.length === 0) return null;
+      raw = (parts[0] ?? "").trim();
+    }
+  }
+  if (!raw) return null;
+  const normalized = raw.toLowerCase().replace(/[*_]/g, "").trim();
+  if (!normalized || NONE_PLACEHOLDERS.has(normalized)) return null;
+  return raw;
+}
+async function l0Present(root) {
+  return await fileExists(path.join(root, MANIFEST_RELATIVE_PATH)) || await fileExists(path.join(root, ".cursor", "commands", "agent-kit-onboard.md")) || await fileExists(path.join(root, ".cursor", "commands", "start-project.md"));
+}
+function checkLabelAndRecommendation(check) {
+  const checkId = check.id;
+  if (typeof checkId !== "string" || !checkId) return null;
+  const actions = check.actions;
+  if (Array.isArray(actions)) {
+    for (const action of actions) {
+      if (!action || typeof action !== "object") continue;
+      const a = action;
+      if (typeof a.id === "string" && typeof a.recommendation === "string") {
+        return [a.id, a.recommendation];
+      }
+    }
+  }
+  const title = check.title;
+  if (typeof title === "string" && title) return [checkId, title];
+  return [checkId, "Resolve this readiness check"];
+}
+function unresolvedReadinessChecks(data) {
+  const essential = [];
+  const nonessential = [];
+  const pillars = data.pillars;
+  if (!Array.isArray(pillars)) return { essential, nonessential };
+  for (const pillar of pillars) {
+    if (!pillar || typeof pillar !== "object") continue;
+    const checks = pillar.checks;
+    if (!Array.isArray(checks)) continue;
+    for (const check of checks) {
+      if (!check || typeof check !== "object") continue;
+      const c = check;
+      if (c.status === "ready") continue;
+      if (c.essential === true) essential.push(c);
+      else nonessential.push(c);
+    }
+  }
+  return { essential, nonessential };
+}
+async function readinessSection(root) {
+  const snapshotPath = path.join(root, READINESS_SNAPSHOT_RELATIVE_PATH);
+  let data;
+  try {
+    data = JSON.parse(await readFile(snapshotPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const { essential, nonessential } = unresolvedReadinessChecks(data);
+  if (essential[0]) {
+    const labeled = checkLabelAndRecommendation(essential[0]);
+    if (!labeled) return null;
+    const [actionId, recommendation] = labeled;
+    return `## Repository readiness
+
+Unresolved essential check: \`${actionId}\`. ${recommendation} Run \`/agent-kit-onboard\` before \`/start-project\`. An active plan or HANDOFF remains the current work and is not replaced.`;
+  }
+  if (nonessential[0]) {
+    const labeled = checkLabelAndRecommendation(nonessential[0]);
+    if (!labeled) return null;
+    const [actionId, recommendation] = labeled;
+    return `## Repository readiness
+
+Optional readiness item: \`${actionId}\`. ${recommendation} This does not block \`/start-project\` or active plan work. Resume later with \`/agent-kit-onboard\` if useful.`;
+  }
+  const actions = data.pendingActions;
+  if (!Array.isArray(actions) || !actions[0] || typeof actions[0] !== "object") return null;
+  const first = actions[0];
+  if (typeof first.id !== "string" || typeof first.recommendation !== "string") return null;
+  return `## Repository readiness
+
+Optional readiness item: \`${first.id}\`. ${first.recommendation} This does not block \`/start-project\` or active plan work. Resume later with \`/agent-kit-onboard\` if useful.`;
+}
+async function dogfoodInboxSection(root) {
+  const candidateReadmes = [
+    path.join(root, "dogfood", "README.md"),
+    path.join(root, ".cursor", "dogfood", "README.md")
+  ];
+  for (const readme of candidateReadmes) {
+    if (!await fileExists(readme)) continue;
+    try {
+      const text = await readFile(readme, "utf8");
+      if (parseUnprocessedDogfoodItems(text).length) return DOGFOOD_INBOX_HINT;
+    } catch {
+    }
+  }
+  return null;
+}
+async function loadUpdateCheckPrefs(root) {
+  const data = await loadContextConfig(root);
+  if (!data) return null;
+  const uc = data.updateCheck;
+  if (!uc || typeof uc !== "object" || uc.enabled !== true) {
+    return null;
+  }
+  return uc;
+}
+var SESSION_START_SECTION_DEADLINE_MS = 6e3;
+function withDeadline(work, ms, onDeadline) {
+  return new Promise((resolve) => {
+    let done = false;
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      try {
+        onDeadline?.();
+      } catch {
+      }
+      resolve(null);
+    }, ms);
+    const settle = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    work.then(settle, () => settle(null));
+  });
+}
+function runSectionWithDeadline(section, root, spawnFn, deadlineMs, attempt) {
+  const children = [];
+  let expired = false;
+  const track = (child) => {
+    if (attempt) attempt.spawned = true;
+    if (expired) releaseChild(child);
+    else children.push(child);
+  };
+  const onResult = (result) => {
+    if (attempt && !expired) attempt.result = result;
+  };
+  return withDeadline(section(root, { spawnFn, track, onResult }), deadlineMs, () => {
+    expired = true;
+    if (attempt) attempt.timedOut = true;
+    for (const child of children) releaseChild(child);
+  });
+}
+function sectionAttemptNeedsStamp(attempt) {
+  if (!attempt.spawned) return false;
+  if (attempt.timedOut || !attempt.result) return true;
+  const status = attempt.result.status;
+  if (typeof status !== "string") return true;
+  return status === "skipped-offline" || !status.startsWith("skipped-");
+}
+function releaseChild(child) {
+  try {
+    child.kill();
+  } catch {
+  }
+  try {
+    child.unref();
+  } catch {
+  }
+}
+function runUpdateCheckJson(root, track) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      process.execPath,
+      [process.argv[1] ?? "", "update", "--check", "--json", "--respect-prefs", "--cwd", root],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: 12e3 }
+    );
+    track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => {
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed && typeof parsed === "object" ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+async function updateCheckSection(root, deps = {}) {
+  if (await loadUpdateCheckPrefs(root) === null) return null;
+  const spawnFn = deps.spawnFn ?? spawn;
+  const runFallback = deps.runFallback ?? runUpdateCheckJson;
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    let fallbackStarted = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const startFallback = () => {
+      if (settled || fallbackStarted) return;
+      fallbackStarted = true;
+      void runFallback(root, deps.track).then(finish);
+    };
+    const child = spawnFn(
+      "agent-kit",
+      ["update", "--check", "--json", "--respect-prefs", "--cwd", root],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: 12e3, shell: false }
+    );
+    deps.track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      startFallback();
+    });
+    child.on("close", (code) => {
+      if (settled || fallbackStarted) return;
+      if (code !== 0 && !out.trim()) {
+        startFallback();
+        return;
+      }
+      try {
+        finish(JSON.parse(out.trim()));
+      } catch {
+        startFallback();
+      }
+    });
+  });
+  deps.onResult?.(result);
+  if (!result || result.status !== "update-available") return null;
+  if (result.applyRecommended === true) return null;
+  const installed = String(result.installedVersion ?? "?");
+  const latest = String(result.latestVersion ?? "?");
+  return UPDATE_CHECK_NUDGE.replace("{installed}", installed).replace("{latest}", latest);
+}
+async function loadCursorUpdateCheckPrefs(root) {
+  const data = await loadContextConfig(root);
+  if (!data) return null;
+  const uc = data.cursorUpdateCheck;
+  if (!uc || typeof uc !== "object" || uc.enabled !== true) {
+    return null;
+  }
+  return uc;
+}
+function runCursorAwarenessJson(root, track) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      process.execPath,
+      [
+        process.argv[1] ?? "",
+        "cursor-awareness",
+        "--check",
+        "--json",
+        "--respect-prefs",
+        "--cwd",
+        root
+      ],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: CURSOR_AWARENESS_SPAWN_TIMEOUT_MS }
+    );
+    track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => {
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed && typeof parsed === "object" ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+function shouldEmitCursorAwarenessNudge(result) {
+  if (!result || result.status !== "gaps-found") return false;
+  if (result.applyRecommended === true || result.fieldReportRecommended === true) return false;
+  const gaps = Array.isArray(result.gaps) ? result.gaps : [];
+  return gaps.some(
+    (g) => g && typeof g === "object" && g.id === "changelog-ahead"
+  );
+}
+async function cursorAwarenessSection(root, deps = {}) {
+  if (await loadCursorUpdateCheckPrefs(root) === null) return null;
+  const spawnFn = deps.spawnFn ?? spawn;
+  const runFallback = deps.runFallback ?? runCursorAwarenessJson;
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    let fallbackStarted = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const startFallback = () => {
+      if (settled || fallbackStarted) return;
+      fallbackStarted = true;
+      void runFallback(root, deps.track).then(finish);
+    };
+    const child = spawnFn(
+      "agent-kit",
+      ["cursor-awareness", "--check", "--json", "--respect-prefs", "--cwd", root],
+      {
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: CURSOR_AWARENESS_SPAWN_TIMEOUT_MS,
+        shell: false
+      }
+    );
+    deps.track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      startFallback();
+    });
+    child.on("close", (code) => {
+      if (settled || fallbackStarted) return;
+      if (code !== 0 && !out.trim()) {
+        startFallback();
+        return;
+      }
+      try {
+        finish(JSON.parse(out.trim()));
+      } catch {
+        startFallback();
+      }
+    });
+  });
+  deps.onResult?.(result);
+  if (!shouldEmitCursorAwarenessNudge(result)) return null;
+  return CURSOR_AWARENESS_NUDGE;
+}
+var PUBLIC_INBOUND_SPAWN_TIMEOUT_MS = 3e4;
+async function loadPublicInboundCheckPrefs(root) {
+  const data = await loadContextConfig(root);
+  if (!data) return null;
+  const uc = data.publicInboundCheck;
+  if (!uc || typeof uc !== "object" || uc.enabled !== true) {
+    return null;
+  }
+  return uc;
+}
+function runPublicInboundJson(root, track) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      process.execPath,
+      [process.argv[1] ?? "", "public-inbound-radar", "--json", "--respect-prefs", "--cwd", root],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: PUBLIC_INBOUND_SPAWN_TIMEOUT_MS }
+    );
+    track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => {
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed && typeof parsed === "object" ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+async function publicInboundSection(root, deps = {}) {
+  if (await loadPublicInboundCheckPrefs(root) === null) return null;
+  const spawnFn = deps.spawnFn ?? spawn;
+  const runFallback = deps.runFallback ?? runPublicInboundJson;
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    let fallbackStarted = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const startFallback = () => {
+      if (settled || fallbackStarted) return;
+      fallbackStarted = true;
+      void runFallback(root, deps.track).then(finish);
+    };
+    const child = spawnFn(
+      "agent-kit",
+      ["public-inbound-radar", "--json", "--respect-prefs", "--cwd", root],
+      {
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: PUBLIC_INBOUND_SPAWN_TIMEOUT_MS,
+        shell: false
+      }
+    );
+    deps.track?.(child);
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      startFallback();
+    });
+    child.on("close", (code) => {
+      if (settled || fallbackStarted) return;
+      if (code !== 0 && !out.trim()) {
+        startFallback();
+        return;
+      }
+      try {
+        finish(JSON.parse(out.trim()));
+      } catch {
+        startFallback();
+      }
+    });
+  });
+  deps.onResult?.(result);
+  if (!shouldEmitPublicInboundNudge(result)) {
+    return null;
+  }
+  return PUBLIC_INBOUND_NUDGE;
+}
+var AUDIT_SESSION_NS_PREFIX = "agent-kit-audit-";
+var AUDIT_SESSION_LIST_TIMEOUT_MS = 2e3;
+function runAuditSessionCommand(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: AUDIT_SESSION_LIST_TIMEOUT_MS,
+      shell: false
+    });
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => resolve(out));
+  });
+}
+function parseTmuxDetachedAuditSessions(out, nowEpochSeconds) {
+  const sessions = [];
+  for (const line of out.split(/\r?\n/)) {
+    const m = /^(\S+)\s+(\d+)\s+(\d+)$/.exec(line.trim());
+    if (!m) continue;
+    const [, name, attached, created] = m;
+    if (!name || !name.startsWith(AUDIT_SESSION_NS_PREFIX)) continue;
+    if (Number(attached) > 0) continue;
+    const createdEpoch = Number(created);
+    const ageSeconds = Number.isFinite(createdEpoch) && nowEpochSeconds >= createdEpoch ? nowEpochSeconds - createdEpoch : -1;
+    sessions.push({ channel: "tmux", name, ageSeconds });
+  }
+  return sessions;
+}
+function parseScreenDetachedAuditSessions(listing) {
+  const lines = listing.split(/\r?\n/);
+  let sockdir = null;
+  for (const line of lines) {
+    const dirMatch = /^\d+\s+Sockets?\s+in\s+(.+)\.$/.exec(line);
+    if (dirMatch?.[1]) sockdir = dirMatch[1];
+  }
+  const entries = [];
+  for (const line of lines) {
+    const m = /^\s+(\d+)\.(\S+)\s+\((.*)\)/.exec(line);
+    if (!m) continue;
+    const [, pid, name, marker] = m;
+    if (!name || !name.startsWith(AUDIT_SESSION_NS_PREFIX)) continue;
+    if (marker && /[Aa]ttached/.test(marker)) continue;
+    entries.push({ name, socketPath: sockdir ? path.join(sockdir, `${pid}.${name}`) : null });
+  }
+  return entries;
+}
+function formatSessionAge(seconds) {
+  if (seconds >= 86400) return `${Math.floor(seconds / 86400)}d`;
+  if (seconds >= 3600) return `${Math.floor(seconds / 3600)}h`;
+  if (seconds >= 60) return `${Math.floor(seconds / 60)}m`;
+  return `${seconds}s`;
+}
+async function detachedAuditSessionsSection(deps = {}) {
+  try {
+    const run = deps.runCommand ?? runAuditSessionCommand;
+    const nowMs = (deps.now ?? Date.now)();
+    const [tmuxOut, screenOut] = await Promise.all([
+      run("tmux", [
+        "list-sessions",
+        "-F",
+        "#{session_name} #{session_attached} #{session_created}"
+      ]),
+      run("screen", ["-ls"])
+    ]);
+    const sessions = tmuxOut ? parseTmuxDetachedAuditSessions(tmuxOut, Math.floor(nowMs / 1e3)) : [];
+    if (screenOut) {
+      for (const entry of parseScreenDetachedAuditSessions(screenOut)) {
+        let ageSeconds = -1;
+        if (entry.socketPath) {
+          try {
+            const { mtimeMs } = await stat(entry.socketPath);
+            if (nowMs >= mtimeMs) ageSeconds = Math.floor((nowMs - mtimeMs) / 1e3);
+          } catch {
+          }
+        }
+        sessions.push({ channel: "screen", name: entry.name, ageSeconds });
+      }
+    }
+    if (sessions.length === 0) return null;
+    const knownAges = sessions.map((s) => s.ageSeconds).filter((a) => a >= 0);
+    const oldest = knownAges.length ? `oldest ~${formatSessionAge(Math.max(...knownAges))}` : "oldest age unknown";
+    const noun = sessions.length === 1 ? "session" : "sessions";
+    return `## Detached audit sessions (host)
+
+${sessions.length} detached \`agent-kit-audit-*\` PTY ${noun} on this host (${oldest}). These are external plan-review terminals: inspect with \`tmux attach -t <name>\` / \`screen -r <name>\`, or let the audit launcher's session GC dispose of them on the next spawn.`;
+  } catch {
+    return null;
+  }
+}
+async function buildSessionStartAdditionalContext(rootDir, _payload = {}, deps = {}) {
+  const root = path.resolve(rootDir);
+  const handoffPath = path.join(root, HANDOFF_REL);
+  const handoffFull = await readFull(handoffPath);
+  const handoff = capHandoffExcerpt(handoffFull);
+  const parts = [HARD_RULES];
+  if (await l0Present(root)) {
+    const readiness = await readinessSection(root);
+    if (readiness) parts.push(readiness);
+  }
+  const dogfood = await dogfoodInboxSection(root);
+  if (dogfood) parts.push(dogfood);
+  const deadlineMs = deps.deadlineMs ?? SESSION_START_SECTION_DEADLINE_MS;
+  const newAttempt = () => ({ spawned: false, timedOut: false, result: null });
+  const updateAttempt = newAttempt();
+  const cursorAttempt = newAttempt();
+  const inboundAttempt = newAttempt();
+  const runSection = (section, attempt) => runSectionWithDeadline(section, root, deps.spawnFn, deadlineMs, attempt);
+  const [updateNudge, cursorNudge, inboundNudge] = await Promise.all([
+    runSection(updateCheckSection, updateAttempt),
+    runSection(cursorAwarenessSection, cursorAttempt),
+    runSection(publicInboundSection, inboundAttempt)
+  ]);
+  await stampSectionAttempts(root, updateAttempt, cursorAttempt, inboundAttempt);
+  if (updateNudge) parts.push(updateNudge);
+  if (cursorNudge) parts.push(cursorNudge);
+  if (inboundNudge) parts.push(inboundNudge);
+  const auditSessions = await detachedAuditSessionsSection().catch(() => null);
+  if (auditSessions) parts.push(auditSessions);
+  const formatWarnings = validateHandoffText(handoffFull);
+  if (formatWarnings.length) {
+    const bullet = formatWarnings.map((w) => `- ${w.message}`).join("\n");
+    parts.push(
+      `## HANDOFF format warning (Mission Control)
+
+${bullet}
+
+Rewrite machine lists as \`- **Field:**\` bullets before trusting Checklist / Current mission.`
+    );
+  }
+  if (handoff.text) {
+    const truncated = handoff.truncatedLines + handoff.machineTruncated;
+    const capped = truncated > 0 || handoff.droppedLines > 0;
+    const note = capped ? `
+
+_Excerpt capped at ${Math.round(HANDOFF_EXCERPT_MAX_BYTES / 1024)} KB (${truncated} lines truncated, ${handoff.droppedLines} dropped); read \`.cursor/HANDOFF.md\` for the full entries._` : "";
+    parts.push(`## Current HANDOFF.md (excerpt)
+
+${handoff.text}${note}`);
+  } else {
+    parts.push(
+      "## HANDOFF.md\n\nNo handoff file yet. If starting work, create a plan with to-dos first (`/start-project`)."
+    );
+  }
+  const pendingPlans = await pendingPlansSection(root);
+  if (pendingPlans) parts.push(pendingPlans);
+  return { additional_context: parts.join("\n\n") };
+}
+async function stampSectionAttempts(root, updateAttempt, cursorAttempt, inboundAttempt) {
+  if (sectionAttemptNeedsStamp(updateAttempt)) {
+    try {
+      await stampLastCheckedAt(root);
+    } catch {
+    }
+  }
+  if (sectionAttemptNeedsStamp(cursorAttempt)) {
+    try {
+      const latest = cursorAttempt.result?.latestCursorVersion;
+      await stampCursorUpdateCheck(
+        await resolveInventoryRoot(root) ?? root,
+        typeof latest === "string" ? { lastSeenCursorVersion: latest } : {}
+      );
+    } catch {
+    }
+  }
+  if (sectionAttemptNeedsStamp(inboundAttempt)) {
+    try {
+      await stampPublicInboundCheck(root);
+    } catch {
+    }
+  }
+}
+async function pendingPlansSection(root) {
+  try {
+    const index = await writePlanIndex(root);
+    return formatPlanIndexSection(index);
+  } catch {
+    return null;
+  }
+}
+function resolveSessionRoot(payload, cwd = process.cwd()) {
+  const roots = payload.workspace_roots;
+  if (Array.isArray(roots) && typeof roots[0] === "string" && roots[0]) {
+    return roots[0];
+  }
+  return cwd;
+}
+
+// src/commands/hook.ts
+async function runSessionStartHook(cwd, formatArg, deps = {}) {
+  const format = resolveSessionStartFormat(formatArg);
+  try {
+    const readStdin = deps.readStdin ?? readStdinJson;
+    const buildContext = deps.buildContext ?? buildSessionStartAdditionalContext;
+    const payload = await readStdin();
+    const root = resolveSessionRoot(payload, path2.resolve(cwd));
+    const out = await buildContext(root, payload);
+    return formatSessionStartOutput(out.additional_context, format);
+  } catch {
+    return formatSessionStartOutput(SESSION_START_DEGRADED_MESSAGE, format);
+  }
+}
+var hookCommand = defineCommand({
+  meta: {
+    name: "hook",
+    description: "Cursor + Claude Code hook adapters (session-start, pre-compact). CLI is SoT."
+  },
+  subCommands: {
+    "session-start": defineCommand({
+      meta: {
+        name: "session-start",
+        description: "Emit sessionStart context (stdin: host payload). --format cursor (default, JSON additional_context) | claude (plain stdout)"
+      },
+      args: {
+        cwd: {
+          type: "string",
+          default: process.cwd()
+        },
+        format: {
+          type: "string",
+          default: "cursor",
+          description: "cursor (default) | claude"
+        }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        console.log(await runSessionStartHook(cwd, args.format));
+      }
+    }),
+    "pre-compact": defineCommand({
+      meta: {
+        name: "pre-compact",
+        description: "Emit preCompact user_message JSON (stdin: Cursor payload)"
+      },
+      async run() {
+        const payload = await readStdinJson();
+        console.log(JSON.stringify(buildPreCompactUserMessage(payload)));
+      }
+    })
+  }
+});
+export {
+  hookCommand,
+  runSessionStartHook
+};