harnery 0.0.1 → 0.2.0

package/dist/lib/format.js

@@ -0,0 +1,139 @@
+/** ANSI color helpers, minimal, no dependencies */
+const isColor = process.stdout.isTTY !== false;
+const code = (n) => (isColor ? `\x1b[${n}m` : "");
+const reset = code(0);
+export const c = {
+    bold: (s) => `${code(1)}${s}${reset}`,
+    dim: (s) => `${code(2)}${s}${reset}`,
+    green: (s) => `${code(32)}${s}${reset}`,
+    red: (s) => `${code(31)}${s}${reset}`,
+    yellow: (s) => `${code(33)}${s}${reset}`,
+    cyan: (s) => `${code(36)}${s}${reset}`,
+    gray: (s) => `${code(90)}${s}${reset}`,
+    magenta: (s) => `${code(35)}${s}${reset}`,
+};
+/** Placeholder shown when a value is missing (null/empty), e.g. an unknown branch or age. */
+export const NO_DATA = "—";
+/**
+ * Pretty-print + ANSI-colorize a JSON value. 2-space indent. TTY-aware: when
+ * stdout is not a TTY, the underlying `c.*` helpers emit no ANSI codes, so
+ * output is plain text. Use this for `--pretty` flags on JSON-emitting commands.
+ *
+ * Colors: keys=cyan, strings=green, numbers=magenta, booleans=yellow, null=dim.
+ */
+export function colorJson(value, indent = 0) {
+    const seen = new WeakSet();
+    const step = "  ";
+    function fmt(v, depth) {
+        if (v === null)
+            return c.dim("null");
+        if (typeof v === "boolean")
+            return c.yellow(String(v));
+        if (typeof v === "number")
+            return c.magenta(String(v));
+        if (typeof v === "string")
+            return c.green(JSON.stringify(v));
+        if (typeof v === "bigint")
+            return c.magenta(`${v}n`);
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                return "[]";
+            if (seen.has(v))
+                return c.dim('"[Circular]"');
+            seen.add(v);
+            const pad = step.repeat(depth + 1);
+            const close = step.repeat(depth);
+            const items = v.map((x) => pad + fmt(x, depth + 1)).join(",\n");
+            return `[\n${items}\n${close}]`;
+        }
+        if (typeof v === "object") {
+            // Class instances that define toJSON() (Big.js, Decimal.js, Date, etc.)
+            // would render as their raw internal shape if we walked Object.keys
+            // directly. Unwrap once so callers see the intended representation
+            // (Big.js → "1.97" instead of {s,e,c} from BigQuery NUMERIC fields).
+            const maybeJsonable = v;
+            if (typeof maybeJsonable.toJSON === "function") {
+                return fmt(maybeJsonable.toJSON(), depth);
+            }
+            const obj = v;
+            const keys = Object.keys(obj);
+            if (keys.length === 0)
+                return "{}";
+            if (seen.has(obj))
+                return c.dim('"[Circular]"');
+            seen.add(obj);
+            const pad = step.repeat(depth + 1);
+            const close = step.repeat(depth);
+            const items = keys
+                .map((k) => `${pad}${c.cyan(JSON.stringify(k))}: ${fmt(obj[k], depth + 1)}`)
+                .join(",\n");
+            return `{\n${items}\n${close}}`;
+        }
+        return JSON.stringify(v) ?? "null";
+    }
+    return fmt(value, indent);
+}
+/** Render a table from rows of objects */
+export function table(rows, opts = {}) {
+    if (rows.length === 0)
+        return c.dim("(no rows)");
+    const maxCol = opts.maxColWidth ?? 60;
+    const keys = Object.keys(rows[0]);
+    // Compute column widths
+    const widths = new Map();
+    for (const key of keys) {
+        let max = key.length;
+        for (const row of rows) {
+            const val = stringify(row[key]);
+            max = Math.max(max, Math.min(val.length, maxCol));
+        }
+        widths.set(key, max);
+    }
+    // Header
+    const header = keys.map((k) => c.bold(k.padEnd(widths.get(k)))).join("  ");
+    const separator = keys.map((k) => "─".repeat(widths.get(k))).join("──");
+    // Rows
+    const lines = rows.map((row) => keys
+        .map((k) => {
+        const val = stringify(row[k]);
+        const display = val.length > maxCol ? `${val.slice(0, maxCol - 1)}…` : val;
+        return display.padEnd(widths.get(k));
+    })
+        .join("  "));
+    return [header, separator, ...lines].join("\n");
+}
+/** Convert a value to a display string */
+function stringify(val) {
+    if (val === null || val === undefined)
+        return "NULL";
+    if (typeof val === "object") {
+        if (val instanceof Date)
+            return val.toISOString();
+        // BigQuery returns { value: "..." } for some types
+        if ("value" in val && Object.keys(val).length === 1) {
+            return String(val.value);
+        }
+        return JSON.stringify(val);
+    }
+    return String(val);
+}
+/** Format rows as CSV */
+export function csv(rows) {
+    if (rows.length === 0)
+        return "";
+    const keys = Object.keys(rows[0]);
+    const header = keys.map(csvEscape).join(",");
+    const lines = rows.map((row) => keys.map((k) => csvEscape(stringify(row[k]))).join(","));
+    return [header, ...lines].join("\n");
+}
+function csvEscape(val) {
+    if (val.includes(",") || val.includes('"') || val.includes("\n")) {
+        return `"${val.replace(/"/g, '""')}"`;
+    }
+    return val;
+}
+/** Print a labeled key-value section */
+export function kvLine(label, value, color) {
+    const colorFn = color ?? ((s) => s);
+    return `  ${c.dim(label.padEnd(14))} ${colorFn(value)}`;
+}

package/dist/lib/http/client.d.ts

@@ -0,0 +1,56 @@
+import type { CookieJar } from "../cookies/index.js";
+/**
+ * Simple cookie-aware HTTP client.
+ *
+ * Wraps the global `fetch` (Bun's native one) with two extras:
+ *   - Attaches a `Cookie:` header from a CookieJar before the request.
+ *   - Persists `Set-Cookie` responses back into the same jar.
+ *
+ * Used by the `fetch` command and other tooling that wants to share session
+ * state with `browse`.
+ */
+export interface FetchOptions {
+    /** HTTP method. Default GET. */
+    method?: string;
+    /** Request body. Strings/Buffers/Streams pass through to fetch directly. */
+    body?: BodyInit | null;
+    /** Extra headers (merged with auto-added Cookie). */
+    headers?: Record<string, string>;
+    /**
+     * Optional CookieJar. When provided:
+     *   - Matching cookies become a Cookie header.
+     *   - Set-Cookie response headers are parsed and merged into the jar.
+     * Pass `null` (or omit) to disable.
+     */
+    jar?: CookieJar | null;
+    /** Optional override for redirect handling. Default `'follow'`. */
+    redirect?: RequestRedirect;
+    /** AbortSignal for timeout/cancel control. */
+    signal?: AbortSignal;
+    /**
+     * Optional callback that returns extra headers to attach based on the
+     * target URL. Consumers can inject extra HTTP headers per-URL via this
+     * callback (e.g., a Cloudflare-bypass header for specific zones).
+     * Caller-provided explicit headers always win; auto-attached values
+     * only land when the key isn't already set.
+     */
+    extraHeaders?: (url: string) => Record<string, string>;
+}
+export interface FetchResult {
+    status: number;
+    statusText: string;
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    /** Number of cookies persisted back into the jar (0 if no jar passed). */
+    cookiesSaved: number;
+}
+/**
+ * Fetch a URL with optional cookie-jar attach + persist.
+ *
+ * Returns the response body as a string (callers handle JSON parsing).
+ * Streams aren't supported; this is a CLI helper, not a streaming HTTP
+ * client. Use Bun's `fetch` directly for streaming workloads.
+ */
+export declare function fetchWithJar(url: string, opts?: FetchOptions): Promise<FetchResult>;
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/http/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD7F"}

package/dist/lib/http/client.js

@@ -0,0 +1,160 @@
+/**
+ * Fetch a URL with optional cookie-jar attach + persist.
+ *
+ * Returns the response body as a string (callers handle JSON parsing).
+ * Streams aren't supported; this is a CLI helper, not a streaming HTTP
+ * client. Use Bun's `fetch` directly for streaming workloads.
+ */
+export async function fetchWithJar(url, opts = {}) {
+    const headers = { ...(opts.headers ?? {}) };
+    if (opts.jar) {
+        const cookieHeader = opts.jar.header(url);
+        if (cookieHeader && !headers.Cookie && !headers.cookie) {
+            headers.Cookie = cookieHeader;
+        }
+    }
+    // Caller-provided extraHeaders callback (e.g., for Cloudflare-bypass or
+    // custom auth headers). Caller-supplied explicit headers always win.
+    if (opts.extraHeaders) {
+        for (const [k, v] of Object.entries(opts.extraHeaders(url))) {
+            if (!(k in headers) && !(k.toLowerCase() in headers))
+                headers[k] = v;
+        }
+    }
+    const response = await fetch(url, {
+        method: opts.method ?? "GET",
+        body: opts.body,
+        headers,
+        redirect: opts.redirect ?? "follow",
+        signal: opts.signal,
+    });
+    let cookiesSaved = 0;
+    if (opts.jar) {
+        const setCookieHeaders = collectSetCookie(response.headers);
+        if (setCookieHeaders.length > 0) {
+            const parsedHost = new URL(response.url).hostname;
+            const cookies = setCookieHeaders
+                .map((sc) => parseSetCookie(sc, parsedHost))
+                .filter((c) => c !== null);
+            for (const cookie of cookies) {
+                opts.jar.set(cookie);
+            }
+            cookiesSaved = cookies.length;
+        }
+    }
+    const headerObj = {};
+    response.headers.forEach((value, key) => {
+        headerObj[key] = value;
+    });
+    return {
+        status: response.status,
+        statusText: response.statusText,
+        url: response.url,
+        headers: headerObj,
+        body: await response.text(),
+        cookiesSaved,
+    };
+}
+// ---------------------------------------------------------------------------
+// Set-Cookie parsing
+// ---------------------------------------------------------------------------
+//
+// `fetch` joins multiple Set-Cookie headers with `, ` per the spec, but that
+// collides with the comma-separated date format in `Expires=`. We use the
+// dual-mode approach: prefer the `getSetCookie()` method when available
+// (Node 20+, Bun 1.0+) and fall back to manual splitting otherwise.
+function collectSetCookie(headers) {
+    const h = headers;
+    if (typeof h.getSetCookie === "function") {
+        return h.getSetCookie();
+    }
+    const raw = headers.get("set-cookie");
+    return raw ? splitSetCookieHeader(raw) : [];
+}
+function splitSetCookieHeader(raw) {
+    // Splits on ", " that precedes a new cookie (heuristic: a token followed
+    // by `=`), avoiding date-internal commas like `Expires=Wed, 21 Oct …`.
+    const parts = [];
+    let depth = 0;
+    let buf = "";
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch === "," && depth === 0) {
+            const ahead = raw.slice(i + 1).trimStart();
+            if (/^[A-Za-z0-9_!#$%&'*+\-.^`|~]+=/.test(ahead)) {
+                parts.push(buf.trim());
+                buf = "";
+                continue;
+            }
+        }
+        if (ch === "=")
+            depth++;
+        if (ch === ";")
+            depth = 0;
+        buf += ch;
+    }
+    if (buf.trim())
+        parts.push(buf.trim());
+    return parts;
+}
+function parseSetCookie(raw, defaultDomain) {
+    const parts = raw.split(";").map((p) => p.trim());
+    if (parts.length === 0)
+        return null;
+    const first = parts[0];
+    if (!first)
+        return null;
+    const eq = first.indexOf("=");
+    if (eq < 0)
+        return null;
+    const name = first.slice(0, eq).trim();
+    const value = first.slice(eq + 1).trim();
+    if (!name)
+        return null;
+    const cookie = {
+        name,
+        value,
+        domain: defaultDomain,
+        path: "/",
+        expires: -1,
+        httpOnly: false,
+        secure: false,
+        session: true,
+        size: name.length + value.length,
+    };
+    for (const attr of parts.slice(1)) {
+        const lower = attr.toLowerCase();
+        if (lower.startsWith("domain=")) {
+            const d = attr.slice(7).trim();
+            cookie.domain = d.startsWith(".") ? d : `.${d}`;
+        }
+        else if (lower.startsWith("path=")) {
+            cookie.path = attr.slice(5).trim() || "/";
+        }
+        else if (lower.startsWith("expires=")) {
+            const ts = Date.parse(attr.slice(8).trim());
+            if (!Number.isNaN(ts)) {
+                cookie.expires = Math.floor(ts / 1000);
+                cookie.session = false;
+            }
+        }
+        else if (lower.startsWith("max-age=")) {
+            const seconds = Number.parseInt(attr.slice(8).trim(), 10);
+            if (!Number.isNaN(seconds)) {
+                cookie.expires = Math.floor(Date.now() / 1000) + seconds;
+                cookie.session = false;
+            }
+        }
+        else if (lower === "secure") {
+            cookie.secure = true;
+        }
+        else if (lower === "httponly") {
+            cookie.httpOnly = true;
+        }
+        else if (lower.startsWith("samesite=")) {
+            const v = attr.slice(9).trim();
+            cookie.sameSite = v.charAt(0).toUpperCase() + v.slice(1).toLowerCase();
+        }
+    }
+    return cookie;
+}

package/dist/lib/http/index.d.ts

@@ -0,0 +1,2 @@
+export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/http/index.js

@@ -0,0 +1 @@
+export { fetchWithJar } from "./client.js";

package/dist/lib/identities/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Agent persona identity registry: per-agent durable UUIDs.
+ *
+ * The coord layer has two id concepts that get confused:
+ *   - `instance_id`: Claude Code session UUID (fresh per session). Lives at
+ *     `.harnery/active/<instance_id>.json` as the heartbeat filename.
+ *   - `agent_id` (this module): durable per-AGENT-PERSONA UUID. Stable
+ *     across sessions; same UUID for every Maya session, regardless of
+ *     how many times she restarts Claude Code.
+ *
+ * Storage: `.harnery/identities/<agent_id>.json`, one file per persona.
+ * The filename IS the id so reverse lookup is O(1) by id; forward lookup
+ * by name is a scan (small directory, ~100 personas tops in practice).
+ *
+ * Used as the canonical identifier in:
+ *   - Council manifests (`created_by_id`, `steward_id`, `member_ids[]`)
+ *   - Council body filenames (`<agent_id>.md` not `<name>.md`)
+ *   - Session events ndjson (new `agent_id` field alongside `agent_name`)
+ *   - Heartbeats (new `agent_id` field; existing CC subagent-call id
+ *     renamed to `subagent_call_id`)
+ */
+export declare const IDENTITY_SCHEMA_VERSION: 1;
+export interface AgentIdentity {
+    schema_version: 1;
+    /** Persistent persona UUID. v4. */
+    agent_id: string;
+    /** Current display name (e.g. "Maya", without the "agent-" prefix). */
+    name: string;
+    /** Prior names this identity has been known by. Updated by renameIdentity(). */
+    aliases: Array<{
+        name: string;
+        retired_at: string;
+    }>;
+    /** UTC ISO-8601 timestamp of first mint. */
+    created_at: string;
+}
+/** Strip an "agent-" prefix if present. The registry stores bare names. */
+export declare function bareName(raw: string): string;
+/** Re-add the "agent-" prefix for display contexts. */
+export declare function displayName(name: string): string;
+/** Read one identity by id. Null if missing. */
+export declare function lookupById(agentId: string): AgentIdentity | null;
+/** Read one identity by display name (case-insensitive on bare name).
+ * Scans the directory; O(N) on identity count. */
+export declare function lookupByName(name: string): AgentIdentity | null;
+/** All known identities, sorted by created_at ascending. */
+export declare function listIdentities(): AgentIdentity[];
+/**
+ * Find an identity by name, or mint one. Returns the resolved identity.
+ * Idempotent: calling twice with the same name returns the same record.
+ *
+ * Mint path: generates a fresh uuid v4, writes the file atomically (tmp +
+ * rename), returns the new identity. Race-safe: if two processes mint
+ * simultaneously, both files land (different ids), but lookupByName will
+ * surface whichever happened to be read first; the second is orphaned.
+ * For agent personas (added at human cadence) this race is theoretical.
+ */
+export declare function ensureIdentity(name: string): AgentIdentity;
+/** Persist an identity (tmp + rename). Creates the dir if missing. */
+export declare function writeIdentity(id: AgentIdentity): void;
+/**
+ * Rename an existing identity. The prior name lands in aliases[] so name
+ * lookup still resolves correctly. The agent_id is stable across renames,
+ * which is the whole point of the registry.
+ */
+export declare function renameIdentity(agentId: string, newName: string): AgentIdentity;
+/**
+ * Resolve a string to an agent_id. Accepts:
+ *   - A UUID (already an id), verified to exist in registry
+ *   - A display name (e.g. "agent-Maya" or "Maya"), resolved via lookupByName
+ * Returns null when the input is neither a known id nor a known name.
+ *
+ * Does NOT mint. Callers that want mint-on-miss should call ensureIdentity()
+ * with a name, then use the returned agent_id.
+ */
+export declare function resolveAgentId(input: string): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/identities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,CAAC,CAAC;IAClB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAqCD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMhE;AAED;kDACkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAc/D;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAWhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAY1D;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAc9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU3D"}

package/dist/lib/identities/index.js

@@ -0,0 +1,190 @@
+/**
+ * Agent persona identity registry: per-agent durable UUIDs.
+ *
+ * The coord layer has two id concepts that get confused:
+ *   - `instance_id`: Claude Code session UUID (fresh per session). Lives at
+ *     `.harnery/active/<instance_id>.json` as the heartbeat filename.
+ *   - `agent_id` (this module): durable per-AGENT-PERSONA UUID. Stable
+ *     across sessions; same UUID for every Maya session, regardless of
+ *     how many times she restarts Claude Code.
+ *
+ * Storage: `.harnery/identities/<agent_id>.json`, one file per persona.
+ * The filename IS the id so reverse lookup is O(1) by id; forward lookup
+ * by name is a scan (small directory, ~100 personas tops in practice).
+ *
+ * Used as the canonical identifier in:
+ *   - Council manifests (`created_by_id`, `steward_id`, `member_ids[]`)
+ *   - Council body filenames (`<agent_id>.md` not `<name>.md`)
+ *   - Session events ndjson (new `agent_id` field alongside `agent_name`)
+ *   - Heartbeats (new `agent_id` field; existing CC subagent-call id
+ *     renamed to `subagent_call_id`)
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { resolve } from "node:path";
+import { monorepoRoot } from "../../core/agents/index.js";
+export const IDENTITY_SCHEMA_VERSION = 1;
+function identitiesDir() {
+    const root = monorepoRoot();
+    if (!root)
+        return null;
+    return resolve(root, ".harnery", "identities");
+}
+function ensureDir() {
+    const dir = identitiesDir();
+    if (!dir)
+        throw new Error("not in an agent session; no monorepo root");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function identityPath(agentId) {
+    return resolve(ensureDir(), `${agentId}.json`);
+}
+function nowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function readIdentityFile(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.schema_version !== IDENTITY_SCHEMA_VERSION) {
+            throw new Error(`identity ${path}: unsupported schema_version=${parsed.schema_version} (expected ${IDENTITY_SCHEMA_VERSION})`);
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Strip an "agent-" prefix if present. The registry stores bare names. */
+export function bareName(raw) {
+    const trimmed = raw.trim();
+    return trimmed.startsWith("agent-") ? trimmed.slice("agent-".length) : trimmed;
+}
+/** Re-add the "agent-" prefix for display contexts. */
+export function displayName(name) {
+    return name.startsWith("agent-") ? name : `agent-${name}`;
+}
+/** Read one identity by id. Null if missing. */
+export function lookupById(agentId) {
+    const dir = identitiesDir();
+    if (!dir)
+        return null;
+    const fp = resolve(dir, `${agentId}.json`);
+    if (!existsSync(fp))
+        return null;
+    return readIdentityFile(fp);
+}
+/** Read one identity by display name (case-insensitive on bare name).
+ * Scans the directory; O(N) on identity count. */
+export function lookupByName(name) {
+    const dir = identitiesDir();
+    if (!dir || !existsSync(dir))
+        return null;
+    const wanted = bareName(name).toLowerCase();
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const id = readIdentityFile(resolve(dir, f));
+        if (!id)
+            continue;
+        if (id.name.toLowerCase() === wanted)
+            return id;
+        for (const alias of id.aliases) {
+            if (alias.name.toLowerCase() === wanted)
+                return id;
+        }
+    }
+    return null;
+}
+/** All known identities, sorted by created_at ascending. */
+export function listIdentities() {
+    const dir = identitiesDir();
+    if (!dir || !existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const id = readIdentityFile(resolve(dir, f));
+        if (id)
+            out.push(id);
+    }
+    out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    return out;
+}
+/**
+ * Find an identity by name, or mint one. Returns the resolved identity.
+ * Idempotent: calling twice with the same name returns the same record.
+ *
+ * Mint path: generates a fresh uuid v4, writes the file atomically (tmp +
+ * rename), returns the new identity. Race-safe: if two processes mint
+ * simultaneously, both files land (different ids), but lookupByName will
+ * surface whichever happened to be read first; the second is orphaned.
+ * For agent personas (added at human cadence) this race is theoretical.
+ */
+export function ensureIdentity(name) {
+    const existing = lookupByName(name);
+    if (existing)
+        return existing;
+    const id = {
+        schema_version: IDENTITY_SCHEMA_VERSION,
+        agent_id: randomUUID(),
+        name: bareName(name),
+        aliases: [],
+        created_at: nowIso(),
+    };
+    writeIdentity(id);
+    return id;
+}
+/** Persist an identity (tmp + rename). Creates the dir if missing. */
+export function writeIdentity(id) {
+    ensureDir();
+    const fp = identityPath(id.agent_id);
+    const tmp = `${fp}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(id, null, 2)}\n`, "utf8");
+    renameSync(tmp, fp);
+}
+/**
+ * Rename an existing identity. The prior name lands in aliases[] so name
+ * lookup still resolves correctly. The agent_id is stable across renames,
+ * which is the whole point of the registry.
+ */
+export function renameIdentity(agentId, newName) {
+    const existing = lookupById(agentId);
+    if (!existing) {
+        throw new Error(`renameIdentity: no identity matching '${agentId}'`);
+    }
+    const bare = bareName(newName);
+    if (existing.name === bare)
+        return existing;
+    const next = {
+        ...existing,
+        name: bare,
+        aliases: [...existing.aliases, { name: existing.name, retired_at: nowIso() }],
+    };
+    writeIdentity(next);
+    return next;
+}
+/**
+ * Resolve a string to an agent_id. Accepts:
+ *   - A UUID (already an id), verified to exist in registry
+ *   - A display name (e.g. "agent-Maya" or "Maya"), resolved via lookupByName
+ * Returns null when the input is neither a known id nor a known name.
+ *
+ * Does NOT mint. Callers that want mint-on-miss should call ensureIdentity()
+ * with a name, then use the returned agent_id.
+ */
+export function resolveAgentId(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    // UUID shape check, relaxed; we only need the lookupById to confirm.
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmed)) {
+        const byId = lookupById(trimmed);
+        if (byId)
+            return byId.agent_id;
+    }
+    const byName = lookupByName(trimmed);
+    return byName ? byName.agent_id : null;
+}

package/dist/lib/machine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a human-friendly label for the current machine. Used to tag
+ * coordination artifacts (scratch-doc headers, session telemetry) by the host
+ * they originated on.
+ *
+ * Precedence (first non-empty wins):
+ *   1. HARNERY_MACHINE env var:          transient / per-launch / CI override
+ *   2. ~/.config/harnery/machine file:   persistent, harness-neutral identity
+ *   3. os.hostname() (normalized):       automatic floor; never empty
+ *
+ * The env var sits on top for ad-hoc overrides; the file is the durable home for
+ * a machine's name (it survives across Claude Code / Cursor / Codex and GUI
+ * launches that don't inherit a shell rc); hostname guarantees a real answer
+ * with zero configuration.
+ */
+export declare function resolveMachineLabel(): string;
+/** Absolute path of the machine-label file, honoring XDG_CONFIG_HOME. */
+export declare function machineFilePath(): string | null;
+//# sourceMappingURL=machine.d.ts.map

package/dist/lib/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/lib/machine.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAK/C"}