harnery 0.5.0 → 0.7.0

package/src/commands/agents.ts

@@ -28,6 +28,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { readStreamTailBounded } from "../core/agents/events/consume.ts";
 import {
   emitCanonical,
   type Heartbeat,
@@ -35,10 +36,18 @@ import {
   normalizeHarness,
   readHeartbeat,
   resolveOwner,
+  resolveOwnerBySessionEnv,
   resolveOwnerWithSource,
 } from "../core/agents/index.ts";
 import { resolveBinName } from "../core/config.ts";
+
+/** Cap for CLI scans of the unbounded event ledger (`trace` / `health`). Well
+ * under V8's ~512MB max string length so a `readFileSync` of the whole file can
+ * never throw; covers ample recent history for a diagnostic scan. */
+const STREAM_SCAN_CAP_BYTES = 128 * 1024 * 1024; // 128 MiB
+
 import { parsePsChainLine } from "../core/hooks/resolve/anchor.ts";
+import { appendEntry, resolveOwnerByName } from "../core/scratch/index.ts";
 import {
   buildCouncilId,
   buildInviteMarkdown,
@@ -73,7 +82,6 @@ import {
   lookupById as lookupIdentityById,
   lookupByName as lookupIdentityByName,
 } from "../lib/identities/index.ts";
-import { appendEntry, resolveOwnerByName } from "../lib/scratch/index.ts";
 
 const FRESHNESS_SECS = 600; // 10-minute heartbeat-freshness window.
 
@@ -159,8 +167,7 @@ export function registerAgentsCommand(program: Command, emitParam: EmitContext):
   cmd
     .command("show <name>")
     .description(
-      "Deep-dive on one peer agent: registry state (files held, last tool, task) " +
-        "plus claude-sessions history (latest title, recent prompts, recent tools, tool-usage tallies). " +
+      "Deep-dive on one peer agent: registry state (files held, last tool, task, turn summary). " +
         "Disambiguates name → instance_id via prefix match.",
     )
     .option("--json", "JSON envelope output")
@@ -687,6 +694,7 @@ function runWhoami(opts: { json?: boolean }): void {
     process.exit(1);
   }
 
+  ensureCursorSession(root);
   const resolved = resolveOwnerWithSource();
   const myOwner = resolved.owner;
   if (!myOwner) {
@@ -1165,6 +1173,50 @@ function formatLocalShort(iso: string): string {
   }).format(d);
 }
 
+function cursorEnvSessionId(): string | null {
+  const raw = process.env.CURSOR_SESSION_ID?.trim() || process.env.CURSOR_CONVERSATION_ID?.trim();
+  if (!raw) return null;
+  return raw.startsWith("bc-") && raw.length > 3 ? raw.slice(3) : raw;
+}
+
+function shouldBootstrapCursorSession(): boolean {
+  return process.env.CURSOR_AGENT === "1" && cursorEnvSessionId() !== null;
+}
+
+function ensureCursorSession(root: string): void {
+  if (!shouldBootstrapCursorSession()) return;
+  if (resolveOwnerBySessionEnv(root)) return;
+
+  const sessionId = cursorEnvSessionId();
+  if (!sessionId) return;
+  const agentHook = resolve(root, "harnery", "bin", "agent-hook");
+  if (!existsSync(agentHook)) return;
+
+  const payload = JSON.stringify({
+    conversation_id: sessionId,
+    session_id: sessionId,
+    hook_event_name: "sessionStart",
+    workspace_roots: [root],
+    cwd: root,
+    composer_mode: "agent",
+    is_background_agent: false,
+  });
+
+  spawnSync("bash", [agentHook, "session-start", "--harness", "cursor"], {
+    input: payload,
+    cwd: root,
+    encoding: "utf8",
+    timeout: 3000,
+    env: {
+      ...process.env,
+      HARNERY_AGENT_COORD_PLATFORM: "cursor",
+      HARNERY_COORD_ROOT_OVERRIDE: root,
+      CURSOR_SESSION_ID: sessionId,
+      CURSOR_CONVERSATION_ID: sessionId,
+    },
+  });
+}
+
 function runReleaseClaim(path: string): void {
   const root = monorepoRoot();
   if (!root) {
@@ -1213,6 +1265,7 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   // Identity: prefer explicit --session-id (the ppid-walk-free escape hatch,
   // mirrors `status`), fall back to the ppid walk. Cursor shell tool calls
   // don't descend from a pid-map-registered anchor, so the walk can miss there.
+  if (!opts?.sessionId) ensureCursorSession(root);
   const myOwner = opts?.sessionId ?? resolveOwner();
   if (!myOwner) {
     emit.error({
@@ -1265,6 +1318,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
 
   // Identity resolution: prefer explicit --session-id (hook-friendly), fall
   // back to ppid walk for interactive shell usage.
+  if (!opts.sessionId) ensureCursorSession(root);
   const myOwner = opts.sessionId ?? resolveOwner();
   if (!myOwner) {
     emit.error({
@@ -2098,8 +2152,12 @@ function readStreamStats(root: string): { bytes: number; lines: number; cursor_b
   let backlog = 0;
   let seenCursor = cursor === null; // no cursor → everything is "backlog"
   try {
-    const raw = readFileSync(streamPath, "utf8");
-    for (const line of raw.split("\n")) {
+    // Bounded tail read: the ledger grows without bound and a whole-file
+    // readFileSync throws past V8's ~512MB string limit. lines/backlog are then
+    // scoped to the scanned window; `bytes` (full size, via statSync above) still
+    // reflects the true stream size for the health rollup.
+    const { text } = readStreamTailBounded(streamPath, STREAM_SCAN_CAP_BYTES);
+    for (const line of text.split("\n")) {
       if (!line.trim()) continue;
       lines++;
       if (seenCursor) {
@@ -2225,24 +2283,34 @@ function runTrace(
   const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 200);
   const candidateIds = targetId.includes("\x00") ? targetId.split("\x00") : [targetId];
 
-  // Scan the full stream once, bucket events by instance_id for the candidates.
+  // Scan the stream tail once, bucket events by instance_id for the candidates.
+  // Bounded read: the ledger grows without bound and a whole-file readFileSync
+  // throws past V8's ~512MB string limit. A trace of an agent whose events all
+  // predate the window is reported as truncated rather than crashing.
   const streamPath = resolve(root, ".harnery", "events.ndjson");
   const byId = new Map<string, CanonicalEvent[]>();
-  if (existsSync(streamPath)) {
-    for (const line of readFileSync(streamPath, "utf8").split("\n")) {
-      if (!line) continue;
-      try {
-        const ev = JSON.parse(line) as CanonicalEvent;
-        if (!ev.instance_id || !candidateIds.includes(ev.instance_id)) continue;
-        if (sinceMs && Date.parse(ev.ts) < sinceMs) continue;
-        const arr = byId.get(ev.instance_id) ?? [];
-        arr.push(ev);
-        byId.set(ev.instance_id, arr);
-      } catch {
-        /* skip */
-      }
+  const { text: streamText, truncated: streamTruncated } = readStreamTailBounded(
+    streamPath,
+    STREAM_SCAN_CAP_BYTES,
+  );
+  for (const line of streamText.split("\n")) {
+    if (!line) continue;
+    try {
+      const ev = JSON.parse(line) as CanonicalEvent;
+      if (!ev.instance_id || !candidateIds.includes(ev.instance_id)) continue;
+      if (sinceMs && Date.parse(ev.ts) < sinceMs) continue;
+      const arr = byId.get(ev.instance_id) ?? [];
+      arr.push(ev);
+      byId.set(ev.instance_id, arr);
+    } catch {
+      /* skip */
     }
   }
+  if (streamTruncated) {
+    process.stderr.write(
+      `note: event ledger exceeds ${Math.round(STREAM_SCAN_CAP_BYTES / 1024 / 1024)}MB; traced only the most recent window (older events omitted)\n`,
+    );
+  }
 
   // If the name mapped to multiple instances, trace the one with the latest event.
   let resolvedId = candidateIds[0]!;
@@ -2629,7 +2697,7 @@ function renderHealthBox(report: HealthReport): void {
   const localTime = formatLocalTime(new Date(report.generated_at));
   const title = `Coord Health (${localTime})`;
 
-  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 + bp-session-teed contexts
+  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) {
     process.stdout.write("\n"); // lint-ok-emission: same chat-paste path
@@ -2686,7 +2754,7 @@ function runHarnessProbe(
   // and `resolveOwner` here, so the probe reports exactly what the live hot
   // path resolves.
   const anchorTokens = new Set(["claude", "claude-code", "cursor", "codex"]);
-  const override = process.env.BP_AGENT_COORD_TEST_ANCHOR_PID;
+  const override = process.env.HARNERY_AGENT_COORD_TEST_ANCHOR_PID;
   let anchorPid = override && Number(override) > 0 ? override : "";
   const chainParts: string[] = [];
   let walkPid = process.pid;
@@ -2795,12 +2863,12 @@ function runHarnessProbe(
  * dispatcher in an isolated sandbox.
  *
  * Sandbox isolation strategy:
- *   - mkdtempSync(tmpdir(), "bp-harness-probe-") creates a non-git tmp dir.
+ *   - mkdtempSync(tmpdir(), "harn-harness-probe-") creates a non-git tmp dir.
  *   - The dispatcher's coord-root resolution falls back to
- *     `BP_COORD_ROOT_OVERRIDE` when git rev-parse fails. We set it to the sandbox.
+ *     `HARNERY_COORD_ROOT_OVERRIDE` when git rev-parse fails. We set it to the sandbox.
  *   - We rewrite the payload's `cwd` field (Cursor cds to it) to the sandbox,
  *     so real `.harnery/` never gets touched.
- *   - We set `BP_AGENT_COORD_OFF=0` explicitly so any user-side off-switch in
+ *   - We set `HARNERY_AGENT_COORD_OFF=0` explicitly so any user-side off-switch in
  *     the environment doesn't mask adapter crashes.
  *
  * Sample shape: probe-meta wrapped (`_probe_meta.event` + `.payload`) OR bare
@@ -2880,7 +2948,7 @@ function replayHarnessSamples(
   };
   const harnessFlag = harness === "claude_code" ? "claude-code" : harness;
 
-  const sandbox = mkdtempSync(join(tmpdir(), "bp-harness-probe-"));
+  const sandbox = mkdtempSync(join(tmpdir(), "harn-harness-probe-"));
   const results: SampleReplayResult[] = [];
 
   try {
@@ -2928,10 +2996,10 @@ function replayHarnessSamples(
         timeout: 10_000,
         env: {
           ...process.env,
-          BP_COORD_ROOT_OVERRIDE: sandbox,
-          BP_AGENT_COORD_HARNESS: harness,
-          BP_AGENT_COORD_PLATFORM: harness,
-          BP_AGENT_COORD_OFF: "0",
+          HARNERY_COORD_ROOT_OVERRIDE: sandbox,
+          HARNERY_AGENT_COORD_HARNESS: harness,
+          HARNERY_AGENT_COORD_PLATFORM: harness,
+          HARNERY_AGENT_COORD_OFF: "0",
         },
       });
 

package/src/commands/browse-ai.ts

@@ -99,7 +99,7 @@ function runBrowseAi(url: string, opts: BrowseAiOpts): void {
   const jar =
     opts.cookies === false
       ? null
-      : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "bp-browse-ai" });
+      : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse-ai" });
   const ab = new AgentBrowser({
     jar,
     timeoutMs: Number.parseInt(opts.timeout, 10),

package/src/commands/browse.ts

@@ -10,6 +10,7 @@ import {
   type DevOverlayResult,
   type Diagnostics,
   type OverflowResult,
+  type RuntsResult,
   type VisibilityResult,
   type WidthResult,
 } from "../lib/browser/index.ts";
@@ -77,16 +78,22 @@ interface BrowseOpts {
   checkVisibleThreshold?: string;
   checkVisibleFail?: boolean;
   checkVisibleSampleGrid?: string;
-  checkVisibleNoAnnotate?: boolean;
+  // Commander maps `--no-check-visible-annotate` to `checkVisibleAnnotate: false`.
+  checkVisibleAnnotate?: boolean;
   // Width-fill check
   checkWidth?: string[];
   checkWidthThreshold?: string;
   checkWidthFail?: boolean;
-  checkWidthNoAnnotate?: boolean;
+  checkWidthAnnotate?: boolean;
+  // `--check-runts [selector]`: true = whole body, string = scope selector.
+  checkRunts?: boolean | string;
+  checkRuntsMinChars?: string;
+  checkRuntsFail?: boolean;
+  checkRuntsAnnotate?: boolean;
   // Horizontal-overflow check
   checkOverflow?: boolean;
   checkOverflowFail?: boolean;
-  checkOverflowNoAnnotate?: boolean;
+  checkOverflowAnnotate?: boolean;
   // Visual regression
   baseline?: string;
   diff?: string;
@@ -232,6 +239,24 @@ export function registerBrowseCommand(
       "--no-check-overflow-annotate",
       "Skip drawing overflow annotations on the screenshot (JSON still emitted).",
     )
+    .option(
+      "--check-runts [selector]",
+      "Scan text blocks for runts (a single word alone on a block's last visual line) " +
+        "by counting words on the last line via per-word Range rects — width thresholds " +
+        "miss narrow-column runts. Optional selector scopes the sweep (default: whole body). " +
+        "Atomic tokens (URLs, emails, phone numbers) are excluded. Reports hits in the JSON " +
+        "envelope under `runts` and annotates them on the screenshot.",
+    )
+    .option(
+      "--check-runts-min-chars <n>",
+      "Minimum block text length to scan (default 40; smaller labels can't meaningfully wrap).",
+      "40",
+    )
+    .option("--check-runts-fail", "Exit non-zero if any runt is detected.")
+    .option(
+      "--no-check-runts-annotate",
+      "Skip drawing runt boxes on the screenshot (JSON still emitted).",
+    )
     .option(
       "--baseline <name>",
       "Save the captured screenshot as a named baseline at " +
@@ -275,7 +300,7 @@ async function runBrowse(
   const jar =
     opts.cookies === false
       ? null
-      : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "bp-browse" });
+      : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse" });
   const headed = opts.login || opts.headed;
   const viewport = parseViewport(opts.viewport ?? "desktop");
 
@@ -330,7 +355,7 @@ async function runBrowse(
       visibility = await browser.checkVisibility(opts.checkVisible, {
         sampleGrid: Number.parseInt(opts.checkVisibleSampleGrid ?? "3", 10),
       });
-      if (opts.checkVisibleNoAnnotate !== true) {
+      if (opts.checkVisibleAnnotate !== false) {
         await browser.annotateVisibility(visibility);
       }
     }
@@ -343,9 +368,16 @@ async function runBrowse(
     if (opts.checkOverflow) {
       overflow = await browser.checkOverflow();
     }
+    let runts: RuntsResult | undefined;
+    if (opts.checkRunts) {
+      runts = await browser.checkRunts({
+        scope: typeof opts.checkRunts === "string" ? opts.checkRunts : null,
+        minChars: Number.parseInt(opts.checkRuntsMinChars ?? "40", 10),
+      });
+    }
     const widthThreshold = Number.parseFloat(opts.checkWidthThreshold ?? "0.9");
-    const annotateWidth = widths && opts.checkWidthNoAnnotate !== true;
-    const annotateOverflow = overflow && opts.checkOverflowNoAnnotate !== true;
+    const annotateWidth = widths && opts.checkWidthAnnotate !== false;
+    const annotateOverflow = overflow && opts.checkOverflowAnnotate !== false;
     if (annotateWidth || annotateOverflow) {
       await browser.annotateLayout({
         widths: annotateWidth ? widths! : [],
@@ -353,6 +385,10 @@ async function runBrowse(
         widthThreshold,
       });
     }
+    const annotateRunts = runts && runts.runts.length > 0 && opts.checkRuntsAnnotate !== false;
+    if (annotateRunts) {
+      await browser.annotateRunts(runts!);
+    }
 
     if (opts.login) {
       await new Promise<void>((res) => {
@@ -385,6 +421,7 @@ async function runBrowse(
         visibility,
         widths,
         overflow,
+        runts,
         devOverlay,
         batchResult,
       );
@@ -397,17 +434,21 @@ async function runBrowse(
         visibility,
         widths,
         overflow,
+        runts,
         devOverlay,
         batchResult,
       );
     }
 
-    if (visibility && opts.checkVisibleNoAnnotate !== true) {
+    if (visibility && opts.checkVisibleAnnotate !== false) {
       await browser.clearVisibilityAnnotations();
     }
     if (annotateWidth || annotateOverflow) {
       await browser.clearLayoutAnnotations();
     }
+    if (annotateRunts) {
+      await browser.clearRuntsAnnotations();
+    }
 
     if (opts.checkVisibleFail && visibility) {
       const threshold = Number.parseFloat(opts.checkVisibleThreshold ?? "0.9");
@@ -446,6 +487,16 @@ async function runBrowse(
       }
     }
 
+    if (opts.checkRuntsFail && runts && runts.runts.length > 0) {
+      for (const hit of runts.runts) {
+        emit.log(
+          `check-runts FAIL ${hit.block}: last line is a lone "${hit.word}" ("…${hit.snippet.slice(-40)}")`,
+          "warn",
+        );
+      }
+      process.exitCode = 2;
+    }
+
     if (opts.checkOverflowFail && overflow?.hasHorizontalOverflow) {
       const culprit = overflow.widerThanViewport[0] ?? overflow.rightOverflow[0] ?? null;
       const detail = culprit
@@ -578,6 +629,7 @@ async function runPrintMode(
   visibility: VisibilityResult[] | undefined,
   widths: WidthResult[] | undefined,
   overflow: OverflowResult | undefined,
+  runts: RuntsResult | undefined,
   devOverlay: DevOverlayResult | undefined,
   batchResult: BatchResult | undefined,
 ): Promise<void> {
@@ -605,6 +657,7 @@ async function runPrintMode(
     if (visibility) result.visibility = visibility;
     if (widths) result.width = widths;
     if (overflow) result.overflow = overflow;
+    if (runts) result.runts = runts;
     if (devOverlay) result.devOverlay = devOverlay;
     if (batchResult && batchResult.clipboardReads.length > 0) {
       result.batchClipboardReads = batchResult.clipboardReads;
@@ -634,6 +687,7 @@ async function runTrioMode(
   visibility: VisibilityResult[] | undefined,
   widths: WidthResult[] | undefined,
   overflow: OverflowResult | undefined,
+  runts: RuntsResult | undefined,
   devOverlay: DevOverlayResult | undefined,
   batchResult: BatchResult | undefined,
 ): Promise<void> {
@@ -675,6 +729,7 @@ async function runTrioMode(
   if (visibility) envelope.visibility = visibility;
   if (widths) envelope.width = widths;
   if (overflow) envelope.overflow = overflow;
+  if (runts) envelope.runts = runts;
   if (devOverlay) envelope.devOverlay = devOverlay;
   if (batchResult && batchResult.clipboardReads.length > 0) {
     envelope.batchClipboardReads = batchResult.clipboardReads;

package/src/commands/cookies.ts

@@ -22,7 +22,7 @@ interface CommonOpts {
 function jarFrom(opts: CommonOpts): CookieJar {
   return new CookieJar({
     path: opts.store ?? DEFAULT_STORE,
-    source: "bp-cookies",
+    source: "harn-cookies",
   });
 }