harnery 0.0.1 → 0.2.1

package/dist/core/agents/state/heartbeat-writer.js

@@ -0,0 +1,271 @@
+/**
+ * TS implementation of the heartbeat-mutating actions. Replaces the previous
+ * flock-serialized bash writes with atomic temp+rename in Bun. Phase 6 of the
+ * agent-hooks/agent-coord refactor.
+ *
+ * Atomicity guarantee: every write goes via a `<path>.tmp.<pid>` sibling +
+ * `renameSync`. POSIX rename is atomic within a filesystem, so concurrent
+ * readers either see the pre-write file or the post-write file but never a
+ * half-written intermediate. Concurrent writers serialize via the rename
+ * (last write wins).
+ *
+ * Owner identity invariant: every action operates on `.harnery/active/<instance_id>.json`
+ * (the file IS the heartbeat). No mutations happen elsewhere.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { emit } from "../events/emit.js";
+/** Inline harness normalizer (mirrors canonical-emit.normalizeHarness), kept
+ * local so the writer's only cross-module dep is the in-process emit(). */
+function harnessOf(platform) {
+    if (platform === "cursor")
+        return "cursor";
+    if (platform === "codex")
+        return "codex";
+    return "claude-code";
+}
+/** Inverse of harnessOf: maps the canonical harness ("claude-code"/"cursor"/
+ * "codex") to the legacy underscore platform label stored on the heartbeat.
+ * Mirrors heartbeat-projector.harnessToPlatform so a healed heartbeat carries
+ * the same platform value projection would have written. */
+function harnessToPlatform(harness) {
+    if (harness === "cursor")
+        return "cursor";
+    if (harness === "codex")
+        return "codex";
+    return "claude_code";
+}
+/**
+ * Emit a canonical `health.*` event for an actual self-heal write. This is the
+ * single source of truth for heal telemetry across BOTH the live auto-heal
+ * (the pre-tool-use hook → agent-coord heal-heartbeat) and the manual `harn agents
+ * heal` path. Write-only by construction (callers only invoke it after a real
+ * write), so an already-correct heal records nothing.
+ * Best-effort: never throws into the heal path.
+ */
+function emitHealthHeal(coordRoot, type, instanceId, hb, data) {
+    try {
+        emit(coordRoot, {
+            event_type: type,
+            instance_id: instanceId,
+            session_id: hb?.session_id ?? instanceId,
+            harness: harnessOf(hb?.platform),
+            source: "agent-coord",
+            data,
+        });
+    }
+    catch {
+        /* telemetry only, never break a heal */
+    }
+}
+function heartbeatPath(coordRoot, instanceId) {
+    return join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+}
+function nowIsoSeconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+export function readHeartbeat(coordRoot, instanceId) {
+    const path = heartbeatPath(coordRoot, instanceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function mutate(coordRoot, instanceId, fn) {
+    const hb = readHeartbeat(coordRoot, instanceId);
+    if (!hb)
+        return null;
+    const next = fn(hb);
+    next.last_heartbeat = nowIsoSeconds();
+    atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(next, null, 2));
+    return next;
+}
+export function setTask(coordRoot, instanceId, task) {
+    return mutate(coordRoot, instanceId, (hb) => {
+        const cleared = !task || task.length === 0;
+        return {
+            ...hb,
+            task: cleared ? undefined : task,
+            task_updated_at: nowIsoSeconds(),
+        };
+    });
+}
+export function stampStatusCheck(coordRoot, instanceId) {
+    return mutate(coordRoot, instanceId, (hb) => ({
+        ...hb,
+        last_status_at: nowIsoSeconds(),
+    }));
+}
+export function setTurnSummary(coordRoot, instanceId, summary) {
+    return mutate(coordRoot, instanceId, (hb) => ({
+        ...hb,
+        turn_summary: summary,
+        turn_summary_updated_at: nowIsoSeconds(),
+    }));
+}
+export function releaseClaim(coordRoot, instanceId, path) {
+    return mutate(coordRoot, instanceId, (hb) => ({
+        ...hb,
+        files_touched: (hb.files_touched ?? []).filter((p) => p !== path),
+    }));
+}
+/**
+ * Session-group-wide unclaim. Walks every heartbeat sharing `groupId`
+ * (parent's session_id == group_id;
+ * subagents inherit it) and removes the path from each one's files_touched.
+ * Idempotent: heartbeats that don't hold the path are untouched.
+ *
+ * This is the Option B fix for post-commit's pid-map attribution hole: a
+ * subagent-held claim that doesn't live on the parent's heartbeat still gets
+ * pruned because the walk covers the whole group.
+ */
+export function groupUnclaim(coordRoot, groupId, path) {
+    if (!groupId || !path)
+        return;
+    const activeDir = join(coordRoot, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return;
+    for (const f of readdirSync(activeDir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const hbPath = join(activeDir, f);
+        let body;
+        try {
+            body = JSON.parse(readFileSync(hbPath, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const peerSession = body.session_id ?? body.instance_id;
+        if (peerSession !== groupId)
+            continue;
+        const files = body.files_touched ?? [];
+        const next = files.filter((p) => p !== path);
+        if (next.length === files.length)
+            continue;
+        body.files_touched = next;
+        try {
+            const tmp = `${hbPath}.tmp.${process.pid}`;
+            writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
+            renameSync(tmp, hbPath);
+        }
+        catch {
+            /* silent */
+        }
+    }
+}
+export function killHeartbeat(coordRoot, instanceId) {
+    const path = heartbeatPath(coordRoot, instanceId);
+    if (!existsSync(path))
+        return false;
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function healPidmap(coordRoot, instanceId, pid) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    mkdirSync(dir, { recursive: true });
+    const hb = readHeartbeat(coordRoot, instanceId);
+    const platform = hb?.platform ?? "claude_code";
+    const pmPath = join(dir, String(pid));
+    // Drift guard: only write + emit telemetry when the entry is missing or
+    // points at a different owner. Without this, a per-tool-call heal would
+    // flood health.pidmap_heal on every call.
+    let existingOwner = "";
+    try {
+        if (existsSync(pmPath))
+            existingOwner = readFileSync(pmPath, "utf8").split("\t")[0] ?? "";
+    }
+    catch {
+        /* treat as missing */
+    }
+    if (existingOwner === instanceId)
+        return;
+    atomicWrite(pmPath, `${instanceId}\t${platform}`);
+    emitHealthHeal(coordRoot, "health.pidmap_heal", instanceId, hb, {
+        reason: existingOwner ? "stale" : "missing",
+        pid,
+        kind: "pidmap",
+        ...(existingOwner ? { prior: existingOwner.slice(0, 8) } : {}),
+    });
+}
+export function healHeartbeat(coordRoot, instanceId, sessionId, model, harness) {
+    const path = heartbeatPath(coordRoot, instanceId);
+    if (existsSync(path)) {
+        // Already alive, return it.
+        return readHeartbeat(coordRoot, instanceId);
+    }
+    const now = nowIsoSeconds();
+    // Recover name + kind from .name-history if present (idempotent across
+    // sweeps: same instance_id always gets the same name).
+    let name = "";
+    let kind = "session";
+    let agentId = "";
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { resolveName } = require("./names.ts");
+        const resolved = resolveName(coordRoot, instanceId, sessionId);
+        if (resolved) {
+            name = resolved.name;
+            kind = resolved.kind;
+            // subagent kind: agent_id == instance_id. Else (session/transient): no id stamp.
+            if (resolved.kind === "subagent")
+                agentId = instanceId;
+        }
+    }
+    catch {
+        /* names module unavailable, fall back to empty */
+    }
+    const hb = {
+        schema_version: 1,
+        instance_id: instanceId,
+        session_id: sessionId ?? instanceId,
+        name,
+        kind,
+        agent_id: agentId,
+        model: model ?? "",
+        started_at: now,
+        last_heartbeat: now,
+        files_touched: [],
+        // Default to claude_code only when the caller can't tell us the harness
+        // (e.g. manual `harn agents heal`). The live tool.pre_use heal threads the
+        // detected harness so a pruned Cursor/Codex heartbeat is recreated with
+        // the correct platform instead of being mislabeled claude_code.
+        platform: harnessToPlatform(harness),
+    };
+    atomicWrite(path, JSON.stringify(hb, null, 2));
+    // Write-only telemetry: only the actual-recreate branch reaches here (the
+    // already-alive case returned above), so this records exactly the heals that
+    // happened.
+    emitHealthHeal(coordRoot, "health.heartbeat_heal", instanceId, hb, {
+        reason: "missing",
+        kind: "heartbeat",
+    });
+    return hb;
+}
+/**
+ * Stamp the heartbeat with the most-recent tool name + target. Written from
+ * the post-tool-use hook.
+ */
+export function stampToolActivity(coordRoot, instanceId, toolName, target) {
+    return mutate(coordRoot, instanceId, (hb) => ({
+        ...hb,
+        last_tool: toolName,
+        last_tool_target: target,
+        last_tool_at: nowIsoSeconds(),
+    }));
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Hurricane-style name pool for the agent coordination layer. The name-pool
+ * assignment + resolution helpers.
+ *
+ * Layout invariant: 260 entries (10 per starting letter A..Z). Counter N
+ * picks COORD_NAMES[N % 260]; wraps to A at N=260.
+ *
+ * Durable persistence: `.harnery/.name-history` (JSONL, one row per assignment)
+ * + `.harnery/.name-counter` (current counter, atomic temp+rename).
+ *
+ * Recreation rule (mirrors v1):
+ *   1. Own instance_id in name-history → (original name, original kind)
+ *   2. session_id in name-history (owner != session) → (parent's name, "transient")
+ *   3. Else: new assignment, consume a counter slot.
+ */
+/** All 260 names. */
+export declare const COORD_NAMES: readonly ["Anna", "Bob", "Carlos", "Dalia", "Erika", "Fred", "Gemma", "Hank", "Imelda", "Jerry", "Kirk", "Lee", "Milton", "Nate", "Oscar", "Patty", "Quentin", "Rafael", "Sara", "Tony", "Ulrik", "Valerie", "Whitney", "Xander", "Yara", "Zara", "Adelaide", "Bertha", "Carmen", "Dorian", "Edna", "Francine", "Greta", "Helene", "Ines", "Joyce", "Karen", "Lorenzo", "Mindy", "Nadine", "Odette", "Paulette", "Quinn", "Rebekah", "Sean", "Tammy", "Ursula", "Vinson", "Wallace", "Xanthe", "Yusuf", "Zoe", "Alex", "Beatrice", "Cyrus", "Delia", "Ernesto", "Florence", "Gordon", "Hester", "Isaias", "Jenna", "Klaus", "Larry", "Maxine", "Nicholas", "Otto", "Peter", "Quill", "Renee", "Stella", "Theresa", "Umberto", "Virgil", "Willow", "Xavier", "Yolanda", "Zane", "Anita", "Bruno", "Cora", "Damon", "Edith", "Felix", "Gloria", "Holly", "Iris", "Jasper", "Kaia", "Linda", "Marco", "Nora", "Olive", "Petra", "Querida", "Roman", "Sebastian", "Tobias", "Una", "Vera", "Walter", "Xena", "Yusra", "Zelda", "Aaron", "Bonnie", "Caleb", "Daphne", "Elias", "Fiona", "Galileo", "Hugo", "Ian", "Jude", "Knox", "Leo", "Maya", "Nash", "Owen", "Paxton", "Quetzal", "Rosa", "Sage", "Talia", "Uri", "Vincent", "Wesley", "Ximena", "Yvette", "Zephyr", "Astrid", "Beau", "Celeste", "Dexter", "Ezra", "Fitz", "Genevieve", "Hadley", "Imogen", "Joaquin", "Kira", "Lila", "Mason", "Nila", "Olga", "Pearl", "Quincy", "Royce", "Sterling", "Trent", "Ulysses", "Violet", "Wynne", "Xerxes", "Yael", "Zinnia", "Amelia", "Bianca", "Cody", "Dahlia", "Esme", "Fern", "Greer", "Harriet", "Ivan", "Juno", "Kendrick", "Luther", "Margot", "Nigel", "Orion", "Phillip", "Quenby", "Reagan", "Sienna", "Tessa", "Uma", "Vesper", "Watson", "Xiomara", "Yuri", "Zoltan", "Andre", "Boris", "Cassidy", "Davis", "Evander", "Forrest", "Gibson", "Henry", "Irene", "Justus", "Kasper", "Lainey", "Miles", "Naomi", "Ophelia", "Phoebe", "Quark", "Rylie", "Saul", "Truman", "Ulrich", "Voss", "Winifred", "Xuxa", "Yvonne", "Zia", "Aria", "Brenda", "Crispin", "Dolores", "Estelle", "Felicity", "Goldie", "Hazel", "Ira", "Jovi", "Kestrel", "Lyric", "Mavis", "Nico", "Otis", "Percy", "Querubin", "Rhett", "Scout", "Tatum", "Unity", "Vivian", "Wyatt", "Xan", "Yancy", "Zev", "Atticus", "Barnaby", "Calliope", "Drake", "Eustace", "Foster", "Granger", "Hollis", "Indira", "Jericho", "Kaleb", "Logan", "Magnus", "Noor", "Oakley", "Posy", "Quito", "Rosalind", "Sloane", "Theron", "Upton", "Vance", "Wendell", "Xola", "Yann", "Zora"];
+export type NameKind = "session" | "subagent" | "transient";
+/**
+ * Resolve (name, kind) for an existing owner without consuming a counter
+ * slot. Returns null if no history match found.
+ *
+ *   1. Own instance_id → original (name, kind)
+ *   2. session_id (owner != session) → (parent's name, "transient")
+ */
+export declare function resolveName(coordRoot: string, instanceId: string, sessionId?: string): {
+    name: string;
+    kind: NameKind;
+} | null;
+/**
+ * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
+ * the owner is new. Idempotent: returns existing name on resume.
+ */
+export declare function assignName(coordRoot: string, instanceId: string, kind: NameKind): string;
+//# sourceMappingURL=names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,qBAAqB;AACrB,eAAO,MAAM,WAAW,y5EA+Qd,CAAC;AAMX,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AA6C5D;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAkBzC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqBxF"}

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

@@ -0,0 +1,376 @@
+/**
+ * Hurricane-style name pool for the agent coordination layer. The name-pool
+ * assignment + resolution helpers.
+ *
+ * Layout invariant: 260 entries (10 per starting letter A..Z). Counter N
+ * picks COORD_NAMES[N % 260]; wraps to A at N=260.
+ *
+ * Durable persistence: `.harnery/.name-history` (JSONL, one row per assignment)
+ * + `.harnery/.name-counter` (current counter, atomic temp+rename).
+ *
+ * Recreation rule (mirrors v1):
+ *   1. Own instance_id in name-history → (original name, original kind)
+ *   2. session_id in name-history (owner != session) → (parent's name, "transient")
+ *   3. Else: new assignment, consume a counter slot.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** All 260 names. */
+export const COORD_NAMES = [
+    // Pass 1
+    "Anna",
+    "Bob",
+    "Carlos",
+    "Dalia",
+    "Erika",
+    "Fred",
+    "Gemma",
+    "Hank",
+    "Imelda",
+    "Jerry",
+    "Kirk",
+    "Lee",
+    "Milton",
+    "Nate",
+    "Oscar",
+    "Patty",
+    "Quentin",
+    "Rafael",
+    "Sara",
+    "Tony",
+    "Ulrik",
+    "Valerie",
+    "Whitney",
+    "Xander",
+    "Yara",
+    "Zara",
+    // Pass 2
+    "Adelaide",
+    "Bertha",
+    "Carmen",
+    "Dorian",
+    "Edna",
+    "Francine",
+    "Greta",
+    "Helene",
+    "Ines",
+    "Joyce",
+    "Karen",
+    "Lorenzo",
+    "Mindy",
+    "Nadine",
+    "Odette",
+    "Paulette",
+    "Quinn",
+    "Rebekah",
+    "Sean",
+    "Tammy",
+    "Ursula",
+    "Vinson",
+    "Wallace",
+    "Xanthe",
+    "Yusuf",
+    "Zoe",
+    // Pass 3
+    "Alex",
+    "Beatrice",
+    "Cyrus",
+    "Delia",
+    "Ernesto",
+    "Florence",
+    "Gordon",
+    "Hester",
+    "Isaias",
+    "Jenna",
+    "Klaus",
+    "Larry",
+    "Maxine",
+    "Nicholas",
+    "Otto",
+    "Peter",
+    "Quill",
+    "Renee",
+    "Stella",
+    "Theresa",
+    "Umberto",
+    "Virgil",
+    "Willow",
+    "Xavier",
+    "Yolanda",
+    "Zane",
+    // Pass 4
+    "Anita",
+    "Bruno",
+    "Cora",
+    "Damon",
+    "Edith",
+    "Felix",
+    "Gloria",
+    "Holly",
+    "Iris",
+    "Jasper",
+    "Kaia",
+    "Linda",
+    "Marco",
+    "Nora",
+    "Olive",
+    "Petra",
+    "Querida",
+    "Roman",
+    "Sebastian",
+    "Tobias",
+    "Una",
+    "Vera",
+    "Walter",
+    "Xena",
+    "Yusra",
+    "Zelda",
+    // Pass 5
+    "Aaron",
+    "Bonnie",
+    "Caleb",
+    "Daphne",
+    "Elias",
+    "Fiona",
+    "Galileo",
+    "Hugo",
+    "Ian",
+    "Jude",
+    "Knox",
+    "Leo",
+    "Maya",
+    "Nash",
+    "Owen",
+    "Paxton",
+    "Quetzal",
+    "Rosa",
+    "Sage",
+    "Talia",
+    "Uri",
+    "Vincent",
+    "Wesley",
+    "Ximena",
+    "Yvette",
+    "Zephyr",
+    // Pass 6
+    "Astrid",
+    "Beau",
+    "Celeste",
+    "Dexter",
+    "Ezra",
+    "Fitz",
+    "Genevieve",
+    "Hadley",
+    "Imogen",
+    "Joaquin",
+    "Kira",
+    "Lila",
+    "Mason",
+    "Nila",
+    "Olga",
+    "Pearl",
+    "Quincy",
+    "Royce",
+    "Sterling",
+    "Trent",
+    "Ulysses",
+    "Violet",
+    "Wynne",
+    "Xerxes",
+    "Yael",
+    "Zinnia",
+    // Pass 7
+    "Amelia",
+    "Bianca",
+    "Cody",
+    "Dahlia",
+    "Esme",
+    "Fern",
+    "Greer",
+    "Harriet",
+    "Ivan",
+    "Juno",
+    "Kendrick",
+    "Luther",
+    "Margot",
+    "Nigel",
+    "Orion",
+    "Phillip",
+    "Quenby",
+    "Reagan",
+    "Sienna",
+    "Tessa",
+    "Uma",
+    "Vesper",
+    "Watson",
+    "Xiomara",
+    "Yuri",
+    "Zoltan",
+    // Pass 8
+    "Andre",
+    "Boris",
+    "Cassidy",
+    "Davis",
+    "Evander",
+    "Forrest",
+    "Gibson",
+    "Henry",
+    "Irene",
+    "Justus",
+    "Kasper",
+    "Lainey",
+    "Miles",
+    "Naomi",
+    "Ophelia",
+    "Phoebe",
+    "Quark",
+    "Rylie",
+    "Saul",
+    "Truman",
+    "Ulrich",
+    "Voss",
+    "Winifred",
+    "Xuxa",
+    "Yvonne",
+    "Zia",
+    // Pass 9
+    "Aria",
+    "Brenda",
+    "Crispin",
+    "Dolores",
+    "Estelle",
+    "Felicity",
+    "Goldie",
+    "Hazel",
+    "Ira",
+    "Jovi",
+    "Kestrel",
+    "Lyric",
+    "Mavis",
+    "Nico",
+    "Otis",
+    "Percy",
+    "Querubin",
+    "Rhett",
+    "Scout",
+    "Tatum",
+    "Unity",
+    "Vivian",
+    "Wyatt",
+    "Xan",
+    "Yancy",
+    "Zev",
+    // Pass 10
+    "Atticus",
+    "Barnaby",
+    "Calliope",
+    "Drake",
+    "Eustace",
+    "Foster",
+    "Granger",
+    "Hollis",
+    "Indira",
+    "Jericho",
+    "Kaleb",
+    "Logan",
+    "Magnus",
+    "Noor",
+    "Oakley",
+    "Posy",
+    "Quito",
+    "Rosalind",
+    "Sloane",
+    "Theron",
+    "Upton",
+    "Vance",
+    "Wendell",
+    "Xola",
+    "Yann",
+    "Zora",
+];
+if (COORD_NAMES.length !== 260) {
+    throw new Error(`COORD_NAMES table corrupt: expected 260 entries, got ${COORD_NAMES.length}`);
+}
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+function counterPath(coordRoot) {
+    return join(coordRoot, ".harnery", ".name-counter");
+}
+function historyPath(coordRoot) {
+    return join(coordRoot, ".harnery", ".name-history");
+}
+function readHistory(coordRoot) {
+    const p = historyPath(coordRoot);
+    if (!existsSync(p))
+        return [];
+    try {
+        return readFileSync(p, "utf8")
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+function appendHistory(coordRoot, row) {
+    const p = historyPath(coordRoot);
+    mkdirSync(dirname(p), { recursive: true });
+    const line = `${JSON.stringify(row)}\n`;
+    // Append is naturally atomic for lines <PIPE_BUF (4096 on Linux).
+    writeFileSync(p, line, { encoding: "utf8", flag: "a" });
+}
+/**
+ * Resolve (name, kind) for an existing owner without consuming a counter
+ * slot. Returns null if no history match found.
+ *
+ *   1. Own instance_id → original (name, kind)
+ *   2. session_id (owner != session) → (parent's name, "transient")
+ */
+export function resolveName(coordRoot, instanceId, sessionId) {
+    const history = readHistory(coordRoot);
+    for (const row of history) {
+        if (row.instance_id === instanceId) {
+            return { name: row.name, kind: row.kind };
+        }
+    }
+    if (sessionId && sessionId !== instanceId) {
+        for (const row of history) {
+            if (row.instance_id === sessionId) {
+                return { name: row.name, kind: "transient" };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
+ * the owner is new. Idempotent: returns existing name on resume.
+ */
+export function assignName(coordRoot, instanceId, kind) {
+    // Check 1: existing history row → original name.
+    const existing = resolveName(coordRoot, instanceId);
+    if (existing)
+        return existing.name;
+    // New owner: consume a counter slot.
+    const cPath = counterPath(coordRoot);
+    let counter = 0;
+    if (existsSync(cPath)) {
+        const raw = readFileSync(cPath, "utf8").trim();
+        if (/^\d+$/.test(raw))
+            counter = Number.parseInt(raw, 10);
+    }
+    const name = COORD_NAMES[counter % 260];
+    atomicWrite(cPath, String(counter + 1));
+    appendHistory(coordRoot, {
+        instance_id: instanceId,
+        name,
+        kind,
+        ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    });
+    return name;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Pid-map writer.
+ *
+ * Per-harness pid-map at `.harnery/pid-map/<pid>` containing
+ * `<instance_id>\t<platform>`. `harn agents whoami` walks ppid up 20 hops looking
+ * for a matching entry (preferring the harness, falling back to any platform).
+ *
+ * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
+ */
+export declare function writePidmapRow(coordRoot: string, pid: number, instanceId: string, platform: string): void;
+//# sourceMappingURL=pidmap.d.ts.map