harnery 0.2.2 → 0.3.1

package/dist/commands/web-fetch.d.ts

@@ -0,0 +1,10 @@
+import type { EmitContext } from "../commander.js";
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export declare function webRunner(): "bun" | "npm";
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export declare function lazyFetchWebRoot(emit: EmitContext): string | null;
+//# sourceMappingURL=web-fetch.d.ts.map

package/dist/commands/web-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/commands/web-fetch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAiDnD,2GAA2G;AAC3G,wBAAgB,SAAS,IAAI,KAAK,GAAG,KAAK,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAmDjE"}

package/dist/commands/web-fetch.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Lazy-fetch of the web dashboard for npm consumers.
+ *
+ * The published npm package ships the CLI + coord engine but deliberately
+ * excludes `web/` (ADR 0001/0003: keep the core lean for CLI-only users). The
+ * dashboard also imports harnery's `src/` directly (see `web/next.config.ts`),
+ * so it can't be lifted out as a standalone folder. Instead, the first time
+ * `harn web up` runs from an install without a local `web/`, we clone the
+ * harnery repo at the *matching version tag* into a cache dir and install the
+ * web app's deps. Subsequent runs reuse the cache.
+ *
+ * The only thing `web/` pulls from `src/` is `harnery/lib/scratch` (a single,
+ * dependency-free module), so the install is `web/` deps only: no root install,
+ * no Playwright browser download.
+ */
+const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
+/** harnery's own package root: src/commands/ -> ../.. ; valid in both src/ and dist/. */
+function packageRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..");
+}
+function readPkg() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+        const raw = typeof pkg.repository === "string" ? pkg.repository : (pkg.repository?.url ?? "");
+        const repoUrl = raw.replace(/^git\+/, "") || DEFAULT_REPO_URL;
+        return { version: typeof pkg.version === "string" ? pkg.version : "0.0.0", repoUrl };
+    }
+    catch {
+        return { version: "0.0.0", repoUrl: DEFAULT_REPO_URL };
+    }
+}
+/** The git ref to fetch: HARNERY_WEB_REF override, else the version tag (`v<version>`). */
+function resolveRef(version) {
+    return process.env.HARNERY_WEB_REF || `v${version}`;
+}
+/** Per-ref cache dir under the XDG cache (matches harnery's `~/.cache/harnery/...`). */
+function webCacheRoot(ref) {
+    const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+    const safeRef = ref.replace(/[^\w.-]/g, "_");
+    return path.join(base, "harnery", "web", safeRef);
+}
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export function webRunner() {
+    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+    return r.status === 0 ? "bun" : "npm";
+}
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export function lazyFetchWebRoot(emit) {
+    const { version, repoUrl } = readPkg();
+    const ref = resolveRef(version);
+    const cacheRoot = webCacheRoot(ref);
+    const webDir = path.join(cacheRoot, "web");
+    // node_modules in the cached web/ is the "fetched + installed" marker.
+    if (existsSync(path.join(webDir, "node_modules"))) {
+        emit.log(`harn web · using cached dashboard (${ref})`, "info");
+        return webDir;
+    }
+    emit.log(`harn web · dashboard is not bundled in the npm package; fetching harnery ${ref} (one-time)`, "info");
+    emit.log(`           into ${cacheRoot}  ·  clone + web/ deps; pass --no-fetch to skip`, "info");
+    // Clear any partial/stale state so a retry is clean.
+    if (existsSync(cacheRoot))
+        rmSync(cacheRoot, { recursive: true, force: true });
+    mkdirSync(path.dirname(cacheRoot), { recursive: true });
+    const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+        stdio: "inherit",
+    });
+    if (clone.status !== 0) {
+        emit.error({
+            code: "web_fetch_failed",
+            message: `git clone of ${repoUrl} @ ${ref} failed${clone.error ? `: ${clone.error.message}` : ` (status ${clone.status})`}`,
+            hint: "Fetching the dashboard needs git + network. Do it manually: " +
+                `git clone ${repoUrl} && cd harnery/web && ${webRunner()} install, then run it pointed at your project via HARNERY_COORD_ROOT. ` +
+                "See https://harnery.com/cli/web/.",
+        });
+        return null;
+    }
+    const runner = webRunner();
+    emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
+    const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
+    if (install.status !== 0) {
+        emit.error({
+            code: "web_fetch_failed",
+            message: `${runner} install in ${webDir} failed (status ${install.status})`,
+            hint: `Try manually: cd ${webDir} && ${runner} install`,
+        });
+        return null;
+    }
+    emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");
+    return webDir;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsDnD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAqI5E"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAwDnD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwI5E"}

package/dist/commands/web.js

@@ -2,6 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { lazyFetchWebRoot, webRunner } from "./web-fetch.js";
 /**
  * `harn web`: Next.js dashboard for harnery's coord state.
  *
@@ -15,6 +16,9 @@ import { fileURLToPath } from "node:url";
  * passing cwd here lets the dashboard show the right project regardless
  * of where the user invokes `harn web up` from.
  *
+ * The dashboard is not bundled in the npm package (ADR 0001/0003), so on an
+ * npm install `resolveWebRoot` lazy-fetches it on first use (see web-fetch.ts).
+ *
  * Localhost-only by default. Network exposure is intentionally out of
  * scope for v1.
  */
@@ -23,25 +27,25 @@ function webRoot() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(here, "..", "..", "web");
 }
-function checkWebPresent(emit) {
-    const root = webRoot();
-    if (!existsSync(path.join(root, "package.json"))) {
-        emit.error({
-            code: "web_missing",
-            message: `harnery/web/ not found at ${root}`,
-            hint: "The dashboard ships with the harnery git repo, not the npm package (which is the CLI + " +
-                "coord engine only). Clone https://github.com/ryanjkelly/harnery, run `bun install`, then " +
-                "`harn web up --coord-root <your-project>` (or run it from inside that project). " +
-                "See https://harnery.com/cli/web/.",
-        });
-        return null;
-    }
-    return root;
-}
-function runner() {
-    // Prefer bun when available; fall back to npx/npm for plain Node installs.
-    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
-    return r.status === 0 ? "bun" : "npx";
+/**
+ * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
+ * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
+ * caller passed --no-fetch, in which case emit the honest manual hint.
+ */
+function resolveWebRoot(emit, allowFetch) {
+    const local = webRoot();
+    if (existsSync(path.join(local, "package.json")))
+        return local;
+    if (allowFetch)
+        return lazyFetchWebRoot(emit);
+    emit.error({
+        code: "web_missing",
+        message: `harnery/web/ not found at ${local}`,
+        hint: "The dashboard is not bundled in the npm package. Re-run without --no-fetch to fetch it " +
+            "automatically, or clone https://github.com/ryanjkelly/harnery and run it from there. " +
+            "See https://harnery.com/cli/web/.",
+    });
+    return null;
 }
 export function registerWebCommand(program, emit) {
     const web = program
@@ -54,8 +58,9 @@ export function registerWebCommand(program, emit) {
         .option("-p, --port <port>", "Listen port", "9000")
         .option("--coord-root <dir>", "Override the coord root (default: cwd; web walks up looking for .harnery/)")
         .option("--prod", "Use next start instead of next dev (requires prior build)")
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
         .action(async (opts) => {
-        const root = checkWebPresent(emit);
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
@@ -77,7 +82,7 @@ export function registerWebCommand(program, emit) {
         }
         emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
-        const child = spawn(runner(), ["run", mode], {
+        const child = spawn(webRunner(), ["run", mode], {
             cwd: root,
             env: {
                 ...process.env,
@@ -105,14 +110,15 @@ export function registerWebCommand(program, emit) {
     web
         .command("build")
         .description("Build the production bundle (next build).")
-        .action(() => {
-        const root = checkWebPresent(emit);
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+        .action((opts) => {
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
         }
         emit.log("running next build…", "info");
-        const r = spawnSync(runner(), ["run", "build"], {
+        const r = spawnSync(webRunner(), ["run", "build"], {
             cwd: root,
             stdio: "inherit",
         });
@@ -123,8 +129,9 @@ export function registerWebCommand(program, emit) {
         .description("Start the production server (next start). Requires prior `harn web build`.")
         .option("-p, --port <port>", "Listen port", "9000")
         .option("--coord-root <dir>", "Override the coord root")
+        .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
         .action((opts) => {
-        const root = checkWebPresent(emit);
+        const root = resolveWebRoot(emit, opts.fetch !== false);
         if (!root) {
             process.exitCode = 1;
             return;
@@ -143,7 +150,7 @@ export function registerWebCommand(program, emit) {
         const port = String(opts.port);
         emit.log(`harn web · http://localhost:${port} (start)`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
-        const child = spawn(runner(), ["run", "start"], {
+        const child = spawn(webRunner(), ["run", "start"], {
             cwd: root,
             env: {
                 ...process.env,

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.2.2",
+  "version": "0.3.1",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -132,6 +132,7 @@
     "test": "bun test src tests",
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
+    "smoke": "node scripts/smoke-test.mjs",
     "docs:dev": "bun --cwd docs run dev",
     "docs:build": "bun --cwd docs run build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs"

package/src/commands/web-fetch.ts

@@ -0,0 +1,117 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EmitContext } from "../commander.ts";
+
+/**
+ * Lazy-fetch of the web dashboard for npm consumers.
+ *
+ * The published npm package ships the CLI + coord engine but deliberately
+ * excludes `web/` (ADR 0001/0003: keep the core lean for CLI-only users). The
+ * dashboard also imports harnery's `src/` directly (see `web/next.config.ts`),
+ * so it can't be lifted out as a standalone folder. Instead, the first time
+ * `harn web up` runs from an install without a local `web/`, we clone the
+ * harnery repo at the *matching version tag* into a cache dir and install the
+ * web app's deps. Subsequent runs reuse the cache.
+ *
+ * The only thing `web/` pulls from `src/` is `harnery/lib/scratch` (a single,
+ * dependency-free module), so the install is `web/` deps only: no root install,
+ * no Playwright browser download.
+ */
+
+const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
+
+/** harnery's own package root: src/commands/ -> ../.. ; valid in both src/ and dist/. */
+function packageRoot(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "..");
+}
+
+function readPkg(): { version: string; repoUrl: string } {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+    const raw = typeof pkg.repository === "string" ? pkg.repository : (pkg.repository?.url ?? "");
+    const repoUrl = raw.replace(/^git\+/, "") || DEFAULT_REPO_URL;
+    return { version: typeof pkg.version === "string" ? pkg.version : "0.0.0", repoUrl };
+  } catch {
+    return { version: "0.0.0", repoUrl: DEFAULT_REPO_URL };
+  }
+}
+
+/** The git ref to fetch: HARNERY_WEB_REF override, else the version tag (`v<version>`). */
+function resolveRef(version: string): string {
+  return process.env.HARNERY_WEB_REF || `v${version}`;
+}
+
+/** Per-ref cache dir under the XDG cache (matches harnery's `~/.cache/harnery/...`). */
+function webCacheRoot(ref: string): string {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  const safeRef = ref.replace(/[^\w.-]/g, "_");
+  return path.join(base, "harnery", "web", safeRef);
+}
+
+/** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
+export function webRunner(): "bun" | "npm" {
+  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+  return r.status === 0 ? "bun" : "npm";
+}
+
+/**
+ * Ensure a cached harnery checkout's `web/` exists for this version and return
+ * its path, fetching (clone + install) on first use. Returns null on failure
+ * (after emitting an actionable error).
+ */
+export function lazyFetchWebRoot(emit: EmitContext): string | null {
+  const { version, repoUrl } = readPkg();
+  const ref = resolveRef(version);
+  const cacheRoot = webCacheRoot(ref);
+  const webDir = path.join(cacheRoot, "web");
+
+  // node_modules in the cached web/ is the "fetched + installed" marker.
+  if (existsSync(path.join(webDir, "node_modules"))) {
+    emit.log(`harn web · using cached dashboard (${ref})`, "info");
+    return webDir;
+  }
+
+  emit.log(
+    `harn web · dashboard is not bundled in the npm package; fetching harnery ${ref} (one-time)`,
+    "info",
+  );
+  emit.log(`           into ${cacheRoot}  ·  clone + web/ deps; pass --no-fetch to skip`, "info");
+
+  // Clear any partial/stale state so a retry is clean.
+  if (existsSync(cacheRoot)) rmSync(cacheRoot, { recursive: true, force: true });
+  mkdirSync(path.dirname(cacheRoot), { recursive: true });
+
+  const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+    stdio: "inherit",
+  });
+  if (clone.status !== 0) {
+    emit.error({
+      code: "web_fetch_failed",
+      message: `git clone of ${repoUrl} @ ${ref} failed${clone.error ? `: ${clone.error.message}` : ` (status ${clone.status})`}`,
+      hint:
+        "Fetching the dashboard needs git + network. Do it manually: " +
+        `git clone ${repoUrl} && cd harnery/web && ${webRunner()} install, then run it pointed at your project via HARNERY_COORD_ROOT. ` +
+        "See https://harnery.com/cli/web/.",
+    });
+    return null;
+  }
+
+  const runner = webRunner();
+  emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
+  const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
+  if (install.status !== 0) {
+    emit.error({
+      code: "web_fetch_failed",
+      message: `${runner} install in ${webDir} failed (status ${install.status})`,
+      hint: `Try manually: cd ${webDir} && ${runner} install`,
+    });
+    return null;
+  }
+
+  emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");
+  return webDir;
+}

package/src/commands/web.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
 
 /**
  * `harn web`: Next.js dashboard for harnery's coord state.
@@ -18,6 +19,9 @@ import type { EmitContext } from "../commander.ts";
  * passing cwd here lets the dashboard show the right project regardless
  * of where the user invokes `harn web up` from.
  *
+ * The dashboard is not bundled in the npm package (ADR 0001/0003), so on an
+ * npm install `resolveWebRoot` lazy-fetches it on first use (see web-fetch.ts).
+ *
  * Localhost-only by default. Network exposure is intentionally out of
  * scope for v1.
  */
@@ -28,33 +32,31 @@ function webRoot(): string {
   return path.resolve(here, "..", "..", "web");
 }
 
-function checkWebPresent(emit: EmitContext): string | null {
-  const root = webRoot();
-  if (!existsSync(path.join(root, "package.json"))) {
-    emit.error({
-      code: "web_missing",
-      message: `harnery/web/ not found at ${root}`,
-      hint:
-        "The dashboard ships with the harnery git repo, not the npm package (which is the CLI + " +
-        "coord engine only). Clone https://github.com/ryanjkelly/harnery, run `bun install`, then " +
-        "`harn web up --coord-root <your-project>` (or run it from inside that project). " +
-        "See https://harnery.com/cli/web/.",
-    });
-    return null;
-  }
-  return root;
-}
-
-function runner(): string {
-  // Prefer bun when available; fall back to npx/npm for plain Node installs.
-  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
-  return r.status === 0 ? "bun" : "npx";
+/**
+ * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
+ * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
+ * caller passed --no-fetch, in which case emit the honest manual hint.
+ */
+function resolveWebRoot(emit: EmitContext, allowFetch: boolean): string | null {
+  const local = webRoot();
+  if (existsSync(path.join(local, "package.json"))) return local;
+  if (allowFetch) return lazyFetchWebRoot(emit);
+  emit.error({
+    code: "web_missing",
+    message: `harnery/web/ not found at ${local}`,
+    hint:
+      "The dashboard is not bundled in the npm package. Re-run without --no-fetch to fetch it " +
+      "automatically, or clone https://github.com/ryanjkelly/harnery and run it from there. " +
+      "See https://harnery.com/cli/web/.",
+  });
+  return null;
 }
 
 interface UpOpts {
   port: string;
   coordRoot?: string;
   prod?: boolean;
+  fetch?: boolean;
 }
 
 export function registerWebCommand(program: Command, emit: EmitContext): void {
@@ -74,8 +76,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       "Override the coord root (default: cwd; web walks up looking for .harnery/)",
     )
     .option("--prod", "Use next start instead of next dev (requires prior build)")
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
     .action(async (opts: UpOpts) => {
-      const root = checkWebPresent(emit);
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
@@ -101,7 +104,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
 
-      const child = spawn(runner(), ["run", mode], {
+      const child = spawn(webRunner(), ["run", mode], {
         cwd: root,
         env: {
           ...process.env,
@@ -130,14 +133,15 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
   web
     .command("build")
     .description("Build the production bundle (next build).")
-    .action(() => {
-      const root = checkWebPresent(emit);
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+    .action((opts: { fetch?: boolean }) => {
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
       }
       emit.log("running next build…", "info");
-      const r = spawnSync(runner(), ["run", "build"], {
+      const r = spawnSync(webRunner(), ["run", "build"], {
         cwd: root,
         stdio: "inherit",
       });
@@ -149,8 +153,9 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
     .description("Start the production server (next start). Requires prior `harn web build`.")
     .option("-p, --port <port>", "Listen port", "9000")
     .option("--coord-root <dir>", "Override the coord root")
-    .action((opts: { port: string; coordRoot?: string }) => {
-      const root = checkWebPresent(emit);
+    .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
+    .action((opts: { port: string; coordRoot?: string; fetch?: boolean }) => {
+      const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
         return;
@@ -170,7 +175,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       emit.log(`harn web · http://localhost:${port} (start)`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
 
-      const child = spawn(runner(), ["run", "start"], {
+      const child = spawn(webRunner(), ["run", "start"], {
         cwd: root,
         env: {
           ...process.env,

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