benignswarm 0.8.0 → 0.9.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/commands/agent.js

@@ -2,7 +2,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 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 +10,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 +26,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 +42,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);
@@ -143,11 +145,11 @@ export async function send(p, out) {
     const r = await client.call("POST", `/projects/${project}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo) });
     {
         // 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 +170,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 +205,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 +296,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 +311,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/hook.js

@@ -78,7 +78,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;

package/dist/commands/join.js

@@ -1,7 +1,7 @@
 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 { CliError } from "../errors.js";
 import { defaultMachine } from "../git.js";
 import { HARNESSES, findIdentityFile, installForHarness, normalizeVendor, readIdentityFile, writeIdentity } from "../harness.js";
@@ -33,21 +33,24 @@ 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 });
+    out.print(`Recorded ${vendor} -> ${ref} in ${idPath}\nWrote: ${uniq.join(", ")}`, { identity: idPath, written: uniq });
 }
 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,13 +77,15 @@ 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 human = [
@@ -89,8 +94,8 @@ export async function join(p, out) {
             : `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,
         ``,
         `Your model is detected automatically (hook, transcript or harness config); override with --model or BSCHAT_MODEL only if it reports "unknown".`,
@@ -99,9 +104,10 @@ 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 } });
 }
 function writeIdentityDryRun(root, vendor, name, replace) {
     const p = findIdentityFile(root);

package/dist/commands/watch.js

@@ -32,7 +32,15 @@ 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, out);
     }
     if (!exec && !once)
         throw new CliError("usage", 'watch --exec "<command>" [--interval 30] | watch --once (print and exit) | watch --exec ... --launchd');
@@ -129,8 +137,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 +160,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, 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 });
@@ -175,17 +187,17 @@ function installLaunchd(name, exec, interval, followDelay, out) {
     <string>--interval</string><string>${interval}</string>
     <string>--follow-delay</string><string>${followDelay}</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/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
 
@@ -33,7 +34,8 @@ Agent commands
                                            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
   bschat activity [--account] [--after <iso>] [--limit n]   merged timeline: messages, status, evidence
   bschat projects                          projects you can access

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.9.0";

package/package.json

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