harnery 0.5.0 → 0.6.0

package/dist/commands/decision.js

@@ -0,0 +1,354 @@
+import { existsSync, readFileSync } from "node:fs";
+import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, } from "../core/agents/index.js";
+import { resolveBinName } from "../core/config.js";
+import { archiveDecision, claimDecision, DECISION_STAKES, fileDecision, isStakes, isStatus, isTier, isVerdict, listDecisions, reopenDecision, resolveDecision, reviewDecision, searchDecisions, showDecision, supersedeDecision, triageDecision, wontfixDecision, } from "../lib/decision/index.js";
+/**
+ * `harn decision`: the decision docket — a persistent queue of decisions an
+ * agent would otherwise route to a human, carried through triage → deliberation
+ * → an evidence-cited resolution → async review.
+ *
+ * The engine is generic: it stores `tier` (0/1/2) + `stakes` but never decides
+ * what belongs in which tier — that's host policy, applied by the filing agent
+ * (for a host, via its own decision skill + rubric).
+ */
+let emit;
+export function registerDecisionCommand(program, emitParam) {
+    emit = emitParam;
+    const bin = () => resolveBinName();
+    const root = program
+        .command("decision")
+        .alias("decisions")
+        .description("Decision docket: file a decision an agent would otherwise escalate, " +
+        "deliberate it, resolve with cited evidence, review async.");
+    // ── file ─────────────────────────────────────────────────────────────────
+    root
+        .command("file <question...>")
+        .description("File a decision into the docket. Tier/stakes are the filer's triage call.")
+        .option("--tier <0|1|2>", "Human-involvement tier (0 none, 1 review, 2 decide-with-brief)", "2")
+        .option("--stakes <small|medium|high>", "Reversal cost / blast radius", "medium")
+        .option("--context <text>", "Why it matters, what's blocked")
+        .option("--default-taken <text>", "What you proceeded with (always-proceed, tier 0/1)")
+        .option("--brief <path>", "Path to a markdown file with the long-form brief")
+        .option("--filed-by <name>", "Filer agent name (else resolved from heartbeat)")
+        .action((question, opts) => {
+        const coordRoot = coordRootOrExit();
+        const tier = parseTier(opts.tier);
+        const stakes = parseStakes(opts.stakes);
+        let brief;
+        if (opts.brief) {
+            if (!existsSync(opts.brief)) {
+                emit.error({ code: "no_brief_file", message: `brief file not found: ${opts.brief}` });
+                process.exit(1);
+            }
+            brief = readFileSync(opts.brief, "utf8");
+        }
+        const owner = resolveOwner();
+        const hb = owner ? readHeartbeat(owner) : null;
+        const r = fileDecision(coordRoot, {
+            question: question.join(" "),
+            tier,
+            stakes,
+            context: opts.context,
+            defaultTaken: opts.defaultTaken,
+            brief,
+            filedBy: opts.filedBy ?? hb?.name ?? undefined,
+            filedById: owner ?? undefined,
+        });
+        if (!r.ok)
+            return fail("file_failed", r.reason);
+        emitDecisionEvent("decision.filed", {
+            decision_id: r.manifest.decision_id,
+            tier,
+            stakes,
+        });
+        emit.data(r.manifest);
+    });
+    // ── list ─────────────────────────────────────────────────────────────────
+    root
+        .command("list")
+        .description("List docket decisions (default: active only, newest first).")
+        .option("--status <status>", "Filter by status")
+        .option("--tier <0|1|2>", "Filter by tier")
+        .option("--stakes <small|medium|high>", "Filter by stakes")
+        .option("--open", "Only non-terminal decisions (the live queue)")
+        .option("--archived", "Include archived (graduated/terminal) decisions")
+        .action((opts) => {
+        const coordRoot = coordRootOrExit();
+        const status = opts.status ? parseStatus(opts.status) : undefined;
+        const tier = opts.tier !== undefined ? parseTier(opts.tier) : undefined;
+        const stakes = opts.stakes ? parseStakes(opts.stakes) : undefined;
+        const rows = listDecisions(coordRoot, {
+            status,
+            tier,
+            stakes,
+            openOnly: opts.open,
+            includeArchived: opts.archived,
+        }).map(summarize);
+        emit.data({
+            rows,
+            meta: {
+                total: rows.length,
+                filter: { status, tier, stakes, open: !!opts.open, archived: !!opts.archived },
+            },
+        });
+    });
+    // ── show ─────────────────────────────────────────────────────────────────
+    root
+        .command("show <id>")
+        .description("Show one decision: manifest + long-form bodies.")
+        .action((id) => {
+        const coordRoot = coordRootOrExit();
+        const detail = showDecision(coordRoot, id);
+        if (!detail)
+            return fail("not_found", `no decision "${id}"`);
+        emit.data(detail);
+    });
+    // ── search ───────────────────────────────────────────────────────────────
+    root
+        .command("search <query...>")
+        .description("Substring search over questions, context, resolutions, bodies (incl. archive).")
+        .action((query) => {
+        const coordRoot = coordRootOrExit();
+        const hits = searchDecisions(coordRoot, query.join(" ")).map((h) => ({
+            ...summarize(h.manifest),
+            where: h.where,
+            snippet: h.snippet,
+        }));
+        emit.data({ rows: hits, meta: { total: hits.length, query: query.join(" ") } });
+    });
+    // ── claim ────────────────────────────────────────────────────────────────
+    root
+        .command("claim <id>")
+        .description("Claim a decision for deliberation (last-writer-wins).")
+        .option("--owner <id>", "Claim as this owner (else the current agent)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const owner = opts.owner ?? resolveOwner();
+        if (!owner) {
+            return fail("no_owner", `not in an agent session; pass --owner or run \`${bin()} agents whoami\` to check`);
+        }
+        const r = claimDecision(coordRoot, id, owner);
+        if (!r.ok)
+            return fail("claim_failed", r.reason);
+        emit.data(r.manifest);
+    });
+    // ── resolve ──────────────────────────────────────────────────────────────
+    root
+        .command("resolve <id>")
+        .description("Resolve a decision. Evidence (≥1 citation) is required.")
+        .requiredOption("--recommendation <text>", "The recommendation")
+        .option("--evidence <text>", "A cited fact (query run, file read, cost computed). Repeatable; ≥1 required.", collect, [])
+        .option("--confidence <text>", "Confidence in the recommendation")
+        .option("--reversal-cost <text>", "Cost to reverse if wrong")
+        .option("--wrong-if <text>", "What would make this wrong (pre-mortem)")
+        .option("--revisit-when <text>", "Revisit trigger")
+        .option("--resolved-by <name>", "Resolver (else the current agent)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const owner = resolveOwner();
+        const resolvedBy = opts.resolvedBy ?? (owner ? readHeartbeat(owner)?.name : undefined);
+        if (!resolvedBy) {
+            return fail("no_resolver", "pass --resolved-by (no agent session to infer it from)");
+        }
+        const r = resolveDecision(coordRoot, id, {
+            recommendation: opts.recommendation,
+            evidence: opts.evidence,
+            confidence: opts.confidence,
+            reversal_cost: opts.reversalCost,
+            wrong_if: opts.wrongIf,
+            revisit_when: opts.revisitWhen,
+            resolved_by: resolvedBy,
+        });
+        if (!r.ok)
+            return fail("resolve_failed", r.reason);
+        emitDecisionEvent("decision.resolved", {
+            decision_id: id,
+            tier: r.manifest.tier,
+            stakes: r.manifest.stakes,
+            confidence: opts.confidence ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── review ───────────────────────────────────────────────────────────────
+    root
+        .command("review <id>")
+        .description("Record a review verdict (calibration, not approval — work already proceeded).")
+        .requiredOption("--verdict <verdict>", "ratified | overridden | wrong-tier-high | wrong-tier-low")
+        .option("--note <text>", "Reviewer note")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        if (!isVerdict(opts.verdict)) {
+            return fail("bad_verdict", "verdict must be: ratified | overridden | wrong-tier-high | wrong-tier-low");
+        }
+        const r = reviewDecision(coordRoot, id, {
+            verdict: opts.verdict,
+            note: opts.note,
+        });
+        if (!r.ok)
+            return fail("review_failed", r.reason);
+        emitDecisionEvent("decision.reviewed", {
+            decision_id: id,
+            verdict: opts.verdict,
+            tier: r.manifest.tier,
+        });
+        emit.data(r.manifest);
+    });
+    // ── triage ─────────────────────────────────────────────────────────────────
+    // Re-set tier/stakes on an already-filed decision (e.g. after a sweeper or
+    // reviewer flags a wrong-tier). Cheap enough to surface in phase 1.
+    root
+        .command("triage <id>")
+        .description("Adjust an already-filed decision's tier/stakes.")
+        .option("--tier <0|1|2>", "New tier")
+        .option("--stakes <small|medium|high>", "New stakes")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        if (opts.tier === undefined && opts.stakes === undefined) {
+            return fail("nothing_to_do", "pass --tier and/or --stakes");
+        }
+        const r = triageDecision(coordRoot, id, {
+            tier: opts.tier !== undefined ? parseTier(opts.tier) : undefined,
+            stakes: opts.stakes !== undefined ? parseStakes(opts.stakes) : undefined,
+        });
+        if (!r.ok)
+            return fail("triage_failed", r.reason);
+        emit.data(r.manifest);
+    });
+    // ── archive ─────────────────────────────────────────────────────────────────
+    // The graduation exit: a reviewed decision's output has landed in a canonical
+    // home (an ADR, AGENTS.md, a code change), so the decision closes and moves to
+    // the archive, still searchable as precedent. `--graduated-to` records where.
+    root
+        .command("archive <id>")
+        .description("Archive a reviewed decision (terminal). Record where its output graduated.")
+        .option("--graduated-to <ref>", "Where the resolved output landed (e.g. docs/decisions.md#foo)")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = archiveDecision(coordRoot, id, opts.graduatedTo);
+        if (!r.ok)
+            return fail("archive_failed", r.reason);
+        emitDecisionEvent("decision.archived", {
+            decision_id: id,
+            tier: r.manifest.tier,
+            graduated_to: opts.graduatedTo ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── reopen ───────────────────────────────────────────────────────────────────
+    // The inverse of archive: pull an archived decision back to `reviewed`. The one
+    // sanctioned way out of the terminal archive (e.g. a fat-fingered graduated_to
+    // or the wrong decision archived). Clears graduated_to; a re-archive sets it fresh.
+    root
+        .command("reopen <id>")
+        .alias("unarchive")
+        .description("Reopen an archived decision back to reviewed (the inverse of archive).")
+        .action((id) => {
+        const coordRoot = coordRootOrExit();
+        const r = reopenDecision(coordRoot, id);
+        if (!r.ok)
+            return fail("reopen_failed", r.reason);
+        emitDecisionEvent("decision.reopened", { decision_id: id, tier: r.manifest.tier });
+        emit.data(r.manifest);
+    });
+    // ── supersede ────────────────────────────────────────────────────────────────
+    root
+        .command("supersede <id>")
+        .description("Mark a decision superseded by a newer one (terminal).")
+        .option("--by <id>", "The superseding decision's id")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = supersedeDecision(coordRoot, id, opts.by);
+        if (!r.ok)
+            return fail("supersede_failed", r.reason);
+        emitDecisionEvent("decision.superseded", {
+            decision_id: id,
+            superseded_by: opts.by ?? null,
+        });
+        emit.data(r.manifest);
+    });
+    // ── wontfix ──────────────────────────────────────────────────────────────────
+    root
+        .command("wontfix <id>")
+        .description("Close an un-deliberated decision without action (terminal).")
+        .option("--reason <text>", "Why it's being closed")
+        .action((id, opts) => {
+        const coordRoot = coordRootOrExit();
+        const r = wontfixDecision(coordRoot, id, opts.reason);
+        if (!r.ok)
+            return fail("wontfix_failed", r.reason);
+        emitDecisionEvent("decision.wontfix", {
+            decision_id: id,
+            reason: opts.reason ?? null,
+        });
+        emit.data(r.manifest);
+    });
+}
+// ─── helpers ───────────────────────────────────────────────────────────────────
+function coordRootOrExit() {
+    const root = monorepoRoot();
+    if (!root) {
+        emit.error({
+            code: "no_coord_root",
+            message: "not in a coord-aware repo (no .harnery/ found)",
+        });
+        process.exit(1);
+    }
+    return root;
+}
+function fail(code, message) {
+    emit.error({ code, message: message ?? code });
+    process.exit(1);
+}
+function parseTier(raw) {
+    const n = Number.parseInt(raw, 10);
+    if (!isTier(n))
+        fail("bad_tier", `tier must be 0, 1, or 2 (got "${raw}")`);
+    return n;
+}
+function parseStakes(raw) {
+    if (!isStakes(raw))
+        fail("bad_stakes", `stakes must be ${DECISION_STAKES.join(" | ")} (got "${raw}")`);
+    return raw;
+}
+function parseStatus(raw) {
+    if (!isStatus(raw))
+        fail("bad_status", `unknown status "${raw}"`);
+    return raw;
+}
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/** Compact row for list/search output — the full manifest is available via `show`. */
+function summarize(m) {
+    return {
+        decision_id: m.decision_id,
+        status: m.status,
+        tier: m.tier,
+        stakes: m.stakes,
+        question: m.question,
+        filed_by: m.filed_by ?? null,
+        filed_at: m.filed_at,
+        claimed_by: m.claimed_by ?? null,
+        resolved: !!m.resolution,
+        reviewed: !!m.review,
+        graduated_to: m.graduated_to ?? null,
+    };
+}
+/**
+ * Emit a canonical `decision.*` event. Soft: no-ops when there's no agent
+ * session to attribute it to (operator-side filing). Powers the docket metrics
+ * without new telemetry plumbing.
+ */
+function emitDecisionEvent(type, data) {
+    const owner = resolveOwner();
+    if (!owner)
+        return;
+    const hb = readHeartbeat(owner);
+    emitCanonical({
+        type,
+        owner,
+        session: hb?.session_id ?? owner,
+        harness: normalizeHarness(hb?.platform),
+        data,
+    });
+}

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

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAuB1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+EN"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA2B1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+EN"}

package/dist/commands/docs.js

@@ -9,7 +9,11 @@ function ensureContext(context) {
     const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
     initDocs(opts);
     initDocsIndex(opts);
-    initDocsLint({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+    initDocsLint({
+        ...opts,
+        extraExcludedPrefixes: context.extraDocsExcludedPrefixes,
+        docsRootAllowlist: context.docsRootAllowlist,
+    });
     initDocsSweep(opts);
 }
 let emit;

package/dist/commands/fetch.js

@@ -48,7 +48,7 @@ async function runFetch(url, opts, emit, context) {
         headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
     }
     const jar = opts.cookies !== false
-        ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "bp-fetch" })
+        ? new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-fetch" })
         : null;
     const timeoutMs = Number.parseInt(opts.timeout, 10);
     const ac = new AbortController();

package/dist/core/agents/events/consume.d.ts

@@ -11,8 +11,12 @@
  * with a bounded **tail read** (reading only the last `tailBytes` of the file
  * and locating the cursor there) which turns an O(file-size) read into
  * O(window). If the cursor is older than the window (a long-idle system, or a
- * cursor that's been rotated out) we fall back to a full read. The fallback is
- * always correct, just slower, so undersizing the window can never lose events.
+ * cursor that's been rotated out) we fall back to a wider read that is itself
+ * capped (`fallbackCapBytes`): the stream is an append-only ledger that grows
+ * without bound, so a whole-file `readFileSync` throws V8's max-string-length
+ * error ("Cannot create a string longer than 0x1fffffe8 characters") once it
+ * passes ~512MB, which would abort the projection. Events older than the cap are
+ * stale for coord-state purposes, so a bounded replay is the correct fallback.
  *
  * Idempotency: projectors are idempotent by `event_id`. The
  * cursor file makes this cheap (we never replay an already-projected event by
@@ -49,11 +53,30 @@ export interface ConsumeOpts {
      * callers should leave it unset.
      */
     tailBytes?: number;
+    /**
+     * Cap in bytes for the fall-through read (cursor missed the tail window).
+     * Defaults to `HARNERY_AGENT_COORD_FALLBACK_CAP_BYTES` env or 64 MiB. Bounds
+     * the read so the unbounded ledger can never overflow V8's max string length.
+     * Mainly a test seam; production callers should leave it unset.
+     */
+    fallbackCapBytes?: number;
 }
 /**
  * Read all events after the persisted cursor, in chronological (file) order.
  */
 export declare function consumeSince(coordRoot: string, opts?: ConsumeOpts): ConsumeResult;
+/**
+ * Read at most `capBytes` from the tail of the event stream as UTF-8, dropping
+ * the (partial) leading line when the file is larger than the cap. Shared
+ * bounded reader for CLI consumers (`agents trace` / `agents health`) that must
+ * never `readFileSync` the whole unbounded ledger — a >512MB read throws V8's
+ * max-string-length error. `truncated` is true when older bytes were skipped, so
+ * callers can surface the cap rather than silently under-reporting.
+ */
+export declare function readStreamTailBounded(streamPath: string, capBytes: number): {
+    text: string;
+    truncated: boolean;
+};
 export declare function readCursor(coordRoot: string): string | null;
 export declare function writeCursor(coordRoot: string, eventId: string): void;
 //# sourceMappingURL=consume.d.ts.map

package/dist/core/agents/events/consume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consume.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/consume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAmBH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,aAAa,CA4CrF;AAwDD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS3D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQpE"}
+{"version":3,"file":"consume.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/consume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAwBH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,aAAa,CAuDrF;AAgBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAWtC;AAiDD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS3D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQpE"}

package/dist/core/agents/events/consume.js

@@ -11,8 +11,12 @@
  * with a bounded **tail read** (reading only the last `tailBytes` of the file
  * and locating the cursor there) which turns an O(file-size) read into
  * O(window). If the cursor is older than the window (a long-idle system, or a
- * cursor that's been rotated out) we fall back to a full read. The fallback is
- * always correct, just slower, so undersizing the window can never lose events.
+ * cursor that's been rotated out) we fall back to a wider read that is itself
+ * capped (`fallbackCapBytes`): the stream is an append-only ledger that grows
+ * without bound, so a whole-file `readFileSync` throws V8's max-string-length
+ * error ("Cannot create a string longer than 0x1fffffe8 characters") once it
+ * passes ~512MB, which would abort the projection. Events older than the cap are
+ * stale for coord-state purposes, so a bounded replay is the correct fallback.
  *
  * Idempotency: projectors are idempotent by `event_id`. The
  * cursor file makes this cheap (we never replay an already-projected event by
@@ -25,6 +29,11 @@ import { coordEnv } from "../../../lib/env.js";
 const STREAM_REL = ".harnery/events.ndjson";
 const CURSOR_REL = ".harnery/.events-cursor";
 const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024; // 2 MiB, thousands of events of headroom
+/** Cap for the fall-through read when the cursor misses the tail window. Well
+ * under V8's ~512MB max string length so it never throws on the unbounded
+ * ledger; comfortably larger than any realistic cursor drift (the global cursor
+ * advances on every agent's turn.stop, so it sits near EOF in practice). */
+const DEFAULT_FALLBACK_CAP_BYTES = 64 * 1024 * 1024; // 64 MiB
 /**
  * Read all events after the persisted cursor, in chronological (file) order.
  */
@@ -54,8 +63,19 @@ export function consumeSince(coordRoot, opts = {}) {
         }
         // Cursor older than the tail window → fall through to a full read.
     }
-    // Full read: first run, replayAll, small file, or cursor not found in tail.
-    const all = parseLines(readFileSync(streamPath, "utf8"));
+    // Bounded fall-through: first run, replayAll, small file, or cursor not found
+    // in the tail. This must NEVER read the whole file: the stream grows without
+    // bound and a >512MB readFileSync throws V8's max-string-length error, which
+    // would abort the projection. Read at most `cap` bytes from the tail; when we
+    // start mid-file, drop the (likely partial) first line.
+    const cap = resolveFallbackCap(opts.fallbackCapBytes);
+    const readBytes = Math.min(fileSize, cap);
+    let text = readTailUtf8(streamPath, fileSize, readBytes);
+    if (readBytes < fileSize) {
+        const firstNl = text.indexOf("\n");
+        text = firstNl >= 0 ? text.slice(firstNl + 1) : "";
+    }
+    const all = parseLines(text);
     const parsed = eventsAfterCursor(all, cursor);
     if (parsed.foundCursor) {
         return {
@@ -64,11 +84,18 @@ export function consumeSince(coordRoot, opts = {}) {
             streamBytes: fileSize,
         };
     }
-    // The cursor names an event that's been rotated out of the file, so replay
-    // everything (safer than silent state drift; the projector is idempotent by
-    // event_id).
+    // The cursor names an event older than the capped window (or rotated out), so
+    // replay what the window holds (safer than silent state drift; the projector
+    // is idempotent by event_id). lastEventId null keeps the cursor put.
     return { events: all, lastEventId: null, streamBytes: fileSize };
 }
+function resolveFallbackCap(override) {
+    if (override !== undefined && override > 0)
+        return override;
+    const env = coordEnv("AGENT_COORD_FALLBACK_CAP_BYTES");
+    const n = env ? Number(env) : Number.NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_FALLBACK_CAP_BYTES;
+}
 function resolveTailBytes(override) {
     if (override !== undefined && override > 0)
         return override;
@@ -76,6 +103,27 @@ function resolveTailBytes(override) {
     const n = env ? Number(env) : Number.NaN;
     return Number.isFinite(n) && n > 0 ? n : DEFAULT_TAIL_BYTES;
 }
+/**
+ * Read at most `capBytes` from the tail of the event stream as UTF-8, dropping
+ * the (partial) leading line when the file is larger than the cap. Shared
+ * bounded reader for CLI consumers (`agents trace` / `agents health`) that must
+ * never `readFileSync` the whole unbounded ledger — a >512MB read throws V8's
+ * max-string-length error. `truncated` is true when older bytes were skipped, so
+ * callers can surface the cap rather than silently under-reporting.
+ */
+export function readStreamTailBounded(streamPath, capBytes) {
+    if (!existsSync(streamPath))
+        return { text: "", truncated: false };
+    const fileSize = statSync(streamPath).size;
+    const readBytes = Math.min(fileSize, capBytes);
+    let text = readTailUtf8(streamPath, fileSize, readBytes);
+    const truncated = readBytes < fileSize;
+    if (truncated) {
+        const nl = text.indexOf("\n");
+        text = nl >= 0 ? text.slice(nl + 1) : "";
+    }
+    return { text, truncated };
+}
 /** Read the trailing `windowBytes` of a file as UTF-8 without loading the rest. */
 function readTailUtf8(streamPath, fileSize, windowBytes) {
     const start = Math.max(0, fileSize - windowBytes);

package/dist/core/agents/events/emit.d.ts

@@ -5,7 +5,8 @@
  * event/schema types).
  *
  * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
- * state.status_checked, state.scratch_append, council.*, presence.*).
+ * state.status_checked, state.scratch_append, council.*, decision.*,
+ * presence.*).
  */
 declare const SCHEMA_VERSION: 1;
 export type Harness = "claude-code" | "cursor" | "codex";

package/dist/core/agents/events/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,QAAA,MAAM,cAAc,EAAG,CAAU,CAAC;AAKlC,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAexD;AAED,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAwBlE"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,QAAA,MAAM,cAAc,EAAG,CAAU,CAAC;AAKlC,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAexD;AAED,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAwBlE"}

package/dist/core/agents/events/emit.js

@@ -5,7 +5,8 @@
  * event/schema types).
  *
  * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
- * state.status_checked, state.scratch_append, council.*, presence.*).
+ * state.status_checked, state.scratch_append, council.*, decision.*,
+ * presence.*).
  */
 import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";

package/dist/core/agents/state/scratch.d.ts

@@ -16,7 +16,7 @@ export declare function appendScratch(coordRoot: string, instanceId: string, cat
 };
 /**
  * Replace the scratchpad with new body, archiving prior contents and
- * appending an "(edited via UI by Ryan)" audit-marker note.
+ * appending an "(edited via UI by the operator)" audit-marker note.
  */
 export declare function editScratchpad(coordRoot: string, instanceId: string, newBody: string, summary: string): {
     ok: boolean;

package/dist/core/agents/state/scratch.js

@@ -58,7 +58,7 @@ export function appendScratch(coordRoot, instanceId, category, body) {
 }
 /**
  * Replace the scratchpad with new body, archiving prior contents and
- * appending an "(edited via UI by Ryan)" audit-marker note.
+ * appending an "(edited via UI by the operator)" audit-marker note.
  */
 export function editScratchpad(coordRoot, instanceId, newBody, summary) {
     if (typeof newBody !== "string") {
@@ -82,7 +82,7 @@ export function editScratchpad(coordRoot, instanceId, newBody, summary) {
             prior += "\n";
     }
     const summaryText = summary && summary.length > 0 ? summary : "(no summary)";
-    const auditMarker = `## [${ts}] note (edited via UI by Ryan)\n` +
+    const auditMarker = `## [${ts}] note (edited via UI by the operator)\n` +
         `${summaryText}\n` +
         `Pre-edit archived at .harnery/scratch/archived/${instanceId}-${archiveSuffix}.md\n\n`;
     atomicWriteText(target, prior + auditMarker + newBody + (newBody.endsWith("\n") ? "" : "\n"));

package/dist/core/hooks/effects/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,IAAI,CAYN;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW3F;AAOD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,IAAI,CAqBN;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,IAAI,CAYN;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW3F;AAOD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,IAAI,CAqBN;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}

package/dist/core/hooks/effects/index.js

@@ -16,6 +16,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.js";
+import { resolveBinName } from "../../config.js";
 export { captureImages, imageJanitor } from "./image-capture.js";
 /**
  * Play a notification sound via the cross-platform utility
@@ -119,7 +120,7 @@ export function scratchArchive(repoRoot, owner) {
  */
 export function syncClaudeSessions(repoRoot, force) {
     try {
-        const bin = join(repoRoot, "bin", "bp");
+        const bin = join(repoRoot, "bin", resolveBinName(repoRoot));
         if (!existsSync(bin))
             return;
         const env = {

package/dist/lib/agent-browser/client.js

@@ -66,7 +66,7 @@ export class AgentBrowser {
                 this.cookiesSeeded = true;
                 return;
             }
-            const stateFile = this.opts.stateFilePath ?? `/tmp/bp-agent-browser-state-${process.pid}.json`;
+            const stateFile = this.opts.stateFilePath ?? `/tmp/harn-agent-browser-state-${process.pid}.json`;
             writeFileSync(stateFile, JSON.stringify(jarStore, null, 2));
             this.exec(["state", "load", stateFile], 10_000);
             this.cookiesSeeded = true;