harnery 0.5.0 → 0.7.0

package/README.md

@@ -7,23 +7,24 @@
 
 # Harnery
 
-> Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.
+> Multi-agent coordination for AI coding agents — Claude Code, Cursor, and Codex.
 
 [![CI](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/harnery.svg)](https://www.npmjs.com/package/harnery)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> ⚠️ **Pre-1.0.** API surface is still settling. Pin a specific minor version (`harnery@^0.1.0`) and read the [CHANGELOG](CHANGELOG.md) before each upgrade.
+> ⚠️ **Pre-1.0.** API surface is still settling. Pin a specific minor version (`harnery@^0.7.0`) and read the [CHANGELOG](CHANGELOG.md) before each upgrade.
 
 ## What it is
 
-`harnery` is a utility layer extracted from years of building agent tooling across a multi-project monorepo. It bundles:
+`harnery` keeps multiple AI coding agents from stepping on each other in a shared checkout. It was extracted from years of running several Claude Code / Cursor / Codex sessions at once against the same monorepo:
 
-- **Multi-agent coordination:** per-agent heartbeats in `.harnery/active/`, claim-time and commit-time guards, the canonical event stream, harness adapters for Claude Code / Cursor / Codex.
-- **Portable CLI utilities:** `tokens`, `eml`, `env`, `grep`, `docs`, `repo`, `wip`, `share`, `browse`, `fetch`, `read`, and more. Cross-platform and dependency-light, with sensible defaults out of the box.
-- **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, and per-project state. Ships with the git clone, not the npm package (see [Install](#install)).
+- **Multi-agent coordination:** per-agent heartbeats in `.harnery/active/`, claim-time and commit-time guards, the canonical event stream, councils, a decision docket, per-agent scratchpads, and harness adapters for Claude Code / Cursor / Codex.
+- **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 
+The CLI also ships batteries: portable utility commands (`tokens`, `eml`, `env`, `grep`, `docs`, `browse`, `fetch`, `read`, `devtools`, and more) plus the library toolkit they're built from. Useful, cross-platform, dependency-light — and deliberately not the headline. Coordination is why harnery exists; the toolkit exists because the CLI needed it (see [Public surface tiers](#public-surface-tiers)).
+
 ## Install
 
 ```bash
@@ -80,6 +81,15 @@ await program.parseAsync(process.argv);
 
 `mycli agents status` then resolves to **the same code** as `harn agents status`, loaded as a library. See [examples/extending-with-commander.ts](examples/extending-with-commander.ts) for the full pattern.
 
+### Public surface tiers
+
+The exports map draws the line between what harnery *is* and what it *ships with*:
+
+- **Product tier** — `harnery`, `harnery/commander`, `harnery/core/*`: the coordination layer and CLI composition. This is the API to build against, and the reason to install harnery.
+- **Toolkit tier** — every `harnery/lib/*` subpath (`http`, `cookies`, `format`, `readability`, `browser`, `machine`, …): the supporting utilities harnery's own CLI is built from, exposed for embedding hosts that want to lean on them. Supported, but secondary: it can evolve faster than the product tier, and it isn't a reason to adopt harnery on its own.
+
+The boundary is enforced, not aspirational: CI verifies that no `harnery/lib/*` export imports the coordination core, directly or transitively (`scripts/check-layering.ts`), so pulling a toolkit module never drags in coordination state. Details: [Embedding + surface tiers](https://harnery.com/concepts/embedding/).
+
 ## Documentation
 
 Full docs at **[harnery.com](https://harnery.com)**:

package/dist/commander.d.ts

@@ -42,6 +42,18 @@ export interface HarneryContextOpts {
      */
     skipCommands?: readonly string[];
 }
+/** One row in a `harn env` section report. */
+export interface EnvCheck {
+    label: string;
+    value: string;
+    status?: "ok" | "missing" | "warn" | "info";
+}
+/**
+ * A `harn env` section: an async probe returning its rows. Hosts register extra
+ * sections (e.g. cloud-provider connectivity) via `context.envSections`; harnery
+ * core ships only the generic sections (runtimes, docker, git).
+ */
+export type EnvSection = () => Promise<EnvCheck[]>;
 export interface HarneryProgramContext {
     /** Project name (e.g., "my-monorepo"). Used in user-facing log lines + telemetry tags. */
     projectName?: string;
@@ -59,6 +71,13 @@ export interface HarneryProgramContext {
      * submodule row.
      */
     submodules?: readonly string[];
+    /**
+     * Extra `harn env` sections keyed by name (e.g. `{ gcp, bq }`). Merged into
+     * the built-in generic sections (runtimes, docker, git), so a host can expose
+     * `harn env <name>` for its own environment probes without harnery core
+     * carrying provider-specific checks. harn standalone ships none.
+     */
+    envSections?: Record<string, EnvSection>;
     /**
      * Optional callback that returns extra HTTP headers to attach to outbound
      * `fetch` calls based on the target URL. Useful for consumers that need
@@ -91,6 +110,16 @@ export interface HarneryProgramContext {
      * exclusions (`.claude/`, `.harnery/`, `.codex/`, `.cursor/`).
      */
     extraDocsExcludedPrefixes?: readonly string[];
+    /**
+     * Filenames permitted at the host project's `docs/` root (parent repo only).
+     * When set, `harn docs lint` flags any other `.md`/`.json` file sitting
+     * loose at `docs/` root (rule `docs-root-file`) — topic docs belong in
+     * `docs/<topic>/` subdirs. Names are matched exactly (basename). When
+     * omitted or empty, the rule is a no-op, so standalone `harn` and consumers
+     * that don't opt in are unaffected. Submodule `docs/` roots are never
+     * checked (their entry tiers differ from the parent's).
+     */
+    docsRootAllowlist?: readonly string[];
     /**
      * Default Host header for `tunnel up` when `--vhost` is omitted: a literal
      * host, or a resolver evaluated at start time (e.g. read a dev stack's

package/dist/commander.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA2C3E"}
+{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA6C3E"}

package/dist/commander.js

@@ -26,7 +26,9 @@ import { registerCompletionCommand } from "./commands/completion.js";
 import { registerConfigGetCommand } from "./commands/config-get.js";
 import { registerContextCommand } from "./commands/context.js";
 import { registerCookiesCommand } from "./commands/cookies.js";
+import { registerDecisionCommand } from "./commands/decision.js";
 import { registerDeinitCommand } from "./commands/deinit.js";
+import { registerDevtoolsCommand } from "./commands/devtools.js";
 import { registerDocsCommand } from "./commands/docs.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerEditBatchCommand } from "./commands/edit-batch.js";
@@ -110,6 +112,8 @@ export function createHarneryProgram(opts = {}) {
     registerCompletionCommand(program, emit, opts.context);
     registerContextCommand(program, emit, opts.context);
     registerScratchCommand(program, emit);
+    registerDecisionCommand(program, emit);
+    registerDevtoolsCommand(program, emit);
     registerTunnelCommand(program, emit, opts.context);
     registerDocsCommand(program, emit, opts.context);
     registerAgentsCommand(program, emit);

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAwFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA4OpF"}

package/dist/commands/agents.js

@@ -16,12 +16,17 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerWithSource, } from "../core/agents/index.js";
+import { readStreamTailBounded } from "../core/agents/events/consume.js";
+import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, } from "../core/agents/index.js";
 import { resolveBinName } from "../core/config.js";
+/** 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.js";
+import { appendEntry, resolveOwnerByName } from "../core/scratch/index.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
-import { appendEntry, resolveOwnerByName } from "../lib/scratch/index.js";
 const FRESHNESS_SECS = 600; // 10-minute heartbeat-freshness window.
 const SUBAGENT_NOTE = "Bash identity is process-level in v1; if you're running inside a subagent, " +
     "this resolves to the parent group's name, not the subagent's. A subagent-aware " +
@@ -75,8 +80,7 @@ export function registerAgentsCommand(program, emitParam) {
     });
     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). " +
+        .description("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")
         .action(async (name, opts) => {
@@ -430,6 +434,7 @@ function runWhoami(opts) {
         });
         process.exit(1);
     }
+    ensureCursorSession(root);
     const resolved = resolveOwnerWithSource();
     const myOwner = resolved.owner;
     if (!myOwner) {
@@ -868,6 +873,49 @@ function formatLocalShort(iso) {
         timeZone: "America/Chicago",
     }).format(d);
 }
+function cursorEnvSessionId() {
+    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() {
+    return process.env.CURSOR_AGENT === "1" && cursorEnvSessionId() !== null;
+}
+function ensureCursorSession(root) {
+    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) {
     const root = monorepoRoot();
     if (!root) {
@@ -915,6 +963,8 @@ function runSetTask(task, opts) {
     // 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({
@@ -961,6 +1011,8 @@ function runStatus(opts) {
     }
     // 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({
@@ -1717,8 +1769,12 @@ function readStreamStats(root) {
     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++;
@@ -1835,27 +1891,32 @@ function runTrace(name, opts) {
     const sinceMs = opts.since ? Date.now() - (parseWindowSecs(opts.since) ?? 0) * 1000 : 0;
     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();
-    if (existsSync(streamPath)) {
-        for (const line of readFileSync(streamPath, "utf8").split("\n")) {
-            if (!line)
+    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);
+            if (!ev.instance_id || !candidateIds.includes(ev.instance_id))
                 continue;
-            try {
-                const ev = JSON.parse(line);
-                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 (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];
@@ -2208,7 +2269,7 @@ function renderHealthBox(report) {
     ];
     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
         for (const a of report.anomalies) {
@@ -2245,7 +2306,7 @@ function runHarnessProbe(id, opts) {
     // 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 = [];
     let walkPid = process.pid;
@@ -2348,12 +2409,12 @@ function runHarnessProbe(id, opts) {
  * 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
@@ -2420,7 +2481,7 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
         StopFailure: "stop-failure",
     };
     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 = [];
     try {
         for (const file of fixtures) {
@@ -2464,10 +2525,10 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
                 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",
                 },
             });
             const exit = dispatch.status ?? -1;

package/dist/commands/browse-ai.js

@@ -62,7 +62,7 @@ export function registerBrowseAiCommand(program, emitParam) {
 function runBrowseAi(url, opts) {
     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/dist/commands/browse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA0G1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAwJN"}
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiH1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0KN"}

package/dist/commands/browse.js

@@ -92,6 +92,14 @@ export function registerBrowseCommand(program, emitParam, context) {
         "Catches the class of mobile-layout bug where a nav/table overflows the viewport edge.")
         .option("--check-overflow-fail", "Exit non-zero if --check-overflow detects horizontal overflow.")
         .option("--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 " +
         "~/.cache/harnery/visual-baselines/<name>.png. Use --diff <name> later to " +
         "compare future captures against it (visual-regression check).")
@@ -117,7 +125,7 @@ async function runBrowse(url, opts, context) {
     // Commander: `--no-cookies` turns `opts.cookies` into `false`. Default is `true`.
     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");
     const browser = new Browser({
@@ -165,7 +173,7 @@ async function runBrowse(url, opts, context) {
             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);
             }
         }
@@ -177,9 +185,16 @@ async function runBrowse(url, opts, context) {
         if (opts.checkOverflow) {
             overflow = await browser.checkOverflow();
         }
+        let runts;
+        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 : [],
@@ -187,6 +202,10 @@ async function runBrowse(url, opts, context) {
                 widthThreshold,
             });
         }
+        const annotateRunts = runts && runts.runts.length > 0 && opts.checkRuntsAnnotate !== false;
+        if (annotateRunts) {
+            await browser.annotateRunts(runts);
+        }
         if (opts.login) {
             await new Promise((res) => {
                 emit.log("[--login] Headed Chromium is open. Walk through your auth flow now. Press Enter here to close + persist cookies into the profile.", "info");
@@ -203,17 +222,20 @@ async function runBrowse(url, opts, context) {
             if (opts.baseline || opts.diff) {
                 throw new Error("--baseline / --diff require trio mode (screenshot file). Remove --snapshot/--html/--json or capture the screenshot first.");
             }
-            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, devOverlay, batchResult);
+            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult);
         }
         else {
-            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, devOverlay, batchResult);
+            await runTrioMode(browser, navResult, opts, evalResult, 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");
             const failed = visibility.filter((r) => !r.found || !r.cssVisible || r.visibleRatio < threshold);
@@ -249,6 +271,12 @@ async function runBrowse(url, opts, context) {
                 process.exitCode = 2;
             }
         }
+        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
@@ -356,7 +384,7 @@ function splitBatchSteps(input) {
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
-async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, devOverlay, batchResult) {
+async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult) {
     let body = null;
     if (opts.html) {
         body = await browser.htmlContent(opts.selector);
@@ -385,6 +413,8 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
             result.width = widths;
         if (overflow)
             result.overflow = overflow;
+        if (runts)
+            result.runts = runts;
         if (devOverlay)
             result.devOverlay = devOverlay;
         if (batchResult && batchResult.clipboardReads.length > 0) {
@@ -408,7 +438,7 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
 // ---------------------------------------------------------------------------
 // Trio mode (default): write <prefix>.{png,html,json}
 // ---------------------------------------------------------------------------
-async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, devOverlay, batchResult) {
+async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult) {
     const prefix = resolveOutPrefix(opts.out);
     mkdirSync(dirname(prefix), { recursive: true });
     const written = [];
@@ -449,6 +479,8 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         envelope.width = widths;
     if (overflow)
         envelope.overflow = overflow;
+    if (runts)
+        envelope.runts = runts;
     if (devOverlay)
         envelope.devOverlay = devOverlay;
     if (batchResult && batchResult.clipboardReads.length > 0) {

package/dist/commands/cookies.js

@@ -12,7 +12,7 @@ const DEFAULT_STORE = resolve(homedir(), ".cache", "harnery", "cookies.json");
 function jarFrom(opts) {
     return new CookieJar({
         path: opts.store ?? DEFAULT_STORE,
-        source: "bp-cookies",
+        source: "harn-cookies",
     });
 }
 // Module-scoped emit assigned by registerCookiesCommand; the module-level

package/dist/commands/decision.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerDecisionCommand(program: Command, emitParam: EmitContext): void;
+//# sourceMappingURL=decision.d.ts.map

package/dist/commands/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/commands/decision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA6CnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAgStF"}