harnery 0.32.0 → 0.34.0

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

@@ -0,0 +1,98 @@
+/**
+ * Headless harness calling — run a one-shot prompt (optionally with images)
+ * through a locally installed AI coding harness CLI and return its reply.
+ *
+ * Backends, in default preference order (subscription seats an embedding
+ * host already pays for, before any metered API a host might add on top):
+ *
+ *   1. claude-code   `claude -p`         JSON envelope on stdout
+ *   2. codex         `codex exec`        last message written to a file
+ *   3. cursor        `cursor-agent -p`   plain text on stdout
+ *
+ * Design rules, each learned from a live failure:
+ *
+ * - Every call runs from a NEUTRAL temp cwd holding only the staged images,
+ *   so the nested session loads no repo instructions, hooks, or coordination
+ *   rituals from the caller's checkout.
+ * - The child's stdin is CLOSED immediately. execFile leaves it open as a
+ *   pipe, and codex interprets that as "more prompt coming" and blocks on
+ *   it, then exits with no output.
+ * - An empty reply THROWS instead of returning "": a one-shot call that
+ *   produced nothing was inconclusive, and callers gating on the result must
+ *   fail closed rather than read silence as success.
+ * - `runHeadless` walks the backend chain PER CALL: a backend that is
+ *   installed but errors (rate limit, timeout, transient exec failure) hands
+ *   the same request to the next backend instead of failing the call. "On
+ *   PATH" is not "working", and under parallel load the first backend can
+ *   flake on a fraction of calls while the second runs clean.
+ *
+ * Env knobs (read through coordEnv, so the HARNERY_ prefix stays in one
+ * place): HARNERY_HEADLESS_BACKEND forces one backend and disables the
+ * fallback walk; HARNERY_HEADLESS_MODEL overrides the model passed to
+ * whichever backend runs.
+ */
+/** Names accepted by `runHeadlessOn`, `runHeadless({backends})`, and the
+ * HARNERY_HEADLESS_BACKEND env knob. */
+export type HeadlessBackendName = "claude-code" | "codex" | "cursor";
+/** An image to stage into the call's neutral cwd. `data` is the PNG bytes
+ * (Buffer) or their base64 encoding (string). */
+export interface HeadlessImage {
+    data: Buffer | string;
+    /** Staged filename inside the neutral dir (default `image-<n>.png`). */
+    name?: string;
+}
+export interface HeadlessRequest {
+    /**
+     * The prompt, or a builder receiving the staged image paths. Backends that
+     * cannot attach an image natively (claude-code, cursor) rely on the prompt
+     * naming the staged paths so the harness reads them with its own tools;
+     * codex additionally attaches every image via `-i`.
+     */
+    prompt: string | ((ctx: {
+        imagePaths: string[];
+    }) => string);
+    images?: HeadlessImage[];
+    /** Model override for this call; HARNERY_HEADLESS_MODEL wins over it. */
+    model?: string;
+    /** Kill the child after this long (default 240_000 ms). */
+    timeoutMs?: number;
+    /** Agentic turn budget where the backend supports one (default 4). */
+    maxTurns?: number;
+}
+export interface HeadlessResult {
+    /** The harness's final reply text, never empty (empty replies throw). */
+    text: string;
+    /** Which backend produced it. */
+    backend: HeadlessBackendName;
+}
+export interface RunHeadlessOptions {
+    /** Preference order (default: HEADLESS_BACKENDS order). */
+    backends?: HeadlessBackendName[];
+    /** Walk the chain past a failing backend (default true). Forcing a backend
+     * via HARNERY_HEADLESS_BACKEND implies false. */
+    fallback?: boolean;
+}
+/** Cross-runtime `which`: walk PATH (and PATHEXT on Windows) for an
+ * executable. Node has no built-in and Bun.which only exists under Bun. */
+export declare function whichBin(bin: string): string | undefined;
+/** The backend registry in default preference order. */
+export declare const HEADLESS_BACKENDS: ReadonlyArray<{
+    name: HeadlessBackendName;
+    bin: string;
+}>;
+/** Backends whose binary is on PATH right now, in preference order. Being
+ * listed means installed, not proven working — that is what the per-call
+ * fallback in `runHeadless` is for. */
+export declare function availableHeadlessBackends(): HeadlessBackendName[];
+/** Run the request on exactly one named backend. Throws when the backend is
+ * not installed or the call fails. */
+export declare function runHeadlessOn(name: HeadlessBackendName, req: HeadlessRequest): Promise<HeadlessResult>;
+/**
+ * Run the request on the first backend that succeeds, walking the preference
+ * order past installed-but-failing backends (unless fallback is disabled or a
+ * backend is forced via HARNERY_HEADLESS_BACKEND). Throws when no backend is
+ * installed, or every attempted backend failed — the error message carries
+ * each backend's failure so a flaky chain is diagnosable.
+ */
+export declare function runHeadless(req: HeadlessRequest, opts?: RunHeadlessOptions): Promise<HeadlessResult>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/headless/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoBH;wCACwC;AACxC,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE;iDACiD;AACjD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,MAAM,CAAC,CAAC;IAC7D,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC;qDACiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;2EAC2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBxD;AA6FD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAIvF,CAAC;AAaF;;uCAEuC;AACvC,wBAAgB,yBAAyB,IAAI,mBAAmB,EAAE,CAEjE;AAED;sCACsC;AACtC,wBAAsB,aAAa,CACjC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,cAAc,CAAC,CASzB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAwBzB"}

package/dist/lib/headless/index.js

@@ -0,0 +1,211 @@
+/**
+ * Headless harness calling — run a one-shot prompt (optionally with images)
+ * through a locally installed AI coding harness CLI and return its reply.
+ *
+ * Backends, in default preference order (subscription seats an embedding
+ * host already pays for, before any metered API a host might add on top):
+ *
+ *   1. claude-code   `claude -p`         JSON envelope on stdout
+ *   2. codex         `codex exec`        last message written to a file
+ *   3. cursor        `cursor-agent -p`   plain text on stdout
+ *
+ * Design rules, each learned from a live failure:
+ *
+ * - Every call runs from a NEUTRAL temp cwd holding only the staged images,
+ *   so the nested session loads no repo instructions, hooks, or coordination
+ *   rituals from the caller's checkout.
+ * - The child's stdin is CLOSED immediately. execFile leaves it open as a
+ *   pipe, and codex interprets that as "more prompt coming" and blocks on
+ *   it, then exits with no output.
+ * - An empty reply THROWS instead of returning "": a one-shot call that
+ *   produced nothing was inconclusive, and callers gating on the result must
+ *   fail closed rather than read silence as success.
+ * - `runHeadless` walks the backend chain PER CALL: a backend that is
+ *   installed but errors (rate limit, timeout, transient exec failure) hands
+ *   the same request to the next backend instead of failing the call. "On
+ *   PATH" is not "working", and under parallel load the first backend can
+ *   flake on a fraction of calls while the second runs clean.
+ *
+ * Env knobs (read through coordEnv, so the HARNERY_ prefix stays in one
+ * place): HARNERY_HEADLESS_BACKEND forces one backend and disables the
+ * fallback walk; HARNERY_HEADLESS_MODEL overrides the model passed to
+ * whichever backend runs.
+ */
+import { execFile } from "node:child_process";
+import { accessSync, constants, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+import { promisify } from "node:util";
+import { coordEnv } from "../env.js";
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 32 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_MAX_TURNS = 4;
+/** Cross-runtime `which`: walk PATH (and PATHEXT on Windows) for an
+ * executable. Node has no built-in and Bun.which only exists under Bun. */
+export function whichBin(bin) {
+    if (isAbsolute(bin))
+        return isExecutable(bin) ? bin : undefined;
+    const paths = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+    for (const dir of paths) {
+        for (const ext of exts) {
+            const candidate = join(dir, bin + ext.toLowerCase());
+            if (isExecutable(candidate))
+                return candidate;
+            if (ext) {
+                const upper = join(dir, bin + ext);
+                if (isExecutable(upper))
+                    return upper;
+            }
+        }
+    }
+    return undefined;
+}
+function isExecutable(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write the request's images into a fresh neutral dir and resolve the
+ * prompt against their staged paths. Caller must clean the dir up. */
+function stageCall(req) {
+    const dir = mkdtempSync(join(tmpdir(), "harnery-headless-"));
+    const imagePaths = (req.images ?? []).map((img, i) => {
+        const path = join(dir, img.name ?? `image-${i + 1}.png`);
+        writeFileSync(path, typeof img.data === "string" ? Buffer.from(img.data, "base64") : img.data);
+        return path;
+    });
+    const prompt = typeof req.prompt === "function" ? req.prompt({ imagePaths }) : req.prompt;
+    return {
+        dir,
+        imagePaths,
+        prompt,
+        model: coordEnv("HEADLESS_MODEL") ?? req.model,
+        timeoutMs: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxTurns: req.maxTurns ?? DEFAULT_MAX_TURNS,
+    };
+}
+/** Run a harness CLI from the neutral dir with stdin CLOSED (see module
+ * comment: an open stdin pipe deadlocks codex). */
+function execHarness(bin, args, call) {
+    const pending = execFileAsync(bin, args, {
+        cwd: call.dir,
+        timeout: call.timeoutMs,
+        maxBuffer: MAX_BUFFER,
+    });
+    pending.child.stdin?.end();
+    return pending;
+}
+function assertReply(text, backend) {
+    if (!text.trim())
+        throw new Error(`${backend}: empty reply (inconclusive; failing closed)`);
+    return { text, backend };
+}
+async function runClaudeCode(bin, call) {
+    const args = ["-p", call.prompt, "--output-format", "json", "--max-turns", String(call.maxTurns)];
+    if (call.imagePaths.length)
+        args.push("--allowedTools", "Read");
+    if (call.model)
+        args.push("--model", call.model);
+    const { stdout } = await execHarness(bin, args, call);
+    const envelope = JSON.parse(stdout);
+    if (envelope.is_error) {
+        throw new Error(typeof envelope.result === "string" ? envelope.result : "claude-code: headless error");
+    }
+    return assertReply(typeof envelope.result === "string" ? envelope.result : "", "claude-code");
+}
+async function runCodex(bin, call) {
+    const outPath = join(call.dir, "last-message.txt");
+    const args = ["exec", "--skip-git-repo-check"];
+    for (const png of call.imagePaths)
+        args.push("-i", png);
+    args.push("--output-last-message", outPath);
+    if (call.model)
+        args.push("-m", call.model);
+    args.push(call.prompt);
+    await execHarness(bin, args, call);
+    return assertReply(existsSync(outPath) ? readFileSync(outPath, "utf-8") : "", "codex");
+}
+/** `-f` trusts the neutral dir so cursor's read tool runs without a prompt. */
+async function runCursor(bin, call) {
+    const args = ["-p", call.prompt, "--output-format", "text", "-f"];
+    if (call.model)
+        args.push("--model", call.model);
+    const { stdout } = await execHarness(bin, args, call);
+    return assertReply(stdout, "cursor");
+}
+/** The backend registry in default preference order. */
+export const HEADLESS_BACKENDS = [
+    { name: "claude-code", bin: "claude" },
+    { name: "codex", bin: "codex" },
+    { name: "cursor", bin: "cursor-agent" },
+];
+const RUNNERS = {
+    "claude-code": runClaudeCode,
+    codex: runCodex,
+    cursor: runCursor,
+};
+function backendBin(name) {
+    const entry = HEADLESS_BACKENDS.find((b) => b.name === name);
+    return entry ? whichBin(entry.bin) : undefined;
+}
+/** Backends whose binary is on PATH right now, in preference order. Being
+ * listed means installed, not proven working — that is what the per-call
+ * fallback in `runHeadless` is for. */
+export function availableHeadlessBackends() {
+    return HEADLESS_BACKENDS.filter((b) => whichBin(b.bin)).map((b) => b.name);
+}
+/** Run the request on exactly one named backend. Throws when the backend is
+ * not installed or the call fails. */
+export async function runHeadlessOn(name, req) {
+    const bin = backendBin(name);
+    if (!bin)
+        throw new Error(`headless backend not installed: ${name}`);
+    const call = stageCall(req);
+    try {
+        return await RUNNERS[name](bin, call);
+    }
+    finally {
+        rmSync(call.dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Run the request on the first backend that succeeds, walking the preference
+ * order past installed-but-failing backends (unless fallback is disabled or a
+ * backend is forced via HARNERY_HEADLESS_BACKEND). Throws when no backend is
+ * installed, or every attempted backend failed — the error message carries
+ * each backend's failure so a flaky chain is diagnosable.
+ */
+export async function runHeadless(req, opts = {}) {
+    const forced = coordEnv("HEADLESS_BACKEND");
+    if (forced && !opts.backends) {
+        if (!HEADLESS_BACKENDS.some((b) => b.name === forced)) {
+            throw new Error(`unknown HARNERY_HEADLESS_BACKEND: ${forced}`);
+        }
+        return runHeadlessOn(forced, req);
+    }
+    const order = opts.backends ?? HEADLESS_BACKENDS.map((b) => b.name);
+    const installed = order.filter((name) => backendBin(name));
+    if (!installed.length) {
+        throw new Error(`no headless backend installed (looked for: ${order.join(", ")})`);
+    }
+    const fallback = opts.fallback ?? true;
+    const attempts = fallback ? installed : installed.slice(0, 1);
+    const failures = [];
+    for (const name of attempts) {
+        try {
+            return await runHeadlessOn(name, req);
+        }
+        catch (err) {
+            failures.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    throw new Error(`every headless backend failed:\n  ${failures.join("\n  ")}`);
+}

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

@@ -3,8 +3,8 @@
  *
  * The operation is serialized because "is this name live?" and "claim it"
  * must be one critical section. Authoritative state is written twice on
- * purpose: `.name-history` heals a missing heartbeat, while the canonical
- * `identity.assumed` event makes replay and derived readers converge.
+ * purpose: `.name-history` supplies display metadata, while the canonical
+ * `coord.identity_attested` event makes replay and derived readers converge.
  *
  * Local collision policy: a fresh heartbeat alone is not enough to block.
  * If the namesake has no live pid-map process (crashed session, healed
@@ -12,7 +12,7 @@
  * Refuse only when another process is still alive, or when cached remote
  * presence reports the name.
  */
-export type IdentityAssumeErrorCode = "identity_busy" | "identity_in_use" | "identity_is_ancestor" | "identity_not_found" | "invalid_identity" | "no_heartbeat" | "not_session" | "projection_failed";
+export type IdentityAssumeErrorCode = "identity_busy" | "identity_in_use" | "identity_is_ancestor" | "identity_not_found" | "invalid_identity" | "no_live_generation" | "not_session" | "projection_failed";
 export declare class IdentityAssumeError extends Error {
     readonly code: IdentityAssumeErrorCode;
     constructor(code: IdentityAssumeErrorCode, message: string);
@@ -38,7 +38,7 @@ export interface IdentityAssumeResult {
 }
 /** Best-effort collision read across local heartbeats and cached remote
  * presence. No network call occurs; absent presence degrades to local-only. */
-export declare function findIdentityConflict(coordRoot: string, instanceId: string, name: string, nowMs?: number): IdentityConflict | null;
+export declare function findIdentityConflict(coordRoot: string, instanceId: string, name: string, nowMs?: number, excludedInstanceIds?: ReadonlySet<string>): IdentityConflict | null;
 /**
  * Drop a local namesake whose adapter process is gone. Fresh heartbeats can
  * linger after a crash (or after heartbeat heal without a live pid-map), and

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

@@ -1 +1 @@
-{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2BH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,GACjB,gBAAgB,GAAG,IAAI,CAiCzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CA2CT;AAyED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,oBAAoB,CA4HtB"}
+{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAuBH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,EAClB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,gBAAgB,GAAG,IAAI,CA6BzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAyCT;AAyED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,oBAAoB,CAkHtB"}

package/dist/lib/identities/assume.js

@@ -3,8 +3,8 @@
  *
  * The operation is serialized because "is this name live?" and "claim it"
  * must be one critical section. Authoritative state is written twice on
- * purpose: `.name-history` heals a missing heartbeat, while the canonical
- * `identity.assumed` event makes replay and derived readers converge.
+ * purpose: `.name-history` supplies display metadata, while the canonical
+ * `coord.identity_attested` event makes replay and derived readers converge.
  *
  * Local collision policy: a fresh heartbeat alone is not enough to block.
  * If the namesake has no live pid-map process (crashed session, healed
@@ -13,12 +13,12 @@
  * presence reports the name.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { emitAndProject } from "../../core/agents/cli-emit.js";
-import { emit } from "../../core/agents/events/emit.js";
-import { readHeartbeat } from "../../core/agents/state/heartbeat-writer.js";
-import { recordNameAssumption, resolveForkAncestry } from "../../core/agents/state/names.js";
+import { recordLiveIdentityChangeV3 } from "../../core/agents/live-authority-v3.js";
+import { recordLiveSweepObservationV3 } from "../../core/agents/live-lifecycle-v3.js";
+import { readLiveCoordinationRow, readLiveCoordinationRows, } from "../../core/agents/state/live-coordination-view.js";
+import { resolveForkAncestry } from "../../core/agents/state/names.js";
 import { instanceHasLivePid, removePidmapRowsForInstance } from "../../core/agents/state/pidmap.js";
 import { coordFreshnessSeconds } from "../../core/config.js";
 import { readRemoteMachines } from "../../core/presence/index.js";
@@ -40,25 +40,16 @@ function heartbeatIsFresh(hb, cutoffMs) {
 }
 /** Best-effort collision read across local heartbeats and cached remote
  * presence. No network call occurs; absent presence degrades to local-only. */
-export function findIdentityConflict(coordRoot, instanceId, name, nowMs = Date.now()) {
+export function findIdentityConflict(coordRoot, instanceId, name, nowMs = Date.now(), excludedInstanceIds = new Set()) {
     const wanted = name.toLowerCase();
     const cutoffMs = nowMs - coordFreshnessSeconds(coordRoot) * 1000;
-    const activeDir = join(coordRoot, ".harnery", "active");
-    if (existsSync(activeDir)) {
-        for (const file of readdirSync(activeDir)) {
-            if (!file.endsWith(".json"))
-                continue;
-            try {
-                const hb = JSON.parse(readFileSync(join(activeDir, file), "utf8"));
-                if (hb.instance_id === instanceId || !heartbeatIsFresh(hb, cutoffMs))
-                    continue;
-                if ((hb.name ?? "").toLowerCase() === wanted) {
-                    return { instance_id: hb.instance_id, name: hb.name ?? name, scope: "local" };
-                }
-            }
-            catch {
-                // Malformed heartbeats are handled by stale sweep, not this command.
-            }
+    for (const row of readLiveCoordinationRows(coordRoot)) {
+        if (row.instance_id === instanceId ||
+            excludedInstanceIds.has(row.instance_id) ||
+            !heartbeatIsFresh(row, cutoffMs))
+            continue;
+        if ((row.name ?? "").toLowerCase() === wanted) {
+            return { instance_id: row.instance_id, name: row.name ?? name, scope: "local" };
         }
     }
     for (const remote of readRemoteMachines(coordRoot)) {
@@ -92,14 +83,21 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
     let adapter = "claude-code";
     let sessionId = conflict.instance_id;
     let ageSecs;
+    const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
+    if (liveRow) {
+        adapter = adapterOf(liveRow.platform);
+        sessionId = liveRow.session_id || conflict.instance_id;
+        const ts = Date.parse(liveRow.last_heartbeat);
+        if (Number.isFinite(ts))
+            ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+    }
     if (existsSync(hbPath)) {
         try {
             const hb = JSON.parse(readFileSync(hbPath, "utf8"));
+            // Native producer identity is private cache metadata, not ledger authority.
+            // It is required to join the exact producer state when recording the sweep.
             adapter = adapterOf(hb.platform);
             sessionId = hb.session_id || conflict.instance_id;
-            const ts = Date.parse(hb.last_heartbeat);
-            if (Number.isFinite(ts))
-                ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
         }
         catch {
             /* content unreadable — still reclaim the file */
@@ -112,24 +110,14 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
         }
     }
     removePidmapRowsForInstance(coordRoot, conflict.instance_id);
-    try {
-        emit(coordRoot, {
-            event_type: "health.heartbeat_swept",
-            instance_id: conflict.instance_id,
-            session_id: sessionId,
-            adapter,
-            source: "agent-coord",
-            data: {
-                reason: "stale",
-                ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}),
-                reclaimed_by: "identity.assume",
-            },
-            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        });
-    }
-    catch {
-        /* telemetry only */
-    }
+    recordLiveSweepObservationV3({
+        coordRoot,
+        owner: conflict.instance_id,
+        nativeSessionId: sessionId,
+        adapter,
+        observation: "stale_heartbeat",
+        ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
+    });
     return true;
 }
 function resolveTarget(coordRoot, input) {
@@ -197,9 +185,9 @@ function adapterOf(platform) {
 export function assumeIdentity(coordRoot, instanceId, target, opts) {
     const release = acquireLock(coordRoot);
     try {
-        const hb = readHeartbeat(coordRoot, instanceId);
+        const hb = readLiveCoordinationRow(coordRoot, instanceId);
         if (!hb) {
-            throw new IdentityAssumeError("no_heartbeat", `no live heartbeat for instance '${instanceId}'`);
+            throw new IdentityAssumeError("no_live_generation", `no authority-safe live V3 generation for instance '${instanceId}'`);
         }
         if (hb.kind && hb.kind !== "session") {
             throw new IdentityAssumeError("not_session", `identity assumption is limited to main sessions (current kind: ${hb.kind})`);
@@ -222,7 +210,10 @@ export function assumeIdentity(coordRoot, instanceId, target, opts) {
         let conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
         if (conflict && reclaimAbandonedLocalConflict(coordRoot, conflict)) {
             reclaimedInstanceId = conflict.instance_id;
-            conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
+            // The V3 sweep is intentionally provisional, so the generation remains
+            // replay-visible after its disposable cache is removed. Ignore that one
+            // reclaimed holder while still checking for any additional namesake.
+            conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name, Date.now(), new Set([reclaimedInstanceId]));
         }
         if (conflict) {
             const where = conflict.scope === "remote" ? ` on ${conflict.machine}` : "";
@@ -232,8 +223,7 @@ export function assumeIdentity(coordRoot, instanceId, target, opts) {
         const created = !targetIdentity.identity;
         const previousName = hb.name || null;
         const previousAgentId = hb.agent_id || null;
-        const history = recordNameAssumption(coordRoot, instanceId, identity.name, identity.agent_id, "session");
-        const changed = history.changed || previousName !== identity.name || previousAgentId !== identity.agent_id;
+        const changed = previousName !== identity.name || previousAgentId !== identity.agent_id;
         if (!changed) {
             return {
                 changed: false,
@@ -248,25 +238,17 @@ export function assumeIdentity(coordRoot, instanceId, target, opts) {
                 reclaimed_instance_id: reclaimedInstanceId,
             };
         }
-        const emitted = emitAndProject({
-            event_type: "identity.assumed",
-            instance_id: instanceId,
-            session_id: hb.session_id,
+        const emitted = recordLiveIdentityChangeV3({
+            coordRoot,
+            owner: instanceId,
+            nativeSessionId: hb.native_session_id ?? hb.session_id,
             adapter: adapterOf(hb.platform),
-            data: {
-                name: identity.name,
-                agent_id: identity.agent_id,
-                ...(previousName ? { previous_name: previousName } : {}),
-                ...(previousAgentId ? { previous_agent_id: previousAgentId } : {}),
-                ...(reclaimedInstanceId ? { reclaimed_instance_id: reclaimedInstanceId } : {}),
-            },
-        }, { coordRoot });
-        if (!emitted?.projected) {
-            throw new IdentityAssumeError("projection_failed", "the durable name binding was recorded but event projection failed; rerun the command to heal it");
-        }
-        const projected = readHeartbeat(coordRoot, instanceId);
+            name: identity.name,
+            identityId: identity.agent_id,
+        });
+        const projected = readLiveCoordinationRow(coordRoot, instanceId);
         if (projected?.name !== identity.name || projected.agent_id !== identity.agent_id) {
-            throw new IdentityAssumeError("projection_failed", "identity.assumed was emitted but the heartbeat did not converge; rerun the command");
+            throw new IdentityAssumeError("projection_failed", "coord.identity_attested was emitted but the V3 projection did not converge; rerun the command");
         }
         return {
             changed: true,
@@ -277,7 +259,9 @@ export function assumeIdentity(coordRoot, instanceId, target, opts) {
             name: identity.name,
             agent_id: identity.agent_id,
             identity_created: created,
-            event_id: emitted.envelope.event_id,
+            event_id: emitted.state === "recorded" && emitted.result.state === "recorded"
+                ? emitted.result.event.event_id
+                : null,
             reclaimed_instance_id: reclaimedInstanceId,
         };
     }

package/dist/lib/instructions/apply.d.ts

@@ -14,8 +14,9 @@
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
- *   - `.claude/skills/<skill>/SKILL.md` — claude-code only; fully-owned files,
- *     honoring `skills.exclude` in `.harnery/config.jsonc`.
+ *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
+ *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
+ *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
  */
 /** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
 export declare function readSkillsExclude(projectRoot: string): Set<string>;
@@ -30,7 +31,7 @@ export interface ApplyResult {
 }
 /**
  * Inject / refresh the instructions block, the CLAUDE.md import shim (claude-code),
- * and the shipped skills (claude-code). Idempotent: a re-run on current content
+ * and the adapter-native shipped skills. Idempotent: a re-run on current content
  * writes nothing. `dryRun` reports without touching the fs.
  */
 export declare function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyResult;
@@ -51,7 +52,7 @@ export interface CheckResult {
 }
 /**
  * Read-only drift report for `init --check`: the AGENTS.md block and each
- * shipped skill (claude-code). Fresh → exit 0; any stale / missing / hand-edit
+ * shipped skill for the selected adapter. Fresh → exit 0; stale / missing / hand-edit
  * → drift (exit 2); an unreadable file → error (exit 1). Mirrors the wiki-theme
  * `--check-only` contract the first host wires into pre-commit.
  */

package/dist/lib/instructions/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8CH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAiBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA8GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAiFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAiDb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAkBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}