harnery 0.0.1 → 0.2.1

package/dist/core/agents/state/pidmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pidmap.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/pidmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CAYN"}

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

@@ -0,0 +1,32 @@
+/**
+ * Pid-map writer.
+ *
+ * Per-harness pid-map at `.harnery/pid-map/<pid>` containing
+ * `<instance_id>\t<platform>`. `harn agents whoami` walks ppid up 20 hops looking
+ * for a matching entry (preferring the harness, falling back to any platform).
+ *
+ * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+export function writePidmapRow(coordRoot, pid, instanceId, platform) {
+    const path = join(coordRoot, ".harnery", "pid-map", String(pid));
+    const row = `${instanceId}\t${platform}`;
+    // Read-then-write idempotency: skip the rename churn when already current.
+    if (existsSync(path)) {
+        try {
+            if (readFileSync(path, "utf8") === row)
+                return;
+        }
+        catch {
+            /* fall through to write */
+        }
+    }
+    atomicWrite(path, row);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Scratchpad mutations: append-only timestamped journal at
+ * `.harnery/scratch/<instance_id>.md`.
+ *
+ * Used by the agents-coord web UI route handlers for both operator-nudge
+ * appends and inline edits.
+ */
+/**
+ * Append a timestamped entry to the owner's scratchpad.
+ * Returns true on success, false if validation failed.
+ */
+export declare function appendScratch(coordRoot: string, instanceId: string, category: string, body: string): {
+    ok: boolean;
+    reason?: string;
+    path?: string;
+};
+/**
+ * Replace the scratchpad with new body, archiving prior contents and
+ * appending an "(edited via UI by Ryan)" audit-marker note.
+ */
+export declare function editScratchpad(coordRoot: string, instanceId: string, newBody: string, summary: string): {
+    ok: boolean;
+    reason?: string;
+    archivePath?: string;
+    path?: string;
+};
+//# sourceMappingURL=scratch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/scratch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CA8BvE"}

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

@@ -0,0 +1,90 @@
+/**
+ * Scratchpad mutations: append-only timestamped journal at
+ * `.harnery/scratch/<instance_id>.md`.
+ *
+ * Used by the agents-coord web UI route handlers for both operator-nudge
+ * appends and inline edits.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+const ALLOWED_CATEGORIES = new Set([
+    "note",
+    "plan",
+    "decision",
+    "blocker",
+    "question",
+    "done",
+    "handoff",
+]);
+const APPEND_BODY_CAP = 4096;
+function nowIsoSeconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function scratchPath(coordRoot, instanceId) {
+    return join(coordRoot, ".harnery", "scratch", `${instanceId}.md`);
+}
+function archivePath(coordRoot, instanceId, suffix) {
+    return join(coordRoot, ".harnery", "scratch", "archived", `${instanceId}-${suffix}.md`);
+}
+function atomicWriteText(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Append a timestamped entry to the owner's scratchpad.
+ * Returns true on success, false if validation failed.
+ */
+export function appendScratch(coordRoot, instanceId, category, body) {
+    if (!ALLOWED_CATEGORIES.has(category)) {
+        return { ok: false, reason: `invalid category "${category}"` };
+    }
+    if (!body || body.length === 0) {
+        return { ok: false, reason: "body required" };
+    }
+    const trimmedBody = body.length > APPEND_BODY_CAP ? `${body.slice(0, APPEND_BODY_CAP - 3)}...` : body;
+    const target = scratchPath(coordRoot, instanceId);
+    const ts = nowIsoSeconds();
+    let prior = "";
+    if (existsSync(target)) {
+        prior = readFileSync(target, "utf8");
+        if (!prior.endsWith("\n"))
+            prior += "\n";
+    }
+    const entry = `## [${ts}] ${category}\n${trimmedBody}\n`;
+    atomicWriteText(target, prior + entry);
+    return { ok: true, path: target };
+}
+/**
+ * Replace the scratchpad with new body, archiving prior contents and
+ * appending an "(edited via UI by Ryan)" audit-marker note.
+ */
+export function editScratchpad(coordRoot, instanceId, newBody, summary) {
+    if (typeof newBody !== "string") {
+        return { ok: false, reason: "newBody required" };
+    }
+    const target = scratchPath(coordRoot, instanceId);
+    const ts = nowIsoSeconds();
+    const archiveSuffix = `pre-ui-${ts.replace(/:/g, "-")}`;
+    const archive = archivePath(coordRoot, instanceId, archiveSuffix);
+    mkdirSync(dirname(archive), { recursive: true });
+    let prior = "";
+    if (existsSync(target)) {
+        try {
+            copyFileSync(target, archive);
+        }
+        catch {
+            /* archive optional; continue */
+        }
+        prior = readFileSync(target, "utf8");
+        if (!prior.endsWith("\n"))
+            prior += "\n";
+    }
+    const summaryText = summary && summary.length > 0 ? summary : "(no summary)";
+    const auditMarker = `## [${ts}] note (edited via UI by Ryan)\n` +
+        `${summaryText}\n` +
+        `Pre-edit archived at .harnery/scratch/archived/${instanceId}-${archiveSuffix}.md\n\n`;
+    atomicWriteText(target, prior + auditMarker + newBody + (newBody.endsWith("\n") ? "" : "\n"));
+    return { ok: true, archivePath: archive, path: target };
+}

package/dist/core/agents/state/shell-mutation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A heuristic parser that extracts file paths likely to be mutated by a
+ * shell command. Used by
+ * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * (warn-only, never blocks).
+ *
+ * Two cases:
+ *   1. Output redirections: `> path` and `>> path`
+ *   2. Common mutators: `sed -i…`, `cp`, `mv`, `touch`: capture the next
+ *      non-space token after the command name (intentionally single-arg even
+ *      though `cp src dest` has two args)
+ *
+ * Caller-supplied `coordRoot` is stripped from absolute paths so the warn
+ * log shows monorepo-relative form.
+ */
+export declare function shellMutationPaths(cmd: string, coordRoot?: string | null): string[];
+//# sourceMappingURL=shell-mutation.d.ts.map

package/dist/core/agents/state/shell-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-mutation.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/shell-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,EAAE,CA2BzF"}

package/dist/core/agents/state/shell-mutation.js

@@ -0,0 +1,41 @@
+/**
+ * A heuristic parser that extracts file paths likely to be mutated by a
+ * shell command. Used by
+ * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * (warn-only, never blocks).
+ *
+ * Two cases:
+ *   1. Output redirections: `> path` and `>> path`
+ *   2. Common mutators: `sed -i…`, `cp`, `mv`, `touch`: capture the next
+ *      non-space token after the command name (intentionally single-arg even
+ *      though `cp src dest` has two args)
+ *
+ * Caller-supplied `coordRoot` is stripped from absolute paths so the warn
+ * log shows monorepo-relative form.
+ */
+export function shellMutationPaths(cmd, coordRoot = null) {
+    if (!cmd)
+        return [];
+    const out = [];
+    // Output redirections: > path / >> path
+    const redirectRe = />>?[ \t]+([^ \t;|&"'`]+)/g;
+    let m = redirectRe.exec(cmd);
+    while (m !== null) {
+        out.push(m[1]);
+        m = redirectRe.exec(cmd);
+    }
+    // Common mutators. Capture up to the first whitespace after the command
+    // name and take the final token. For 1-arg commands (touch, sed -i 'expr',
+    // cp WITHOUT a dest) that's the path; for 2-arg commands (`cp src dest`,
+    // `mv src dest`) it's the source, intentionally heuristic-only.
+    const cmdRe = /\b(?:sed -i\S*|cp|mv|touch)[ \t]+([^ \t;|&]+)/g;
+    m = cmdRe.exec(cmd);
+    while (m !== null) {
+        out.push(m[1]);
+        m = cmdRe.exec(cmd);
+    }
+    return out
+        .map((p) => p.replace(/^\.\//, ""))
+        .map((p) => (coordRoot && p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p))
+        .filter((p) => p.length > 0);
+}

package/dist/core/agents/state/stale-sweep.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stale-sweep: prune dead heartbeats + orphaned pid-map + .last-peer-hash
+ * files.
+ *
+ * Fires at session.start to clean up crashed-peer detritus before the new
+ * session's UX layer reads peer state.
+ *
+ * Freshness threshold defaults to 600s; configurable via
+ * HARNERY_AGENT_COORD_FRESHNESS env var.
+ */
+export declare function staleSweep(coordRoot: string): {
+    heartbeatsRemoved: string[];
+    pidmapsRemoved: number;
+    peerHashesRemoved: number;
+};
+//# sourceMappingURL=stale-sweep.d.ts.map

package/dist/core/agents/state/stale-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiDH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CA+HA"}

package/dist/core/agents/state/stale-sweep.js

@@ -0,0 +1,166 @@
+/**
+ * Stale-sweep: prune dead heartbeats + orphaned pid-map + .last-peer-hash
+ * files.
+ *
+ * Fires at session.start to clean up crashed-peer detritus before the new
+ * session's UX layer reads peer state.
+ *
+ * Freshness threshold defaults to 600s; configurable via
+ * HARNERY_AGENT_COORD_FRESHNESS env var.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+import { emit } from "../events/emit.js";
+const DEFAULT_FRESHNESS_SECS = 600;
+/** platform → harness, for the swept-event envelope (mirrors heartbeat-writer's harnessOf). */
+function harnessFromPlatform(platform) {
+    if (platform === "cursor")
+        return "cursor";
+    if (platform === "codex")
+        return "codex";
+    return "claude-code";
+}
+/** Emit a best-effort health.heartbeat_swept event. Telemetry only, never throws. */
+function emitSwept(coordRoot, instanceId, harness, sessionId, reason, ageSecs) {
+    try {
+        emit(coordRoot, {
+            event_type: "health.heartbeat_swept",
+            instance_id: instanceId,
+            session_id: sessionId,
+            harness,
+            source: "agent-coord",
+            data: { reason, ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}) },
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        });
+    }
+    catch {
+        /* telemetry only, never break the sweep */
+    }
+}
+/** File mtime in epoch-seconds, or +Infinity if it can't be read (treat as fresh → don't reap). */
+function mtimeSecs(path) {
+    try {
+        return Math.floor(statSync(path).mtimeMs / 1000);
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+export function staleSweep(coordRoot) {
+    const heartbeatsRemoved = [];
+    let pidmapsRemoved = 0;
+    let peerHashesRemoved = 0;
+    const freshness = Number.parseInt(coordEnv("AGENT_COORD_FRESHNESS") ?? String(DEFAULT_FRESHNESS_SECS), 10);
+    const nowSec = Math.floor(Date.now() / 1000);
+    const cutoff = nowSec - (Number.isFinite(freshness) && freshness > 0 ? freshness : DEFAULT_FRESHNESS_SECS);
+    // 1. Prune stale heartbeats from the canonical `.harnery/active/` dir.
+    //
+    // Two deletion regimes, deliberately asymmetric:
+    //   • Valid JSON with an OLD last_heartbeat → the legitimate dead/idle-agent
+    //     prune. Delete (this is the whole point of stale-sweep; idle agents get
+    //     healed back on their next tool call).
+    //   • Can't-trust-content (JSON.parse failed, or no/NaN last_heartbeat) →
+    //     fall back to file MTIME as the liveness signal. Only delete if the file
+    //     is also mtime-old. A fresh-mtime file failing to parse is almost always
+    //     a transient (mid-write / partial read), and deleting it would nuke a
+    //     LIVE agent's heartbeat, the worst possible outcome. So: never reap a
+    //     fresh file on a content failure.
+    // Every deletion now emits health.heartbeat_swept so the lifecycle is
+    // auditable (sweeps used to be silent; see the swept-event schema doc).
+    const liveInstanceIds = new Set();
+    const d = join(coordRoot, ".harnery", "active");
+    if (existsSync(d)) {
+        for (const f of readdirSync(d)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const path = join(d, f);
+            const idFromFile = f.replace(/\.json$/, "");
+            let parsed = null;
+            try {
+                parsed = JSON.parse(readFileSync(path, "utf8"));
+            }
+            catch {
+                parsed = null;
+            }
+            if (parsed === null) {
+                // Unparseable: only reap if the file itself is mtime-old.
+                if (mtimeSecs(path) < cutoff) {
+                    try {
+                        unlinkSync(path);
+                        heartbeatsRemoved.push(f);
+                        emitSwept(coordRoot, idFromFile, "claude-code", idFromFile, "unparseable");
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+                continue;
+            }
+            const instanceId = parsed.instance_id ?? idFromFile;
+            const harness = harnessFromPlatform(parsed.platform);
+            const sessionId = parsed.session_id ?? instanceId;
+            const ts = parsed.last_heartbeat
+                ? Math.floor(Date.parse(parsed.last_heartbeat) / 1000)
+                : Number.NaN;
+            if (!parsed.last_heartbeat || !Number.isFinite(ts)) {
+                // No / NaN last_heartbeat: can't trust content; gate on mtime.
+                if (mtimeSecs(path) < cutoff) {
+                    unlinkSync(path);
+                    heartbeatsRemoved.push(f);
+                    emitSwept(coordRoot, instanceId, harness, sessionId, "missing_ts");
+                }
+                else if (parsed.instance_id) {
+                    liveInstanceIds.add(parsed.instance_id);
+                }
+                continue;
+            }
+            if (ts < cutoff) {
+                // Legitimate stale prune (valid timestamp, past the freshness cutoff).
+                unlinkSync(path);
+                heartbeatsRemoved.push(f);
+                emitSwept(coordRoot, instanceId, harness, sessionId, "stale", nowSec - ts);
+                continue;
+            }
+            if (parsed.instance_id)
+                liveInstanceIds.add(parsed.instance_id);
+        }
+    }
+    // 2. Prune pid-map entries whose instance has no live heartbeat.
+    const pidmapDir = join(coordRoot, ".harnery", "pid-map");
+    if (existsSync(pidmapDir)) {
+        for (const f of readdirSync(pidmapDir)) {
+            const path = join(pidmapDir, f);
+            try {
+                const row = readFileSync(path, "utf8").trim();
+                const ownerId = row.split("\t")[0]?.trim() ?? "";
+                if (!ownerId || !liveInstanceIds.has(ownerId)) {
+                    unlinkSync(path);
+                    pidmapsRemoved += 1;
+                }
+            }
+            catch {
+                /* swallow */
+            }
+        }
+    }
+    // 3. Prune .last-peer-hash files for dead owners.
+    const agentsDir = join(coordRoot, ".harnery");
+    if (existsSync(agentsDir)) {
+        for (const f of readdirSync(agentsDir)) {
+            if (!f.startsWith(".last-peer-hash."))
+                continue;
+            const owner = f.slice(".last-peer-hash.".length);
+            if (!liveInstanceIds.has(owner)) {
+                try {
+                    unlinkSync(join(agentsDir, f));
+                    peerHashesRemoved += 1;
+                }
+                catch {
+                    /* swallow */
+                }
+            }
+        }
+    }
+    return { heartbeatsRemoved, pidmapsRemoved, peerHashesRemoved };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `.harnery/config.jsonc` reader: the host-project config the coord/hook layer
+ * consults when it can't see the consumer CLI's own process.
+ *
+ * The single field this module owns today is `binName`: the host CLI's binary
+ * name (e.g. `myapp`), used in user-facing strings the agent reads and runs:
+ * council prompts, end-of-turn nudges, command help/errors. The coord binaries
+ * (`agent-hook`, `agent-coord`) and the web UI run as harnery itself, so they
+ * have no other way to learn the consumer's bin name; `harn init` stamps it here
+ * for them to read back. The `files` deny/override section is parsed separately
+ * by `web/lib/files.ts`.
+ *
+ * Dependency-free (no jsonc npm dep) so it runs on both Bun and Node, and so the
+ * ADR-009 vendored copies stay portable.
+ */
+/** The standalone CLI's bin name: the resolution floor when nothing else is set. */
+export declare const DEFAULT_BIN_NAME = "harn";
+/** Strip `//` and `/* *​/` comments from JSONC, ignoring comment-like runs inside strings. */
+export declare function stripJsonComments(input: string): string;
+/**
+ * Resolve the host CLI's bin name for user-facing strings. Precedence:
+ *   1. `HARNERY_BIN` env (explicit per-process override)
+ *   2. `.harnery/config.jsonc` `binName` (stamped by `harn init`)
+ *   3. `"harn"` (standalone default)
+ *
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function resolveBinName(coordRoot?: string | null): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAQvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE"}

package/dist/core/config.js

@@ -0,0 +1,108 @@
+/**
+ * `.harnery/config.jsonc` reader: the host-project config the coord/hook layer
+ * consults when it can't see the consumer CLI's own process.
+ *
+ * The single field this module owns today is `binName`: the host CLI's binary
+ * name (e.g. `myapp`), used in user-facing strings the agent reads and runs:
+ * council prompts, end-of-turn nudges, command help/errors. The coord binaries
+ * (`agent-hook`, `agent-coord`) and the web UI run as harnery itself, so they
+ * have no other way to learn the consumer's bin name; `harn init` stamps it here
+ * for them to read back. The `files` deny/override section is parsed separately
+ * by `web/lib/files.ts`.
+ *
+ * Dependency-free (no jsonc npm dep) so it runs on both Bun and Node, and so the
+ * ADR-009 vendored copies stay portable.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../lib/env.js";
+import { findCoordRoot } from "./hooks/resolve/coord-root.js";
+/** The standalone CLI's bin name: the resolution floor when nothing else is set. */
+export const DEFAULT_BIN_NAME = "harn";
+/** Strip `//` and `/* *​/` comments from JSONC, ignoring comment-like runs inside strings. */
+export function stripJsonComments(input) {
+    let out = "";
+    let i = 0;
+    let inString = false;
+    while (i < input.length) {
+        const ch = input[i];
+        if (inString) {
+            out += ch;
+            if (ch === "\\" && i + 1 < input.length) {
+                out += input[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === "/" && input[i + 1] === "/") {
+            while (i < input.length && input[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (ch === "/" && input[i + 1] === "*") {
+            i += 2;
+            while (i < input.length && !(input[i] === "*" && input[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+// mtime-keyed per-process cache: a stat is cheap, a parse on every render isn't.
+let cache = null;
+function readConfig(root) {
+    const p = join(root, ".harnery", "config.jsonc");
+    let mtimeMs = -1;
+    try {
+        mtimeMs = statSync(p).mtimeMs;
+    }
+    catch {
+        /* missing → -1; cache still valid until the file appears */
+    }
+    if (cache && cache.root === root && cache.mtimeMs === mtimeMs)
+        return cache.cfg;
+    let cfg = {};
+    try {
+        const parsed = JSON.parse(stripJsonComments(readFileSync(p, "utf8")));
+        if (parsed && typeof parsed === "object")
+            cfg = parsed;
+    }
+    catch {
+        /* missing or unparseable → defaults (the files-section resolver fails loud; bin name is non-critical) */
+    }
+    cache = { root, mtimeMs, cfg };
+    return cfg;
+}
+/**
+ * Resolve the host CLI's bin name for user-facing strings. Precedence:
+ *   1. `HARNERY_BIN` env (explicit per-process override)
+ *   2. `.harnery/config.jsonc` `binName` (stamped by `harn init`)
+ *   3. `"harn"` (standalone default)
+ *
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function resolveBinName(coordRoot) {
+    const env = coordEnv("BIN");
+    if (env?.trim())
+        return env.trim();
+    const root = coordRoot ?? findCoordRoot();
+    if (root) {
+        const binName = readConfig(root).binName;
+        if (typeof binName === "string" && binName.trim())
+            return binName.trim();
+    }
+    return DEFAULT_BIN_NAME;
+}

package/dist/core/hooks/cli.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `agent-hook` CLI entry point. Phase 2: real canonical-event emission
+ * alongside the legacy stream.
+ *
+ * Flow:
+ *   1. Parse argv → event-name + harness.
+ *   2. Read stdin → harness payload (JSON or empty).
+ *   3. Find coord root (walk up for .harnery/).
+ *   4. Resolve instance_id (env → payload → pid-map walk).
+ *   5. Map event-name → canonical event_type.
+ *   6. Build event data from payload + resolvers (intent, transcript scan).
+ *   7. Append envelope to .harnery/events.ndjson via emit() under flock.
+ *   8. (Still also writes a debug breadcrumb to .harnery/debug/ for visibility.)
+ *
+ * Phase 2 ship criterion: confirms parser correctness across thousands of
+ * real events without affecting behavior. Always exits 0. Failures land in
+ * `.harnery/debug/agent-hook.errors.ndjson` for audit but never break the
+ * harness flow.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/core/hooks/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}