harnery 0.3.0 → 0.3.1

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,

package/package.json

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

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;
 }
 
 /**