harnery 0.36.0 → 0.38.0

package/src/commands/agents.ts

@@ -49,6 +49,15 @@ import {
   LiveCoordinationAuthorityV3Error,
   reopenLiveCoordinationGenerationV3,
 } from "../core/agents/live-authority-v3.ts";
+import {
+  isAddressableName,
+  MailboxCapacityError,
+  type QueueResult,
+  queueMailboxMessage,
+  suggestNames,
+} from "../core/agents/mailbox.ts";
+import { qaSignalStatusRow } from "../core/agents/qa-signal.ts";
+import { reconcileCoordinationV3 } from "../core/agents/reconcile-coordination-v3.ts";
 import {
   listSessionFinalizationRequestsV3,
   observeHostDisappearedV3,
@@ -83,7 +92,10 @@ import {
 } from "../core/config.ts";
 import type { EventTypeV3 } from "../core/events/v3/contract.ts";
 import { readEventV3ControlState } from "../core/events/v3/control.ts";
-import { projectCoordinationViewV3 } from "../core/events/v3/coordination-view.ts";
+import {
+  projectCoordinationViewV3,
+  readCoordinationViewV3,
+} from "../core/events/v3/coordination-view.ts";
 import { liveInstanceIdV3 } from "../core/events/v3/live-routing.ts";
 import {
   countSummarizedSinceV3,
@@ -435,7 +447,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 +498,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 +560,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 +761,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);
@@ -2389,6 +2403,12 @@ function runStatus(opts: {
     /* non-fatal: status box should not fail on council errors */
   }
 
+  // Latest page-QA verdict for this session, with the RUNNER's clock. Session
+  // age is not QA time; without this row an operator reads "session 58m" as if
+  // the QA run took 58 minutes. Best-effort by contract — no pointer, a
+  // malformed one, or any read failure renders no row.
+  const qaSignal = qaSignalStatusRow({ coordRoot: root, instanceId: hb.instance_id });
+
   const data = {
     name: displayName,
     instance_id: hb.instance_id,
@@ -2426,6 +2446,7 @@ function runStatus(opts: {
     timestamp_iso: new Date().toISOString(),
     timestamp_local: timeStr,
     ...(quality ? { quality } : {}),
+    ...(qaSignal ? { qa: qaSignal.pointer } : {}),
     ...(finalization ? { finalization } : {}),
     ...(sessionEnd ? { session_end: sessionEnd } : {}),
   };
@@ -2464,6 +2485,10 @@ function runStatus(opts: {
     const idx = rows.findIndex((row) => row[0] === "time");
     rows.splice(idx, 0, ["quality", formatRunQuality(quality.status, quality.signal_ids)]);
   }
+  if (qaSignal) {
+    const idx = rows.findIndex((row) => row[0] === "time");
+    rows.splice(idx, 0, ["qa", qaSignal.value]);
+  }
   if (sessionEnd) {
     const idx = rows.findIndex((row) => row[0] === "time");
     rows.splice(idx, 0, [
@@ -3022,7 +3047,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 +3063,7 @@ interface HealthReport {
     latest_at: string | null;
     sessions: string[];
   };
-  anomalies: string[];
+  findings: string[];
 }
 
 /** Open-span soft watermark per producer state. The producer-state reader
@@ -3091,6 +3116,13 @@ export type EventLedgerHealthV3 =
         /** Times the summary gate failed open (loose write proceeded). */
         mitigation_fail_open: number;
       };
+      coordination_authority: {
+        safe: boolean;
+        global_diagnostics: number;
+        isolated_diagnostics: number;
+        affected_generations: string[];
+        codes: string[];
+      };
       span_pressure: Array<{ instance_id: string; generation_id: string; span_count: number }>;
       collection_errors: string[];
     };
@@ -3270,6 +3302,57 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
     collectionErrors.push(`diagnostic summaries unreadable: ${errorText(error)}`);
   }
 
+  let coordinationAuthority: Extract<
+    EventLedgerHealthV3,
+    { state: "live" }
+  >["coordination_authority"] = {
+    safe: false,
+    global_diagnostics: 0,
+    isolated_diagnostics: 0,
+    affected_generations: [],
+    codes: [],
+  };
+  try {
+    const view = readCoordinationViewV3(root);
+    const globalDiagnostics = view.global_diagnostics.filter(
+      (diagnostic) => diagnostic.authority_blocking,
+    );
+    const isolatedDiagnostics = new Map<string, (typeof globalDiagnostics)[number]>();
+    const affectedGenerations: string[] = [];
+    for (const [generationId, diagnostics] of Object.entries(view.diagnostics_by_generation)) {
+      const blocking = diagnostics.filter((diagnostic) => diagnostic.authority_blocking);
+      if (blocking.length === 0) continue;
+      affectedGenerations.push(generationId);
+      for (const diagnostic of blocking) {
+        isolatedDiagnostics.set(
+          [
+            diagnostic.code,
+            diagnostic.source_code ?? "",
+            diagnostic.event_id ?? "",
+            diagnostic.generation_id ?? "",
+            diagnostic.subject_instance_id ?? "",
+          ].join("\0"),
+          diagnostic,
+        );
+      }
+    }
+    coordinationAuthority = {
+      safe: view.authority_safe,
+      global_diagnostics: globalDiagnostics.length,
+      isolated_diagnostics: isolatedDiagnostics.size,
+      affected_generations: affectedGenerations.sort(),
+      codes: [
+        ...new Set(
+          [...globalDiagnostics, ...isolatedDiagnostics.values()].map(
+            (diagnostic) => diagnostic.source_code ?? diagnostic.code,
+          ),
+        ),
+      ].sort(),
+    };
+  } catch (error) {
+    collectionErrors.push(`coordination authority unreadable: ${errorText(error)}`);
+  }
+
   return {
     state: "live",
     mode: control.state,
@@ -3293,6 +3376,7 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
       recent_by_category: recentByCategory,
       mitigation_fail_open: mitigationFailOpen,
     },
+    coordination_authority: coordinationAuthority,
     span_pressure: spanPressure,
     collection_errors: collectionErrors,
   };
@@ -3946,8 +4030,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 +4044,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 +4069,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 +4084,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 +4093,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,11 +4127,22 @@ 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`,
     );
   }
   if (eventLedger.state === "live") {
+    const authority = eventLedger.coordination_authority;
+    if (authority.global_diagnostics > 0) {
+      findings.push(
+        `${authority.global_diagnostics} global coordination authority diagnostic(s): ${authority.codes.join(", ")}`,
+      );
+    }
+    if (authority.isolated_diagnostics > 0) {
+      findings.push(
+        `${authority.isolated_diagnostics} coordination authority diagnostic(s) isolated to ${authority.affected_generations.length} generation(s): ${authority.codes.join(", ")}`,
+      );
+    }
     // Open spans whose generation has no open turn: the turn ended without its
     // tool spans closing, so an explicit end can only queue, never finalize.
     const orphanGenerations = eventLedger.open_spans.generations.filter(
@@ -4056,17 +4153,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 +4208,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) {
@@ -4186,6 +4283,7 @@ function renderHealthBox(report: HealthReport): void {
       )
       .join(", ");
     ledgerStr = [
+      `authority ${ledger.coordination_authority.safe ? "safe" : "unsafe"}${ledger.coordination_authority.isolated_diagnostics > 0 ? ` (${ledger.coordination_authority.isolated_diagnostics} isolated)` : ""}`,
       `open spans ${ledger.open_spans.total}${orphanGenerations > 0 ? ` (${orphanGenerations} gen turn-closed)` : ""}`,
       `pending ends ${ledger.pending_finalizations.length}${pendingAges ? ` (${pendingAges})` : ""}`,
       `intake ${ledger.intake_spool.total}`,
@@ -4211,12 +4309,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 +4322,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 +4758,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 +4815,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 +4838,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(