benignswarm 0.8.0 → 0.10.0

package/dist/args.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { CliError } from "./errors.js";
-const STRING_FLAGS = ["as", "admin", "key", "url", "label", "model", "since", "limit", "after", "topic", "goal", "task", "state", "blocked-on", "tags", "custom", "vendor", "role", "description", "permissions", "cardinality", "machine", "dir", "confirm", "type", "name", "out", "token", "prefix", "uses", "expires-hours", "skill-dir", "harness", "reply-to", "event", "project", "projects", "post", "title", "body", "body-file", "handoff-to", "evidence", "agent", "parent", "parent-item", "channel", "statuses", "assign", "if-status", "status", "exec", "interval", "requeue-after", "category", "command", "follow-delay"];
+const STRING_FLAGS = ["as", "admin", "key", "url", "label", "model", "since", "limit", "after", "topic", "goal", "task", "state", "blocked-on", "tags", "custom", "vendor", "role", "description", "permissions", "cardinality", "machine", "dir", "confirm", "type", "name", "out", "token", "prefix", "uses", "expires-hours", "skill-dir", "harness", "reply-to", "event", "project", "projects", "post", "title", "body", "body-file", "handoff-to", "evidence", "agent", "parent", "parent-item", "channel", "statuses", "assign", "if-status", "status", "exec", "interval", "requeue-after", "category", "command", "follow-delay", "env"];
 const BOOL_FLAGS = ["json", "follow", "account", "help", "version", "broadcast", "create-channels", "read-account-status", "replace-key", "mentions-me", "no-skill", "replace", "unread", "force", "no-hooks", "yes", "open", "bind-here", "peek", "once", "launchd", "full", "no-bind"];
 export function parse(argv) {
     const options = {};

package/dist/client.js

@@ -13,8 +13,13 @@ export class Client {
         this.auto = auto;
         this.agentName = agentName;
     }
-    static forAgent(c, model) {
-        return new Client(c.url, c.key, { ...collectAuto({ model, machine: c.machine }) }, c.agent);
+    /**
+     * presence: send the X-Bschat-Auto header, which refreshes the agent's automatic status and
+     * marks it seen. True for commands the agent runs itself; false for polls made on its behalf
+     * by the hook or the watcher, which say nothing about whether the agent is alive.
+     */
+    static forAgent(c, model, opts = {}) {
+        return new Client(c.url, c.key, opts.presence === false ? null : { ...collectAuto({ model, machine: c.machine }) }, c.agent);
     }
     static forAdmin(c) {
         return new Client(c.url, c.key, null);
@@ -28,31 +33,50 @@ export class Client {
             h["x-bschat-auto"] = JSON.stringify(this.auto);
         return h;
     }
-    async call(method, path, body) {
+    /**
+     * opts.retries: how many times to retry on a network failure or a 5xx. Only safe for calls
+     * that are idempotent on the server (posts carry a client_id for exactly this reason).
+     */
+    async call(method, path, body, opts = {}) {
         const headers = this.headers();
         if (body !== undefined)
             headers["content-type"] = "application/json";
-        let res;
-        try {
-            res = await fetch(this.url + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+        const retries = opts.retries ?? 0;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await fetch(this.url + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+            }
+            catch (e) {
+                if (attempt < retries) {
+                    await backoff(attempt);
+                    continue;
+                }
+                throw new CliError("network", `could not reach ${this.url}: ${e.message}`);
+            }
+            noteServerVersions(res.headers, this.agentName);
+            const text = await res.text();
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                throw new CliError("bad_response", `${method} ${path} returned non-JSON (${res.status}): ${text.slice(0, 200)}`);
+            }
+            if (!res.ok) {
+                if (res.status >= 500 && attempt < retries) {
+                    process.stderr.write(`bschat: ${method} ${path} failed (${res.status}${json?.reference ? `, reference ${json.reference}` : ""}); retrying\n`);
+                    await backoff(attempt);
+                    continue;
+                }
+                const err = json;
+                const hint = res.status >= 500
+                    ? `This is a platform failure, not something to fix on your side. Do not retry in a loop. Report it once: bschat feedback "<what you were doing>${err.reference ? ` ref ${err.reference}` : ""}" and carry on with other work.`
+                    : undefined;
+                throw new CliError(err.error ?? `http_${res.status}`, err.message ?? text, hint);
+            }
+            return json;
         }
-        catch (e) {
-            throw new CliError("network", `could not reach ${this.url}: ${e.message}`);
-        }
-        noteServerVersions(res.headers, this.agentName);
-        const text = await res.text();
-        let json;
-        try {
-            json = JSON.parse(text);
-        }
-        catch {
-            throw new CliError("bad_response", `${method} ${path} returned non-JSON (${res.status}): ${text.slice(0, 200)}`);
-        }
-        if (!res.ok) {
-            const err = json;
-            throw new CliError(err.error ?? `http_${res.status}`, err.message ?? text);
-        }
-        return json;
     }
     wsUrl(path) {
         return this.url.replace(/^http/, "ws") + path;
@@ -63,3 +87,6 @@ export class Client {
         return ws;
     }
 }
+function backoff(attempt) {
+    return new Promise((r) => setTimeout(r, Math.min(8000, 500 * 2 ** attempt)));
+}

package/dist/commands/agent.js

@@ -1,8 +1,9 @@
 import { mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { bool, need, str } from "../args.js";
 import { Client } from "../client.js";
-import { DEFAULT_URL, listSaved, loadAgent, removeAgent, resolveAgentName, resolveModel, saveAgent } from "../config.js";
+import { agentRef, DEFAULT_URL, listSaved, loadAgent, removeAgent, resolveAgentName, resolveModel, saveAgent } from "../config.js";
 import { CliError } from "../errors.js";
 import { defaultMachine } from "../git.js";
 import { fmtMessage, fmtStatus, table } from "../output.js";
@@ -10,7 +11,7 @@ import { readState, writeState } from "../state.js";
 function agentClient(p) {
     const name = resolveAgentName(str(p.flags, "as"));
     const creds = loadAgent(name);
-    const model = resolveModel(str(p.flags, "model"));
+    const model = resolveModel(str(p.flags, "model"), process.env, process.cwd(), name);
     return { client: Client.forAgent(creds, model), creds };
 }
 /**
@@ -26,9 +27,10 @@ export function projectOf(p, creds) {
     return v;
 }
 export async function login(p, out) {
-    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
-    if (!name)
+    const asFlag = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
+    if (!asFlag)
         throw new CliError("usage", "login needs --as <agent-name>");
+    const name = asFlag.includes("/") ? asFlag.slice(asFlag.indexOf("/") + 1) : asFlag;
     const key = need(p.flags, "key");
     if (!key.startsWith("bs_agent_"))
         throw new CliError("usage", "login expects an agent key (bs_agent_...). For admin keys use: bschat admin login");
@@ -41,23 +43,24 @@ export async function login(p, out) {
     }
     const project = me.project ? me.project.name : null;
     const path = saveAgent({ url, key, account: me.project ? me.project.id : "", project, agent: name, vendor: me.agent.vendor, machine: defaultMachine(str(p.flags, "label")) });
-    out.print(`Saved identity ${name} (${project ? `project ${project}` : "account-scoped"}) to ${path}\nNext: export BSCHAT_AGENT=${name}`, { saved: path, agent: name, project });
+    const ref = agentRef({ project, agent: name });
+    out.print(`Saved identity ${ref} (${project ? `project ${project}` : "account-scoped"}) to ${path}\nNext: export BSCHAT_AGENT=${ref}`, { saved: path, agent: name, project, ref });
 }
 export async function logout(p, out) {
     const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
     if (!name)
         throw new CliError("usage", "logout needs --as <agent-name>");
-    removeAgent(name);
-    out.print(`Removed saved identity ${name}`, { removed: name });
+    const ref = removeAgent(name);
+    out.print(`Removed saved identity ${ref}`, { removed: ref });
 }
 export async function identities(_p, out) {
     const names = listSaved("agents");
     const rows = names.map((n) => {
         const c = loadAgent(n);
-        return { agent: n, project: c.project ?? "(account)", url: c.url, machine: c.machine };
+        return { ref: n, agent: c.agent, project: c.project ?? "(account)", url: c.url, machine: c.machine };
     });
     const current = process.env.BSCHAT_AGENT ?? "(BSCHAT_AGENT not set)";
-    out.print(`${table(rows, ["agent", "project", "url", "machine"])}\n\ncurrent: ${current}`, { identities: rows, current: process.env.BSCHAT_AGENT ?? null });
+    out.print(`${table(rows, ["ref", "agent", "project", "url", "machine"])}\n\ncurrent: ${current}`, { identities: rows, current: process.env.BSCHAT_AGENT ?? null });
 }
 export async function me(p, out) {
     const { client } = agentClient(p);
@@ -140,14 +143,17 @@ export async function send(p, out) {
     if (replyTo !== undefined && !/^\d+$/.test(replyTo))
         throw new CliError("usage", "--reply-to takes the seq number of the message you are answering");
     const project = projectOf(p, creds);
-    const r = await client.call("POST", `/projects/${project}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo) });
+    // One client id per post, reused across retries: a timeout or 5xx after the archive write
+    // returns the message that landed instead of posting it twice.
+    const clientId = randomUUID();
+    const r = await client.call("POST", `/projects/${project}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo), client_id: clientId }, { retries: 3 });
     {
         // Our own post must not count as unread for us; advance the cursor if we were caught up.
-        const st = readState(creds.agent);
+        const st = readState(agentRef(creds));
         const key = `${project}/${channel}`;
         const last = st.channel_read?.[key];
         if (last !== undefined && last >= r.message.seq - 1)
-            writeState(creds.agent, { ...st, channel_read: { ...(st.channel_read ?? {}), [key]: r.message.seq } });
+            writeState(agentRef(creds), { ...st, channel_read: { ...(st.channel_read ?? {}), [key]: r.message.seq } });
     }
     out.print(`sent #${channel} seq ${r.message.seq}${r.message.reply_to_seq ? ` (reply to #${r.message.reply_to_seq})` : ""}${r.message.mentions.length ? ` (mentions ${r.message.mentions.length})` : ""}`, r);
 }
@@ -168,8 +174,8 @@ export async function read(p, out) {
     qs.set("limit", str(p.flags, "limit") ?? "100");
     const r = await client.call("GET", `/projects/${project}/channels/${channel}/messages?${qs}`);
     const text = r.messages.length ? r.messages.map(fmtMessage).join("\n") : "(no messages)";
-    const st = readState(creds.agent);
-    writeState(creds.agent, { ...st, channel_read: { ...(st.channel_read ?? {}), [`${project}/${channel}`]: r.cursor } });
+    const st = readState(agentRef(creds));
+    writeState(agentRef(creds), { ...st, channel_read: { ...(st.channel_read ?? {}), [`${project}/${channel}`]: r.cursor } });
     out.print(`${text}\ncursor: ${r.cursor}`, r);
 }
 function follow(client, path, out) {
@@ -203,14 +209,14 @@ export async function inbox(p, out) {
     const { client, creds } = agentClient(p);
     const qs = new URLSearchParams();
     const unread = bool(p.flags, "unread");
-    const state = readState(creds.agent);
+    const state = readState(agentRef(creds));
     const after = str(p.flags, "after") ?? (unread ? state.inbox_after : undefined);
     if (after)
         qs.set("after", after);
     qs.set("limit", str(p.flags, "limit") ?? "50");
     const r = await client.call("GET", `/inbox?${qs}`);
     if (unread && r.messages.length)
-        writeState(creds.agent, { ...state, inbox_after: r.messages[r.messages.length - 1].created_at, last_check: Date.now() });
+        writeState(agentRef(creds), { ...state, inbox_after: r.messages[r.messages.length - 1].created_at, last_check: Date.now() });
     const fmt = (m) => `${creds.project ? "" : `[${m.project}] `}${fmtMessage(m)}${m.reply_to_seq ? `  (reply to #${m.reply_to_seq})` : ""}`;
     const items = (r.items ?? []).map((i) => `list "${i.list}": [${i.status}] ${i.title}  (item ${i.id})`);
     const text = [...r.messages.map(fmt), ...(items.length ? ["assigned to you:", ...items] : [])].join("\n");
@@ -294,7 +300,7 @@ export async function followCmd(p, out) {
     const channel = p.positionals[1];
     const { creds, client } = agentClient(p);
     const unfollow = p.positionals[0] === "unfollow";
-    const st = readState(creds.agent);
+    const st = readState(agentRef(creds));
     const follows = new Set(st.follows ?? []);
     if (p.positionals[0] === "following" || !channel) {
         out.print(follows.size ? [...follows].join("\n") : "(following no channels; the hook shows a digest line only)", { follows: [...follows] });
@@ -309,6 +315,6 @@ export async function followCmd(p, out) {
         await client.call("GET", `/projects/${project}/channels/${channel}/messages?limit=1`); // validates access
         follows.add(key);
     }
-    writeState(creds.agent, { ...st, follows: [...follows] });
+    writeState(agentRef(creds), { ...st, follows: [...follows] });
     out.print(`${unfollow ? "unfollowed" : "following"} #${channel} in ${project}`, { follows: [...follows] });
 }

package/dist/commands/evidence.js

@@ -21,7 +21,7 @@ export async function evidence(p, out) {
     const sub = p.positionals[1];
     const name = resolveAgentName(str(p.flags, "as"));
     const creds = loadAgent(name);
-    const client = Client.forAgent(creds, resolveModel(str(p.flags, "model")));
+    const client = Client.forAgent(creds, resolveModel(str(p.flags, "model"), process.env, process.cwd(), name));
     const project = projectOf(p, creds);
     if (sub === "post") {
         const file = p.positionals[2];

package/dist/commands/goal.js

@@ -0,0 +1,55 @@
+import { str } from "../args.js";
+import { Client } from "../client.js";
+import { agentRef, loadAgent, resolveAgentName } from "../config.js";
+import { CliError } from "../errors.js";
+import { heartbeatNow, HARNESS_GOAL_STATES } from "../heartbeat.js";
+import { readState, writeState } from "../state.js";
+/**
+ * Harness goal self-report, for harnesses whose /goal state lives where no file on this machine
+ * shows it (Codex app threads keep it in the cloud; DeepSeek exposes it through get_goal). Claude
+ * Code needs none of this: the hook reads the goal from the transcript.
+ *
+ *   bschat goal set "<the /goal text>" [--state pursuing|paused|stalled|achieved|abandoned]
+ *   bschat goal achieved | paused | stalled | abandoned     (same text, new state)
+ *   bschat goal clear
+ *   bschat goal                                             (what the server has for you)
+ */
+export async function goal(p, out) {
+    const sub = p.positionals[1];
+    const name = resolveAgentName(str(p.flags, "as"));
+    const creds = loadAgent(name);
+    const client = Client.forAgent(creds, undefined, { presence: false });
+    const ref = agentRef(creds);
+    if (!sub) {
+        const path = creds.project ? `/projects/${creds.project}/agents/status` : "/account/agents/status";
+        const r = await client.call("GET", path);
+        const mine = (creds.project ? r.statuses : r.account.statuses).find((s) => s.agent_name === creds.agent);
+        const g = mine?.harness?.goal;
+        out.print(g ? `harness goal (${g.state}): ${g.text}\nstatus goal (${mine.goal_source ?? "agent"}): ${mine.goal ?? "-"}` : `no harness goal reported for ${ref}`, { harness_goal: g ?? null, goal: mine?.goal ?? null, goal_source: mine?.goal_source ?? null });
+        return;
+    }
+    let next;
+    if (sub === "clear")
+        next = null;
+    else if (sub === "set") {
+        const text = p.positionals.slice(2).join(" ").trim();
+        if (!text)
+            throw new CliError("usage", 'goal set "<the goal text exactly as given to /goal>" [--state pursuing]');
+        const state = str(p.flags, "state") ?? "pursuing";
+        if (!HARNESS_GOAL_STATES.includes(state))
+            throw new CliError("usage", `--state must be one of ${HARNESS_GOAL_STATES.join(", ")}`);
+        next = { text, state: state };
+    }
+    else if (HARNESS_GOAL_STATES.includes(sub)) {
+        const last = readState(ref).harness_goal;
+        if (!last)
+            throw new CliError("no_goal", `no goal recorded on this machine to mark ${sub}`, 'Report it first: bschat goal set "<text>"');
+        next = { text: last.text, state: sub };
+    }
+    else {
+        throw new CliError("usage", `goal [set <text> [--state s] | ${HARNESS_GOAL_STATES.join(" | ")} | clear]`);
+    }
+    const r = await heartbeatNow(client, "agent-report", next);
+    writeState(ref, { ...readState(ref), harness_goal: next ?? undefined });
+    out.print(next ? `reported harness goal (${next.state}): ${next.text}` : "reported: no harness goal", { status: r });
+}

package/dist/commands/hook.js

@@ -1,12 +1,12 @@
 import { readFileSync } from "node:fs";
 import { str } from "../args.js";
 import { Client } from "../client.js";
-import { findIdentityFile, readIdentityFile } from "../harness.js";
-import { loadAgent, resolveModel } from "../config.js";
+import { loadAgent, resolveAgentName, resolveModel } from "../config.js";
+import { heartbeatNow } from "../heartbeat.js";
 import { fmtMessage } from "../output.js";
 import { readState, writeState } from "../state.js";
-import { detectVendor } from "../vendor.js";
-import { modelFromClaudeTranscript } from "../model.js";
+import { goalFromClaudeTranscript, modelFromClaudeTranscript } from "../model.js";
+const HEARTBEAT_MS = 60_000;
 /** Reads the harness's hook payload from stdin without blocking when there is none. */
 function readStdinJson() {
     try {
@@ -39,7 +39,8 @@ export async function gatherUpdates(name, opts) {
         return null;
     let messages;
     let items = [];
-    const client = Client.forAgent(creds, resolveModel(opts.model, process.env, process.cwd(), name));
+    // A poll on the agent's behalf: no presence header, so last_seen keeps meaning "the agent acted".
+    const client = Client.forAgent(creds, resolveModel(opts.model, process.env, process.cwd(), name), { presence: false });
     try {
         const qs = new URLSearchParams({ limit: "20" });
         if (state.inbox_after)
@@ -78,7 +79,7 @@ export async function gatherUpdates(name, opts) {
                 if (follows.has(key)) {
                     const r = await client.call("GET", `/projects/${project}/channels/${ch.name}/messages?since=${last}&limit=5`);
                     const seen = new Set(messages.map((m) => m.id));
-                    const others = r.messages.filter((m) => m.agent_name !== name && !seen.has(m.id));
+                    const others = r.messages.filter((m) => m.agent_name !== creds.agent && !seen.has(m.id));
                     for (const m of others)
                         followed.push(`${creds.project ? "" : `[${project}] `}${fmtMessage(m)}`);
                     const shown = r.messages.length ? r.messages[r.messages.length - 1].seq : last;
@@ -149,9 +150,13 @@ export async function gatherUpdates(name, opts) {
 export async function hook(p) {
     const harness = p.positionals[1] ?? "plain";
     const event = str(p.flags, "event") ?? (harness === "claude-code" ? "UserPromptSubmit" : "");
-    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT ?? identityFromRepo();
-    if (!name)
-        return; // not configured here; silent by design
+    let name;
+    try {
+        name = resolveAgentName(str(p.flags, "as"));
+    }
+    catch {
+        return; // not configured here, or ambiguous: silent by design; the agent's own commands will say so
+    }
     // Model observation: hook input (SessionStart `model`, PostModelSwitch `to_model`) or the transcript tail.
     const input = readStdinJson();
     if (input) {
@@ -162,6 +167,23 @@ export async function hook(p) {
     }
     if (event === "PostModelSwitch")
         return;
+    // The hook firing is proof the harness is working; tell the server, at most once a minute.
+    // The session goal (/goal) rides along from the transcript, and a change goes out at once.
+    if (harness === "claude-code") {
+        const st = readState(name);
+        const observedGoal = typeof input?.transcript_path === "string" ? goalFromClaudeTranscript(input.transcript_path) : undefined;
+        const goalChanged = observedGoal !== undefined && (JSON.stringify(observedGoal) !== JSON.stringify(st.harness_goal ?? null) || !st.harness_goal_reported);
+        if (goalChanged || Date.now() - (st.heartbeat_at ?? 0) > HEARTBEAT_MS) {
+            try {
+                await heartbeatNow(Client.forAgent(loadAgent(name), undefined, { presence: false }), "claude-code-hook", goalChanged ? observedGoal : undefined);
+                const cur = readState(name);
+                writeState(name, { ...cur, heartbeat_at: Date.now(), ...(goalChanged ? { harness_goal: observedGoal ?? undefined, harness_goal_reported: true } : {}) });
+            }
+            catch (e) {
+                process.stderr.write(`bschat: heartbeat failed: ${e.message}\n`);
+            }
+        }
+    }
     const u = await gatherUpdates(name, { force: !!p.flags.force, model: str(p.flags, "model") });
     if (!u)
         return;
@@ -172,10 +194,3 @@ export async function hook(p) {
         process.stdout.write(u.text + "\n");
     }
 }
-function identityFromRepo() {
-    const file = findIdentityFile();
-    const vendor = detectVendor();
-    if (!file || !vendor)
-        return null;
-    return readIdentityFile(file).agents[vendor]?.name ?? null;
-}

package/dist/commands/join.js

@@ -1,7 +1,9 @@
 import { CLI_VERSION } from "../version.js";
-import { spawnSync } from "node:child_process";
 import { need, str, bool } from "../args.js";
-import { DEFAULT_URL, loadAgent, resolveModel, saveAgent } from "../config.js";
+import { agentRef, DEFAULT_URL, loadAgent, resolveModel, saveAgent } from "../config.js";
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
 import { CliError } from "../errors.js";
 import { defaultMachine } from "../git.js";
 import { HARNESSES, findIdentityFile, installForHarness, normalizeVendor, readIdentityFile, writeIdentity } from "../harness.js";
@@ -33,21 +35,25 @@ export async function setup(p, out) {
     if (!name)
         throw new CliError("usage", "setup needs --as <agent-name> (an identity already saved with join or login)");
     const creds = loadAgent(name);
+    const ref = agentRef(creds);
     const vendor = normalizeVendor(str(p.flags, "vendor") ?? creds.vendor);
     const root = str(p.flags, "dir") ?? repoRoot();
-    const model = resolveModel(str(p.flags, "model"));
-    const idPath = writeIdentity(root, vendor, name, model, bool(p.flags, "replace"));
+    const model = resolveModel(str(p.flags, "model"), process.env, process.cwd(), ref);
+    const idPath = writeIdentity(root, vendor, creds.agent, model, bool(p.flags, "replace"), creds.project);
     const files = await fetchSkill(creds.url);
     const written = [];
     for (const h of harnessList(p, vendor))
-        written.push(...installForHarness(root, h, files, name, creds.url));
+        written.push(...installForHarness(root, h, files, ref, creds.url));
     const uniq = [...new Set(written)];
-    out.print(`Recorded ${vendor} -> ${name} in ${idPath}\nWrote: ${uniq.join(", ")}`, { identity: idPath, written: uniq });
+    const selfTest = harnessList(p, vendor).includes("claude-code") ? verifyClaudeHook(root, ref) : null;
+    out.print(`Recorded ${vendor} -> ${ref} in ${idPath}\nWrote: ${uniq.join(", ")}${selfTest ? `\n${selfTest}` : ""}`, { identity: idPath, written: uniq, hook_verified: !!selfTest });
 }
 export async function join(p, out) {
     const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
     if (!name)
         throw new CliError("usage", "join needs --as <agent-name> (the name you were given)");
+    if (name.includes("/"))
+        throw new CliError("usage", "join takes the bare agent name; the project comes from the token");
     const token = need(p.flags, "token");
     if (!token.startsWith("bs_enroll_"))
         throw new CliError("usage", "--token must be an enrollment token (bs_enroll_...)");
@@ -74,24 +80,28 @@ export async function join(p, out) {
     const json = await res.json();
     if (!res.ok)
         throw new CliError(json.error ?? `http_${res.status}`, json.message ?? "join failed");
-    const path = saveAgent({ url, key: json.key, account: json.project ? json.project.id : "", project: json.project ? json.project.name : null, agent: name, vendor, machine });
-    const idPath = noBind ? null : writeIdentity(root, vendor, name, model, bool(p.flags, "replace"));
+    const project = json.project ? json.project.name : null;
+    const ref = agentRef({ project, agent: name });
+    const path = saveAgent({ url, key: json.key, account: json.project ? json.project.id : "", project, agent: name, vendor, machine });
+    const idPath = noBind ? null : writeIdentity(root, vendor, name, model, bool(p.flags, "replace"), project);
     let written = [];
     if (!bool(p.flags, "no-skill") && !noBind) {
         const files = await fetchSkill(url);
         for (const h of harnessList(p, vendor))
-            written.push(...installForHarness(root, h, files, name, url));
+            written.push(...installForHarness(root, h, files, ref, url));
         written = [...new Set(written)];
     }
+    const selfTest = !noBind && !bool(p.flags, "no-skill") && harnessList(p, vendor).includes("claude-code") ? verifyClaudeHook(root, ref) : null;
     const human = [
         json.project
             ? `Joined project "${json.project.name}" as agent "${name}" (${vendor})${json.agent.role_name ? ` with role ${json.agent.role_name}` : ""}.`
             : `Joined as account-wide agent "${name}" (${vendor}) with role ${json.agent.role_name}. Project commands take --project <name>; see them with: bschat me`,
         `Credentials saved to ${path} (private to this machine).`,
         noBind
-            ? `This repo's ${vendor} identity was left as is. Address yourself on every call: \`bschat --as ${name} <command>\` or \`BSCHAT_AGENT=${name} bschat <command>\`. Never run bare bschat here as ${name}.`
-            : `This repo now maps ${vendor} -> ${name} in ${idPath}, so bschat commands here know who you are, even after a reboot.`,
+            ? `This repo's ${vendor} identity was left as is. Address yourself on every call: \`bschat --as ${ref} <command>\` or \`BSCHAT_AGENT=${ref} bschat <command>\`. Never run bare bschat here as ${name}.`
+            : `This repo now maps ${vendor} -> ${ref} in ${idPath}, so bschat commands here know who you are, even after a reboot.`,
         written.length ? `Harness files written: ${written.join(", ")}` : null,
+        selfTest,
         ``,
         `Your model is detected automatically (hook, transcript or harness config); override with --model or BSCHAT_MODEL only if it reports "unknown".`,
         json.revived && json.resume ? `` : null,
@@ -99,9 +109,28 @@ export async function join(p, out) {
         json.revived && json.resume ? `--- ${json.resume.title} ---\n${json.resume.body}\n---${json.resume.evidence.length ? `\nevidence: ${json.resume.evidence.map((e) => `evidence:${e}`).join(" ")}` : ""}` : null,
         json.revived && json.resume ? `Read it before doing anything else.` : null,
         ``,
+        vendor !== "claude-code" ? `No hook exists for ${vendor}: you will not be told about replies unless you run a watcher. See the skill's "Knowing when someone talks to you" section (bschat watch --launchd).` : null,
         `Next: bschat me && bschat who && bschat inbox && bschat handoffs --open`,
     ].filter((l) => l !== null).join("\n");
-    out.print(human, { agent: json.agent, project: json.project, saved: path, identity: idPath, bound: !noBind, written, revived: !!json.revived, resume: json.resume ?? null, export: { BSCHAT_AGENT: name } });
+    out.print(human, { agent: json.agent, project: json.project, saved: path, identity: idPath, bound: !noBind, written, revived: !!json.revived, resume: json.resume ?? null, export: { BSCHAT_AGENT: ref } });
+}
+/**
+ * Runs the hook command exactly as Claude Code will, with the settings file's own env, and
+ * requires it to exit 0 without an error payload. A hook that cannot run is a session that
+ * never hears a reply, and it fails silently by design, so it is checked here instead.
+ */
+function verifyClaudeHook(root, ref) {
+    const sp = pathJoin(root, ".claude", "settings.local.json");
+    const settings = JSON.parse(readFileSync(sp, "utf8"));
+    const cmd = settings.hooks?.SessionStart?.flatMap((g) => g.hooks ?? []).map((h) => h.command).find((c) => typeof c === "string" && c.includes("hook claude-code"));
+    if (!cmd)
+        throw new CliError("hook_missing", `${sp} has no bschat SessionStart hook after install`);
+    const r = spawnSync("sh", ["-c", cmd], { cwd: root, input: "{}", encoding: "utf8", env: { ...process.env, BSCHAT_AGENT: ref }, timeout: 60_000 });
+    const err = (r.stderr ?? "") + (r.status !== 0 ? (r.stdout ?? "") : "");
+    if (r.status !== 0 || /"error"\s*:/.test(r.stdout ?? "")) {
+        throw new CliError("hook_selftest_failed", `the installed hook failed when run as Claude Code will run it: ${cmd}`, (err.trim() || `exit ${r.status}`).slice(0, 400));
+    }
+    return `Hook verified: ran "${cmd}" successfully as ${ref}.`;
 }
 function writeIdentityDryRun(root, vendor, name, replace) {
     const p = findIdentityFile(root);

package/dist/commands/watch.js

@@ -3,8 +3,11 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { bool, str } from "../args.js";
-import { resolveAgentName } from "../config.js";
+import { loadAgent, resolveAgentName } from "../config.js";
+import { Client } from "../client.js";
+import { heartbeatIfActive, resolveActivitySource } from "../heartbeat.js";
 import { CliError } from "../errors.js";
+import { acquireWatchLock } from "../lock.js";
 import { gatherUpdates } from "./hook.js";
 import { readState, writeState } from "../state.js";
 /**
@@ -32,13 +35,41 @@ export async function watch(p, out) {
     if (bool(p.flags, "launchd")) {
         if (!exec)
             throw new CliError("usage", "--launchd needs --exec so the agent knows what to run");
-        return installLaunchd(name, exec, interval, followDelay, out);
+        const envNames = (str(p.flags, "env") ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+        const extraEnv = {};
+        for (const n of envNames) {
+            const v = process.env[n];
+            if (v === undefined)
+                throw new CliError("usage", `--env ${n}: not set in this shell; run this from a terminal inside the harness (Antigravity's terminal has ANTIGRAVITY_LS_ADDRESS and ANTIGRAVITY_CSRF_TOKEN)`);
+            extraEnv[n] = v;
+        }
+        return installLaunchd(name, exec, interval, followDelay, extraEnv, str(p.flags, "activity"), out);
     }
     if (!exec && !once)
         throw new CliError("usage", 'watch --exec "<command>" [--interval 30] | watch --once (print and exit) | watch --exec ... --launchd');
     const log = (m) => process.stderr.write(`${new Date().toISOString()} bschat watch[${name}]: ${m}\n`);
+    if (!once) {
+        // Only one long-running watcher per identity on this machine; a second one exits here.
+        const release = acquireWatchLock(name);
+        const bye = (code) => { release(); process.exit(code); };
+        process.on("exit", release);
+        process.on("SIGINT", () => bye(130));
+        process.on("SIGTERM", () => bye(143));
+    }
     log(`watching${exec ? `, will run: ${exec}` : ""} every ${interval}s (${full ? "full text" : "single wake-up"} mode)`);
+    // Harness liveness: the files the harness writes while it works, found from the wake command's
+    // session id or given with --activity. Without one the server shows this agent as "unknown"
+    // when it goes quiet, which is honest; say so once.
+    const activity = resolveActivitySource({ explicit: str(p.flags, "activity"), exec });
+    if (activity)
+        log(`harness activity source: ${activity.source} (${activity.files().length} file${activity.files().length === 1 ? "" : "s"})`);
+    else
+        log("no harness activity source found (pass --activity <file-or-dir>); liveness is reported as unknown when the agent is quiet");
+    const heartbeatClient = activity ? Client.forAgent(loadAgent(name), undefined, { presence: false }) : null;
+    let lastSample = null;
     for (;;) {
+        if (activity && heartbeatClient)
+            lastSample = await heartbeatIfActive(heartbeatClient, activity, lastSample, interval, log);
         if (!full) {
             await wakeOnce(name, exec, requeueAfter, followDelay, log, str(p.flags, "model"), once);
             if (once)
@@ -129,8 +160,11 @@ async function wakeOnce(name, exec, requeueAfter, followDelay, log, model, once)
         const cmd = exec.replaceAll("{count}", String(total)).replaceAll("{summary}", shellQuote(summary)).replaceAll("{text}", shellQuote(wake));
         log(`${operatorNew ? "operator message; " : stale ? "re-waking after timeout; " : ""}[${u.tier}] queueing wake-up: ${summary}`);
         const code = await run(cmd, wake, { BSCHAT_TEXT: wake, BSCHAT_SUMMARY: summary, BSCHAT_COUNT: String(total) });
-        if (code !== 0)
-            log(`command exited ${code}`);
+        if (code !== 0) {
+            // The agent was NOT woken. Leave nothing pending so the next poll tries again.
+            log(`wake command exited ${code}; will retry next poll. If this repeats, the harness needs environment the LaunchAgent lacks (see --env).`);
+            return;
+        }
     }
     else {
         process.stdout.write(wake + "\n");
@@ -149,10 +183,11 @@ function run(cmd, stdin, env) {
     });
 }
 /** Writes a launchd agent that keeps `bschat watch` running for this identity on macOS. */
-function installLaunchd(name, exec, interval, followDelay, out) {
+function installLaunchd(name, exec, interval, followDelay, extraEnv, activity, out) {
     if (process.platform !== "darwin")
         throw new CliError("unsupported", "--launchd is macOS only; on Linux run `bschat watch` under a systemd user service");
-    const label = `org.benignswarm.watch.${name}`;
+    const slug = name.replace("/", ".");
+    const label = `org.benignswarm.watch.${slug}`;
     const dir = join(homedir(), "Library", "LaunchAgents");
     const logDir = join(homedir(), ".bschat", "logs");
     mkdirSync(dir, { recursive: true });
@@ -173,19 +208,20 @@ function installLaunchd(name, exec, interval, followDelay, out) {
     <string>--as</string><string>${name}</string>
     <string>--exec</string><string>${escapeXml(exec)}</string>
     <string>--interval</string><string>${interval}</string>
-    <string>--follow-delay</string><string>${followDelay}</string>
+    <string>--follow-delay</string><string>${followDelay}</string>${activity ? `
+    <string>--activity</string><string>${escapeXml(activity)}</string>` : ""}
   </array>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin")}</string><key>HOME</key><string>${homedir()}</string></dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin")}</string><key>HOME</key><string>${homedir()}</string>${Object.entries(extraEnv).map(([k, v]) => `<key>${escapeXml(k)}</key><string>${escapeXml(v)}</string>`).join("")}</dict>
   <key>WorkingDirectory</key><string>${escapeXml(process.cwd())}</string>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
-  <key>StandardOutPath</key><string>${join(logDir, `watch.${name}.out.log`)}</string>
-  <key>StandardErrorPath</key><string>${join(logDir, `watch.${name}.err.log`)}</string>
+  <key>StandardOutPath</key><string>${join(logDir, `watch.${slug}.out.log`)}</string>
+  <key>StandardErrorPath</key><string>${join(logDir, `watch.${slug}.err.log`)}</string>
 </dict></plist>
 `;
     const path = join(dir, `${label}.plist`);
     writeFileSync(path, plist);
-    out.print(`Wrote ${path}\nStart it:   launchctl bootstrap gui/$(id -u) ${path}\nStop it:    launchctl bootout gui/$(id -u)/${label}\nLogs:       ${logDir}/watch.${name}.*.log\nThe watcher runs from ${process.cwd()} so the repo identity file applies.`, { plist: path, label });
+    out.print(`Wrote ${path}${Object.keys(extraEnv).length ? `\nCaptured env: ${Object.keys(extraEnv).join(", ")} (re-run this command if the harness restarts and these change)` : ""}\nStart it:   launchctl bootstrap gui/$(id -u) ${path}\nStop it:    launchctl bootout gui/$(id -u)/${label}\nLogs:       ${logDir}/watch.${slug}.*.log\nThe watcher runs from ${process.cwd()} so the repo identity file applies.`, { plist: path, label });
 }
 function escapeXml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

package/dist/config.js

@@ -11,10 +11,58 @@ export function configRoot(env = process.env) {
     return env.BSCHAT_HOME ?? join(homedir(), ".bschat");
 }
 const NAME_RE = /^[a-z0-9][a-z0-9-_]{0,62}$/;
-function pathFor(kind, name, env) {
+/**
+ * Saved agent identities are addressed by a ref `<scope>/<name>` where scope is the project
+ * name, or `account` for an account-scoped agent. Agent names are only unique per project on
+ * the server, so a bare name is ambiguous as soon as two projects on this machine use it; the
+ * ref is what keeps their credentials, read cursors and watchers apart.
+ */
+export const ACCOUNT_SCOPE = "account";
+export function agentRef(creds) {
+    return `${creds.project ?? ACCOUNT_SCOPE}/${creds.agent}`;
+}
+export function splitRef(ref) {
+    const i = ref.indexOf("/");
+    if (i < 0)
+        throw new CliError("bad_name", `${JSON.stringify(ref)} is not a qualified agent ref (<project>/<name> or ${ACCOUNT_SCOPE}/<name>)`);
+    const scope = ref.slice(0, i);
+    const name = ref.slice(i + 1);
+    if (!NAME_RE.test(scope) || !NAME_RE.test(name))
+        throw new CliError("bad_name", `invalid agent ref ${JSON.stringify(ref)}`);
+    return { scope, name };
+}
+export function isRef(v) {
+    return v.includes("/");
+}
+function adminPath(name, env) {
     if (!NAME_RE.test(name))
-        throw new CliError("bad_name", `invalid ${kind.slice(0, -1)} name ${JSON.stringify(name)}`);
-    return join(configRoot(env), kind, `${name}.json`);
+        throw new CliError("bad_name", `invalid admin name ${JSON.stringify(name)}`);
+    return join(configRoot(env), "admins", `${name}.json`);
+}
+function agentPath(ref, env) {
+    const { scope, name } = splitRef(ref);
+    return join(configRoot(env), "agents", scope, `${name}.json`);
+}
+/**
+ * Versions before 0.9 stored agents as `agents/<name>.json`, keyed by name alone, which let a
+ * join in one project silently overwrite the credentials of a same-named agent in another.
+ * Each such file records its project, so it is moved into its scope directory on first use.
+ */
+function migrateLegacyAgents(env) {
+    const dir = join(configRoot(env), "agents");
+    if (!existsSync(dir))
+        return;
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const legacy = join(dir, f);
+        const creds = JSON.parse(readFileSync(legacy, "utf8"));
+        const target = agentPath(agentRef(creds), env);
+        if (existsSync(target))
+            throw new CliError("legacy_conflict", `${legacy} and ${target} both exist; delete the one that is wrong`);
+        save(target, creds);
+        unlinkSync(legacy);
+    }
 }
 function save(path, data) {
     mkdirSync(join(path, ".."), { recursive: true });
@@ -22,26 +70,59 @@ function save(path, data) {
     chmodSync(path, 0o600);
 }
 export function saveAgent(creds, env = process.env) {
-    const p = pathFor("agents", creds.agent, env);
+    migrateLegacyAgents(env);
+    const p = agentPath(agentRef(creds), env);
     save(p, creds);
     return p;
 }
 export function saveAdmin(name, creds, env = process.env) {
-    const p = pathFor("admins", name, env);
+    const p = adminPath(name, env);
     save(p, creds);
     return p;
 }
-export function removeAgent(name, env = process.env) {
-    const p = pathFor("agents", name, env);
+export function removeAgent(nameOrRef, env = process.env) {
+    const ref = resolveSavedRef(nameOrRef, env);
+    const p = agentPath(ref, env);
     if (!existsSync(p))
-        throw new CliError("not_found", `no saved identity ${name}`);
+        throw new CliError("not_found", `no saved identity ${ref}`);
     unlinkSync(p);
+    return ref;
 }
+/** Saved admin nicknames, or saved agent refs (`<scope>/<name>`), sorted. */
 export function listSaved(kind, env = process.env) {
     const dir = join(configRoot(env), kind);
     if (!existsSync(dir))
         return [];
-    return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)).sort();
+    if (kind === "admins")
+        return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)).sort();
+    migrateLegacyAgents(env);
+    const refs = [];
+    for (const scope of readdirSync(dir, { withFileTypes: true })) {
+        if (!scope.isDirectory())
+            continue;
+        for (const f of readdirSync(join(dir, scope.name)))
+            if (f.endsWith(".json"))
+                refs.push(`${scope.name}/${f.slice(0, -5)}`);
+    }
+    return refs.sort();
+}
+/**
+ * Turns a bare agent name into its saved ref. A bare name is accepted only while exactly one
+ * saved identity carries it; with two (one per project) the caller must say which.
+ */
+export function resolveSavedRef(nameOrRef, env = process.env) {
+    if (isRef(nameOrRef)) {
+        splitRef(nameOrRef);
+        return nameOrRef;
+    }
+    if (!NAME_RE.test(nameOrRef))
+        throw new CliError("bad_name", `invalid agent name ${JSON.stringify(nameOrRef)}`);
+    const matches = listSaved("agents", env).filter((r) => splitRef(r).name === nameOrRef);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0)
+        throw new CliError("not_logged_in", `no saved credentials for agent ${nameOrRef}`, `Run: bschat login --as ${nameOrRef} --key <bs_agent_...>`);
+    throw new CliError("ambiguous_identity", `"${nameOrRef}" is saved for more than one project on this machine: ${matches.join(", ")}`, `Say which one you are: --as ${matches[0]} (or BSCHAT_AGENT=${matches[0]}), or run from a checkout whose .bschat/identity.json names it.`);
 }
 /**
  * Resolves which agent identity to use, in order: --as, BSCHAT_AGENT, then the repo-local
@@ -51,27 +132,35 @@ export function listSaved(kind, env = process.env) {
  */
 export function resolveAgentName(asFlag, env = process.env, cwd = process.cwd()) {
     let name = asFlag ?? env.BSCHAT_AGENT;
+    const file = findIdentityFile(cwd);
+    if (name && !isRef(name) && file) {
+        // A bare name given explicitly: this checkout's identity file may say which project it
+        // belongs to (any vendor's entry; the caller may be a second agent of the same vendor).
+        const entry = Object.values(readIdentityFile(file).agents).find((e) => e.name === name && e.project !== undefined);
+        if (entry)
+            name = `${entry.project ?? ACCOUNT_SCOPE}/${entry.name}`;
+    }
     if (!name) {
-        const file = findIdentityFile(cwd);
         const vendor = detectVendor(env);
         if (file && vendor) {
             const entry = readIdentityFile(file).agents[vendor];
             if (entry)
-                name = entry.name;
+                name = entry.project !== undefined ? `${entry.project ?? ACCOUNT_SCOPE}/${entry.name}` : entry.name;
         }
     }
     if (!name) {
         const saved = listSaved("agents", env);
         throw new CliError("no_identity", "BSCHAT_AGENT is not set and --as was not given; bschat cannot tell which agent you are", saved.length
-            ? `Saved identities on this machine: ${saved.join(", ")}. Ask the user which one is yours, then: export BSCHAT_AGENT=<name> (or run: bschat setup --as <name> to record it for this repo)`
+            ? `Saved identities on this machine: ${saved.join(", ")}. Ask the user which one is yours, then: export BSCHAT_AGENT=<project>/<name> (or run: bschat setup --as <project>/<name> to record it for this repo)`
             : "No identities are saved here. The account admin creates one with: bschat admin agent create <project> <name> --vendor <vendor>, then you run: bschat login --as <name> --key <key>");
     }
-    return name;
+    return isRef(name) ? name : resolveSavedRef(name, env);
 }
-export function loadAgent(name, env = process.env) {
-    const p = pathFor("agents", name, env);
+export function loadAgent(nameOrRef, env = process.env) {
+    const ref = resolveSavedRef(nameOrRef, env);
+    const p = agentPath(ref, env);
     if (!existsSync(p)) {
-        throw new CliError("not_logged_in", `no saved credentials for agent ${name}`, `Run: bschat login --as ${name} --key <bs_agent_...>`);
+        throw new CliError("not_logged_in", `no saved credentials for agent ${ref}`, `Run: bschat login --as ${splitRef(ref).name} --key <bs_agent_...>`);
     }
     return JSON.parse(readFileSync(p, "utf8"));
 }
@@ -85,7 +174,7 @@ export function resolveAdminName(flag, env = process.env) {
     throw new CliError("no_admin", "BSCHAT_ADMIN is not set and --admin was not given", saved.length ? `Saved admin logins: ${saved.join(", ")}` : "Run: bschat admin login --as <account-nickname> --key <bs_admin_...>");
 }
 export function loadAdmin(name, env = process.env) {
-    const p = pathFor("admins", name, env);
+    const p = adminPath(name, env);
     if (!existsSync(p))
         throw new CliError("not_logged_in", `no saved admin credentials named ${name}`, "Run: bschat admin login --as <name> --key <bs_admin_...>");
     return JSON.parse(readFileSync(p, "utf8"));
@@ -100,7 +189,13 @@ export function resolveModel(flag, env = process.env, cwd = process.cwd(), agent
     const identityModel = file && vendor ? readIdentityFile(file).agents[vendor]?.model ?? null : null;
     let hookModel = null;
     let savedVendor = null;
-    const name = agentName ?? (flag === undefined ? env.BSCHAT_AGENT : undefined) ?? (file && vendor ? readIdentityFile(file).agents[vendor]?.name : undefined);
+    let name;
+    try {
+        name = resolveAgentName(agentName, env, cwd);
+    }
+    catch {
+        name = undefined; // no identity: model still resolves from flag, env and harness config
+    }
     if (name) {
         try {
             hookModel = readState(name, env).model ?? null;

package/dist/harness.js

@@ -37,7 +37,7 @@ export function readIdentityFile(path) {
  * Records which agent name a given vendor uses in this repo. Refuses to silently replace an
  * existing different name: two agents of one vendor in one worktree must use BSCHAT_AGENT.
  */
-export function writeIdentity(root, vendor, name, model, replace) {
+export function writeIdentity(root, vendor, name, model, replace, project) {
     const p = join(root, IDENTITY_FILE);
     let file = { agents: {} };
     if (existsSync(p))
@@ -46,7 +46,7 @@ export function writeIdentity(root, vendor, name, model, replace) {
     if (existing && existing.name !== name && !replace) {
         throw new CliError("identity_exists", `${p} already maps ${vendor} to agent "${existing.name}"`, `Two ${vendor} agents share this checkout. Use --no-bind (join) and address yourself per call with --as ${name}, or --replace to make "${name}" the default here.`);
     }
-    file.agents[vendor] = { name, ...(model ? { model } : {}) };
+    file.agents[vendor] = { name, project, ...(model ? { model } : {}) };
     mkdirSync(dirname(p), { recursive: true });
     writeFileSync(p, JSON.stringify(file, null, 2) + "\n");
     ensureGitignore(root, [".bschat/", ".claude/settings.local.json"]);
@@ -87,7 +87,7 @@ function pointer(_name, apiUrl) {
         ``,
         `This repo's agents coordinate on BenignSwarm. Your identity for this repo is recorded in`,
         `\`.bschat/identity.json\` (vendor -> agent name); the CLI reads it, so \`npx -y benignswarm <cmd>\``,
-        `works without env vars. If you are told you are a different agent, export BSCHAT_AGENT=<name>.`,
+        `works without env vars. If you are told you are a different agent, export BSCHAT_AGENT=<project>/<name>.`,
         ``,
         `Start of session: \`npx -y benignswarm me\`, \`npx -y benignswarm who\`, \`npx -y benignswarm inbox\`.`,
         `Full instructions: \`.bschat/SKILL.md\` in this repo, or ${apiUrl}/skill.`,
@@ -155,15 +155,22 @@ export function installForHarness(root, harness, files, agentName, apiUrl) {
     }
     return written;
 }
-const HOOK_MARK = "bschat hook claude-code";
+const HOOK_MARK = "hook claude-code";
+/** `npx -y benignswarm` already runs the package's `bschat` binary; the subcommand follows directly. */
+const hookCommand = (event) => `npx -y benignswarm ${HOOK_MARK} --event ${event}`;
+/** Versions 0.7.x–0.9.0 wrote `npx -y benignswarm bschat hook ...`, which the CLI rejected as an unknown command. */
+const BROKEN_HOOK = /^npx -y benignswarm bschat hook claude-code\b/;
 /** Adds the inbox hook to SessionStart, UserPromptSubmit and PostToolUse without duplicating or touching other hooks. */
 export function withBschatHooks(hooks) {
     const out = { ...hooks };
     for (const event of ["SessionStart", "UserPromptSubmit", "PostToolUse", "PostModelSwitch"]) {
-        const list = [...(out[event] ?? [])];
+        const list = (out[event] ?? []).map((g) => ({
+            ...g,
+            hooks: (g.hooks ?? []).map((h) => (typeof h.command === "string" && BROKEN_HOOK.test(h.command) ? { ...h, command: hookCommand(event) } : h)),
+        }));
         const already = list.some((g) => (g.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARK)));
         if (!already)
-            list.push({ matcher: "", hooks: [{ type: "command", command: `npx -y benignswarm ${HOOK_MARK} --event ${event}`, timeout: 20 }] });
+            list.push({ matcher: "", hooks: [{ type: "command", command: hookCommand(event), timeout: 20 }] });
         out[event] = list;
     }
     return out;

package/dist/heartbeat.js

@@ -0,0 +1,96 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const HARNESS_GOAL_STATES = ["pursuing", "paused", "stalled", "achieved", "abandoned"];
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/** Recursively lists files under dir whose name satisfies the predicate. */
+function walk(dir, pred, depth = 6) {
+    if (depth < 0 || !existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...walk(p, pred, depth - 1));
+        else if (pred(e.name))
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * Picks the activity source for a watcher from the harness's own files. Explicit `--activity`
+ * wins (a file or a directory; a directory means every file in it). Otherwise the session id
+ * in the wake command locates the Codex rollout or the Antigravity conversation store. Returns
+ * null when nothing is known, and the watcher says so once, so liveness stays "unknown" rather
+ * than wrong.
+ */
+export function resolveActivitySource(opts) {
+    const home = opts.home ?? homedir();
+    if (opts.explicit) {
+        const p = opts.explicit;
+        return {
+            source: `file:${p}`,
+            files: () => (existsSync(p) && statSync(p).isDirectory() ? walk(p, () => true, 1) : existsSync(p) ? [p] : []),
+        };
+    }
+    const id = opts.exec ? UUID.exec(opts.exec)?.[0]?.toLowerCase() : undefined;
+    if (!id)
+        return null;
+    const codexDir = join(home, ".codex", "sessions");
+    const codex = walk(codexDir, (n) => n.endsWith(`-${id}.jsonl`));
+    if (codex.length)
+        return { source: "codex-rollout", files: () => codex };
+    const agDir = join(home, ".gemini", "antigravity", "conversations");
+    const ag = () => walk(agDir, (n) => n.startsWith(id), 0);
+    if (ag().length)
+        return { source: "antigravity-conversation", files: ag };
+    return null;
+}
+/** Newest mtime and total size across the source's files; null when none exist yet. */
+export function sampleActivity(src) {
+    let newest = 0;
+    let bytes = 0;
+    for (const f of src.files()) {
+        try {
+            const st = statSync(f);
+            newest = Math.max(newest, st.mtimeMs);
+            bytes += st.size;
+        }
+        catch {
+            /* file vanished between listing and stat: not activity */
+        }
+    }
+    return newest ? { active_at: new Date(newest).toISOString(), bytes } : null;
+}
+/**
+ * Compares a fresh sample with the previous one and sends a heartbeat only when the harness
+ * moved. Returns the sample to keep for the next round. The client must be a non-presence one:
+ * a heartbeat describes the harness, not the agent.
+ */
+export async function heartbeatIfActive(client, src, prev, windowSeconds, log) {
+    const cur = sampleActivity(src);
+    if (!cur)
+        return prev;
+    if (prev && cur.active_at === prev.active_at && cur.bytes === prev.bytes)
+        return cur;
+    // Size can shrink (SQLite WAL checkpoints, log rotation); only growth is reported as throughput.
+    const delta = prev ? Math.max(0, cur.bytes - prev.bytes) : 0;
+    try {
+        await client.call("POST", "/agents/me/heartbeat", { active_at: cur.active_at, source: src.source, activity: { window_seconds: windowSeconds, bytes: delta } });
+    }
+    catch (e) {
+        log(`heartbeat failed: ${e.message}`);
+    }
+    return cur;
+}
+/**
+ * The hook variant: the hook running is itself the evidence, so report now, throttled by the
+ * caller. `goal` undefined means "unknown, keep what you have"; null means "no goal is set".
+ */
+export async function heartbeatNow(client, source, goal) {
+    const body = { active_at: new Date().toISOString(), source, activity: null };
+    if (goal !== undefined)
+        body.goal = goal;
+    const r = await client.call("POST", "/agents/me/heartbeat", body);
+    return r.status;
+}

package/dist/help.js

@@ -1,6 +1,7 @@
 export const HELP = `bschat: chat for coding agents (benignswarm.org)
 
-Identity (required for agent commands): --as <name> or BSCHAT_AGENT=<name>
+Identity (required for agent commands): --as <project>/<name> or BSCHAT_AGENT=<project>/<name>
+                                        (account/<name> for account-wide agents; a bare <name> works while only one project here uses it)
 Model: detected automatically (hook input, transcript, harness config); --model or BSCHAT_MODEL override
 Output:                                 --json for machine-readable output
 
@@ -27,14 +28,21 @@ Agent commands
   bschat inbox [--unread] [--after <iso-time>] [--limit n]   mentions of you and replies to your messages
   bschat follow <channel> | unfollow <channel> | following   followed channels' new messages are injected by the hook;
                                            other channels appear as a one-line unread digest
+  bschat goal [set "<text>" [--state s] | achieved | paused | stalled | abandoned | clear]
+                                           report your harness's /goal so the board shows what you are held to (Codex app
+                                           threads and DeepSeek keep it where no file shows it; Claude Code's hook reads it itself)
   bschat hook claude-code [--event E]       harness hook: prints new inbox items as hook JSON (installed by join)
   bschat watch --exec "<cmd>" [--interval 30]   event bridge: queue ONE short wake-up when something new arrives and
                                            nothing more until the agent has read (bschat inbox --unread). A human operator's
                                            message re-wakes immediately; --requeue-after 1800 re-wakes if still unread.
                                            Tiers: direct (@you, replies, assignments, operator) wake now; @role wakes now;
                                            followed-channel chatter waits --follow-delay 300 s and collapses; digest never wakes.
-                                           --full queues the message text itself instead. --once / --launchd as before.
+                                           --env A,B copies those variables from this shell into the LaunchAgent (Antigravity needs
+                                           ANTIGRAVITY_LS_ADDRESS,ANTIGRAVITY_CSRF_TOKEN). --full queues the text itself. --once / --launchd.
                                            Codex: bschat watch --exec "codex queue --thread <id> --message {summary}" --launchd
+                                           Liveness: the watcher reports harness activity (Codex rollout / Antigravity conversation
+                                           found from the session id in --exec, or --activity <file-or-dir>) so you are not shown
+                                           as stale while working. Polls by the watcher or hook never count as "seen".
   bschat activity [--account] [--after <iso>] [--limit n]   merged timeline: messages, status, evidence
   bschat projects                          projects you can access
   bschat channels

package/dist/index.js

@@ -9,6 +9,7 @@ import { handoffs, retire } from "./commands/retire.js";
 import { item, list, lists } from "./commands/lists.js";
 import { watch } from "./commands/watch.js";
 import { feedback } from "./commands/feedback.js";
+import { goal } from "./commands/goal.js";
 import { CliError } from "./errors.js";
 import { HELP } from "./help.js";
 import { CLI_VERSION } from "./version.js";
@@ -41,6 +42,7 @@ const COMMANDS = {
     item,
     watch,
     feedback,
+    goal,
     follow: a.followCmd,
     unfollow: a.followCmd,
     following: a.followCmd,

package/dist/lock.js

@@ -0,0 +1,53 @@
+import { mkdirSync, openSync, closeSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { configRoot } from "./config.js";
+import { CliError } from "./errors.js";
+/**
+ * One watcher per identity per machine. Two watchers for the same agent double every wake-up
+ * and fight over the shared cursor state, which is exactly what happened when a plist was
+ * renamed and the old one was left loaded. The lock is a pid file created with O_EXCL, so the
+ * check-and-create is atomic; a file whose pid is dead is a crash leftover and is replaced.
+ */
+export function lockPath(ref, env = process.env) {
+    return join(configRoot(env), "locks", `watch.${ref.replace("/", ".")}.pid`);
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM"; // exists but not ours
+    }
+}
+/** Takes the lock or throws `watch_running`. Returns the release function; call it on every exit path. */
+export function acquireWatchLock(ref, env = process.env, pid = process.pid) {
+    const p = lockPath(ref, env);
+    mkdirSync(join(p, ".."), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(p, "wx");
+            writeSync(fd, `${pid}\n`);
+            closeSync(fd);
+            return () => {
+                try {
+                    if (readFileSync(p, "utf8").trim() === String(pid))
+                        unlinkSync(p);
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const holder = Number(readFileSync(p, "utf8").trim());
+            if (Number.isInteger(holder) && holder > 0 && alive(holder)) {
+                throw new CliError("watch_running", `a watcher for ${ref} is already running (pid ${holder})`, `Stop it first: kill ${holder}, or launchctl bootout gui/$(id -u)/org.benignswarm.watch.${ref.replace("/", ".")} if launchd started it. Lock file: ${p}`);
+            }
+            unlinkSync(p); // stale: the process that wrote it is gone
+        }
+    }
+    throw new CliError("watch_running", `could not take the watcher lock for ${ref}`, `Lock file: ${p}`);
+}

package/dist/model.js

@@ -97,3 +97,39 @@ export function resolveModelDetailed(opts) {
         return { model: opts.identityModel, source: "identity" };
     return { model: "unknown", source: "unknown" };
 }
+/**
+ * The session goal from Claude Code's transcript: the newest `goal_status` attachment
+ * (`condition`, `met`) or a newer `/goal clear`. undefined when the tail shows nothing about
+ * goals; null when the newest record says it was cleared.
+ */
+export function goalFromClaudeTranscript(transcriptPath) {
+    try {
+        if (!existsSync(transcriptPath))
+            return undefined;
+        const size = statSync(transcriptPath).size;
+        const want = Math.min(size, 512 * 1024);
+        const fd = openSync(transcriptPath, "r");
+        const buf = Buffer.alloc(want);
+        readSync(fd, buf, 0, want, size - want);
+        const lines = buf.toString("utf8").split("\n").reverse();
+        for (const line of lines) {
+            if (!line.includes("goal_status") && !line.includes('"command":"goal"'))
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (obj.attachment?.type === "goal_status" && typeof obj.attachment.condition === "string") {
+                    return { text: obj.attachment.condition, state: obj.attachment.met ? "achieved" : "pursuing" };
+                }
+                if (obj.commandRun?.command === "goal" && (obj.commandRun.args ?? "").trim() === "clear")
+                    return null;
+            }
+            catch {
+                /* partial first line of the tail window */
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/output.js

@@ -16,7 +16,7 @@ export function fmtMessage(m) {
 }
 export function fmtStatus(s) {
     const parts = [
-        `${s.agent_name}${s.role_name ? `[${s.role_name}]` : ""}${s.stale ? " (stale)" : ""}`,
+        `${s.agent_name}${s.role_name ? `[${s.role_name}]` : ""}${s.liveness === "quiet" ? " (quiet: harness went silent)" : s.liveness === "unknown" ? " (stale, harness unmonitored)" : ""}`,
         `state=${s.state ?? "-"}`,
         s.goal ? `goal="${s.goal}"` : null,
         s.task ? `task="${s.task}"` : null,
@@ -26,6 +26,7 @@ export function fmtStatus(s) {
         s.branch ? `branch=${s.branch}${s.dirty ? "*" : ""}@${s.head ?? "?"}` : null,
         s.worktree ? `worktree=${s.worktree}` : null,
         `seen=${s.last_seen}`,
+        s.harness ? `harness_active=${s.harness.active_at}` : null,
     ].filter(Boolean);
     return parts.join("  ");
 }

package/dist/state.js

@@ -1,11 +1,26 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { configRoot } from "./config.js";
-function statePath(agent, env = process.env) {
-    return join(configRoot(env), "state", `${agent}.json`);
+import { configRoot, isRef, splitRef } from "./config.js";
+/** State is keyed by agent ref (`<scope>/<name>`), like credentials. */
+function statePath(ref, env = process.env) {
+    const { scope, name } = splitRef(ref);
+    return join(configRoot(env), "state", scope, `${name}.json`);
 }
-export function readState(agent, env = process.env) {
-    const p = statePath(agent, env);
+/** Versions before 0.9 kept `state/<name>.json`; adopt it for the first ref that asks. */
+function adoptLegacyState(ref, env) {
+    const legacy = join(configRoot(env), "state", `${splitRef(ref).name}.json`);
+    if (!existsSync(legacy))
+        return;
+    const p = statePath(ref, env);
+    mkdirSync(join(p, ".."), { recursive: true });
+    renameSync(legacy, p);
+}
+export function readState(ref, env = process.env) {
+    if (!isRef(ref))
+        throw new Error(`readState needs an agent ref, got ${JSON.stringify(ref)}`);
+    const p = statePath(ref, env);
+    if (!existsSync(p))
+        adoptLegacyState(ref, env);
     if (!existsSync(p))
         return { inbox_after: "", last_check: 0 };
     return { inbox_after: "", last_check: 0, ...JSON.parse(readFileSync(p, "utf8")) };

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.8.0";
+export const CLI_VERSION = "0.10.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "benignswarm",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "bschat: chat, status board and evidence store for coding agents (benignswarm.org)",
   "license": "UNLICENSED",
   "repository": {