harnery 0.4.0 → 0.6.0

package/dist/commander.d.ts

@@ -91,6 +91,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;AAgCpC,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;;;;;;;;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,CA4C3E"}

package/dist/commander.js

@@ -26,6 +26,7 @@ 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 { registerDocsCommand } from "./commands/docs.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
@@ -110,6 +111,7 @@ export function createHarneryProgram(opts = {}) {
     registerCompletionCommand(program, emit, opts.context);
     registerContextCommand(program, emit, opts.context);
     registerScratchCommand(program, emit);
+    registerDecisionCommand(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;AAuFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}

package/dist/commands/agents.js

@@ -16,8 +16,13 @@ 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 { readStreamTailBounded } from "../core/agents/events/consume.js";
 import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, 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 { 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";
@@ -1717,8 +1722,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 +1844,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 +2222,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 +2259,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 +2362,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 +2434,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 +2478,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/completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAY1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8DN"}
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAkB1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAqGN"}

package/dist/commands/completion.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { generateBash, generateFish, generateZsh, walkProgram, } from "../lib/completion/index.js";
+import { encodeResult, generateBash, generateBashDynamic, generateFish, generateFishDynamic, generateZsh, generateZshDynamic, resolveCompletions, walkProgram, } from "../lib/completion/index.js";
 const noopProviderRunner = async () => [];
 const noopLookup = () => undefined;
 /**
@@ -22,25 +22,35 @@ export function registerCompletionCommand(program, _emit, context) {
     const root = program
         .command("completion")
         .description("Shell tab-completion. Emit a script per shell or install to the standard location.");
+    const dynamicHint = "Emit a thin shim that calls the binary at tab-time (never goes stale; install once)";
     root
         .command("bash")
         .description("Emit bash completion script to stdout")
-        .action(() => {
-        const out = generateBash(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateBashDynamic(program.name())
+            : generateBash(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
         .command("zsh")
         .description("Emit zsh completion script to stdout")
-        .action(() => {
-        const out = generateZsh(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateZshDynamic(program.name())
+            : generateZsh(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
         .command("fish")
         .description("Emit fish completion script to stdout")
-        .action(() => {
-        const out = generateFish(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateFishDynamic(program.name())
+            : generateFish(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
@@ -49,6 +59,7 @@ export function registerCompletionCommand(program, _emit, context) {
         .option("--shell <name>", "bash | zsh | fish (default: auto-detect from $SHELL)")
         .option("--path <file>", "Override destination path")
         .option("--print-path", "Print the destination path and exit (no write)")
+        .option("--dynamic", `${dynamicHint} (recommended)`)
         .action(async (opts) => {
         await installCompletion(program, opts, lookup);
     });
@@ -72,6 +83,26 @@ export function registerCompletionCommand(program, _emit, context) {
     });
     // Keep TS happy that the variable is used.
     void hidden;
+    // Hidden internal entry for DYNAMIC completion: the thin shim passes the live
+    // command line (cursor index + all words after `--`) and we compute the full
+    // candidate set from the live command tree. `--` stops option parsing so
+    // words like `-h` reach the variadic instead of being read as our flags.
+    const hiddenLine = program
+        .command("__complete-line <cword> [words...]", { hidden: true })
+        .description("Internal: full-line completion callback for the dynamic shell shim")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(async (cword, words) => {
+        try {
+            const result = await resolveCompletions(program, words ?? [], Number.parseInt(cword, 10) || 0, lookup, runProvider);
+            process.stdout.write(encodeResult(result)); // lint-ok-emission: shell callback; the encoded candidate/directive stream is the contract with the shim.
+        }
+        catch {
+            // Never break the user's tab: emit just the file-fallback directive.
+            process.stdout.write("\x1f:1\n"); // lint-ok-emission: shell callback fallback directive.
+        }
+    });
+    void hiddenLine;
 }
 async function installCompletion(program, opts, lookup) {
     const shell = opts.shell ?? detectShell();
@@ -84,16 +115,23 @@ async function installCompletion(program, opts, lookup) {
         process.stdout.write(`${destination}\n`); // lint-ok-emission: --print-path is meant to be piped (e.g., dest=$(harn completion install --print-path)).
         return;
     }
+    const name = program.name();
     let content;
     switch (shell) {
         case "bash":
-            content = generateBash(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateBashDynamic(name)
+                : generateBash(walkProgram(program, lookup), name);
             break;
         case "zsh":
-            content = generateZsh(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateZshDynamic(name)
+                : generateZsh(walkProgram(program, lookup), name);
             break;
         case "fish":
-            content = generateFish(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateFishDynamic(name)
+                : generateFish(walkProgram(program, lookup), name);
             break;
         default:
             process.stderr.write(`Unknown shell: ${shell}\n`); // lint-ok-emission: install-time error, see above.

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"}