benignswarm 0.9.0 → 0.10.0

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,4 +1,5 @@
 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";
@@ -142,7 +143,10 @@ 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(agentRef(creds));

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)
@@ -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 { 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";
@@ -43,7 +45,8 @@ export async function setup(p, out) {
     for (const h of harnessList(p, vendor))
         written.push(...installForHarness(root, h, files, ref, creds.url));
     const uniq = [...new Set(written)];
-    out.print(`Recorded ${vendor} -> ${ref} 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;
@@ -88,6 +91,7 @@ export async function join(p, out) {
             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}` : ""}.`
@@ -97,6 +101,7 @@ export async function join(p, out) {
             ? `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,
@@ -109,6 +114,24 @@ export async function join(p, out) {
     ].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: 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);
     if (!p || !p.startsWith(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";
 /**
@@ -40,13 +43,33 @@ export async function watch(p, out) {
                 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);
+        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)
@@ -160,7 +183,7 @@ 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, extraEnv, 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 slug = name.replace("/", ".");
@@ -185,7 +208,8 @@ function installLaunchd(name, exec, interval, followDelay, extraEnv, 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>${Object.entries(extraEnv).map(([k, v]) => `<key>${escapeXml(k)}</key><string>${escapeXml(v)}</string>`).join("")}</dict>
   <key>WorkingDirectory</key><string>${escapeXml(process.cwd())}</string>

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

@@ -28,6 +28,9 @@ 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
@@ -37,6 +40,9 @@ Agent commands
                                            --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/version.js

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

package/package.json

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