harnery 0.34.0 → 0.35.0

package/src/commander.ts

@@ -53,6 +53,7 @@ import { registerPolicyCommand } from "./commands/policy.ts";
 import { registerPresenceCommand } from "./commands/presence.ts";
 import { registerReadCommand } from "./commands/read.ts";
 import { registerRelayCommand } from "./commands/relay.ts";
+import { registerSemanticCommand } from "./commands/semantic.ts";
 import { registerSyncCommand } from "./commands/sync.ts";
 import { registerSectionCommand, registerTocCommand } from "./commands/toc.ts";
 import { registerTokensCommand } from "./commands/tokens.ts";
@@ -290,6 +291,7 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   registerCheckpointCommand(program, emit, opts.context);
   registerJournalCommand(program, emit);
   registerLedgerV3Command(program, emit, opts.context);
+  registerSemanticCommand(program, emit, opts.context);
   registerEventsCommand(program, emit, opts.context);
   registerArtifactsCommand(program, emit, opts.context);
   registerDecisionCommand(program, emit);

package/src/commands/agents.ts

@@ -21,7 +21,6 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -38,6 +37,7 @@ import {
 import {
   emitEventV3,
   monorepoRoot,
+  nativeSessionIdentity,
   normalizeAdapter,
   resolveOwner,
   resolveOwnerBySessionEnv,
@@ -52,7 +52,10 @@ import {
   requestSessionEndExplicitV3,
   type SessionFinalizationRequestV3,
 } from "../core/agents/session-finalizer-v3.ts";
-import { SESSION_NAME_DISPLAY_NOTE } from "../core/agents/session-name-display.ts";
+import {
+  SESSION_NAME_DISPLAY_NOTE,
+  sessionNameDisplayPending,
+} from "../core/agents/session-name-display.ts";
 import {
   buildLifecycleSuggestedName,
   buildSuggestedName,
@@ -89,6 +92,7 @@ import { readLedgerV3 } from "../core/events/v3/reader.ts";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../core/events/v3/writer.ts";
 import type { RunQualitySnapshot, RunQualityStatus } from "../core/guard/index.ts";
 import { evaluateRunQualityIfDue } from "../core/guard/index.ts";
+import { readRuntimeContextUsage } from "../core/hooks/adapter/runtime-telemetry.ts";
 import { type RemoteMachine, readRemoteMachines } from "../core/presence/index.ts";
 import { registerContextCommand } from "./context.ts";
 
@@ -152,9 +156,8 @@ function freshnessCutoffSecs(): number {
 }
 
 const SUBAGENT_NOTE =
-  "Bash identity is process-level; if you're running inside a subagent, " +
-  "this resolves to the parent group's name, not the subagent's. A subagent-aware " +
-  "bridge (per-shell marker file at .harnery/shells/<pid>) is out of scope.";
+  "Native adapter subagents resolve to their own child generation after the hook bridge " +
+  "observes delegation. An unbridged subprocess shell still resolves through its parent.";
 
 /**
  * Spawn options for agent-coord child processes: pin the coord root the
@@ -248,19 +251,7 @@ function taskStateOf(hb: Pick<Heartbeat, "task_state">): TaskState {
   return hb.task_state ?? "active";
 }
 
-/** Producer joins use the private native session ID; `session_id` is the canonical V3 fingerprint. */
-export function nativeSessionIdentity(
-  row: Pick<Heartbeat, "native_session_id" | "session_id"> | null | undefined,
-  fallback: string,
-): string {
-  if (row?.native_session_id) return row.native_session_id;
-  // A projection-only row carries the privacy-safe canonical session
-  // fingerprint, not the adapter's native session ID needed to join the hook
-  // producer. Until a disposable cache exists, the resolved owner is the only
-  // native identity available to command surfaces such as `agents status`.
-  if (row?.session_id && !/^sid_[a-f0-9]{64}$/.test(row.session_id)) return row.session_id;
-  return fallback;
-}
+export { nativeSessionIdentity };
 
 function lifecycleLabel(hb: Pick<Heartbeat, "task_state" | "task_state_reason">): string {
   const state = taskStateOf(hb);
@@ -329,9 +320,9 @@ export function registerAgentsCommand(
     .command("suggest-name [description...]")
     .description(
       'Reprint a session name ("Agent <you> - <description>") for the operator to set as their ' +
-        "adapter tab title. With no arg, derives it from your current task. The primary naming path " +
+        "adapter tab title. With no arg, prefers the exact pending name, then derives from your current task. The primary naming path " +
         "is set-task (it suggests a name on the first focus declaration); reach for this to reprint " +
-        "or re-suggest after a topic pivot. Read-only.",
+        "or to create an explicit pending-display retry with --json. Read-only.",
     )
     .option("--json", "JSON output instead of the bare name")
     .option(
@@ -1854,11 +1845,18 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   // the first time. `first_of_session: true` means exactly "this call produced
   // the session name" — it is never true with a null name (an empty first
   // declaration or a `--session-id` relay both keep the window open instead).
-  const suggestedName =
-    !priorHb?.suggested_session_name && hb?.suggested_session_name
-      ? hb.suggested_session_name
-      : null;
-  const firstOfSession = suggestedName !== null;
+  // A native generation restart may rebuild the current cache during the
+  // mutation and carry an already-seen suggestion from the prior generation.
+  // That title is continuity evidence, not a new display request.
+  const pendingName = sessionNameDisplayPending(hb);
+  const firstSuggestedName = !priorHb?.suggested_session_name && pendingName ? pendingName : null;
+
+  // Routine focus declarations stay title-silent. A pending display no longer
+  // turns every repeated set-task into a fresh name instruction; explicit
+  // recovery belongs to `agents suggest-name --json`.
+  const suggestedName = firstSuggestedName;
+  const firstOfSession = firstSuggestedName !== null;
+  const sessionNameRetry = false;
 
   emit.data({
     instance_id: myOwner,
@@ -1866,6 +1864,7 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
     task: hb?.task ?? null,
     cleared: !task || task.length === 0,
     first_of_session: firstOfSession,
+    session_name_retry: sessionNameRetry,
     suggested_session_name: suggestedName,
     ...(lifecycleWarning ? { warning: lifecycleWarning } : {}),
     // Right-time instruction: the UserPromptSubmit nudge fires before the name
@@ -2093,12 +2092,16 @@ function runSuggestName(
 
   const hb = readCurrentCoordinationRow(myOwner);
   const agentName = hb?.name || "unknown";
-  // Description resolution: an explicit arg wins; with no arg, fall back to the
-  // agent's current declared task, so a bare `suggest-name` reprints the running
-  // session's name (handy after a topic pivot). Read-only — mutates no state;
-  // the primary naming path is set-task's first-of-session suggestion.
+  // A bare suggest-name must prefer the exact pending suggestion over rebuilding
+  // from the current task. The task may have changed since the title was minted;
+  // reconstructing it would produce a block the display latch can never accept.
+  // An explicit description keeps the read-only re-suggest behavior.
+  const pendingName = sessionNameDisplayPending(hb);
   const parts = descriptionParts.length > 0 ? descriptionParts : hb?.task ? [hb.task] : [];
-  const built = buildSuggestedName(agentName, parts);
+  const built =
+    descriptionParts.length === 0 && pendingName
+      ? { suggestedName: pendingName, description: hb?.task ?? pendingName }
+      : buildSuggestedName(agentName, parts);
   if (!built) {
     emit.error({
       code: "no_description",
@@ -2115,6 +2118,7 @@ function runSuggestName(
     emit.data({
       name: displayName,
       suggested_session_name: suggestedName,
+      session_name_retry: pendingName === suggestedName,
       agent_name: agentName,
       description,
     });
@@ -2519,9 +2523,9 @@ function readContextUsage(
   // Cursor doesn't surface token counts in its transcript JSONL but DOES
   // store `contextUsagePercent` per composer in workspaceStorage's state.vscdb;
   // readCursorContextUsage reads that via bun:sqlite (percent-only).
-  if (platform === "codex") return readCodexContextUsage(sessionId);
+  if (platform === "codex") return readRuntimeContextUsage("codex", sessionId);
   if (platform === "cursor") return readCursorContextUsage(sessionId);
-  return readClaudeContextUsage(sessionId);
+  return readRuntimeContextUsage("claude-code", sessionId);
 }
 
 function readCursorContextUsage(
@@ -2592,126 +2596,6 @@ function readCursorContextUsage(
   return null;
 }
 
-function readClaudeContextUsage(sessionId: string): { used: number; window: number } | null {
-  const root = monorepoRoot();
-  if (!root) return null;
-  // Claude Code's project dir scheme: prepend "-", replace "/" → "-".
-  const encoded = `-${root.replace(/^\//, "").replace(/\//g, "-")}`;
-  const transcriptPath = resolve(homedir(), ".claude", "projects", encoded, `${sessionId}.jsonl`);
-  if (!existsSync(transcriptPath)) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(transcriptPath, "utf8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split("\n");
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    try {
-      const entry = JSON.parse(line);
-      const usage = entry?.message?.usage;
-      if (entry?.type === "assistant" && usage) {
-        const used =
-          (usage.input_tokens ?? 0) +
-          (usage.cache_creation_input_tokens ?? 0) +
-          (usage.cache_read_input_tokens ?? 0);
-        // Window: hardcode 1M for Opus 4.7 1M (current default). Refine to
-        // model-aware lookup when other models become routine.
-        return { used, window: 1000000 };
-      }
-    } catch {
-      // skip malformed line
-    }
-  }
-  return null;
-}
-
-function readCodexContextUsage(sessionId: string): { used: number; window: number } | null {
-  // Codex transcripts: ~/.codex/sessions/YYYY/MM/DD/rollout-<TS>-<sessionId>.jsonl
-  // On WSL the active install often lives on the Windows side under
-  // /mnt/c/Users/<user>/.codex/sessions/; both are searched.
-  const path = findCodexTranscript(sessionId);
-  if (!path) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split("\n");
-  // Walk backwards: most recent token_count event wins.
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    try {
-      const entry = JSON.parse(line);
-      if (entry?.type === "event_msg" && entry?.payload?.type === "token_count") {
-        const info = entry.payload.info;
-        const used = info?.last_token_usage?.input_tokens;
-        const window = info?.model_context_window;
-        if (typeof used === "number" && typeof window === "number" && window > 0) {
-          return { used, window };
-        }
-      }
-    } catch {
-      // skip malformed line
-    }
-  }
-  return null;
-}
-
-function findCodexTranscript(sessionId: string): string | null {
-  // Candidate roots in priority order.
-  const homeRoot = resolve(homedir(), ".codex", "sessions");
-  const wslRoots: string[] = [];
-  try {
-    if (existsSync("/mnt/c/Users")) {
-      for (const entry of readdirSync("/mnt/c/Users")) {
-        wslRoots.push(`/mnt/c/Users/${entry}/.codex/sessions`);
-      }
-    }
-  } catch {
-    // ignore
-  }
-  const roots = [homeRoot, ...wslRoots];
-  const suffix = `-${sessionId}.jsonl`;
-  for (const root of roots) {
-    if (!existsSync(root)) continue;
-    try {
-      // Recursive scan: sessions are partitioned by YYYY/MM/DD/, so depth
-      // is bounded at 3 + one file per session. Cheap enough at status time.
-      const stack: string[] = [root];
-      while (stack.length) {
-        const dir = stack.pop()!;
-        let entries: string[];
-        try {
-          entries = readdirSync(dir);
-        } catch {
-          continue;
-        }
-        for (const name of entries) {
-          const full = `${dir}/${name}`;
-          try {
-            const stat = statSync(full);
-            if (stat.isDirectory()) {
-              stack.push(full);
-            } else if (name.endsWith(suffix)) {
-              return full;
-            }
-          } catch {
-            // ignore
-          }
-        }
-      }
-    } catch {
-      // ignore root scan failures
-    }
-  }
-  return null;
-}
-
 function formatLocalTime(d: Date): string {
   // "Sat, May 9, 2026, 3:48 AM CDT", rendered in the Chicago timezone.
   return new Intl.DateTimeFormat("en-US", {
@@ -3119,6 +3003,15 @@ interface HealthReport {
   // V3 event-ledger producer health: open tool spans, pending finalization
   // requests, intake/diagnostics spool depth, span-count pressure.
   event_ledger: EventLedgerHealthV3;
+  // Stop-hook remediation cap exhaustions in the window: sessions whose
+  // end-of-turn evidence never landed, so the hook stopped bouncing them and
+  // let the turn end unenforced. Each one is a session that could not comply —
+  // the signal that used to be visible only as a repeating notification sound.
+  stop_remediation: {
+    total: number;
+    latest_at: string | null;
+    sessions: string[];
+  };
   anomalies: string[];
 }
 
@@ -3325,6 +3218,50 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
   };
 }
 
+/**
+ * Tally stop-hook remediation-cap exhaustions in the window from
+ * `.harnery/debug/agent-hook.ndjson` (rows with
+ * `skipped: "stop-remediation-cap-exhausted"`). Each one is a session whose
+ * end-of-turn evidence never landed, so the Stop hook gave up bouncing it and
+ * let the turn end unenforced — a compliance gap an operator should see
+ * without grepping the debug ledger.
+ */
+export function readStopRemediationExhaustions(
+  root: string,
+  cutoffMs: number,
+): { total: number; latestAt: string | null; sessions: string[] } {
+  const p = resolve(root, ".harnery", "debug", "agent-hook.ndjson");
+  if (!existsSync(p)) return { total: 0, latestAt: null, sessions: [] };
+  let raw: string;
+  try {
+    raw = readFileSync(p, "utf8");
+  } catch {
+    return { total: 0, latestAt: null, sessions: [] };
+  }
+  let total = 0;
+  let latestMs = Number.NEGATIVE_INFINITY;
+  const sessions = new Set<string>();
+  for (const line of raw.split("\n")) {
+    if (!line.includes("stop-remediation-cap-exhausted")) continue;
+    try {
+      const e = JSON.parse(line) as { ts?: string; skipped?: string; session_id?: string };
+      if (e.skipped !== "stop-remediation-cap-exhausted") continue;
+      const tsMs = e.ts ? Date.parse(e.ts) : Number.NaN;
+      if (!Number.isFinite(tsMs) || tsMs < cutoffMs) continue;
+      total++;
+      latestMs = Math.max(latestMs, tsMs);
+      if (e.session_id && sessions.size < 5) sessions.add(e.session_id);
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return {
+    total,
+    latestAt: Number.isFinite(latestMs) ? new Date(latestMs).toISOString() : null,
+    sessions: [...sessions],
+  };
+}
+
 /** Tally agent-hook failures (.harnery/debug/agent-hook.errors.ndjson) in the
  * window by exact error and phase, while separating current-hour failures from
  * historical rows. Each line is {ts, error, phase, ...}. */
@@ -3885,6 +3822,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
   }
 
   const hookErrors = readHookErrors(root, cutoffMs, nowMs);
+  const stopRemediation = readStopRemediationExhaustions(root, cutoffMs);
   const stream = readStreamStats(root);
   const eventLedger = collectEventLedgerHealthV3(root);
 
@@ -4004,6 +3942,15 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       `${zombieCount} zombie heartbeat(s) in active/ (${zombieSamples.join(", ")}); broken files the sweep isn't reaping`,
     );
   }
+  if (stopRemediation.total > 0) {
+    const who =
+      stopRemediation.sessions.length > 0
+        ? ` (sessions: ${stopRemediation.sessions.map((s) => s.slice(0, 8)).join(", ")})`
+        : "";
+    anomalies.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") {
     // 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.
@@ -4072,6 +4019,11 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     stream,
     zombies: { count: zombieCount, samples: zombieSamples },
     event_ledger: eventLedger,
+    stop_remediation: {
+      total: stopRemediation.total,
+      latest_at: stopRemediation.latestAt,
+      sessions: stopRemediation.sessions,
+    },
     anomalies,
   };
 

package/src/commands/browse.ts

@@ -24,6 +24,7 @@ import {
   parseAssertSpec,
   type RuntsResult,
   runCritique,
+  type StandaloneHtmlResult,
   type TargetSizeProfile,
   type TargetSizeResult,
   tilesFromFullPage,
@@ -1529,9 +1530,22 @@ async function runTrioMode(
     throw new Error("--capture-evaluate requires a screenshot; remove --no-screenshot.");
   }
 
+  // A trio `.html` is opened in a browser later — from the files origin, from
+  // another machine, from disk — so it has to carry its own CSS and media. A
+  // selector capture is a DOM fragment, not a document, and stays raw.
   const htmlPath = `${prefix}.html`;
-  const html = await browser.htmlContent(opts.selector);
-  writeFileSync(htmlPath, html);
+  let snapshot: StandaloneHtmlResult | undefined;
+  if (opts.selector) {
+    writeFileSync(htmlPath, await browser.htmlContent(opts.selector));
+  } else {
+    try {
+      snapshot = await browser.standaloneHtml();
+      writeFileSync(htmlPath, snapshot.html);
+    } catch {
+      // Inlining is best-effort; a raw serialization beats no snapshot at all.
+      writeFileSync(htmlPath, await browser.htmlContent());
+    }
+  }
   written.push(htmlPath);
 
   const diag = browser.diagnostics();
@@ -1548,6 +1562,15 @@ async function runTrioMode(
     ...summarizeDiagnostics(diag),
   };
   if (pngBytes !== undefined) envelope.screenshotBytes = pngBytes;
+  if (snapshot) {
+    envelope.htmlSnapshot = {
+      stylesheetsInlined: snapshot.stylesheetsInlined,
+      stylesheetsLinked: snapshot.stylesheetsLinked,
+      resourcesInlined: snapshot.resourcesInlined,
+      resourcesLinked: snapshot.resourcesLinked,
+      inlinedBytes: snapshot.inlinedBytes,
+    };
+  }
   if (opts.evaluate) envelope.eval = evalResult;
   if (opts.captureEvaluate) {
     envelope.captureEval = captureEvalResult;

package/src/commands/decision.ts

@@ -1,7 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
-import { emitEventV3, monorepoRoot, normalizeAdapter, resolveOwner } from "../core/agents/index.ts";
+import {
+  emitEventV3,
+  monorepoRoot,
+  nativeSessionIdentity,
+  normalizeAdapter,
+  resolveOwner,
+} from "../core/agents/index.ts";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
 import { resolveBinName } from "../core/config.ts";
 import {
@@ -442,7 +448,7 @@ function emitDecisionEvent(
   const hb = root ? readLiveCoordinationRow(root, owner) : null;
   emitEventV3({
     owner,
-    session: hb?.session_id ?? owner,
+    session: nativeSessionIdentity(hb, owner),
     adapter: normalizeAdapter(hb?.platform),
     observation: {
       event_type: "decision.state_changed",

package/src/commands/events.ts

@@ -25,6 +25,7 @@ interface GenerationLatencyRow {
   tool_ms: LatencyMetricV3;
   command_ms: LatencyMetricV3;
   wait_ms: LatencyMetricV3;
+  agent_action_ms: LatencyMetricV3;
   inference_ms: LatencyMetricV3;
   harness_ms: LatencyMetricV3;
   residual_ms: LatencyMetricV3;
@@ -112,6 +113,9 @@ function summarizeByGeneration(turns: TurnLatencyV3[]): GenerationLatencyRow[] {
       tool_ms: sumMetrics(group.map(({ tool_ms }) => tool_ms)),
       command_ms: sumMetrics(group.map(({ command_exclusive_ms }) => command_exclusive_ms)),
       wait_ms: sumMetrics(group.map(({ wait_ms }) => wait_ms)),
+      agent_action_ms: sumMetrics(
+        group.map(({ response_latency }) => response_latency.agent_action_ms),
+      ),
       inference_ms: sumMetrics(group.map(({ inference_ms }) => inference_ms)),
       harness_ms: sumMetrics(group.map(({ harness_ms }) => harness_ms)),
       residual_ms: sumMetrics(group.map(({ residual_ms }) => residual_ms)),
@@ -180,6 +184,8 @@ function renderTurns(turns: TurnLatencyV3[]): string {
       "TOOL",
       "COMMAND",
       "WAIT",
+      "ACTION",
+      "POST-TOOL",
       "INFERENCE",
       "HARNESS",
       "RESIDUAL",
@@ -192,6 +198,8 @@ function renderTurns(turns: TurnLatencyV3[]): string {
       formatMetric(turn.tool_ms),
       formatMetric(turn.command_exclusive_ms),
       formatMetric(turn.wait_ms),
+      formatMetric(turn.response_latency.agent_action_ms),
+      formatMetric(turn.response_latency.post_tool_response_ms),
       formatMetric(turn.inference_ms),
       formatMetric(turn.harness_ms),
       formatMetric(turn.residual_ms),
@@ -202,7 +210,18 @@ function renderTurns(turns: TurnLatencyV3[]): string {
 
 function renderGenerations(rows: GenerationLatencyRow[]): string {
   return renderTable(
-    ["GENERATION", "TURNS", "WALL", "TOOL", "COMMAND", "WAIT", "INFERENCE", "HARNESS", "RESIDUAL"],
+    [
+      "GENERATION",
+      "TURNS",
+      "WALL",
+      "TOOL",
+      "COMMAND",
+      "WAIT",
+      "ACTION",
+      "INFERENCE",
+      "HARNESS",
+      "RESIDUAL",
+    ],
     rows.map((row) => [
       row.generation_id,
       String(row.turns),
@@ -210,6 +229,7 @@ function renderGenerations(rows: GenerationLatencyRow[]): string {
       formatMetric(row.tool_ms),
       formatMetric(row.command_ms),
       formatMetric(row.wait_ms),
+      formatMetric(row.agent_action_ms),
       formatMetric(row.inference_ms),
       formatMetric(row.harness_ms),
       formatMetric(row.residual_ms),

package/src/commands/presence.ts

@@ -1,7 +1,12 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { monorepoRoot } from "../core/agents/coord-client.ts";
-import { emitEventV3, normalizeAdapter, resolveOwner } from "../core/agents/index.ts";
+import {
+  emitEventV3,
+  nativeSessionIdentity,
+  normalizeAdapter,
+  resolveOwner,
+} from "../core/agents/index.ts";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
 import {
   fetchPresence,
@@ -253,7 +258,7 @@ function emitPresenceChange(
   const hb = root ? readLiveCoordinationRow(root, owner) : null;
   emitEventV3({
     owner,
-    session: hb?.session_id ?? owner,
+    session: nativeSessionIdentity(hb, owner),
     adapter: normalizeAdapter(hb?.platform),
     observation: {
       event_type: "coord.presence_changed",