@botbuddy/cli 1.30.2 → 1.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.30.2",
+  "version": "1.31.1",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/agent-cleanup.mjs

@@ -0,0 +1,150 @@
+// BOT-1650 — the durable cleanup marker and the guarded cache clear that pair
+// with the unified agent-state store (agent-state.mjs). Kept in a small module of
+// their own so both the bootstrap bridge and the Codex bridge can share them
+// without re-importing the whole credential resolver.
+import { mkdir, open, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { AGENT_KEY_RE } from "./agent-key.mjs";
+import { agentStatePath, readAgentState, withStateLock, worktreeRoot } from "./agent-state.mjs";
+import { restrictWindowsAcl, restrictWindowsAclDir, sessionPathIsConfidential } from "./agent-state-fs.mjs";
+
+// BOT-1650 (Codex round-32 P2): bind the confidentiality check to the EXACT bytes
+// parsed. A separate stat()+readFile() lets a hostile local writer swap the
+// owner-only marker between the check and the read (the CLI state lock does not
+// coordinate foreign processes). Open ONCE, verify the open handle's mode — on
+// POSIX the fd is pinned to that inode, so a later rename cannot change what we
+// read — then read from the SAME handle. Returns the entries array, or null when
+// the marker is absent, non-confidential, or corrupt. (Windows ACLs are checked by
+// path via icacls, so there the guarantee is the owner-only ACL applied at publish;
+// the handle-bound atomicity is POSIX.)
+async function readConfidentialMarker(file, { platform } = {}) {
+  let handle;
+  try {
+    handle = await open(file, "r");
+  } catch { return null; }
+  try {
+    const { mode } = await handle.stat();
+    if (!(await sessionPathIsConfidential(file, mode, platform ? { platform } : {}))) return null;
+    const parsed = JSON.parse(await handle.readFile("utf8"));
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+// BOT-1650 (Codex round-29 P2): the marker records session ids + generations the
+// next bootstrap TRUSTS and retires with the operator's durable credential, so its
+// integrity matters. Publish it with the same confidentiality as agent-state.json:
+// exclusive 0600 temp, an explicit owner-only Windows ACL (0600 is a no-op for
+// ACLs and the marker lives under an arbitrary worktree), then an atomic rename. A
+// failure surfaces (the temp is unlinked) — a permissive marker is never published.
+async function publishMarker(file, data, { platform = process.platform, restrictAcl = restrictWindowsAcl } = {}) {
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(data)}\n`, { mode: 0o600, flag: "wx" });
+    if (platform === "win32") await restrictAcl(temporary);
+    await rename(temporary, file);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+// BOT-1650 (Codex round-24): a marker for sessions the server admitted but that
+// this harness could not retire (a compound outage failed both the cached close
+// and the new session's retirement). It records only the session id + generation
+// — NOT a bearer — because the durable owner/MCP credential retires a session by
+// id, so the marker is not a secret. A later bootstrap drains it, preventing an
+// orphaned session from lingering and blocking with agent_session_conflict.
+export const AGENT_CLEANUP_STATE = join(".botbuddy", "agent-cleanup.json");
+
+export async function recordPendingCleanup(entry, { cwd = process.cwd(), platform, restrictAcl, restrictAclDir = restrictWindowsAclDir } = {}) {
+  if (!entry?.session_id) return;
+  const file = join(await worktreeRoot(cwd), AGENT_CLEANUP_STATE);
+  const directory = dirname(file);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  // BOT-1650 (Codex round-34 P2): protect the CONTAINING directory on Windows
+  // (owner-only, no inheritance) so no other local account can create or replace
+  // marker entries — the by-path ACL check on the marker is only trustworthy when
+  // the directory itself cannot be swapped. POSIX 0o700 already does this.
+  if ((platform ?? process.platform) === "win32") await restrictAclDir(directory);
+  // BOT-1650 (Codex round-31/32 P2): only merge a PRE-EXISTING marker when it is
+  // still confidential (owner-only), verified against the OPEN handle we read from
+  // (see readConfidentialMarker). A marker another account could substitute in a
+  // shared worktree is discarded, not merged, so its attacker-supplied session ids
+  // are never republished under our owner-only ACL and later retired with the
+  // operator's durable credential.
+  const existing = (await readConfidentialMarker(file, { platform })) ?? [];
+  const record = {
+    session_id: entry.session_id,
+    ...(entry.session_token_generation ? { session_token_generation: entry.session_token_generation } : {}),
+  };
+  const merged = [...existing.filter((e) => e?.session_id !== record.session_id), record];
+  await publishMarker(file, merged, { platform, restrictAcl });
+}
+
+// Retry retiring previously-orphaned sessions. `retire(entry)` returns true when
+// the remote session is confirmed retired; confirmed entries drop from the marker
+// and the marker file is removed once empty.
+export async function drainPendingCleanup({ cwd = process.cwd(), retire, platform, restrictAcl } = {}) {
+  const file = join(await worktreeRoot(cwd), AGENT_CLEANUP_STATE);
+  // BOT-1650 (Codex round-30/32 P2): every entry here is retired with the operator's
+  // durable credential, so a marker another account could substitute must not be
+  // trusted. Verify confidentiality against the OPEN handle we read from (see
+  // readConfidentialMarker) so a forged marker can neither retire the victim's
+  // sessions nor discard pending orphan cleanup — and a swap between check and read
+  // cannot slip past. A null result (absent, non-confidential, or corrupt) keeps the
+  // marker untouched for a later drain.
+  const entries = await readConfidentialMarker(file, { platform });
+  if (entries === null) return;
+  if (entries.length === 0) {
+    await unlink(file).catch(() => {});
+    return;
+  }
+  const remaining = [];
+  for (const entry of entries) {
+    let done = false;
+    try { done = await retire(entry); } catch { done = false; }
+    if (!done) remaining.push(entry);
+  }
+  if (remaining.length === entries.length) return; // nothing retired; keep marker
+  if (remaining.length === 0) {
+    await unlink(file).catch(() => {});
+    return;
+  }
+  try {
+    await publishMarker(file, remaining, { platform, restrictAcl });
+  } catch { /* leave the existing marker in place; a later drain retries */ }
+}
+
+/**
+ * Remove only the cached credential belonging to this exact closed incarnation.
+ *
+ * Guarded: it unlinks only when the CURRENT on-disk state still matches this
+ * session id AND token. A close→reopen intentionally reuses `session_id` but mints
+ * a new bearer, so an old close can never delete a successor's cache.
+ *
+ * BOT-1650 (Codex round-27 P2): the read-compare-unlink must be serialized with
+ * cache writers on the SAME `<agent-state>.lock` writes take, or a concurrent
+ * bootstrap can rename a successor cache between this read and the unlink — and the
+ * unlink then deletes the successor, stranding an active remote holder with no
+ * local credential. Hold the lock by default. The bootstrap transaction already
+ * holds it (the file lock is not re-entrant), so that caller passes `lock: false`.
+ */
+export async function clearAgentSessionIfMatches(sessionId, { cwd = process.cwd(), sessionToken, lock = true } = {}) {
+  if (typeof sessionToken !== "string" || !AGENT_KEY_RE.test(sessionToken)) {
+    throw new Error("clearing a harness session requires its expected session token");
+  }
+  const compareAndUnlink = async () => {
+    const state = await readAgentState(cwd);
+    if (state && state.session_id === sessionId && state.agent_session_token === sessionToken) {
+      await unlink(await agentStatePath(cwd)).catch(() => {});
+      return true;
+    }
+    return false;
+  };
+  return lock ? withStateLock(cwd, {}, compareAndUnlink) : compareAndUnlink();
+}

package/src/agent-key.mjs

@@ -1,7 +1,7 @@
 // BOT-1649 — the per-session agent token the CLI presents to the relay for
 // `botbuddy wait`/`run`/`test`/`pw`.
 //
-// register_agent mints this token (bound to the work-graph session it returns)
+// bootstrap_agent_session mints this token (bound to the work-graph session it returns)
 // and the relay derives agent, tenant, and the arming session from it, so a
 // session that exports it needs no --profile/--session-id/--token.
 //

package/src/agent-state-fs.mjs

@@ -0,0 +1,90 @@
+// BOT-1650 — confidentiality hardening for the per-worktree agent-session cache,
+// shared by agent-state.mjs (read/write) so the plaintext tier-3 bearer is never
+// exposed to another account. The mechanism differs by platform:
+//  • POSIX: the 0o077 "group/other must be empty" bitmask on the file mode.
+//  • Windows: mode 0o600 does NOT restrict Windows ACLs, and the cache lives under
+//    the ARBITRARY worktree (not a guaranteed user-profile dir), so a permissive
+//    inherited ACL could expose the bearer to another account. Verify an owner-only
+//    ACL via `icacls` and fail closed if a broad principal is granted or the ACL
+//    cannot be read.
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+// BOT-1650 (Codex round-19/20 P1): validate that EVERY granted principal is on an
+// explicit allow-list, comparing the FULL account identity (DOMAIN\user), not a
+// short-name suffix — a suffix match on `\me` would accept both CONTOSO\me and
+// EVIL\me on a domain host. The only principals that may hold the bearer are the
+// current user and the OS-privileged SYSTEM / Administrators. Any other grantee —
+// or an unparseable entry — fails closed.
+export function windowsAclIsOwnerOnly(aclText, { self = windowsSelfIdentity(), file } = {}) {
+  if (typeof aclText !== "string" || !aclText.trim()) return false;
+  const owner = self.trim().toLowerCase();
+  const permitted = (principal) => {
+    const p = principal.trim().toLowerCase();
+    return p === "nt authority\\system"
+      || p === "builtin\\administrators"
+      || p === owner;
+  };
+  // icacls prints the target path before the FIRST ACE, then one "<principal>:(<perms>)"
+  // per line. BOT-1650 (Codex round-27 P2): both the worktree path AND a Windows
+  // principal ("NT AUTHORITY\SYSTEM") can contain spaces, so a whitespace heuristic
+  // truncates a spaced path INTO the first principal and wrongly rejects an
+  // owner-only ACL. Strip the EXACT known path when the caller supplies it; only
+  // fall back to a leading space-free drive path otherwise (the confidential-read
+  // caller always supplies `file`, so a spaced worktree path takes the exact strip).
+  let text = aclText;
+  if (file && text.includes(file)) text = text.replace(file, "");
+  else text = text.replace(/^[A-Za-z]:\\\S*\s+(?=\S)/, "");
+  // BOT-1650 (Codex round-28 P1): native icacls appends a "Successfully processed N
+  // files; Failed processing M files" summary after the ACEs. Validate ONLY lines
+  // carrying a "<principal>:(<perms>)" ACE — the footer and blank lines are not
+  // ACEs and must be skipped, not treated as an unparseable grant. Still fail
+  // closed when there is NO ACE at all or an ACE's principal/perms is malformed.
+  const aces = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.includes(":("));
+  if (aces.length === 0) return false;
+  for (const line of aces) {
+    const at = line.indexOf(":(");
+    const perms = line.slice(at + 1);
+    if (!/^(?:\([A-Za-z,]+\))+$/.test(perms)) return false;
+    if (!permitted(line.slice(0, at))) return false;
+  }
+  return true;
+}
+
+// The current account as icacls records it: DOMAIN\username (USERDOMAIN is the
+// computer name for a local account, the AD domain for a domain account). Falls
+// back to the bare username only when the domain is unknown.
+export function windowsSelfIdentity(env = process.env) {
+  const user = env.USERNAME || os.userInfo().username;
+  const domain = env.USERDOMAIN;
+  return domain ? `${domain}\\${user}` : user;
+}
+
+const readWindowsAcl = (file) => execFileAsync("icacls", [file], { encoding: "utf8" }).then((r) => r.stdout);
+
+export async function sessionPathIsConfidential(file, mode, { platform = process.platform, readAcl = readWindowsAcl } = {}) {
+  if (platform !== "win32") return (mode & 0o077) === 0;
+  try {
+    return windowsAclIsOwnerOnly(await readAcl(file), { file });
+  } catch {
+    return false; // an unreadable ACL is not provably confidential — fail closed.
+  }
+}
+
+// Apply an owner-only ACL (strip inheritance, grant only the current user) so a
+// freshly written cache is confidential on Windows regardless of the worktree's
+// inherited permissions. A failure must surface, never persist a readable bearer.
+export const restrictWindowsAcl = (file, run = (args) => execFileAsync("icacls", args)) =>
+  run([file, "/inheritance:r", "/grant:r", `${windowsSelfIdentity()}:(F)`]);
+
+// BOT-1650 (Codex round-34 P2): the Windows ACL check is inherently by path (icacls
+// cannot bind to an open handle), so a foreign account could swap a file between
+// open and the icacls check. Close that at the DIRECTORY: restrict `.botbuddy` to
+// the current user with no inheritance, and mark it (OI)(CI) so new children
+// inherit the owner-only ACE — no other local account can then create or replace
+// entries inside it, which is what makes the by-path check trustworthy on Windows.
+export const restrictWindowsAclDir = (dir, run = (args) => execFileAsync("icacls", args)) =>
+  run([dir, "/inheritance:r", "/grant:r", `${windowsSelfIdentity()}:(OI)(CI)(F)`]);

package/src/agent-state.mjs

@@ -1,17 +1,20 @@
 // BOT-1649 — a per-worktree, gitignored cache for the short-lived agent session.
 // It deliberately holds a session token (mode 0600), never a durable client key.
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, parse } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { AGENT_KEY_RE } from "./agent-key.mjs";
 import { acquireStackLock } from "./stack-file-lock.mjs";
+import { restrictWindowsAcl, restrictWindowsAclDir, sessionPathIsConfidential } from "./agent-state-fs.mjs";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 // BOT-1649 (Codex round-4 P2): every mutation of the cache (self-heal mint, an
 // SSE keepalive expiry touch, logout's clear) must be serialized on ONE lock —
 // the same `<agent-state>.lock` selfHealAgentSession takes — so a delayed touch
 // can never rename a stale credential back over a newer mint or a logout delete.
-async function withStateLock(cwd, { timeoutMs } = {}, fn) {
+export async function withStateLock(cwd, { timeoutMs } = {}, fn) {
   const lockPath = `${await agentStatePath(cwd)}.lock`;
   await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
   const lease = await acquireStackLock(lockPath, timeoutMs ? { timeoutMs } : {});
@@ -45,38 +48,102 @@ export async function agentStatePath(cwd = process.cwd()) {
   return join(await findAgentStateRoot(cwd), AGENT_STATE_PATH);
 }
 
+/** BOT-1650: the nearest enclosing git worktree root, never crossing above a
+ * repository binding. A standalone caller falls back to its cwd. Used by the
+ * bootstrap bridge and the Codex bridge to anchor the per-worktree cache.
+ *
+ * BOT-1650 (Codex round-32 P2): the result is canonicalized through realpath so
+ * the SAME checkout reached via a symlink or a case alias resolves to one path.
+ * The Codex bridge compares these strings to detect an existing bootstrapped
+ * thread; without canonicalization an aliased path bypasses that gate and boots a
+ * second thread against the same physical cache, whose replacement flow then
+ * revokes the first thread's session and overwrites its cache. */
+export async function worktreeRoot(cwd = process.cwd()) {
+  const canonical = async (p) => { try { return await realpath(p); } catch { return resolve(p); } };
+  let dir = resolve(cwd);
+  const root = parse(dir).root;
+  while (true) {
+    try {
+      await stat(join(dir, ".git"));
+      return await canonical(dir);
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err;
+    }
+    if (dir === root) return await canonical(cwd);
+    dir = dirname(dir);
+  }
+}
+
 function validState(value) {
-  return Boolean(value) && typeof value === "object" && value.schema_version === 1
+  if (!(Boolean(value) && typeof value === "object" && value.schema_version === 1
     && typeof value.agent_id === "string" && value.agent_id.length > 0
     && typeof value.agent_session_token === "string" && AGENT_KEY_RE.test(value.agent_session_token)
     && (typeof value.session_id === "string" || value.session_id === null)
-    && typeof value.tenant === "string" && value.tenant.length > 0
-    && typeof value.host === "string" && value.host.length > 0
-    && typeof value.worktree === "string" && value.worktree.length > 0
-    && typeof value.minted_at === "string" && !Number.isNaN(Date.parse(value.minted_at))
-    && typeof value.expires_at === "string" && !Number.isNaN(Date.parse(value.expires_at));
+    && typeof value.expires_at === "string" && !Number.isNaN(Date.parse(value.expires_at)))) {
+    return false;
+  }
+  // BOT-1650: tenant/host/worktree/minted_at are always present on a self-heal
+  // minted state, but OPTIONAL on a bootstrap-written one — bootstrap_agent_session
+  // does not echo the tenant (the relay derives it from the token). When present
+  // they must still be well formed.
+  if (value.tenant !== undefined && !(typeof value.tenant === "string" && value.tenant.length > 0)) return false;
+  if (value.host !== undefined && !(typeof value.host === "string" && value.host.length > 0)) return false;
+  if (value.worktree !== undefined && !(typeof value.worktree === "string" && value.worktree.length > 0)) return false;
+  if (value.minted_at !== undefined && !(typeof value.minted_at === "string" && !Number.isNaN(Date.parse(value.minted_at)))) return false;
+  // BOT-1650: the nonsecret incarnation fence for close/heartbeat idempotency.
+  if (value.session_token_generation !== undefined
+    && !(typeof value.session_token_generation === "string" && UUID_RE.test(value.session_token_generation))) return false;
+  return true;
 }
 
 /** Never throw malformed cache contents into credential resolution. */
 export async function readAgentState(cwd = process.cwd()) {
+  const path = await agentStatePath(cwd);
+  let handle;
   try {
-    const value = JSON.parse(await readFile(await agentStatePath(cwd), "utf8"));
+    handle = await open(path, "r");
+  } catch {
+    return null; // absent or unreadable
+  }
+  try {
+    // BOT-1650: never load a plaintext bearer from a group/other-readable file
+    // (POSIX) or a broadly-ACL'd file (Windows). Fail closed exactly like a missing
+    // cache. BOT-1650 (Codex round-33 P2): verify the OPEN handle's mode and read
+    // from the SAME handle so a hostile local writer cannot swap agent-state.json
+    // between the check and the read (TOCTOU) — on POSIX the fd is pinned to the
+    // inode. Windows ACLs are a by-path icacls check backed by the owner-only ACL
+    // applied at write.
+    const { mode } = await handle.stat();
+    if (!(await sessionPathIsConfidential(path, mode))) return null;
+    const value = JSON.parse(await handle.readFile("utf8"));
     return validState(value) ? value : null;
   } catch {
     return null;
+  } finally {
+    await handle.close().catch(() => {});
   }
 }
 
 /** Atomically replace cache content and ensure the destination remains owner-only. */
-export async function writeAgentState(cwd, state) {
+export async function writeAgentState(cwd, state, { platform = process.platform, restrictAcl = restrictWindowsAcl, restrictAclDir = restrictWindowsAclDir } = {}) {
   if (!validState(state)) throw new Error("agent state is missing required fields");
   const path = await agentStatePath(cwd);
   const directory = dirname(path);
   await mkdir(directory, { recursive: true, mode: 0o700 });
+  // BOT-1650 (Codex round-34 P2): on Windows the by-path ACL check can be raced by
+  // swapping a file in the directory, so protect the CONTAINING directory itself —
+  // owner-only, no inheritance — so no other local account can create or replace
+  // entries in .botbuddy. On POSIX the 0o700 mode already does this.
+  if (platform === "win32") await restrictAclDir(directory);
   const temp = join(directory, `.${AGENT_STATE_FILE}.${process.pid}.${randomUUID()}.tmp`);
   try {
     await writeFile(temp, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
     await chmod(temp, 0o600);
+    // BOT-1650: mode 0o600 is a no-op for Windows ACLs and the cache lives under an
+    // arbitrary worktree, so explicitly restrict the temp to the current user before
+    // publishing it. A failure surfaces (the finally unlinks the temp) — the bearer
+    // is never published under an inherited, possibly-shared ACL.
+    if (platform === "win32") await restrictAcl(temp);
     await rename(temp, path);
     await chmod(path, 0o600);
   } finally {