harnery 0.3.0 → 0.3.2

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA+EnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}

package/dist/commands/agents.js

@@ -18,6 +18,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerWithSource, } from "../core/agents/index.js";
 import { resolveBinName } from "../core/config.js";
+import { parsePsChainLine } from "../core/hooks/resolve/anchor.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
 import { appendEntry, resolveOwnerByName } from "../lib/scratch/index.js";
@@ -2251,14 +2252,26 @@ function runHarnessProbe(id, opts) {
     for (let hops = 0; hops < 20; hops++) {
         let comm = "?";
         let ppid = 0;
+        let got = false;
         try {
             comm = readFileSync(`/proc/${walkPid}/comm`, "utf8").trim() || "?";
             const status = readFileSync(`/proc/${walkPid}/status`, "utf8");
             const m = status.match(/^PPid:\s+(\d+)/m);
             ppid = m ? Number(m[1]) : 0;
+            got = true;
         }
         catch {
-            // non-Linux (no /proc) or the pid is gone: stop walking.
+            // non-Linux (no /proc): fall through to the portable ps walk below.
+        }
+        if (!got) {
+            const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(walkPid)], {
+                encoding: "utf8",
+            });
+            const parsed = out.status === 0 ? parsePsChainLine(out.stdout) : null;
+            if (parsed) {
+                comm = parsed.comm || "?";
+                ppid = parsed.ppid;
+            }
         }
         chainParts.push(`${walkPid}:${comm}`);
         if (!anchorPid && anchorTokens.has(comm))

package/dist/core/agents/coord-client.d.ts

@@ -69,8 +69,29 @@ export declare function resolveOwner(): string | null;
  */
 export declare function resolveOwnerWithSource(): {
     owner: string | null;
-    source: "env" | "pidmap" | "pidmap_fallback" | "none";
+    source: "env" | "pidmap" | "pidmap_fallback" | "session_env" | "active_singleton" | "none";
 };
+/**
+ * Resolve the owner by matching the harness session-id env var against the
+ * `session_id` of a live heartbeat in this coord root. Returns the matching
+ * `instance_id`, or null if there's no session-id env var or no live heartbeat
+ * carries it. "Live" reuses the same 10-minute freshness window the singleton
+ * fallback applies, so a stale heartbeat from a prior session of the same id
+ * doesn't resolve.
+ *
+ * Exported for unit testing with an injectable root.
+ */
+export declare function resolveOwnerBySessionEnv(root: string): string | null;
+/**
+ * Return the instance_id of the sole live agent in this coord root, or null
+ * if there are zero or more than one. "Live" reuses the 10-minute heartbeat
+ * freshness window the rest of the agents surface applies (kept inline as a
+ * literal so this file stays node-builtins-only for vendored downstream use).
+ *
+ * Exported for unit testing with an injectable root (the caller in
+ * `resolveOwnerWithSource` passes `monorepoRoot()`).
+ */
+export declare function resolveSingleActiveOwner(root: string): string | null;
 /**
  * Read and parse a heartbeat file. Returns null if the file is missing,
  * unreadable, or contains malformed JSON. Does not throw.

package/dist/core/agents/coord-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,MAAM,CAAC;CACvD,CAgCA;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}
+{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;CAC5F,CAuDA;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}

package/dist/core/agents/coord-client.js

@@ -7,7 +7,7 @@
  * either side without divergence.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 /**
  * Resolve the monorepo root for coord-state purposes.
@@ -133,10 +133,142 @@ export function resolveOwnerWithSource() {
         }
         pid = readPpid(pid);
     }
-    return {
-        owner: fallbackOwner,
-        source: fallbackOwner ? "pidmap_fallback" : "none",
-    };
+    if (fallbackOwner) {
+        return { owner: fallbackOwner, source: "pidmap_fallback" };
+    }
+    // The ppid walk found nothing (e.g. a Bash-tool subshell whose process tree
+    // doesn't climb back to the harness anchor). Before guessing, try the
+    // harness-provided session id from the environment: every supported harness
+    // exports its session id into the tool subprocess env, and each heartbeat
+    // records the `session_id` it was minted under. Matching the two resolves us
+    // unambiguously even with multiple live agents, which is the case the
+    // singleton fallback below cannot handle.
+    const bySession = resolveOwnerBySessionEnv(root);
+    if (bySession) {
+        return { owner: bySession, source: "session_env" };
+    }
+    // Last resort: if exactly one agent is live in this coord root, it's
+    // unambiguously us — resolve to it. This is what lets the bare `agents
+    // status` / `set-task` the stop hook recommends work without a `--session-id`
+    // flag in the common single-agent case. With 0 or 2+ live agents it would be
+    // a guess, so we stay null and require the explicit flag.
+    const singleton = resolveSingleActiveOwner(root);
+    if (singleton) {
+        return { owner: singleton, source: "active_singleton" };
+    }
+    return { owner: null, source: "none" };
+}
+/**
+ * Harness-exported session-id environment variables, in precedence order. Each
+ * supported harness propagates its session id into the env of the subprocess it
+ * spawns for a tool call (Claude Code's Bash tool, Cursor's terminal, Codex's
+ * shell). A coord CLI invoked as such a tool can therefore recover its own
+ * identity from the env even when the ppid walk misses.
+ *
+ * Kept inline (no shared-helper import) so this file stays node-builtins-only
+ * for the vendored downstream consumer.
+ */
+const SESSION_ID_ENV_VARS = [
+    "HARNERY_AGENT_COORD_SESSION_ID", // explicit override, wins if set
+    "CLAUDE_CODE_SESSION_ID",
+    "CURSOR_SESSION_ID",
+    "CODEX_SESSION_ID",
+];
+/** Read the first non-empty harness session-id env var, or null. */
+function sessionIdFromEnv() {
+    for (const key of SESSION_ID_ENV_VARS) {
+        const v = process.env[key]?.trim();
+        if (v)
+            return v;
+    }
+    return null;
+}
+/**
+ * Resolve the owner by matching the harness session-id env var against the
+ * `session_id` of a live heartbeat in this coord root. Returns the matching
+ * `instance_id`, or null if there's no session-id env var or no live heartbeat
+ * carries it. "Live" reuses the same 10-minute freshness window the singleton
+ * fallback applies, so a stale heartbeat from a prior session of the same id
+ * doesn't resolve.
+ *
+ * Exported for unit testing with an injectable root.
+ */
+export function resolveOwnerBySessionEnv(root) {
+    const sessionId = sessionIdFromEnv();
+    if (!sessionId)
+        return null;
+    const activeDir = resolve(root, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return null;
+    const FRESHNESS_SECS = 600;
+    const cutoffMs = Date.now() - FRESHNESS_SECS * 1000;
+    let files;
+    try {
+        files = readdirSync(activeDir);
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
+            if (!parsed || parsed.session_id !== sessionId)
+                continue;
+            if (typeof parsed.instance_id !== "string")
+                continue;
+            const ts = Date.parse(parsed.last_heartbeat);
+            if (Number.isFinite(ts) && ts >= cutoffMs)
+                return parsed.instance_id;
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return null;
+}
+/**
+ * Return the instance_id of the sole live agent in this coord root, or null
+ * if there are zero or more than one. "Live" reuses the 10-minute heartbeat
+ * freshness window the rest of the agents surface applies (kept inline as a
+ * literal so this file stays node-builtins-only for vendored downstream use).
+ *
+ * Exported for unit testing with an injectable root (the caller in
+ * `resolveOwnerWithSource` passes `monorepoRoot()`).
+ */
+export function resolveSingleActiveOwner(root) {
+    const activeDir = resolve(root, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return null;
+    const FRESHNESS_SECS = 600;
+    const cutoffMs = Date.now() - FRESHNESS_SECS * 1000;
+    const live = [];
+    let files;
+    try {
+        files = readdirSync(activeDir);
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
+            if (!parsed || typeof parsed.instance_id !== "string")
+                continue;
+            const ts = Date.parse(parsed.last_heartbeat);
+            if (Number.isFinite(ts) && ts >= cutoffMs)
+                live.push(parsed.instance_id);
+        }
+        catch {
+            // skip malformed
+        }
+        if (live.length > 1)
+            return null; // ambiguous; bail early
+    }
+    return live.length === 1 ? live[0] : null;
 }
 /**
  * Read and parse a heartbeat file. Returns null if the file is missing,
@@ -198,15 +330,30 @@ export function selfDisplayName() {
     return displayName(owner);
 }
 function readPpid(pid) {
+    // Linux/WSL fast path: /proc/<pid>/status carries `PPid:`.
     try {
         const status = readFileSync(`/proc/${pid}/status`, "utf8");
         const m = status.match(/^PPid:\s+(\d+)/m);
-        if (!m)
-            return null;
-        const parsed = Number.parseInt(m[1], 10);
-        return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+        if (m) {
+            const parsed = Number.parseInt(m[1], 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
     }
     catch {
-        return null;
+        // no /proc (macOS/BSD) — fall through to ps
     }
+    // Portable fallback: `ps -o ppid= -p <pid>` works on macOS/BSD/Linux.
+    try {
+        const out = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+        if (out.status === 0) {
+            const parsed = Number.parseInt(out.stdout.trim(), 10);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
+    }
+    catch {
+        // ps unavailable — give up
+    }
+    return null;
 }

package/dist/core/hooks/cli.js

@@ -30,7 +30,7 @@ import { captureImages, detectPresence, imageJanitor, playSound, resetSoundCount
 import { emit } from "./events/emit.js";
 import { detectHarness } from "./harness/detect.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./harness/parse.js";
-import { selectAnchorPid } from "./resolve/anchor.js";
+import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
 import { findCoordRoot } from "./resolve/coord-root.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
@@ -820,10 +820,10 @@ function healHeartbeatViaCli(coordRoot, instanceId, sessionId, harness) {
  * the next tool call rather than going invisible until SessionStart fires
  * again, which it may never do.
  *
- * Returns undefined on macOS (no /proc) or when no anchor is found; callers
- * fall back to `process.ppid` (the bash wrapper's parent, which is usually
- * the harness binary itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides
- * everything so the test sandbox can pin a deterministic PID.
+ * Returns undefined only when no anchor is found; callers fall back to
+ * `process.ppid` (the bash wrapper's parent, which is usually the harness binary
+ * itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides everything so the
+ * test sandbox can pin a deterministic PID.
  */
 function findHarnessAnchorPid(harness) {
     const override = coordEnv("AGENT_COORD_TEST_ANCHOR_PID");
@@ -832,30 +832,35 @@ function findHarnessAnchorPid(harness) {
         if (Number.isFinite(n) && n > 0)
             return n;
     }
-    // Build the ppid chain (nearest → root, up to 20 hops) from /proc, then hand
-    // it to the pure selector. Splitting the /proc walk (untestable off a live
-    // box) from the comm-matching (unit-tested against the real Phase 0 chains in
-    // resolve/anchor.ts) keeps the cursor `node`-fallback logic verifiable.
+    // Build the ppid chain (nearest → root, up to 20 hops), then hand it to the
+    // pure selector. Linux/WSL reads /proc; macOS/BSD (no /proc) falls back to
+    // `ps -o ppid=,comm=` parsed by the unit-tested `parsePsChainLine`. Splitting
+    // the walk (untestable off a live box) from the comm-matching keeps the
+    // cursor `node`-fallback logic verifiable.
     const chain = [];
     let pid = process.pid;
     for (let hops = 0; hops < 20; hops++) {
-        let comm;
-        let status;
+        let hop = null;
         try {
-            comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
-            status = readFileSync(`/proc/${pid}/status`, "utf8");
+            const comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+            const status = readFileSync(`/proc/${pid}/status`, "utf8");
+            const m = status.match(/^PPid:\s+(\d+)/m);
+            hop = { comm, ppid: m ? Number(m[1]) : 0 };
         }
         catch {
-            break;
+            // no /proc (macOS/BSD) — fall through to ps
+        }
+        if (!hop) {
+            const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], { encoding: "utf8" });
+            if (out.status === 0)
+                hop = parsePsChainLine(out.stdout);
         }
-        chain.push({ pid, comm });
-        const m = status.match(/^PPid:\s+(\d+)/m);
-        if (!m)
+        if (!hop)
             break;
-        const ppid = Number(m[1]);
-        if (!Number.isFinite(ppid) || ppid === 0 || ppid === 1)
+        chain.push({ pid, comm: hop.comm });
+        if (!Number.isFinite(hop.ppid) || hop.ppid === 0 || hop.ppid === 1)
             break;
-        pid = ppid;
+        pid = hop.ppid;
     }
     return selectAnchorPid(chain, harness);
 }

package/dist/core/hooks/resolve/anchor.d.ts

@@ -34,4 +34,19 @@ export declare function selectAnchorPid(chain: ReadonlyArray<{
     pid: number;
     comm: string;
 }>, harness?: string): number | undefined;
+/**
+ * Parse one `ps -o ppid=,comm= -p <pid>` line into the same `{ ppid, comm }`
+ * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
+ * walk. `ps` prints `comm` as a full executable path (and some Apple helper
+ * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
+ * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * basename does. Returns null when the line has no leading numeric ppid.
+ *
+ * Pure (no I/O) so the parsing — the error-prone part — is unit-testable
+ * without a live process tree; the caller owns the `ps` spawn.
+ */
+export declare function parsePsChainLine(line: string): {
+    ppid: number;
+    comm: string;
+} | null;
 //# sourceMappingURL=anchor.d.ts.map

package/dist/core/hooks/resolve/anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAUpB"}
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQpF"}

package/dist/core/hooks/resolve/anchor.js

@@ -46,3 +46,25 @@ export function selectAnchorPid(chain, harness) {
     }
     return undefined;
 }
+/**
+ * Parse one `ps -o ppid=,comm= -p <pid>` line into the same `{ ppid, comm }`
+ * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
+ * walk. `ps` prints `comm` as a full executable path (and some Apple helper
+ * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
+ * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * basename does. Returns null when the line has no leading numeric ppid.
+ *
+ * Pure (no I/O) so the parsing — the error-prone part — is unit-testable
+ * without a live process tree; the caller owns the `ps` spawn.
+ */
+export function parsePsChainLine(line) {
+    const m = line.trim().match(/^(\d+)\s+(.*)$/);
+    if (!m)
+        return null;
+    const ppid = Number.parseInt(m[1], 10);
+    if (!Number.isFinite(ppid))
+        return null;
+    const commPath = m[2].trim();
+    const comm = commPath.split("/").pop() || commPath;
+    return { ppid, comm };
+}

package/dist/core/hooks/resolve/owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/owner.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,iBAAiB,CAAA;CAAE,GAAG,IAAI,CA+ChG;AAmBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnF"}
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/owner.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,iBAAiB,CAAA;CAAE,GAAG,IAAI,CA+ChG;AA2BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnF"}

package/dist/core/hooks/resolve/owner.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.js";
@@ -67,19 +68,30 @@ export function resolveOwner(opts) {
     return null;
 }
 function readPpid(pid) {
-    // Linux/WSL: /proc/<pid>/status carries `PPid:`. Falls back to null on
-    // macOS or any read failure; ancestor walk just terminates.
+    // Linux/WSL fast path: /proc/<pid>/status carries `PPid:`.
     try {
         const status = readFileSync(`/proc/${pid}/status`, "utf8");
-        for (const line of status.split("\n")) {
-            if (line.startsWith("PPid:")) {
-                const n = Number(line.split(/\s+/)[1]);
-                return Number.isFinite(n) ? n : null;
-            }
+        const m = status.match(/^PPid:\s+(\d+)/m);
+        if (m) {
+            const n = Number.parseInt(m[1], 10);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+    }
+    catch {
+        /* no /proc (macOS/BSD) — fall through to ps */
+    }
+    // Portable fallback: `ps -o ppid= -p <pid>` works on macOS/BSD/Linux.
+    try {
+        const out = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+        if (out.status === 0) {
+            const n = Number.parseInt(out.stdout.trim(), 10);
+            if (Number.isFinite(n) && n > 0)
+                return n;
         }
     }
     catch {
-        /* fallthrough */
+        /* ps unavailable — give up */
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/agents.ts

@@ -38,6 +38,7 @@ import {
   resolveOwnerWithSource,
 } from "../core/agents/index.ts";
 import { resolveBinName } from "../core/config.ts";
+import { parsePsChainLine } from "../core/hooks/resolve/anchor.ts";
 import {
   buildCouncilId,
   buildInviteMarkdown,
@@ -2692,13 +2693,25 @@ function runHarnessProbe(
   for (let hops = 0; hops < 20; hops++) {
     let comm = "?";
     let ppid = 0;
+    let got = false;
     try {
       comm = readFileSync(`/proc/${walkPid}/comm`, "utf8").trim() || "?";
       const status = readFileSync(`/proc/${walkPid}/status`, "utf8");
       const m = status.match(/^PPid:\s+(\d+)/m);
       ppid = m ? Number(m[1]) : 0;
+      got = true;
     } catch {
-      // non-Linux (no /proc) or the pid is gone: stop walking.
+      // non-Linux (no /proc): fall through to the portable ps walk below.
+    }
+    if (!got) {
+      const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(walkPid)], {
+        encoding: "utf8",
+      });
+      const parsed = out.status === 0 ? parsePsChainLine(out.stdout) : null;
+      if (parsed) {
+        comm = parsed.comm || "?";
+        ppid = parsed.ppid;
+      }
     }
     chainParts.push(`${walkPid}:${comm}`);
     if (!anchorPid && anchorTokens.has(comm)) anchorPid = String(walkPid);

package/src/core/agents/coord-client.ts

@@ -8,7 +8,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 // NOTE: kept dependency-free (node builtins only); this file is vendored verbatim into
 // a downstream consumer, so it cannot import the coordEnv helper.
@@ -144,7 +144,7 @@ export function resolveOwner(): string | null {
  */
 export function resolveOwnerWithSource(): {
   owner: string | null;
-  source: "env" | "pidmap" | "pidmap_fallback" | "none";
+  source: "env" | "pidmap" | "pidmap_fallback" | "session_env" | "active_singleton" | "none";
 } {
   const envOwner = process.env.HARNERY_AGENT_COORD_OWNER?.trim();
   if (envOwner) {
@@ -173,10 +173,134 @@ export function resolveOwnerWithSource(): {
     }
     pid = readPpid(pid);
   }
-  return {
-    owner: fallbackOwner,
-    source: fallbackOwner ? "pidmap_fallback" : "none",
-  };
+  if (fallbackOwner) {
+    return { owner: fallbackOwner, source: "pidmap_fallback" };
+  }
+
+  // The ppid walk found nothing (e.g. a Bash-tool subshell whose process tree
+  // doesn't climb back to the harness anchor). Before guessing, try the
+  // harness-provided session id from the environment: every supported harness
+  // exports its session id into the tool subprocess env, and each heartbeat
+  // records the `session_id` it was minted under. Matching the two resolves us
+  // unambiguously even with multiple live agents, which is the case the
+  // singleton fallback below cannot handle.
+  const bySession = resolveOwnerBySessionEnv(root);
+  if (bySession) {
+    return { owner: bySession, source: "session_env" };
+  }
+
+  // Last resort: if exactly one agent is live in this coord root, it's
+  // unambiguously us — resolve to it. This is what lets the bare `agents
+  // status` / `set-task` the stop hook recommends work without a `--session-id`
+  // flag in the common single-agent case. With 0 or 2+ live agents it would be
+  // a guess, so we stay null and require the explicit flag.
+  const singleton = resolveSingleActiveOwner(root);
+  if (singleton) {
+    return { owner: singleton, source: "active_singleton" };
+  }
+
+  return { owner: null, source: "none" };
+}
+
+/**
+ * Harness-exported session-id environment variables, in precedence order. Each
+ * supported harness propagates its session id into the env of the subprocess it
+ * spawns for a tool call (Claude Code's Bash tool, Cursor's terminal, Codex's
+ * shell). A coord CLI invoked as such a tool can therefore recover its own
+ * identity from the env even when the ppid walk misses.
+ *
+ * Kept inline (no shared-helper import) so this file stays node-builtins-only
+ * for the vendored downstream consumer.
+ */
+const SESSION_ID_ENV_VARS = [
+  "HARNERY_AGENT_COORD_SESSION_ID", // explicit override, wins if set
+  "CLAUDE_CODE_SESSION_ID",
+  "CURSOR_SESSION_ID",
+  "CODEX_SESSION_ID",
+] as const;
+
+/** Read the first non-empty harness session-id env var, or null. */
+function sessionIdFromEnv(): string | null {
+  for (const key of SESSION_ID_ENV_VARS) {
+    const v = process.env[key]?.trim();
+    if (v) return v;
+  }
+  return null;
+}
+
+/**
+ * Resolve the owner by matching the harness session-id env var against the
+ * `session_id` of a live heartbeat in this coord root. Returns the matching
+ * `instance_id`, or null if there's no session-id env var or no live heartbeat
+ * carries it. "Live" reuses the same 10-minute freshness window the singleton
+ * fallback applies, so a stale heartbeat from a prior session of the same id
+ * doesn't resolve.
+ *
+ * Exported for unit testing with an injectable root.
+ */
+export function resolveOwnerBySessionEnv(root: string): string | null {
+  const sessionId = sessionIdFromEnv();
+  if (!sessionId) return null;
+
+  const activeDir = resolve(root, ".harnery", "active");
+  if (!existsSync(activeDir)) return null;
+  const FRESHNESS_SECS = 600;
+  const cutoffMs = Date.now() - FRESHNESS_SECS * 1000;
+  let files: string[];
+  try {
+    files = readdirSync(activeDir);
+  } catch {
+    return null;
+  }
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
+      if (!parsed || parsed.session_id !== sessionId) continue;
+      if (typeof parsed.instance_id !== "string") continue;
+      const ts = Date.parse(parsed.last_heartbeat);
+      if (Number.isFinite(ts) && ts >= cutoffMs) return parsed.instance_id;
+    } catch {
+      // skip malformed
+    }
+  }
+  return null;
+}
+
+/**
+ * Return the instance_id of the sole live agent in this coord root, or null
+ * if there are zero or more than one. "Live" reuses the 10-minute heartbeat
+ * freshness window the rest of the agents surface applies (kept inline as a
+ * literal so this file stays node-builtins-only for vendored downstream use).
+ *
+ * Exported for unit testing with an injectable root (the caller in
+ * `resolveOwnerWithSource` passes `monorepoRoot()`).
+ */
+export function resolveSingleActiveOwner(root: string): string | null {
+  const activeDir = resolve(root, ".harnery", "active");
+  if (!existsSync(activeDir)) return null;
+  const FRESHNESS_SECS = 600;
+  const cutoffMs = Date.now() - FRESHNESS_SECS * 1000;
+  const live: string[] = [];
+  let files: string[];
+  try {
+    files = readdirSync(activeDir);
+  } catch {
+    return null;
+  }
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
+      if (!parsed || typeof parsed.instance_id !== "string") continue;
+      const ts = Date.parse(parsed.last_heartbeat);
+      if (Number.isFinite(ts) && ts >= cutoffMs) live.push(parsed.instance_id);
+    } catch {
+      // skip malformed
+    }
+    if (live.length > 1) return null; // ambiguous; bail early
+  }
+  return live.length === 1 ? live[0]! : null;
 }
 
 /**
@@ -237,13 +361,26 @@ export function selfDisplayName(): string {
 }
 
 function readPpid(pid: number): number | null {
+  // Linux/WSL fast path: /proc/<pid>/status carries `PPid:`.
   try {
     const status = readFileSync(`/proc/${pid}/status`, "utf8");
     const m = status.match(/^PPid:\s+(\d+)/m);
-    if (!m) return null;
-    const parsed = Number.parseInt(m[1]!, 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+    if (m) {
+      const parsed = Number.parseInt(m[1]!, 10);
+      if (Number.isFinite(parsed) && parsed > 0) return parsed;
+    }
   } catch {
-    return null;
+    // no /proc (macOS/BSD) — fall through to ps
   }
+  // Portable fallback: `ps -o ppid= -p <pid>` works on macOS/BSD/Linux.
+  try {
+    const out = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+    if (out.status === 0) {
+      const parsed = Number.parseInt(out.stdout.trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) return parsed;
+    }
+  } catch {
+    // ps unavailable — give up
+  }
+  return null;
 }

package/src/core/hooks/cli.ts

@@ -51,7 +51,7 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./harness/parse.ts";
-import { selectAnchorPid } from "./resolve/anchor.ts";
+import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.ts";
 import { findCoordRoot } from "./resolve/coord-root.ts";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.ts";
 import { resolveOwner } from "./resolve/owner.ts";
@@ -908,10 +908,10 @@ function healHeartbeatViaCli(
  * the next tool call rather than going invisible until SessionStart fires
  * again, which it may never do.
  *
- * Returns undefined on macOS (no /proc) or when no anchor is found; callers
- * fall back to `process.ppid` (the bash wrapper's parent, which is usually
- * the harness binary itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides
- * everything so the test sandbox can pin a deterministic PID.
+ * Returns undefined only when no anchor is found; callers fall back to
+ * `process.ppid` (the bash wrapper's parent, which is usually the harness binary
+ * itself). `HARNERY_AGENT_COORD_TEST_ANCHOR_PID` overrides everything so the
+ * test sandbox can pin a deterministic PID.
  */
 function findHarnessAnchorPid(harness?: Harness): number | undefined {
   const override = coordEnv("AGENT_COORD_TEST_ANCHOR_PID");
@@ -919,27 +919,31 @@ function findHarnessAnchorPid(harness?: Harness): number | undefined {
     const n = Number(override);
     if (Number.isFinite(n) && n > 0) return n;
   }
-  // Build the ppid chain (nearest → root, up to 20 hops) from /proc, then hand
-  // it to the pure selector. Splitting the /proc walk (untestable off a live
-  // box) from the comm-matching (unit-tested against the real Phase 0 chains in
-  // resolve/anchor.ts) keeps the cursor `node`-fallback logic verifiable.
+  // Build the ppid chain (nearest → root, up to 20 hops), then hand it to the
+  // pure selector. Linux/WSL reads /proc; macOS/BSD (no /proc) falls back to
+  // `ps -o ppid=,comm=` parsed by the unit-tested `parsePsChainLine`. Splitting
+  // the walk (untestable off a live box) from the comm-matching keeps the
+  // cursor `node`-fallback logic verifiable.
   const chain: Array<{ pid: number; comm: string }> = [];
   let pid = process.pid;
   for (let hops = 0; hops < 20; hops++) {
-    let comm: string;
-    let status: string;
+    let hop: { comm: string; ppid: number } | null = null;
     try {
-      comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
-      status = readFileSync(`/proc/${pid}/status`, "utf8");
+      const comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+      const status = readFileSync(`/proc/${pid}/status`, "utf8");
+      const m = status.match(/^PPid:\s+(\d+)/m);
+      hop = { comm, ppid: m ? Number(m[1]) : 0 };
     } catch {
-      break;
+      // no /proc (macOS/BSD) — fall through to ps
     }
-    chain.push({ pid, comm });
-    const m = status.match(/^PPid:\s+(\d+)/m);
-    if (!m) break;
-    const ppid = Number(m[1]);
-    if (!Number.isFinite(ppid) || ppid === 0 || ppid === 1) break;
-    pid = ppid;
+    if (!hop) {
+      const out = spawnSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], { encoding: "utf8" });
+      if (out.status === 0) hop = parsePsChainLine(out.stdout);
+    }
+    if (!hop) break;
+    chain.push({ pid, comm: hop.comm });
+    if (!Number.isFinite(hop.ppid) || hop.ppid === 0 || hop.ppid === 1) break;
+    pid = hop.ppid;
   }
   return selectAnchorPid(chain, harness);
 }

package/src/core/hooks/resolve/anchor.ts

@@ -49,3 +49,24 @@ export function selectAnchorPid(
   }
   return undefined;
 }
+
+/**
+ * Parse one `ps -o ppid=,comm= -p <pid>` line into the same `{ ppid, comm }`
+ * shape the `/proc` fast path produces, for the macOS/BSD branch of the anchor
+ * walk. `ps` prints `comm` as a full executable path (and some Apple helper
+ * names contain spaces, e.g. `Code Helper (Plugin)`), so the comm is reduced to
+ * its basename to match the harness comm tokens the way Linux's `/proc/<pid>/comm`
+ * basename does. Returns null when the line has no leading numeric ppid.
+ *
+ * Pure (no I/O) so the parsing — the error-prone part — is unit-testable
+ * without a live process tree; the caller owns the `ps` spawn.
+ */
+export function parsePsChainLine(line: string): { ppid: number; comm: string } | null {
+  const m = line.trim().match(/^(\d+)\s+(.*)$/);
+  if (!m) return null;
+  const ppid = Number.parseInt(m[1]!, 10);
+  if (!Number.isFinite(ppid)) return null;
+  const commPath = m[2]!.trim();
+  const comm = commPath.split("/").pop() || commPath;
+  return { ppid, comm };
+}

package/src/core/hooks/resolve/owner.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
@@ -73,18 +74,26 @@ export function resolveOwner(opts: {
 }
 
 function readPpid(pid: number): number | null {
-  // Linux/WSL: /proc/<pid>/status carries `PPid:`. Falls back to null on
-  // macOS or any read failure; ancestor walk just terminates.
+  // Linux/WSL fast path: /proc/<pid>/status carries `PPid:`.
   try {
     const status = readFileSync(`/proc/${pid}/status`, "utf8");
-    for (const line of status.split("\n")) {
-      if (line.startsWith("PPid:")) {
-        const n = Number(line.split(/\s+/)[1]);
-        return Number.isFinite(n) ? n : null;
-      }
+    const m = status.match(/^PPid:\s+(\d+)/m);
+    if (m) {
+      const n = Number.parseInt(m[1]!, 10);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  } catch {
+    /* no /proc (macOS/BSD) — fall through to ps */
+  }
+  // Portable fallback: `ps -o ppid= -p <pid>` works on macOS/BSD/Linux.
+  try {
+    const out = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+    if (out.status === 0) {
+      const n = Number.parseInt(out.stdout.trim(), 10);
+      if (Number.isFinite(n) && n > 0) return n;
     }
   } catch {
-    /* fallthrough */
+    /* ps unavailable — give up */
   }
   return null;
 }