harnery 0.9.0 → 0.11.0

package/dist/lib/claude-desktop.js

@@ -0,0 +1,217 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+const SESSIONS_DIRNAME = "claude-code-sessions";
+function isWsl() {
+    if (process.env.WSL_DISTRO_NAME)
+        return true;
+    try {
+        return readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Candidate desktop-app data directories for this machine, most specific
+ * first. Only directories that exist AND contain a claude-code-sessions/
+ * subdirectory are returned. Precedence: explicit arg, then
+ * HARNERY_CLAUDE_DESKTOP_DIR, then platform defaults (on WSL that means
+ * scanning every /mnt/c/Users/<user>/AppData/Roaming/Claude).
+ */
+export function findDesktopDataDirs(explicit) {
+    const candidates = [];
+    if (explicit)
+        candidates.push(explicit);
+    else if (process.env.HARNERY_CLAUDE_DESKTOP_DIR) {
+        candidates.push(process.env.HARNERY_CLAUDE_DESKTOP_DIR);
+    }
+    else {
+        const home = homedir();
+        if (process.platform === "darwin") {
+            candidates.push(join(home, "Library", "Application Support", "Claude"));
+        }
+        else if (process.platform === "win32") {
+            if (process.env.APPDATA)
+                candidates.push(join(process.env.APPDATA, "Claude"));
+            candidates.push(join(home, "AppData", "Roaming", "Claude"));
+        }
+        else {
+            candidates.push(join(home, ".config", "Claude"));
+            if (isWsl()) {
+                for (const usersRoot of ["/mnt/c/Users"]) {
+                    if (!existsSync(usersRoot))
+                        continue;
+                    for (const user of safeReaddir(usersRoot)) {
+                        candidates.push(join(usersRoot, user, "AppData", "Roaming", "Claude"));
+                    }
+                }
+            }
+        }
+    }
+    const seen = new Set();
+    const out = [];
+    for (const dir of candidates) {
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        if (existsSync(join(dir, SESSIONS_DIRNAME)))
+            out.push(dir);
+    }
+    return out;
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readEntry(file, accountUuid, envId) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const d = raw;
+    const str = (k) => (typeof d[k] === "string" ? d[k] : null);
+    const num = (k) => (typeof d[k] === "number" ? d[k] : null);
+    return {
+        file,
+        accountUuid,
+        envId,
+        sessionId: str("sessionId"),
+        cliSessionId: str("cliSessionId"),
+        cwd: str("cwd"),
+        title: str("title"),
+        model: str("model"),
+        isArchived: d.isArchived === true,
+        createdAt: num("createdAt"),
+        lastActivityAt: num("lastActivityAt"),
+    };
+}
+/** Enumerate every account directory + its session entries under one data dir. */
+export function listAccounts(dataDir) {
+    const root = join(dataDir, SESSIONS_DIRNAME);
+    const accounts = [];
+    for (const accountUuid of safeReaddir(root)) {
+        const accountPath = join(root, accountUuid);
+        if (!isDir(accountPath))
+            continue;
+        const entries = [];
+        for (const envId of safeReaddir(accountPath)) {
+            const envPath = join(accountPath, envId);
+            if (!isDir(envPath))
+                continue;
+            for (const f of safeReaddir(envPath)) {
+                if (!f.endsWith(".json"))
+                    continue;
+                const entry = readEntry(join(envPath, f), accountUuid, envId);
+                if (entry)
+                    entries.push(entry);
+            }
+        }
+        entries.sort((a, b) => (b.lastActivityAt ?? 0) - (a.lastActivityAt ?? 0));
+        accounts.push({ accountUuid, path: accountPath, entries });
+    }
+    accounts.sort((a, b) => (b.entries[0]?.lastActivityAt ?? 0) - (a.entries[0]?.lastActivityAt ?? 0) ||
+        a.accountUuid.localeCompare(b.accountUuid));
+    return accounts;
+}
+/**
+ * The account the runtime environment's Claude Code CLI is signed into,
+ * read from ~/.claude.json (best-effort; null when unavailable). Lets the
+ * command label an otherwise-opaque account UUID with an email address.
+ */
+export function readCliAccount() {
+    try {
+        const raw = JSON.parse(readFileSync(join(homedir(), ".claude.json"), "utf8"));
+        const oa = raw.oauthAccount;
+        if (!oa || typeof oa.accountUuid !== "string")
+            return null;
+        return {
+            accountUuid: oa.accountUuid,
+            email: typeof oa.emailAddress === "string" ? oa.emailAddress : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function entryMatchesSelector(entry, selector) {
+    if (entry.cliSessionId === selector || entry.sessionId === selector)
+        return true;
+    return entry.title !== null && entry.title.toLowerCase().includes(selector.toLowerCase());
+}
+/**
+ * Plan the copies that would make each target account list the selected
+ * sessions. Union semantics: every entry a source account has and a target
+ * account lacks (keyed by cliSessionId, falling back to filename) becomes a
+ * copy action. Idempotent by construction — planning again after applying
+ * yields zero actions.
+ */
+export function planMirror(accounts, opts = {}) {
+    const matchPrefix = (uuid, prefixes) => !prefixes || prefixes.length === 0 || prefixes.some((p) => uuid.startsWith(p));
+    const targets = accounts.filter((a) => matchPrefix(a.accountUuid, opts.to));
+    const sources = accounts.filter((a) => matchPrefix(a.accountUuid, opts.from));
+    const actions = [];
+    let skippedExisting = 0;
+    let skippedArchived = 0;
+    for (const target of targets) {
+        const have = new Set();
+        for (const e of target.entries) {
+            if (e.cliSessionId)
+                have.add(e.cliSessionId);
+            have.add(basename(e.file));
+        }
+        for (const source of sources) {
+            if (source.accountUuid === target.accountUuid)
+                continue;
+            for (const entry of source.entries) {
+                if (opts.sessions?.length && !opts.sessions.some((s) => entryMatchesSelector(entry, s))) {
+                    continue;
+                }
+                const key = entry.cliSessionId ?? basename(entry.file);
+                if (have.has(key) || have.has(basename(entry.file))) {
+                    skippedExisting++;
+                    continue;
+                }
+                if (entry.isArchived && !opts.includeArchived) {
+                    skippedArchived++;
+                    continue;
+                }
+                have.add(key);
+                actions.push({
+                    from: entry.file,
+                    to: join(target.path, entry.envId, basename(entry.file)),
+                    entry,
+                    targetAccountUuid: target.accountUuid,
+                });
+            }
+        }
+    }
+    return { actions, skippedExisting, skippedArchived };
+}
+/** Apply a plan: verbatim file copies (never rewrites entry contents). */
+export function applyMirror(plan) {
+    let copied = 0;
+    for (const action of plan.actions) {
+        mkdirSync(dirname(action.to), { recursive: true });
+        copyFileSync(action.from, action.to);
+        copied++;
+    }
+    return { copied };
+}

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAcA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAKP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuHD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AAsQD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBlE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAcA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAKP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AAsQD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBlE"}

package/dist/lib/docs-lint.js

@@ -27,8 +27,10 @@ import { basename, join } from "node:path";
 /** Files allowed at a submodule root level. Includes:
  *  - In-repo conventions: README.md, CLAUDE.md, LLM-BRIEFING.md, AGENTS.md
  *  - GitHub OSS conventions: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
- *    SECURITY.md, SUPPORT.md, AUTHORS.md, MAINTAINERS.md, PULL_REQUEST_TEMPLATE.md
- *    (these are recognized by the GitHub UI, and renaming them breaks the integration)
+ *    LICENSE.md, SECURITY.md, SUPPORT.md, AUTHORS.md, MAINTAINERS.md,
+ *    PULL_REQUEST_TEMPLATE.md (these are recognized by the GitHub UI, and
+ *    renaming them breaks the integration; LICENSE.md also appears inside
+ *    vendored upstream trees, where renaming would damage provenance)
  */
 const ROOT_FILE_ALLOWLIST = new Set([
     "README.md",
@@ -39,6 +41,7 @@ const ROOT_FILE_ALLOWLIST = new Set([
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",
+    "LICENSE.md",
     "SECURITY.md",
     "SUPPORT.md",
     "AUTHORS.md",

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

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+export type IdentityAssumeErrorCode = "identity_busy" | "identity_in_use" | "identity_not_found" | "invalid_identity" | "no_heartbeat" | "not_session" | "projection_failed";
+export declare class IdentityAssumeError extends Error {
+    readonly code: IdentityAssumeErrorCode;
+    constructor(code: IdentityAssumeErrorCode, message: string);
+}
+export interface IdentityConflict {
+    instance_id: string;
+    name: string;
+    scope: "local" | "remote";
+    machine?: string;
+}
+export interface IdentityAssumeResult {
+    changed: boolean;
+    instance_id: string;
+    session_id: string;
+    previous_name: string | null;
+    previous_agent_id: string | null;
+    name: string;
+    agent_id: string;
+    identity_created: boolean;
+    event_id: string | null;
+    /** Prior local holder swept because it had no live process. */
+    reclaimed_instance_id: string | null;
+}
+/** 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;
+/**
+ * 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 declare function reclaimAbandonedLocalConflict(coordRoot: string, conflict: IdentityConflict): boolean;
+/** Assume `target` for one live main session. Safe to retry. */
+export declare function assumeIdentity(coordRoot: string, instanceId: string, target: string): IdentityAssumeResult;
+//# sourceMappingURL=assume.d.ts.map

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

@@ -0,0 +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,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,GACb,oBAAoB,CAyGtB"}

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"}