harnery 0.36.0 → 0.37.0

package/dist/lib/coord-root-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-root-id.d.ts","sourceRoot":"","sources":["../../src/lib/coord-root-id.ts"],"names":[],"mappings":"AAIA,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,MAAM,GAAG,MAAyB,EACxC,QAAQ,SAAU,GACjB,MAAM,CAGR"}

package/dist/lib/coord-root-id.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { DEFAULT_WEB_PORT } from "./local-file-url.js";
+/** Local-only endpoint used to prove that a dashboard serves the caller's repo. */
+export const COORD_ROOT_ID_PATH = "/api/coord-root";
+/**
+ * Opaque identity for a canonical coordination root. The path stays local;
+ * only its digest crosses the dashboard boundary.
+ */
+export function coordRootId(root) {
+    const canonical = realpathSync(root);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function localCoordRootIdUrl(port = DEFAULT_WEB_PORT, protocol = "http:") {
+    const portPart = String(port) === "" ? "" : `:${port}`;
+    return `${protocol}//127.0.0.1${portPart}${COORD_ROOT_ID_PATH}`;
+}

package/dist/lib/instructions/apply.d.ts

@@ -7,13 +7,15 @@
  * writes, and deletes so init/deinit stay thin and this stays integration-
  * testable against a temp dir.
  *
- * Two files, one dir:
+ * Three files, one dir:
  *   - `AGENTS.md` — the always-on orientation block (a managed region; the
  *     consumer owns the rest of the file).
  *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.cursor/rules/harnery-turn-ritual.mdc` — cursor only; an Always Apply
+ *     rule that makes the Stop-enforced status footer visible in reply text.
  *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
  *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
  *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.

package/dist/lib/instructions/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAyFH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CAoInF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CA8FrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CA2Db"}

package/dist/lib/instructions/apply.js

@@ -7,25 +7,28 @@
  * writes, and deletes so init/deinit stay thin and this stays integration-
  * testable against a temp dir.
  *
- * Two files, one dir:
+ * Three files, one dir:
  *   - `AGENTS.md` — the always-on orientation block (a managed region; the
  *     consumer owns the rest of the file).
  *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.cursor/rules/harnery-turn-ritual.mdc` — cursor only; an Always Apply
+ *     rule that makes the Stop-enforced status footer visible in reply text.
  *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
  *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
  *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { stripJsonComments } from "../../core/config.js";
+import { endOfTurnStatusCommand, stripJsonComments } from "../../core/config.js";
 import { readHostAddendum } from "./host-addendum.js";
-import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, spliceRegion, } from "./splice.js";
+import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, shortHash, spliceRegion, } from "./splice.js";
 import { HOST_ADDENDUM_REGION, IMPORT_REGION, INSTRUCTIONS_REGION, renderInstructionsBlock, SKILLS, } from "./templates.js";
 const AGENTS_FILE = "AGENTS.md";
 const CLAUDE_FILE = "CLAUDE.md";
+const CURSOR_RULE_FILE = join(".cursor", "rules", "harnery-turn-ritual.mdc");
 const ADAPTER_SKILLS_DIR = {
     "claude-code": join(".claude", "skills"),
     cursor: join(".agents", "skills"),
@@ -43,6 +46,36 @@ function skillBody(render, binName) {
     const content = render(binName);
     return content.slice(content.indexOf("-->") + 3).trim();
 }
+function cursorRuleBody(projectRoot, binName) {
+    const statusCommand = endOfTurnStatusCommand(projectRoot);
+    return [
+        "# Harnery turn ritual",
+        "",
+        "On every turn that uses tools:",
+        "",
+        `1. Run \`${binName} agents set-task "<short focus>"\` during the turn, even when the focus is unchanged.`,
+        `2. Make \`${statusCommand}\` your final tool call.`,
+        "3. Append that command's stdout verbatim in a fenced code block at the bottom of the same substantive reply.",
+        "",
+        "Cursor Stop enforces all three signals. A missing signal produces one follow-up that names every repair needed.",
+    ].join("\n");
+}
+function cursorRuleContent(projectRoot, binName) {
+    const body = cursorRuleBody(projectRoot, binName);
+    const marker = `<!-- harnery:generated cursor-turn-ritual v=${shortHash(body)}; machine-owned; ` +
+        `regenerated by \`${binName} init\`, removed by \`${binName} deinit\`. ` +
+        "Edit the harnery template, not this file. -->";
+    return [
+        "---",
+        "description: Harnery end-of-turn coordination ritual",
+        "alwaysApply: true",
+        "---",
+        marker,
+        "",
+        body,
+        "",
+    ].join("\n");
+}
 /** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
 export function readSkillsExclude(projectRoot) {
     const p = join(projectRoot, ".harnery", "config.jsonc");
@@ -157,6 +190,26 @@ export function applyInstructions(projectRoot, opts) {
             }
         }
     }
+    // ── Cursor Always Apply rule ────────────────────────────────────────────
+    if (opts.adapter === "cursor") {
+        const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+        const content = cursorRuleContent(projectRoot, opts.binName);
+        const before = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : null;
+        if (before === content) {
+            actions.push(`· ${CURSOR_RULE_FILE} already current`);
+        }
+        else if (before !== null && !isOwnedFile(before)) {
+            warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+        }
+        else {
+            if (!opts.dryRun) {
+                mkdirSync(dirname(rulePath), { recursive: true });
+                writeFileSync(rulePath, content);
+            }
+            const fresh = before === null;
+            actions.push(`${fresh ? "+" : "~"} ${verbed(fresh ? "write" : "update", fresh ? "wrote" : "updated")} ${CURSOR_RULE_FILE}`);
+        }
+    }
     // ── shipped skills ───────────────────────────────────────────────────────
     if (skillsDir) {
         const exclude = readSkillsExclude(projectRoot);
@@ -239,6 +292,19 @@ export function removeInstructions(projectRoot, opts) {
             }
         }
     }
+    if (opts.adapter === "cursor") {
+        const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+        if (existsSync(rulePath)) {
+            if (!isOwnedFile(readFileSync(rulePath, "utf8"))) {
+                warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+            }
+            else {
+                if (!opts.dryRun)
+                    rmSync(rulePath);
+                actions.push(`+ ${opts.dryRun ? "would delete" : "deleted"} ${CURSOR_RULE_FILE}`);
+            }
+        }
+    }
     // ── shipped skills ───────────────────────────────────────────────────────
     if (skillsDir) {
         for (const skill of SKILLS) {
@@ -305,6 +371,11 @@ export function checkInstructions(projectRoot, opts) {
                 note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
             }
         }
+        if (opts.adapter === "cursor") {
+            const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+            const content = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : "";
+            note(`${CURSOR_RULE_FILE} rule`, checkOwnedSkill(content, cursorRuleBody(projectRoot, opts.binName)));
+        }
     }
     catch (err) {
         errored = true;

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CA0GR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAgHR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -113,6 +113,12 @@ coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
 
+**Messaging another agent.** \`${b} agents ping <name> "<message>"\` reaches an
+agent by name whether or not they are running: a live agent sees it on their next
+prompt, and a dormant name holds it until a session of that name next starts.
+Send it as your first and only step. Do not check who is live first, and do not
+hunt for somewhere else to leave it. Only a never-used name is refused.
+
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
 \`${b} journal read\` reads yours, \`${b} journal read --name <peer>\` reads a peer's.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -132,6 +132,16 @@
       "types": "./dist/core/semantic/index.d.ts",
       "import": "./dist/core/semantic/index.js"
     },
+    "./core/supervisor": {
+      "bun": "./src/core/supervisor/index.ts",
+      "types": "./dist/core/supervisor/index.d.ts",
+      "import": "./dist/core/supervisor/index.js"
+    },
+    "./core/diagnostics": {
+      "bun": "./src/core/diagnostics/index.ts",
+      "types": "./dist/core/diagnostics/index.d.ts",
+      "import": "./dist/core/diagnostics/index.js"
+    },
     "./core/governor/plans": {
       "bun": "./src/core/governor/plan-read.ts",
       "types": "./dist/core/governor/plan-read.d.ts",
@@ -230,6 +240,7 @@
     "check:portability": "bun run scripts/check-portability.ts",
     "check:public-surface": "bun run scripts/check-public-surface.ts",
     "check:layering": "bun run scripts/check-layering.ts",
+    "probe:supervisor-budget": "bun run scripts/probe-supervisor-budget.ts",
     "lint:fix": "bun x @biomejs/biome check --write src",
     "format": "bun x @biomejs/biome format --write src",
     "test": "bun run scripts/test.mjs",

package/src/commander.ts

@@ -440,6 +440,12 @@ function harneryCommandBundles({
         ),
       { hasOptions: true },
     ),
+    lazy(
+      "qa-run <target>",
+      `Run the whole page-QA matrix in one command (planner, deterministic gates per context, interactions, critique, snapshot) via child \`${binName} browse\` processes; writes page-qa-result.json with a fail-closed verdict.`,
+      async (program) => (await import("./commands/qa-run.ts")).registerQaRunCommand(program, emit),
+      { hasOptions: true },
+    ),
     lazy(
       "browse-session",
       "Control an opted-in headed browse session through an owner-only descriptor",
@@ -509,6 +515,26 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/semantic.ts")).registerSemanticCommand(program, emit, context),
     ),
+    lazy(
+      "resources",
+      "Observe local CPU and memory pressure by agent and process tree",
+      async (program) =>
+        (await import("./commands/resources.ts")).registerResourcesCommand(program, emit, context),
+    ),
+    lazy("supervisor", "Run Harnery's optional local diagnostic supervisor", async (program) =>
+      (await import("./commands/supervisor.ts")).registerSupervisorCommand(program, emit, context),
+    ),
+    lazy(
+      "diagnostics",
+      "Inspect, capture, and replay bounded local diagnostic findings",
+      async (program) =>
+        (await import("./commands/diagnostics.ts")).registerDiagnosticsCommand(
+          program,
+          emit,
+          context,
+        ),
+      { hasOptions: true },
+    ),
     lazy(
       "storage",
       "Inspect registered Harnery storage without reading file bodies",

package/src/commands/agents.ts

@@ -49,6 +49,14 @@ import {
   LiveCoordinationAuthorityV3Error,
   reopenLiveCoordinationGenerationV3,
 } from "../core/agents/live-authority-v3.ts";
+import {
+  isAddressableName,
+  MailboxCapacityError,
+  type QueueResult,
+  queueMailboxMessage,
+  suggestNames,
+} from "../core/agents/mailbox.ts";
+import { reconcileCoordinationV3 } from "../core/agents/reconcile-coordination-v3.ts";
 import {
   listSessionFinalizationRequestsV3,
   observeHostDisappearedV3,
@@ -435,7 +443,8 @@ export function registerAgentsCommand(
   cmd
     .command("reconcile")
     .description(
-      "Reconcile archive, idle, parent/run completion, stale, superseded, and host lifecycle signals into V3 session finalization.",
+      "Sweep the stale coordination cache, then reconcile archive, idle, parent/run " +
+        "completion, stale, superseded, and host lifecycle signals into V3 session finalization.",
     )
     .option("--watch", "Keep reconciling until interrupted")
     .option("--interval-seconds <n>", "Watch interval in seconds")
@@ -485,9 +494,10 @@ export function registerAgentsCommand(
   cmd
     .command("ping <name> <message...>")
     .description(
-      "Append a 'handoff' entry to a peer agent's journal. Body prefixed with " +
-        "`from agent-<me>:`. Use to leave actionable coordination notes for peers " +
-        "currently holding files you need.",
+      "Send a message to another agent by name. Works whether or not that agent " +
+        "is running: a live peer sees it on their next prompt, and a name with no " +
+        "live session gets it queued until a session of that name next starts. " +
+        "Only an unknown name is refused.",
     )
     .option("--json", "JSON output")
     .action((name: string, message: string[], opts: { json?: boolean }) => {
@@ -546,7 +556,7 @@ export function registerAgentsCommand(
     .command("health")
     .description(
       "One-screen coord-layer health rollup: heal events, council activity, " +
-        "zombie detection, and anomalies. Designed for " +
+        "heartbeat cache issues, and findings. Designed for " +
         "daily glance + dashboard ingestion. Reads .harnery/.",
     )
     .option("--since <window>", "Window (Nh | Nd). Default: 24h.", "24h")
@@ -747,7 +757,7 @@ async function runSessionReconcile(opts: {
   }
   let stopped = false;
   do {
-    emit.data(reconcileSessionFinalizationV3(root));
+    emit.data(reconcileCoordinationV3(root));
     if (!opts.watch || stopped) return;
     await new Promise<void>((resolvePromise) => {
       const timer = setTimeout(resolvePromise, interval * 1_000);
@@ -3022,7 +3032,7 @@ interface HealthReport {
   // Heartbeat cache files present in active/ but stale or malformed. These are
   // files the sweep is not catching; a parseable old heartbeat is stale, not
   // evidence of an epoch-like or corrupt timestamp.
-  zombies: {
+  heartbeat_cache_issues: {
     count: number;
     samples: string[];
   };
@@ -3038,7 +3048,7 @@ interface HealthReport {
     latest_at: string | null;
     sessions: string[];
   };
-  anomalies: string[];
+  findings: string[];
 }
 
 /** Open-span soft watermark per producer state. The producer-state reader
@@ -3946,8 +3956,8 @@ function runHealth(opts: { since: string; json?: boolean }): void {
   // Heartbeat cache issues: files in active/ that are unparseable, nameless,
   // invalidly timestamped, or stale. Old parseable timestamps are ordinary
   // staleness, not evidence of epoch-like timestamp corruption.
-  let zombieCount = 0;
-  const zombieSamples: string[] = [];
+  let cacheIssueCount = 0;
+  const cacheIssueSamples: string[] = [];
   const STALE_HEARTBEAT_AGE_MS = 24 * 60 * 60 * 1000;
   if (existsSync(activeDir)) {
     for (const file of readdirSync(activeDir)) {
@@ -3960,16 +3970,16 @@ function runHealth(opts: { since: string; json?: boolean }): void {
         hb = null;
       }
       if (!hb || typeof hb.instance_id !== "string") {
-        zombieCount++;
-        if (zombieSamples.length < 5)
-          zombieSamples.push(`${idFromFile.slice(0, 12)} (unparseable/no-id)`);
+        cacheIssueCount++;
+        if (cacheIssueSamples.length < 5)
+          cacheIssueSamples.push(`${idFromFile.slice(0, 12)} (unparseable/no-id)`);
         continue;
       }
       const cacheIssue = classifyHeartbeatCacheIssue(hb, nowMs, STALE_HEARTBEAT_AGE_MS);
       if (cacheIssue) {
-        zombieCount++;
-        if (zombieSamples.length < 5) {
-          zombieSamples.push(`${idFromFile.slice(0, 12)} (${cacheIssue})`);
+        cacheIssueCount++;
+        if (cacheIssueSamples.length < 5) {
+          cacheIssueSamples.push(`${idFromFile.slice(0, 12)} (${cacheIssue})`);
         }
       }
     }
@@ -3985,11 +3995,11 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     }
   }
 
-  // Anomaly detection.
-  const anomalies: string[] = [];
+  // Finding detection.
+  const findings: string[] = [];
   for (const { agent, count } of healTopAgents) {
     if (count >= 5) {
-      anomalies.push(
+      findings.push(
         `${agent} self-healed ${count}x in ${opts.since}; possible idle-prune loop or PID instability`,
       );
     }
@@ -4000,7 +4010,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       activeAgents.source === "event-ledger-v3"
         ? "lifecycle reconciliation may be delayed"
         : "heal mechanism may not be firing";
-    anomalies.push(
+    findings.push(
       `${activeAgents.stale} active ${noun}(s) without activity for ${Math.floor(freshnessCutoffSecs() / 60)}min; ${action}`,
     );
   }
@@ -4009,31 +4019,33 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     (schema) => schema !== expectedSchema,
   );
   if (unexpectedSchemas.length > 0) {
-    anomalies.push(
+    findings.push(
       `Unexpected active-agent schema versions in use: ${unexpectedSchemas.join(", ")} (expected ${expectedSchema})`,
     );
   }
-  // Only recent hook failures are active anomalies. Historical rows remain in
+  // Only recent hook failures are active findings. Historical rows remain in
   // the report with exact error signatures and their latest timestamp.
   if (hookErrors.last1h > 0) {
     const top = hookErrors.recentTopErrors[0];
     const detail = top ? `: top '${top.error.slice(0, 80)}' x${top.count} (${top.phase})` : "";
-    anomalies.push(`agent-hook errored ${hookErrors.last1h}x in the last hour${detail}`);
+    findings.push(`agent-hook errored ${hookErrors.last1h}x in the last hour${detail}`);
   }
   if (stream.cursor_backlog > 500) {
-    anomalies.push(
+    findings.push(
       `projection cursor is ${stream.cursor_backlog} events behind; drain lagging (stop projection may be failing)`,
     );
   }
-  // Raw V3 stream size is not an anomaly; catalog rotation bounds readers.
+  // Raw V3 stream size is not a finding; catalog rotation bounds readers.
   if ((sweptByReason.unparseable ?? 0) > 0) {
-    anomalies.push(
+    findings.push(
       `${sweptByReason.unparseable} heartbeat(s) swept as unparseable in ${opts.since}; possible corruption or a non-atomic writer`,
     );
   }
-  if (zombieCount > 0) {
-    anomalies.push(
-      `${zombieCount} heartbeat cache issue(s) in active/ (${zombieSamples.join(", ")}); stale or malformed files the sweep isn't reaping`,
+  if (cacheIssueCount > 0) {
+    findings.push(
+      `${cacheIssueCount} heartbeat cache issue(s) in active/ (${cacheIssueSamples.join(", ")}); ` +
+        "rows the last sweep deliberately kept (malformed but mtime-fresh, or neither audit " +
+        "write could persist), or that aged past the freshness cutoff since it ran",
     );
   }
   if (stopRemediation.total > 0) {
@@ -4041,7 +4053,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       stopRemediation.sessions.length > 0
         ? ` (sessions: ${stopRemediation.sessions.map((s) => s.slice(0, 8)).join(", ")})`
         : "";
-    anomalies.push(
+    findings.push(
       `stop-hook remediation cap exhausted ${stopRemediation.total}x in ${opts.since}${who}; these sessions ended turns without the end-of-turn ritual — check why their evidence never lands`,
     );
   }
@@ -4056,17 +4068,17 @@ function runHealth(opts: { since: string; json?: boolean }): void {
         (sum, generation) => sum + generation.span_count,
         0,
       );
-      anomalies.push(
+      findings.push(
         `${orphanSpans} open tool span(s) across ${orphanGenerations.length} generation(s) with no open turn; orphaned spans block clean session end`,
       );
     }
     for (const pressure of eventLedger.span_pressure) {
-      anomalies.push(
+      findings.push(
         `${pressure.instance_id} (${pressure.generation_id}) holds ${pressure.span_count} open spans (soft watermark ${SPAN_PRESSURE_SOFT_WATERMARK}; the reader's 256-span cap makes the state unreadable)`,
       );
     }
     for (const collectionError of eventLedger.collection_errors) {
-      anomalies.push(`event-ledger health: ${collectionError}`);
+      findings.push(`event-ledger health: ${collectionError}`);
     }
   }
 
@@ -4111,14 +4123,14 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       recent_top_errors: hookErrors.recentTopErrors,
     },
     stream,
-    zombies: { count: zombieCount, samples: zombieSamples },
+    heartbeat_cache_issues: { count: cacheIssueCount, samples: cacheIssueSamples },
     event_ledger: eventLedger,
     stop_remediation: {
       total: stopRemediation.total,
       latest_at: stopRemediation.latestAt,
       sessions: stopRemediation.sessions,
     },
-    anomalies,
+    findings,
   };
 
   if (opts.json) {
@@ -4211,12 +4223,12 @@ function renderHealthBox(report: HealthReport): void {
     ["event ledger", ledgerStr],
     [
       "cache issues",
-      report.zombies.count === 0
+      report.heartbeat_cache_issues.count === 0
         ? "0"
-        : `${report.zombies.count} (${report.zombies.samples.join(", ")})`,
+        : `${report.heartbeat_cache_issues.count} (${report.heartbeat_cache_issues.samples.join(", ")})`,
     ],
     ["councils", councilParts.join(", ")],
-    ["anomalies", report.anomalies.length === 0 ? "(clean)" : `${report.anomalies.length} flagged`],
+    ["findings", report.findings.length === 0 ? "(clean)" : `${report.findings.length} flagged`],
   ];
 
   const localTime = formatLocalTime(new Date(report.generated_at));
@@ -4224,9 +4236,9 @@ function renderHealthBox(report: HealthReport): void {
 
   process.stdout.write(`${formatBox(title, rows)}\n`); // lint-ok-emission: chat-paste path; mirrors runStatus's direct write so the box surfaces in both TTY + harn-session-teed contexts
 
-  if (report.anomalies.length > 0) {
+  if (report.findings.length > 0) {
     process.stdout.write("\n"); // lint-ok-emission: same chat-paste path
-    for (const a of report.anomalies) {
+    for (const a of report.findings) {
       process.stdout.write(`  ! ${a}\n`); // lint-ok-emission: same
     }
   }
@@ -4660,18 +4672,52 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
     );
     process.exit(1);
   }
+  const coordRoot = monorepoRoot();
   const peerOwner = resolveOwnerByName(name);
-  if (!peerOwner) {
+
+  // A name with no live session is the common case, not an error: the agent it
+  // refers to may have ended minutes ago and may come back under the same name.
+  // Refuse only a name that no agent has ever held, which is a typo — queueing
+  // that would swallow the message silently.
+  if (!peerOwner && coordRoot && !isAddressableName(coordRoot, name)) {
+    const suggestions = suggestNames(coordRoot, name);
     emit.error({
-      code: "no_peer",
-      message: `no live agent named "${name}" (case-insensitive). Run \`${resolveBinName()} agents list\` to see who's active.`,
+      code: "unknown_agent",
+      message:
+        `no agent has ever been named "${name}". ` +
+        (suggestions.length > 0 ? `Did you mean ${suggestions.join(", ")}? ` : "") +
+        `Run \`${resolveBinName()} agents list\` for live sessions.`,
     });
     process.exit(1);
   }
+
   const myHb = readCurrentCoordinationRow(myOwner);
   const fromName = myHb?.name ?? "anonymous";
   const body = `from agent-${fromName}: ${message.trim()}`;
-  const doc = appendEntry(peerOwner, "handoff", body);
+
+  // A live recipient gets the journal entry immediately, so a peer reading
+  // their own journal mid-session sees it without waiting for a prompt. A
+  // dormant recipient has no journal to write to yet; the drain writes it into
+  // whichever session picks the message up.
+  const doc = peerOwner ? appendEntry(peerOwner, "handoff", body) : null;
+
+  let queued: QueueResult;
+  try {
+    queued = queueMailboxMessage({
+      coordRoot: coordRoot ?? process.cwd(),
+      toName: name,
+      fromName,
+      fromInstanceId: myOwner,
+      body: message.trim(),
+      journaled: Boolean(peerOwner),
+    });
+  } catch (error) {
+    if (error instanceof MailboxCapacityError) {
+      emit.error({ code: `mailbox_${error.reason_code}`, message: error.message });
+      process.exit(1);
+    }
+    throw error;
+  }
 
   // Canonical delivery record: sender is the envelope owner, recipient rides
   // in data, so read-only observers can render the communication without
@@ -4683,18 +4729,21 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
     observation: {
       event_type: "coord.message_observed",
       direction: "sent",
-      subject: peerOwner,
+      subject: peerOwner ?? `name:${queued.message.to_name}`,
       body: message.trim(),
     },
   });
 
   const data = {
-    peer: name,
+    peer: queued.message.to_name,
     peer_instance_id: peerOwner,
+    delivery: peerOwner ? ("live" as const) : ("queued" as const),
+    message_id: queued.message.message_id,
+    pending: queued.pending,
     from: fromName,
     body,
-    journal_path: doc.path,
-    journal_bytes: doc.bytes,
+    journal_path: doc?.path ?? null,
+    journal_bytes: doc?.bytes ?? null,
   };
 
   if (opts.json) {
@@ -4703,7 +4752,11 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
     return;
   }
   emit.data(data);
-  emit.text(`pinged agent-${name}: "${truncate(message.trim(), 80)}"\n`);
+  emit.text(
+    peerOwner
+      ? `delivered to agent-${data.peer} (live; they see it on their next prompt): "${truncate(message.trim(), 80)}"\n`
+      : `queued for agent-${data.peer} (no live session; delivered when a session of that name next starts): "${truncate(message.trim(), 80)}"\n`,
+  );
 }
 
 async function runWait(