@hybridlabor-api/aos 4.14.1 → 4.16.0

package/.claude/hooks/aos-bus.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// aos-bus spike: master -> running OpenCode session via per-session inbox files.
+// Library + CLI. The receiver (OpenCode plugin) injects each message as a synthetic + ignored part pair.
+
+import {
+  chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, utimesSync, writeFileSync,
+} from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { slug } from "./go-gate.mjs";
+
+const MAX_SEND = 8 * 1024;
+const MAX_FILE = 16 * 1024;
+
+export function busPaths(name) {
+  const n = slug(String(name ?? ""));
+  if (!n || n.startsWith(".")) throw new Error("invalid session name");
+  const root = join(homedir(), ".aos", "bus");
+  return { name: n, root, sessions: join(root, "sessions"), reg: join(root, "sessions", `${n}.json`), inbox: join(root, "inbox", n) };
+}
+
+export function ensurePrivateDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+}
+
+// Returns null when usable, else the refusal reason.
+export function checkPrivateDir(dir) {
+  let st;
+  try { st = lstatSync(dir); } catch { return `${dir} does not exist`; }
+  if (!st.isDirectory()) return `${dir} is not a real directory`;
+  if (st.uid !== process.getuid()) return `${dir} is not owned by the current user`;
+  if (st.mode & 0o077) return `${dir} is accessible to others (mode ${(st.mode & 0o777).toString(8)})`;
+  return null;
+}
+
+export function registerSession({ name, sessionID, cwd }) {
+  const p = busPaths(name);
+  ensurePrivateDir(join(p.root, "inbox"));
+  ensurePrivateDir(p.sessions);
+  ensurePrivateDir(p.inbox);
+  writeFileSync(p.reg, JSON.stringify({ name: p.name, harness: "opencode", pid: process.pid, cwd, sessionID, inbox: p.inbox, ts: Date.now() }), { mode: 0o600 });
+  return p.name;
+}
+
+export function unregisterSession(name, pid = process.pid) {
+  try {
+    const p = busPaths(name);
+    if (JSON.parse(readFileSync(p.reg, "utf8")).pid === pid) unlinkSync(p.reg);
+  } catch { /* already gone */ }
+}
+
+// A registration is live only while its owner keeps touching it: a pid check alone passes
+// for a reused pid, and a killed or exited TUI leaves the file behind (no exit hook fires).
+export const STALE_MS = Number(process.env.AOS_BUS_STALE_MS) || 15_000;
+
+export function touchSession(name, pid = process.pid) {
+  try {
+    const p = busPaths(name);
+    if (JSON.parse(readFileSync(p.reg, "utf8")).pid !== pid) return false;
+    const now = new Date();
+    utimesSync(p.reg, now, now);
+    return true;
+  } catch { return false; }
+}
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+
+export function listSessions() {
+  const dir = join(homedir(), ".aos", "bus", "sessions");
+  const out = [];
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => f.endsWith(".json")); } catch { /* none */ }
+  for (const f of files) {
+    try {
+      const file = join(dir, f);
+      const r = JSON.parse(readFileSync(file, "utf8"));
+      if (Number.isInteger(r.pid) && alive(r.pid) && Date.now() - lstatSync(file).mtimeMs < STALE_MS) out.push(r);
+    } catch { /* corrupt entry */ }
+  }
+  return out;
+}
+
+// Throws with the refusal reason; returns the message file path.
+export function sendMessage(name, text, { from, wake = false } = {}) {
+  const p = busPaths(name);
+  if (!listSessions().some((s) => s.name === p.name)) throw new Error(`session "${p.name}" is not registered or not alive`);
+  const bad = checkPrivateDir(p.inbox);
+  if (bad) throw new Error(bad);
+  text = String(text ?? "");
+  if (Buffer.byteLength(text) > MAX_SEND) throw new Error(`message exceeds ${MAX_SEND} bytes`);
+  from ||= process.env.AOS_SESSION_NAME || `${userInfo().username}:${process.ppid}`;
+  const base = `${Date.now()}-${randomBytes(4).toString("hex")}`;
+  const tmp = join(p.inbox, `${base}.tmp`);
+  const file = join(p.inbox, `${base}.json`);
+  writeFileSync(tmp, JSON.stringify({ v: 1, from, text, ts: Date.now(), ...(wake ? { wake: true } : {}) }), { mode: 0o600 });
+  renameSync(tmp, file);
+  return file;
+}
+
+export function readInbox(name) {
+  const p = busPaths(name);
+  if (checkPrivateDir(p.inbox)) return [];
+  const out = [];
+  for (const f of readdirSync(p.inbox).filter((x) => x.endsWith(".json")).sort()) {
+    const file = join(p.inbox, f);
+    try {
+      const st = lstatSync(file);
+      if (!st.isFile() || st.uid !== process.getuid() || st.size > MAX_FILE) throw new Error("rejected");
+      const m = JSON.parse(readFileSync(file, "utf8"));
+      if (typeof m?.text !== "string") throw new Error("rejected");
+      const from = String(m.from ?? "").replace(/[\x00-\x1f\x7f\]]/g, "").slice(0, 64) || "unknown";
+      out.push({ file, from, text: m.text, wake: m.wake === true, uid: st.uid, ts: Number.isFinite(m.ts) ? m.ts : undefined, mtimeMs: st.mtimeMs });
+    } catch {
+      try { renameSync(file, `${file}.rejected`); } catch { /* gone */ }
+    }
+  }
+  return out;
+}
+
+const isMain = () => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+
+if (isMain()) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opts = {}; const words = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--from") opts.from = rest[++i];
+    else if (rest[i] === "--wake") opts.wake = true;
+    else words.push(rest[i]);
+  }
+  try {
+    if (cmd === "send" && words.length >= 2) {
+      console.log(sendMessage(words[0], words.slice(1).join(" "), opts));
+    } else if (cmd === "list") {
+      for (const s of listSessions()) console.log(`${s.name}\tpid ${s.pid}\t${s.cwd}`);
+    } else {
+      console.error("usage: aos-bus send <name> <text...> [--from x] [--wake] | aos-bus list");
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error(`aos-bus: ${e.message}`);
+    process.exit(2);
+  }
+}

package/.claude/hooks/go-gate.mjs

@@ -150,7 +150,8 @@ function opencodeLastUser(sessionId) {
     if (!msg) return null;
     const text = db.prepare("SELECT data FROM part WHERE message_id = ? ORDER BY id").all(msg.id)
       .map((r) => JSON.parse(r.data))
-      .filter((p) => p?.type === "text" && !p.synthetic && typeof p.text === "string")
+      // synthetic = model-only, ignored = display-only, aos_bus = bus delivery: none is a human turn.
+      .filter((p) => p?.type === "text" && !p.synthetic && !p.ignored && !p.metadata?.aos_bus && typeof p.text === "string")
       .map((p) => p.text)
       .join("\n")
       .trim();

package/.opencode/plugins/bdb-aos.js

@@ -15,7 +15,7 @@
  * on unguarded destructive actions.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
 // Decision logic lives in the shared hooks: installed copy next to this file
@@ -23,8 +23,8 @@ import path from 'node:path';
 // so a broken installed hook fails loudly instead of silently falling back.
 const HOOKS = existsSync(new URL('./aos-hooks/go-gate.mjs', import.meta.url)) ? './aos-hooks/' : '../../.claude/hooks/';
 const hook = (f) => import(new URL(HOOKS + f, import.meta.url).href);
-const [{ GUARDED_PATTERNS, tokenGrantsGo }, { issueGoToken }, { checkConventionalCommit }, { envFileReason }, { buildMemoryBlock }] =
-  await Promise.all(['go-gate.mjs', 'go-token.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs', 'memb-inject.mjs'].map(hook));
+const [{ GUARDED_PATTERNS, tokenGrantsGo }, { issueGoToken }, { checkConventionalCommit }, { envFileReason }, { buildMemoryBlock }, bus] =
+  await Promise.all(['go-gate.mjs', 'go-token.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs', 'memb-inject.mjs', 'aos-bus.mjs'].map(hook));
 
 // ---------------------------------------------------------------------------
 // Graph gate (W-5, W-6)
@@ -130,6 +130,15 @@ async function ownSessionName(client, sessionID) {
   } catch { return ''; }
 }
 
+// Only plain text parts are human turns: synthetic = model-only, ignored = display-only,
+// aos_bus = bus delivery (both copies). Each excluded on its own, so safety never hangs on one flag.
+const isHumanText = (p) => p && p.type === 'text' && typeof p.text === 'string' && !p.synthetic && !p.ignored && !p.metadata?.aos_bus;
+const isNonHuman = (p) => p && (p.synthetic || p.ignored || p.metadata?.aos_bus);
+
+// A plugin reload (SIGUSR2) re-runs init on the cached module in the same process:
+// stop the previous instance's timers and keep its bus names alive. Keyed by directory.
+const busInstances = new Map();
+
 // Best-effort fire-and-forget telemetry for the AOS live map (agenttrail daemon).
 // 300 ms timeout per request, all errors swallowed, never throws. Self-contained
 // on purpose: the plugin must not import from mcps/.
@@ -199,6 +208,94 @@ export default async function bdbAosPlugin(input) {
     if (!sessions.has(id)) sessions.set(id, { prompt: '', parentID: null, identitySent: false });
     return sessions.get(id);
   };
+  // aos-bus: bus name -> sessionID of the root session that owns it.
+  const prevBus = busInstances.get(directory);
+  for (const t of prevBus?.timers || []) clearInterval(t);
+  const busNames = prevBus?.names || new Map();
+  const busTimers = [];
+  busInstances.set(directory, { timers: busTimers, names: busNames });
+  const every = (ms, fn) => { const t = setInterval(fn, ms); t.unref?.(); busTimers.push(t); };
+  const BUS_PROMPT_TIMEOUT_MS = Number(process.env.AOS_BUS_PROMPT_TIMEOUT_MS) || 10 * 60 * 1000;
+  const BUS_BUSY_MAX_MS = Number(process.env.AOS_BUS_BUSY_MAX_MS) || 10 * 60 * 1000;
+  const ensureBus = async (id, parentID) => {
+    const s = sess(id);
+    if (s.bus || !id) return;
+    s.bus = true;
+    try {
+      if (parentID === undefined) {
+        const res = await input.client?.session?.get?.({ path: { id } });
+        if (!res?.data) { s.bus = false; return; }
+        parentID = res.data.parentID ?? null;
+      }
+      if (parentID) return;
+      const name = bus.registerSession({ name: process.env.AOS_SESSION_NAME || id, sessionID: id, cwd: directory });
+      busNames.set(name, id);
+    } catch (e) {
+      console.error(`[aos-bus] registration failed: ${e?.message}`);
+      s.bus = /invalid session name/.test(e?.message);
+    }
+  };
+  const dropBus = (id) => {
+    for (const [name, sid] of busNames) if (sid === id) { bus.unregisterSession(name); busNames.delete(name); }
+  };
+  process.on('exit', () => { for (const name of busNames.keys()) bus.unregisterSession(name); });
+
+  // Heartbeat on its own timer (the poll loop can sit in one prompt for minutes); readers drop a
+  // registration whose mtime is older than bus.STALE_MS. touchSession only touches this pid's files.
+  every(5000, () => { for (const name of busNames.keys()) bus.touchSession(name); });
+
+  const busyFirst = new Map(); // inbox file -> time of its first busy attempt
+  let polling = false;
+  every(1000, async () => {
+    if (polling || !busNames.size) return;
+    polling = true;
+    try {
+      for (const [name, sessionID] of busNames) {
+        // Only the registered owner (this pid + this session) may consume the inbox.
+        let reg; try { reg = JSON.parse(readFileSync(bus.busPaths(name).reg, 'utf8')); } catch {}
+        if (reg?.pid !== process.pid || reg?.sessionID !== sessionID) continue;
+        for (const m of bus.readInbox(name)) {
+          // Claim atomically: with two live pollers (ownership handover) only one rename wins.
+          const claim = `${m.file.slice(0, -'.json'.length)}.inflight`;
+          try { renameSync(m.file, claim); } catch { continue; }
+          // The gate checks this cache before any DB lookup; a stale human GO must not authorize a woken turn.
+          sess(sessionID).prompt = '';
+          try {
+            let timer;
+            const text = `[aos-bus from ${m.from}] ${m.text}`;
+            const metadata = { aos_bus: { from: m.from, uid: m.uid, ts: m.ts } };
+            const res = await Promise.race([input.client.session.prompt({
+              path: { id: sessionID },
+              query: directory ? { directory } : undefined,
+              body: {
+                noReply: !m.wake,
+                // OpenCode 1.18.30: the TUI hides synthetic parts and the model never sees ignored
+                // ones, so one copy each. Neither counts as a human turn (isHumanText).
+                parts: [
+                  { type: 'text', text, synthetic: true, metadata },
+                  { type: 'text', text, ignored: true, metadata },
+                ],
+              },
+            }), new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error('aos-bus prompt timeout'), { timedOut: true })), BUS_PROMPT_TIMEOUT_MS); timer.unref?.(); })]).finally(() => clearTimeout(timer));
+            if (res?.error) throw res.error;
+            unlinkSync(claim);
+            busyFirst.delete(m.file);
+            input.client.tui?.showToast?.({ body: { title: 'aos-bus', message: `from ${m.from}`, variant: 'info', duration: 15000 } })?.catch?.(() => {});
+          } catch (e) {
+            // Busy: hand the file back and retry next tick, up to BUS_BUSY_MAX_MS after the first busy attempt.
+            const isBusy = /busy/i.test(`${e?.name} ${e?.message} ${e?.data?.message}`);
+            const first = busyFirst.get(m.file) ?? Date.now();
+            if (isBusy) busyFirst.set(m.file, first);
+            if (isBusy && Date.now() - first < BUS_BUSY_MAX_MS) { try { renameSync(claim, m.file); } catch {} break; }
+            busyFirst.delete(m.file);
+            // A timed-out prompt may still complete: delivery state unknown, so not .failed.
+            try { renameSync(claim, `${m.file}${e?.timedOut ? '.timeout' : '.failed'}`); } catch {}
+          }
+        }
+      }
+    } catch {} finally { polling = false; }
+  // ponytail: 1 s poll; fs.watch if latency matters. A wake turn is awaited, so it delays later messages until it ends.
+  });
   const trail = (hook_event_name, session_id, extra = {}) =>
     void postTrail({ hook_event_name, session_id, cwd: directory, agent: 'opencode', ...extra });
 
@@ -212,10 +309,14 @@ export default async function bdbAosPlugin(input) {
         if (event?.type === 'session.created' && props.info?.id) {
           sess(props.info.id).parentID = props.info.parentID ?? null;
           trail('SessionStart', props.info.id);
+          void ensureBus(props.info.id, props.info.parentID ?? null);
+        } else if (event?.type === 'session.deleted' && props.info?.id) {
+          dropBus(props.info.id);
         } else if (event?.type === 'permission.updated') {
           trail('Notification', props.sessionID, { message: props.title });
         } else if (event?.type === 'session.idle' && props.sessionID) {
           trail(sess(props.sessionID).parentID ? 'SubagentStop' : 'Stop', props.sessionID);
+          void ensureBus(props.sessionID);
         }
       } catch {}
 
@@ -246,10 +347,15 @@ export default async function bdbAosPlugin(input) {
     },
 
     'chat.message': async (msgInput, msgOutput) => {
-      const textParts = (msgOutput.parts || []).filter((p) => p && p.type === 'text' && typeof p.text === 'string' && !p.synthetic);
+      const textParts = (msgOutput.parts || []).filter(isHumanText);
       const fullText = textParts.map((p) => p.text).join('\n').trim();
       const s = sess(msgInput.sessionID);
+      void ensureBus(msgInput.sessionID);
       s.prompt = fullText;
+      // No human text (aos-bus pair, nudges): never a human GO, skip memB/pipeline/token.
+      const parts = msgOutput.parts || [];
+      const texts = parts.filter((p) => p && p.type === 'text');
+      if ((parts.length > 0 && parts.every((p) => p && p.synthetic)) || (texts.length > 0 && texts.every(isNonHuman))) { s.prompt = ''; return; }
 
       try {
         if (!s.parentID) issueGoToken(fullText, { session_id: msgInput.sessionID, message_id: msgInput.messageID || msgOutput.message?.id });
@@ -333,7 +439,7 @@ export default async function bdbAosPlugin(input) {
                 const m = msgs[i];
                 if ((m.info?.role ?? m.role) === 'user') {
                   const parts = m.parts || [];
-                  const text = parts.filter((p) => p.type === 'text' && !p.synthetic).map((p) => p.text).join('\n').trim();
+                  const text = parts.filter(isHumanText).map((p) => p.text).join('\n').trim();
                   authorized = text.toUpperCase() === 'GO';
                   break;
                 }

package/bin/aos-acp.mjs

@@ -9,7 +9,7 @@
 //   aos-acp <claude|codex|opencode|agy> --name <worker> [--cwd <dir>]
 //           (--prompt "<text>" | --prompt-file <f>) [--allow-default deny|allow]
 //           [--go-wait <sec>] [--consume|--no-consume] [--log <file>]
-//           [--timeout <sec>] [--cmd "<custom agent command>"]
+//           [--model <id>] [--timeout <sec>] [--cmd "<custom agent command>"]
 
 import { spawn } from "node:child_process";
 import { appendFileSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
@@ -130,8 +130,9 @@ export async function run(opts) {
     ? "agy has no sanctioned ACP adapter (antigravity-acp breaches Google's Antigravity terms); delegate via the mcsc skill instead"
     : `unknown adapter "${opts.adapter}" (claude|codex|opencode)`);
   if (adapter?.cwdFlag && !opts.cmd) cmd.push(adapter.cwdFlag, opts.cwd);
+  if (/fable/i.test(opts.model || "")) throw new Error(`model "${opts.model}" rejected: workers run on opus, sonnet or haiku only`);
   const consume = opts.consume ?? adapter?.consume ?? true;
-  log("start", { adapter: opts.adapter, cmd: cmd.join(" "), cwd: opts.cwd, allow_default: opts.allowDefault, consume });
+  log("start", { adapter: opts.adapter, cmd: cmd.join(" "), cwd: opts.cwd, allow_default: opts.allowDefault, consume, model: opts.model || "adapter default" });
 
   let sessionId;
   const out = opts.stdout || process.stdout;
@@ -169,6 +170,8 @@ export async function run(opts) {
     log("initialized", { agent: init?.agentInfo, auth: init?.authMethods });
     ({ sessionId } = await client.request("session/new", { cwd: opts.cwd, mcpServers: [] }));
     log("session", { sessionId });
+    // ACP session config option "model": claude-agent-acp, codex-acp and opencode all implement it.
+    if (opts.model) await client.request("session/set_config_option", { sessionId, configId: "model", value: opts.model });
     const res = await client.request("session/prompt", { sessionId, prompt: [{ type: "text", text: opts.prompt }] });
     out.write("\n");
     log("done", { stopReason: res?.stopReason });
@@ -194,12 +197,13 @@ export function parseArgs(argv) {
     else if (a === "--go-wait") o.goWait = Number(v), i++;
     else if (a === "--timeout") o.timeout = Number(v), i++;
     else if (a === "--log") o.log = v, i++;
+    else if (a === "--model") o.model = v, i++;
     else if (a === "--cmd") o.cmd = v, i++;
     else if (a === "--consume") o.consume = true;
     else if (a === "--no-consume") o.consume = false;
     else throw new Error(`unknown argument ${a}`);
   }
-  if (!o.adapter || !o.name || !o.prompt) throw new Error("usage: aos-acp <claude|codex|opencode> --name <worker> --prompt <text> [--cwd <dir>] [--allow-default deny|allow] [--go-wait <sec>] [--no-consume] [--log <file>] [--timeout <sec>]");
+  if (!o.adapter || !o.name || !o.prompt) throw new Error("usage: aos-acp <claude|codex|opencode> --name <worker> --prompt <text> [--cwd <dir>] [--allow-default deny|allow] [--go-wait <sec>] [--no-consume] [--model <id>] [--log <file>] [--timeout <sec>]");
   if (!["deny", "allow"].includes(o.allowDefault)) throw new Error("--allow-default must be deny or allow");
   return o;
 }

package/bin/aos-doctor.mjs

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { connect } from 'node:net';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -300,6 +301,20 @@ async function checkDaemonsAndModules() {
       ? 'Enable AO in the installer or run: ao service install'
       : 'AO binary is arm64 macOS native; build from source on other platforms: github.com/hybridlabor-api/bdb-agent-orchestrator', false);
 
+  // Installed ao vs a local AO checkout's HEAD, read from the binary's embedded build info.
+  const aoCheckout = firstExisting([h('dev', 'agents', 'bdb-agent-orchestrator'), h('dev', 'bdb-dev', 'bdb-agent-orchestrator')]);
+  if (aoBin && aoCheckout && existsSync(path.join(aoCheckout, '.git'))) {
+    const { readGoBuildInfo } = createRequire(import.meta.url)('../installer.js');
+    const build = readGoBuildInfo(aoBin.replace(/^~/, HOME));
+    let head = null;
+    try { head = execFileSync('git', ['--no-optional-locks', '-C', aoCheckout, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+    const same = !!(build && head && build.revision === head && !build.modified);
+    add('daemons', 'AO revision vs checkout', same,
+      !build ? 'Installed ao has no readable build revision'
+        : `Installed ${build.revision.slice(0, 9)}${build.modified ? ' (dirty build)' : ''} · checkout HEAD ${head ? head.slice(0, 9) : 'unknown'}`,
+      `Rebuild from a clean checkout: cd ${tilde(path.join(aoCheckout, 'backend'))} && go build -ldflags='-s -w' -o ~/.local/bin/ao.new ./cmd/ao && mv ~/.local/bin/ao.new ~/.local/bin/ao && ao service install`, true);
+  }
+
   // Code-signing check for AO on macOS
   if (IS_MAC && aoBin) {
     let signed = false;
@@ -318,15 +333,15 @@ function printAoAnnouncement() {
   console.log(`
 ╭──────────────────────────────────────────────────────────────────────────────╮
 │                                                                              │
-│   🚀 BDB AGENT ORCHESTRATOR APP — FINALE BETA JETZT VERFÜGBAR!              │
+│   BDB AGENT ORCHESTRATOR APP — FINAL BETA NOW AVAILABLE                      │
 │                                                                              │
-│   Die nächste Generation der Cross-Harness Multi-Agenten-Orchestrierung      │
-│   ist jetzt als finale Beta für alle User freigeschaltet.                    │
+│   The next generation of cross-harness multi-agent orchestration             │
+│   is now open to every user as a final beta.                                 │
 │                                                                              │
 │   • Dashboard & WebUI:  http://localhost:3101                                │
-│   • Service-Befehl:     ao service install  (Hintergrunddienst aktivieren)   │
-│   • Quick Launch:       ao open  oder  ao service status                     │
-│   • Features:           Session-Telemetrie, Live-AgentTrail & Multi-Workspaces│
+│   • Service command:    ao service install  (enables the background service) │
+│   • Quick launch:       ao open  or  ao service status                       │
+│   • Features:           session telemetry, live AgentTrail, multi-workspaces │
 │                                                                              │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 `);

package/docs/master-session-acp.md

@@ -49,3 +49,18 @@ Double gate: opencode and claude workers also run their own AOS gate inside the
 - OpenCode token path end to end needs the installed plugin updated; verified by unit test only.
 - Neither live adapter sent `session/request_permission` for a shell command in the smoke runs (the inner gate answered first); the mapping is covered by the fake-agent tests.
 - One `aos-acp` process per worker; no resume (`session/load`) and no concurrency cap yet.
+
+## Bus (spike): messaging a hand-started OpenCode session
+
+A master can drop a message into a running OpenCode session (no `--port`, no restart). OpenCode only.
+
+- **Paths:** registry `~/.aos/bus/sessions/<name>.json` (0600), inbox `~/.aos/bus/inbox/<name>/` (0700), one `<ms>-<rand>.json` per message. `<name>` is `slug(AOS_SESSION_NAME)`, else the OpenCode session id. The inbox path is always derived from the name, never from the registry file.
+- **CLI:** `aos-bus send <name> <text...> [--from x] [--wake]`, `aos-bus list`. Exit 2 with a reason on refusal (unregistered or dead pid, inbox not a private real dir owned by you, text over 8 KiB).
+- **Injection:** the plugin polls the inbox every 1 s and calls `client.session.prompt` with `noReply: true` (`false` with `--wake`) and one text part `[aos-bus from <from>] <text>`, `synthetic: true`, `metadata.aos_bus`. The API has no non-user message, so the stored row is `role: user`; exclusion from GO rests on the part flag.
+- **GO exclusion (3 layers):** `synthetic: true` (existing `!synthetic` filters in `chat.message`, the `session.messages` fallback and `opencodeLastUser`); the `[aos-bus from ...]` prefix, so the text can never be `GO` or `GO <name>`; the plugin clears its cached prompt before each injection and returns early from `chat.message` for all-synthetic messages.
+- **Fail-closed side effect:** a bus message becomes the newest user row, so the last human `GO` no longer opens that session's gate, and a pending OpenCode-issued `GO <worker>` token for it is invalidated. The human re-types GO.
+- **Delivery rules:** only the registered owner (pid + session) polls. Each file is claimed by renaming `<x>.json` to `<x>.inflight` before the prompt, so a message is delivered by at most one process; a failed claim means someone else has it. Success deletes the claim. A busy session gets the file renamed back to `.json` and retried every tick for up to 10 min counted from the first busy attempt (`AOS_BUS_BUSY_MAX_MS`), then `.failed`. A prompt not finished within 10 min (`AOS_BUS_PROMPT_TIMEOUT_MS`) is parked as `.timeout`: the prompt is not aborted, so delivery state is unknown and it must not be resent blindly. Any other error parks the file as `.failed` (not delivered).
+- **Smoke:** `tests/aos-bus-smoke.sh` (opt-in, isolated HOME/XDG, `opencode serve`).
+  - **[verified]** `synthetic: true`, prefix and `metadata.aos_bus` persist in `opencode.db`; no token file; `tokenGrantsGo` rejects a token pointing at the bus message.
+  - **[open]** TUI mode (toast, plugin client without `--port`), `--wake` (needs model credentials), real busy-session behaviour.
+- **Out of scope:** Claude Code receivers (native `SendMessage`), Codex/agy, AO daemon, slash commands, agenttrail roster, replies/acks/expiry, `fs.watch`, authenticating `from` beyond file-owner uid.

package/docs/sessions/audit-agents.md

@@ -105,6 +105,8 @@ Additionally the parser at `installer.js:1857` uses `block.match(/([A-Za-z0-9_]+
 The same ruleset exists in `CLAUDE.md`, `GEMINI.md`, `agent.md`, `.codex-plugin/system.md`, `.cursor/rules/000_global_rules.mdc`, and (partially) `.roomodes`. `GEMINI.md` is missing two clauses that `CLAUDE.md` has ("Plans are not approval", "No inheritance, no silent retries"). `CODEX.md` contains no rules at all. There is no single source of truth; the installer regenerates *some* targets from `agent.md` but the root `CLAUDE.md`/`GEMINI.md` are separately maintained.
 
 ### F-07 — No `disable-model-invocation`, no argument contract *(P1)*
+
+> **Superseded (2026-10).** The flag was later set on pipeline and role skills and playbooks, which stopped the Master and every orchestrator from starting `/startcycle` through the Skill tool. It was removed again; go-gate guards the side effects and `validate-skills` (E-DMI01, E-PB06) keeps pipeline skills model-invocable. Kept only on `bdb-updater` and `triage`.
 B1: *"Use `disable-model-invocation: true` for workflows with side effects that you want to trigger manually."*
 
 `/startcycle`, `/ship`, `/build` and `bdbsaastraining` all have side effects (git commit, git push, npm publish, cloud calls). **0 of 134** skills set `disable-model-invocation`. Only 2 skills use `$ARGUMENTS`. Frontmatter census: