harnery 0.9.0 → 0.10.0

package/dist/lib/identities/assume.js

@@ -0,0 +1,274 @@
+/**
+ * Bind a live session to a durable agent persona.
+ *
+ * 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.
+ *
+ * Local collision policy: a fresh heartbeat alone is not enough to block.
+ * If the namesake has no live pid-map process (crashed session, healed
+ * zombie, or abandoned harness), reclaim that heartbeat and continue.
+ * Refuse only when another process is still alive, or when cached remote
+ * presence reports the name.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, 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 } 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";
+import { bareName, ensureIdentity, lookupById, lookupByName } from "./index.js";
+const ASSUME_LOCK = "identity-assume.lock";
+const ASSUME_LOCK_STALE_MS = 30_000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export class IdentityAssumeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "IdentityAssumeError";
+    }
+}
+function heartbeatIsFresh(hb, cutoffMs) {
+    const ts = Date.parse(hb.last_heartbeat);
+    return Number.isFinite(ts) && ts >= 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()) {
+    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 remote of readRemoteMachines(coordRoot)) {
+        for (const agent of remote.agents) {
+            if (agent.instance_id === instanceId)
+                continue;
+            if ((agent.name ?? "").toLowerCase() === wanted) {
+                return {
+                    instance_id: agent.instance_id,
+                    name: agent.name ?? name,
+                    scope: "remote",
+                    machine: remote.machine,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Drop a local namesake whose harness process is gone. Fresh heartbeats can
+ * linger after a crash (or after heartbeat heal without a live pid-map), and
+ * `identity assume` is the supported takeover path — operators should not
+ * need a separate kill/sweep step.
+ */
+export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
+    if (conflict.scope !== "local")
+        return false;
+    if (instanceHasLivePid(coordRoot, conflict.instance_id))
+        return false;
+    const hbPath = join(coordRoot, ".harnery", "active", `${conflict.instance_id}.json`);
+    let harness = "claude-code";
+    let sessionId = conflict.instance_id;
+    let ageSecs;
+    if (existsSync(hbPath)) {
+        try {
+            const hb = JSON.parse(readFileSync(hbPath, "utf8"));
+            harness = harnessOf(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 */
+        }
+        try {
+            unlinkSync(hbPath);
+        }
+        catch {
+            return false;
+        }
+    }
+    removePidmapRowsForInstance(coordRoot, conflict.instance_id);
+    try {
+        emit(coordRoot, {
+            event_type: "health.heartbeat_swept",
+            instance_id: conflict.instance_id,
+            session_id: sessionId,
+            harness,
+            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 */
+    }
+    return true;
+}
+function resolveTarget(coordRoot, input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new IdentityAssumeError("invalid_identity", "identity name cannot be empty");
+    }
+    if (UUID_RE.test(trimmed)) {
+        const identity = lookupById(trimmed, coordRoot);
+        if (!identity) {
+            throw new IdentityAssumeError("identity_not_found", `no durable identity matching '${trimmed}'`);
+        }
+        return { identity, name: identity.name };
+    }
+    const name = bareName(trimmed);
+    if (!name) {
+        throw new IdentityAssumeError("invalid_identity", "identity name cannot be empty");
+    }
+    const existing = lookupByName(name, coordRoot);
+    return { identity: existing, name: existing?.name ?? name };
+}
+function acquireLock(coordRoot) {
+    const dir = join(coordRoot, ".harnery");
+    const path = join(dir, ASSUME_LOCK);
+    mkdirSync(dir, { recursive: true });
+    const token = `${process.pid}:${randomUUID()}`;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(path, token, { encoding: "utf8", flag: "wx" });
+            return () => {
+                try {
+                    if (readFileSync(path, "utf8") === token)
+                        unlinkSync(path);
+                }
+                catch {
+                    // The critical section completed; a missing lock needs no recovery.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - statSync(path).mtimeMs > ASSUME_LOCK_STALE_MS) {
+                    unlinkSync(path);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            break;
+        }
+    }
+    throw new IdentityAssumeError("identity_busy", "another identity assumption is in progress; retry in a moment");
+}
+function harnessOf(platform) {
+    if (platform === "cursor")
+        return "cursor";
+    if (platform === "codex")
+        return "codex";
+    return "claude-code";
+}
+/** Assume `target` for one live main session. Safe to retry. */
+export function assumeIdentity(coordRoot, instanceId, target) {
+    const release = acquireLock(coordRoot);
+    try {
+        const hb = readHeartbeat(coordRoot, instanceId);
+        if (!hb) {
+            throw new IdentityAssumeError("no_heartbeat", `no live heartbeat 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})`);
+        }
+        const targetIdentity = resolveTarget(coordRoot, target);
+        let reclaimedInstanceId = null;
+        let conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
+        if (conflict && reclaimAbandonedLocalConflict(coordRoot, conflict)) {
+            reclaimedInstanceId = conflict.instance_id;
+            conflict = findIdentityConflict(coordRoot, instanceId, targetIdentity.name);
+        }
+        if (conflict) {
+            const where = conflict.scope === "remote" ? ` on ${conflict.machine}` : "";
+            throw new IdentityAssumeError("identity_in_use", `agent-${targetIdentity.name} is already live${where} (${conflict.instance_id}); end or stale-sweep that session before assuming the identity`);
+        }
+        const identity = targetIdentity.identity ?? ensureIdentity(targetIdentity.name, coordRoot);
+        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;
+        if (!changed) {
+            return {
+                changed: false,
+                instance_id: instanceId,
+                session_id: hb.session_id,
+                previous_name: previousName,
+                previous_agent_id: previousAgentId,
+                name: identity.name,
+                agent_id: identity.agent_id,
+                identity_created: false,
+                event_id: null,
+                reclaimed_instance_id: reclaimedInstanceId,
+            };
+        }
+        const emitted = emitAndProject({
+            event_type: "identity.assumed",
+            instance_id: instanceId,
+            session_id: hb.session_id,
+            harness: harnessOf(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);
+        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");
+        }
+        return {
+            changed: true,
+            instance_id: instanceId,
+            session_id: hb.session_id,
+            previous_name: previousName,
+            previous_agent_id: previousAgentId,
+            name: identity.name,
+            agent_id: identity.agent_id,
+            identity_created: created,
+            event_id: emitted.envelope.event_id,
+            reclaimed_instance_id: reclaimedInstanceId,
+        };
+    }
+    finally {
+        release();
+    }
+}

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

@@ -39,12 +39,12 @@ 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;
+export declare function lookupById(agentId: string, coordRoot?: 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;
+export declare function lookupByName(name: string, coordRoot?: string): AgentIdentity | null;
 /** All known identities, sorted by created_at ascending. */
-export declare function listIdentities(): AgentIdentity[];
+export declare function listIdentities(coordRoot?: string): AgentIdentity[];
 /**
  * Find an identity by name, or mint one. Returns the resolved identity.
  * Idempotent: calling twice with the same name returns the same record.
@@ -55,15 +55,15 @@ export declare function listIdentities(): AgentIdentity[];
  * 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;
+export declare function ensureIdentity(name: string, coordRoot?: string): AgentIdentity;
 /** Persist an identity (tmp + rename). Creates the dir if missing. */
-export declare function writeIdentity(id: AgentIdentity): void;
+export declare function writeIdentity(id: AgentIdentity, coordRoot?: string): 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;
+export declare function renameIdentity(agentId: string, newName: string, coordRoot?: string): AgentIdentity;
 /**
  * Resolve a string to an agent_id. Accepts:
  *   - A UUID (already an id), verified to exist in registry
@@ -73,5 +73,5 @@ export declare function renameIdentity(agentId: string, newName: string): AgentI
  * 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;
+export declare function resolveAgentId(input: string, coordRoot?: string): string | null;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMpF;AAED;kDACkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAcnF;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAWlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAY9E;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAMzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,aAAa,CAcf;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU/E"}

package/dist/lib/identities/index.js

@@ -24,22 +24,22 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFile
 import { resolve } from "node:path";
 import { monorepoRoot } from "../../core/agents/index.js";
 export const IDENTITY_SCHEMA_VERSION = 1;
-function identitiesDir() {
-    const root = monorepoRoot();
+function identitiesDir(coordRoot) {
+    const root = coordRoot ?? monorepoRoot();
     if (!root)
         return null;
     return resolve(root, ".harnery", "identities");
 }
-function ensureDir() {
-    const dir = identitiesDir();
+function ensureDir(coordRoot) {
+    const dir = identitiesDir(coordRoot);
     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 identityPath(agentId, coordRoot) {
+    return resolve(ensureDir(coordRoot), `${agentId}.json`);
 }
 function nowIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -66,8 +66,8 @@ 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();
+export function lookupById(agentId, coordRoot) {
+    const dir = identitiesDir(coordRoot);
     if (!dir)
         return null;
     const fp = resolve(dir, `${agentId}.json`);
@@ -77,8 +77,8 @@ export function lookupById(agentId) {
 }
 /** 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();
+export function lookupByName(name, coordRoot) {
+    const dir = identitiesDir(coordRoot);
     if (!dir || !existsSync(dir))
         return null;
     const wanted = bareName(name).toLowerCase();
@@ -98,8 +98,8 @@ export function lookupByName(name) {
     return null;
 }
 /** All known identities, sorted by created_at ascending. */
-export function listIdentities() {
-    const dir = identitiesDir();
+export function listIdentities(coordRoot) {
+    const dir = identitiesDir(coordRoot);
     if (!dir || !existsSync(dir))
         return [];
     const out = [];
@@ -123,8 +123,8 @@ export function listIdentities() {
  * 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);
+export function ensureIdentity(name, coordRoot) {
+    const existing = lookupByName(name, coordRoot);
     if (existing)
         return existing;
     const id = {
@@ -134,13 +134,13 @@ export function ensureIdentity(name) {
         aliases: [],
         created_at: nowIso(),
     };
-    writeIdentity(id);
+    writeIdentity(id, coordRoot);
     return id;
 }
 /** Persist an identity (tmp + rename). Creates the dir if missing. */
-export function writeIdentity(id) {
-    ensureDir();
-    const fp = identityPath(id.agent_id);
+export function writeIdentity(id, coordRoot) {
+    ensureDir(coordRoot);
+    const fp = identityPath(id.agent_id, coordRoot);
     const tmp = `${fp}.tmp.${process.pid}`;
     writeFileSync(tmp, `${JSON.stringify(id, null, 2)}\n`, "utf8");
     renameSync(tmp, fp);
@@ -150,8 +150,8 @@ export function writeIdentity(id) {
  * 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);
+export function renameIdentity(agentId, newName, coordRoot) {
+    const existing = lookupById(agentId, coordRoot);
     if (!existing) {
         throw new Error(`renameIdentity: no identity matching '${agentId}'`);
     }
@@ -163,7 +163,7 @@ export function renameIdentity(agentId, newName) {
         name: bare,
         aliases: [...existing.aliases, { name: existing.name, retired_at: nowIso() }],
     };
-    writeIdentity(next);
+    writeIdentity(next, coordRoot);
     return next;
 }
 /**
@@ -175,16 +175,16 @@ export function renameIdentity(agentId, newName) {
  * 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) {
+export function resolveAgentId(input, coordRoot) {
     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);
+        const byId = lookupById(trimmed, coordRoot);
         if (byId)
             return byId.agent_id;
     }
-    const byName = lookupByName(trimmed);
+    const byName = lookupByName(trimmed, coordRoot);
     return byName ? byName.agent_id : null;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAA6C,GACpD,MAAM,CA+CR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsKD,eAAO,MAAM,MAAM,EAAE,aAAa,EA4BjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAA6C,GACpD,MAAM,CA4DR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsKD,eAAO,MAAM,MAAM,EAAE,aAAa,EA4BjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -10,6 +10,7 @@
  * files), so they compile into `dist/` and resolve identically under Bun and
  * Node — no `files`-field copy or package-path guesswork.
  */
+import { SCRATCH_CATEGORIES } from "../../core/scratch/index.js";
 import { buildOwnedSkill } from "./splice.js";
 /** Managed-region name for the AGENTS.md orientation block. */
 export const INSTRUCTIONS_REGION = "instructions";
@@ -39,6 +40,12 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     const councilPointer = skills.council
         ? "The `harn-council` skill has the steward and member flow."
         : `See \`${b} council --help\` for the steward and member flow.`;
+    // Render the scratch categories from the canonical enum so this prose can
+    // never drift from what `scratch add` actually accepts (the "note, plan…" list
+    // silently lagged the tool by two categories before this).
+    const scratchCats = SCRATCH_CATEGORIES.length > 1
+        ? `${SCRATCH_CATEGORIES.slice(0, -1).join(", ")}, or ${SCRATCH_CATEGORIES.at(-1)}`
+        : SCRATCH_CATEGORIES[0];
     return `## harnery coordination
 
 This project runs [harnery](https://harnery.com) for multi-agent coordination.
@@ -52,13 +59,19 @@ active peers and the files they've claimed; \`${b} agents set-task "<focus>"\`
 declares your current focus so peers can see it. Check for peers before editing
 widely-shared files.
 
+**Durable role handoff.** When you are replacing a prior session in the same
+named role, run \`${b} agents identity assume <name>\` before declaring your task.
+It reclaims an abandoned namesake (no live process) and refuses only when another
+live process still holds the name; never hand-edit Harnery's history, heartbeat,
+or derived identity cache.
+
 **Declare intent on shell commands.** Every command you run is captured to the
 coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or set
 the tool's description) so the recorded event carries a reason instead of
 \`(no intent)\`.
 
-**Scratch journal.** \`${b} scratch add <category> "<text>"\` (category = note, plan,
-decision, blocker, or handoff) leaves breadcrumbs that survive context compaction;
+**Scratch journal.** \`${b} scratch add <category> "<text>"\` (category = ${scratchCats})
+leaves breadcrumbs that survive context compaction;
 \`${b} scratch read\` reads yours, \`${b} scratch read --name <peer>\` reads a peer's.
 Use it for anything future-you or a peer will need to pick up your thread.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -52,6 +52,16 @@
       "types": "./dist/core/hooks/index.d.ts",
       "import": "./dist/core/hooks/index.js"
     },
+    "./core/harnesses": {
+      "bun": "./src/core/harnesses/index.ts",
+      "types": "./dist/core/harnesses/index.d.ts",
+      "import": "./dist/core/harnesses/index.js"
+    },
+    "./core/context": {
+      "bun": "./src/core/context/index.ts",
+      "types": "./dist/core/context/index.d.ts",
+      "import": "./dist/core/context/index.js"
+    },
     "./lib/agent-browser": {
       "bun": "./src/lib/agent-browser/index.ts",
       "types": "./dist/lib/agent-browser/index.d.ts",
@@ -129,6 +139,7 @@
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x @biomejs/biome check src",
     "check:portability": "bun run scripts/check-portability.ts",
+    "check:public-surface": "bun run scripts/check-public-surface.ts",
     "check:layering": "bun run scripts/check-layering.ts",
     "lint:fix": "bun x @biomejs/biome check --write src",
     "format": "bun x @biomejs/biome format --write src",