@hybridlabor-api/aos 4.14.0 → 4.15.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/.claude/hooks/trail-relay.mjs

@@ -8,6 +8,7 @@ let raw = '';
 try { for await (const c of process.stdin) raw += c; } catch {}
 let ev;
 try { ev = JSON.parse(raw); } catch { process.exit(0); }
+if (!ev || typeof ev !== 'object') process.exit(0);
 
 ev.agent = arg('--agent') || ev.agent || 'claude';
 ev.hook_event_name ||= arg('--event');

package/.claude/settings.json

@@ -6,11 +6,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/go-gate.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/go-gate.mjs\""
           },
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/conventional-commits.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/conventional-commits.mjs\""
           }
         ]
       },
@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/env-file-protection.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/env-file-protection.mjs\""
           }
         ]
       },
@@ -48,7 +48,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/graph-gate.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/graph-gate.mjs\""
           }
         ]
       },
@@ -119,7 +119,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/go-token.mjs\""
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/go-token.mjs\""
           }
         ]
       },

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/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:

package/installer.js

@@ -4004,8 +4004,8 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
     // Global installs must point at the copies installGlobalHooks put under
     // $HOME/.claude/hooks; $CLAUDE_PROJECT_DIR would not exist in other projects.
     const localize = (cmd) => (projectLocal
-        ? (machineGlobalHooks.some((n) => cmd.includes(n)) ? cmd : cmd.split('${HOME}').join('$CLAUDE_PROJECT_DIR'))
-        : cmd.split('$CLAUDE_PROJECT_DIR/.claude/hooks/').join('$HOME/.claude/hooks/'));
+        ? (machineGlobalHooks.some((n) => cmd.includes(n)) ? cmd : cmd.split('${HOME}').join('${CLAUDE_PROJECT_DIR}').replace(/\$CLAUDE_PROJECT_DIR\b/g, '${CLAUDE_PROJECT_DIR}'))
+        : cmd.replace(/\$\{?CLAUDE_PROJECT_DIR\}?\/\.claude\/hooks\//g, '$HOME/.claude/hooks/'));
     const cloneBdbEntries = (entries) =>
         JSON.parse(JSON.stringify(entries)).map((e) => ({
             ...e,
@@ -4067,18 +4067,61 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
     }
 }
 
+// agy runs a hook command through `sh -c` / `cmd /c` with cwd = the hooks.json folder, and
+// cmd cannot parse the \" Go emits for quotes. So the command is relative and quote-free.
+function agyHookCommand(hooksJsonDir, scriptPath, args = '') {
+    const rel = path.relative(hooksJsonDir, scriptPath).split(path.sep).join('/');
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || /[\s"'&|<>^%]/.test(rel)) {
+        throw new Error(`agy hook script must sit under ${hooksJsonDir} with a plain path, got ${scriptPath}`);
+    }
+    return `node ${rel}${args}`;
+}
+
+// Runs every AOS command of a hooks.json once with `{}` on stdin, the way agy does.
+// Returns [{ command, reason }] for each failure; `spawn` is injectable for tests.
+function selfCheckAgyHooks(hooksPath, spawn = spawnSync) {
+    const bdbScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'startcycle-dispatch.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    const data = readJsonFile(hooksPath);
+    const commands = [];
+    const walk = (v) => {
+        if (Array.isArray(v)) v.forEach(walk);
+        else if (v && typeof v === 'object') {
+            if (typeof v.command === 'string' && bdbScripts.some((n) => v.command.includes(n))) commands.push(v.command);
+            Object.values(v).forEach(walk);
+        }
+    };
+    walk(data && data.hooks);
+    const [shell, flag] = process.platform === 'win32' ? ['cmd', '/c'] : ['sh', '-c'];
+    const failures = [];
+    for (const command of [...new Set(commands)]) {
+        // AGENTTRAIL_PORT=1: the no-op payload must not show up on a live map.
+        const r = spawn(shell, [flag, command], { cwd: path.dirname(hooksPath), input: '{}', encoding: 'utf8', timeout: 5000, windowsHide: true, env: { ...process.env, AGENTTRAIL_PORT: '1' } });
+        const stderr = String((r && r.stderr) || '');
+        let reason = null;
+        if (!r || r.error) reason = `spawn failed: ${r && r.error ? r.error.message : 'no result'}`;
+        else if (r.status !== 0) reason = `exit ${r.status}\n  ${stderr.trim().slice(0, 500)}`;
+        else if (/MODULE_NOT_FOUND|Cannot find module/.test(stderr)) reason = `module not found\n  ${stderr.trim().slice(0, 500)}`;
+        if (reason) failures.push({ command, reason });
+    }
+    return failures;
+}
+
 // Merge the BDB hooks into Google Antigravity's hooks.json (.agents/hooks.json or
 // ~/.gemini/config/hooks.json), preserving user-defined foreign hooks.
-function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
+function mergeAntigravityHooks(hooksPath, { projectLocal = false, selfCheck = spawnSync } = {}) {
     const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'startcycle-dispatch.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
     const isBdbHandler = (h) => typeof h?.command === 'string' && bdbHookScripts.some((name) => h.command.includes(name));
 
     const baseDir = path.dirname(hooksPath);
-    const hooksDir = projectLocal ? path.join(currentDir, '.agents', 'hooks') : path.join(baseDir, 'hooks');
-    const workflowsDir = projectLocal ? path.join(currentDir, '.agents', 'workflows') : path.join(baseDir, 'workflows');
-    const globalHooksDir = projectLocal ? path.join(homeDir, '.gemini', 'config', 'hooks') : hooksDir;
-
-    const cmd = (dir, script, args = '') => `node "${path.join(dir, script)}"${args}`;
+    // Commands are relative to hooks.json's folder, so every script must live under it
+    // (installProjectHarness copies the hooks into .agents/hooks for the project-local file).
+    const hooksDir = path.join(baseDir, 'hooks');
+    const workflowsDir = path.join(baseDir, 'workflows');
+    const globalHooksDir = hooksDir;
+
+    const cmd = (dir, script, args = '') => agyHookCommand(baseDir, path.join(dir, script), args);
+    // Observability hooks must never block a tool call when they cannot start.
+    const obs = (dir, script, args = '') => cmd(dir, script, `${args} || exit 0`);
     const bdbHooks = {
         PreToolUse: [
             {
@@ -4094,15 +4137,15 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
             },
             {
                 matcher: "*",
-                hooks: [{ type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event PreToolUse'), timeout: 2 }]
+                hooks: [{ type: "command", command: obs(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event PreToolUse'), timeout: 2 }]
             }
         ],
         Stop: [
             { type: "command", command: cmd(hooksDir, 'graph-gate.mjs'), timeout: 10 },
-            { type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event Stop'), timeout: 2 }
+            { type: "command", command: obs(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event Stop'), timeout: 2 }
         ],
         PreInvocation: [
-            { type: "command", command: cmd(globalHooksDir, 'memb-inject.mjs'), timeout: 8 },
+            { type: "command", command: obs(globalHooksDir, 'memb-inject.mjs'), timeout: 8 },
             { type: "command", command: cmd(workflowsDir, 'startcycle-dispatch.mjs'), timeout: 30 }
         ]
     };
@@ -4160,9 +4203,19 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
 
     try {
         fs.mkdirSync(path.dirname(hooksPath), { recursive: true });
+        const previousRaw = existing ? fs.readFileSync(hooksPath, 'utf8') : null;
         const tmpPath = `${hooksPath}.${process.pid}.tmp`;
         fs.writeFileSync(tmpPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
         fs.renameSync(tmpPath, hooksPath);
+        if (!DRY_RUN) {
+            const failures = selfCheckAgyHooks(hooksPath, selfCheck);
+            if (failures.length) {
+                if (previousRaw === null) fs.unlinkSync(hooksPath);
+                else fs.writeFileSync(hooksPath, previousRaw);
+                log.warn(`Antigravity hook self-check FAILED for ${hooksPath}; the previous hooks.json was ${previousRaw === null ? 'removed (none existed)' : 'restored'}.`);
+                for (const f of failures) log.warn(`  command: ${f.command}\n  ${f.reason}`);
+            }
+        }
     } catch (e) {
         log.warn(`Could not write ${hooksPath}: ${e.message}`);
     }
@@ -5916,6 +5969,8 @@ module.exports = {
     keepExistingEnvValues,
     mergeBdbSettingsHooks,
     mergeAntigravityHooks,
+    agyHookCommand,
+    selfCheckAgyHooks,
     mergeCodexTomlHooks,
     mergeCodexHooks: mergeCodexTomlHooks,
     mergeCodexTomlMcpServers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.14.0",
+  "version": "4.15.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "engines": {
@@ -12,6 +12,7 @@
     "bdb-agent-skills-pro": "installer.js",
     "bdb-agent-skills": "installer.js",
     "aos-plan-canvas": "skills/global_config/plan-canvas/scripts/plan-canvas.js",
+    "aos-bus": ".claude/hooks/aos-bus.mjs",
     "aos-trail": "skills/global_config/agenttrail/bin/agenttrail.mjs",
     "aos-archify": "skills/global_config/archify/bin/archify.mjs",
     "aos-dashboard": "bin/aos-dashboard.mjs",
@@ -28,7 +29,7 @@
     "plugin:build": "node scripts/build-plugin-manifest.mjs",
     "plugin:check": "node scripts/build-plugin-manifest.mjs --check",
     "doctor": "node bin/aos-doctor.mjs",
-    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node --test tests/opencode-graph-gate.test.js && node --test tests/cross-harness-hooks.test.js && node --test tests/plan-canvas-security.test.mjs && node --test tests/plan-canvas-modes.test.mjs && node --test tests/swarm-wiring.test.js && node tests/aos-store.test.mjs && node --test tests/aos-store-ui.test.mjs && node tests/aos-store-scenario.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs && node --test tests/agent-models.test.js && node --test tests/installer-p3.test.js && node --test tests/installer-binary.test.js && node --test tests/installer-version.test.js && node --test tests/mcsc-server.test.js && node --test tests/antigravity-hooks.test.js && node --test tests/plan-builder.test.mjs && node --test tests/plan-builder-trail.test.mjs && node --test tests/plan-builder-showcase.test.mjs && node --test tests/plan-builder-templates.test.mjs && node --test tests/plan-canvas-home.test.mjs && node --test tests/launchpad-installer.test.js && node --test tests/launchpad-plan-canvas.test.js && node --test tests/go-token.test.js && node --test tests/master-session-skill.test.js && node --test tests/aos-acp.test.js && node --test tests/opencode-go-token.test.js && node --test tests/opencode-adapter.test.js && node --test tests/pr-recap.test.mjs && node --test tests/bdb-visual-edit.test.mjs && node --test tests/opencode-trail-autostart.test.mjs && node --test tests/trail-autostart-hook.test.mjs && node --test tests/agenttrail-ensure.test.mjs"
+    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node --test tests/opencode-graph-gate.test.js && node --test tests/cross-harness-hooks.test.js && node --test tests/plan-canvas-security.test.mjs && node --test tests/plan-canvas-modes.test.mjs && node --test tests/swarm-wiring.test.js && node tests/aos-store.test.mjs && node --test tests/aos-store-ui.test.mjs && node tests/aos-store-scenario.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs && node --test tests/agent-models.test.js && node --test tests/installer-p3.test.js && node --test tests/installer-binary.test.js && node --test tests/installer-version.test.js && node --test tests/mcsc-server.test.js && node --test tests/antigravity-hooks.test.js && node --test tests/windows-hooks.test.js && node --test tests/plan-builder.test.mjs && node --test tests/plan-builder-trail.test.mjs && node --test tests/plan-builder-showcase.test.mjs && node --test tests/plan-builder-templates.test.mjs && node --test tests/plan-canvas-home.test.mjs && node --test tests/launchpad-installer.test.js && node --test tests/launchpad-plan-canvas.test.js && node --test tests/go-token.test.js && node --test tests/master-session-skill.test.js && node --test tests/aos-acp.test.js && node --test tests/opencode-go-token.test.js && node --test tests/opencode-adapter.test.js && node --test tests/pr-recap.test.mjs && node --test tests/bdb-visual-edit.test.mjs && node --test tests/opencode-trail-autostart.test.mjs && node --test tests/trail-autostart-hook.test.mjs && node --test tests/agenttrail-ensure.test.mjs && node --test tests/aos-bus.test.js"
   },
   "publishConfig": {
     "access": "public"

package/scripts/validate-skills.mjs

@@ -242,7 +242,7 @@ function checkSkillRefs(text, file, known, self, findings) {
 }
 
 // Playbooks are skills with `kind: playbook`; skills without `kind` are untouched.
-const PB_REQUIRED = ['trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation'];
+const PB_REQUIRED = ['trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time'];
 const DIFFICULTY = new Set(['beginner', 'intermediate', 'advanced']);
 const EXTERNAL = ' (external)';
 
@@ -274,12 +274,28 @@ export function checkPlaybook(byKey, known) {
     add('E-PB04', `\`difficulty: ${unquote(diff.value)}\` is not one of: ${[...DIFFICULTY].join(', ')}`, 'difficulty');
   }
   const dmi = byKey.get('disable-model-invocation');
-  if (dmi && unquote(dmi.value) !== 'true') {
-    add('E-PB06', 'playbooks are user-invoked only — set `disable-model-invocation: true`', 'disable-model-invocation');
+  if (dmi && unquote(dmi.value) === 'true') {
+    add('E-PB06', 'playbooks must stay invocable by agents — remove `disable-model-invocation: true` (side effects are guarded by go-gate)', 'disable-model-invocation');
   }
   return out;
 }
 
+// Pipeline and role skills must stay invocable through the Skill tool: the Master and
+// every orchestrator start them. Side effects are guarded by go-gate, not by hiding the
+// skill from the model. Anything not listed here may still set the flag.
+export const MODEL_INVOCABLE = new Set([
+  'startcycle', 'startcycle-graph', 'startcycle-graph-user', 'teamwork-preview',
+  'godmode-engineering', 'godmode-shipping', 'godmode-ui-ux', 'godmode-media-eventtech',
+  'master-session', 'ao-orchestrator', 'bdbrainstorm', 'bdbmediastorm',
+  'grill-me', 'grill-with-docs', 'ask-tim', 'memb-skill',
+]);
+
+export function checkInvocation(name, byKey) {
+  const dmi = byKey.get('disable-model-invocation');
+  if (!dmi || unquote(dmi.value) !== 'true' || !MODEL_INVOCABLE.has(name)) return [];
+  return [{ level: 'error', code: 'E-DMI01', line: dmi.line, msg: `\`${name}\` is a pipeline/role skill and must stay model-invocable — remove \`disable-model-invocation: true\` (go-gate guards its side effects)` }];
+}
+
 function validate() {
   const { skills, strays } = collect();
   const known = new Set(skills.map((f) => basename(dirname(f))));
@@ -351,6 +367,7 @@ function validate() {
     }
 
     for (const f of checkPlaybook(byKey, known)) findings.push({ ...f, file: rel });
+    for (const f of checkInvocation(basename(dir), byKey)) findings.push({ ...f, file: rel });
 
     checkLeakedPaths(text, rel, findings);
     checkLocalRefs(text, dir, rel, findings);
@@ -509,7 +526,7 @@ function selftest() {
       trigger: '["a"]', inputs: '[repo]',
       requires: '\n  skills: [github, gh (external)]\n  agents: []\n  mcps: []\n  store: []',
       go_points: '[]', outputs: '["x"]', verify: '"x"', difficulty: 'beginner',
-      est_time: '5 min', 'disable-model-invocation': 'true', ...over,
+      est_time: '5 min', ...over,
     };
     const lines = Object.entries(base).filter(([k]) => !drop.includes(k)).map(([k, v]) => `${k}: ${v}`);
     const fm = scanFrontmatter(['---', ...lines, '---'].join('\n'));
@@ -530,8 +547,14 @@ function selftest() {
   assert.equal(kind.length, 1);
   assert.equal(kind[0].code, 'E-PB01');
   assert.equal(checkPlaybook(pb({ requires: '\n  skills:\n    - github' }), known)[0].code, 'E-PB05');
-  assert.equal(checkPlaybook(pb({ 'disable-model-invocation': 'false' }), known)[0].code, 'E-PB06');
-  assert.deepEqual(checkPlaybook(pb({}, ['kind', 'trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation']), known).length, 0, 'no kind, no playbook rules');
+  assert.equal(checkPlaybook(pb({ 'disable-model-invocation': 'true' }), known)[0].code, 'E-PB06');
+  assert.deepEqual(checkPlaybook(pb({ 'disable-model-invocation': 'false' }), known), [], 'explicit false is fine');
+  const dm = (v) => new Map([['disable-model-invocation', { key: 'disable-model-invocation', value: v, line: 3 }]]);
+  assert.equal(checkInvocation('startcycle-graph', dm('true'))[0].code, 'E-DMI01');
+  assert.deepEqual(checkInvocation('startcycle-graph', dm('false')), []);
+  assert.deepEqual(checkInvocation('bdb-updater', dm('true')), [], 'unlisted skills may keep the flag');
+  assert.deepEqual(checkInvocation('startcycle', new Map()), []);
+  assert.deepEqual(checkPlaybook(pb({}, ['kind', 'trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time']), known).length, 0, 'no kind, no playbook rules');
   assert.deepEqual(
     checkPlaybook(pb({ requires: '\n  skills: ["gh (external)", github,]' }), known), [],
     'quoted item and trailing comma survive',

package/skills/basic/godmode-shipping/SKILL.md

@@ -2,7 +2,6 @@
 name: godmode-shipping
 description: BDB Shipping Godmode, the final gatekeeper for production releases. Use when running pre-launch checks, feature-flag rollouts, or rollback planning under Spec-Driven Development before a release ships.
 category: engineering-method
-disable-model-invocation: true
 ---
 
 # 🚀 BDB Shipping Godmode

package/skills/basic/startcycle/SKILL.md

@@ -2,7 +2,6 @@
 name: startcycle
 description: Linear multi-agent build pipeline with file hand-offs in production_artifacts/, run after /bdbrainstorm or /grill-me. This is the linear variant — no state.json, no repair loop, no dispatcher graph — distinct from startcycle-graph, which adds durable state and automated escalation.
 category: bdb-core
-disable-model-invocation: true
 ---
 
 # `/startcycle` — Linear Build Pipeline

package/skills/basic/startcycle-graph/SKILL.md

@@ -2,7 +2,6 @@
 name: startcycle-graph
 description: Use when running the autonomous multi-agent build pipeline after /bdbrainstorm or /grill-me. Routes to the startcycle-dispatch Dynamic Workflow, which reads production_artifacts/state.json and invokes Architect, TechLead, UI/UX, Engineering, Media/EventTech, Reviewer, and Shipping in turn per .agents/graph.md's edge table — the agents never invoke each other.
 category: bdb-core
-disable-model-invocation: true
 ---
 
 # 🚀 BDB Autonomous Development Cycle (`/startcycle-graph`)

package/skills/global_config/ask-tim/SKILL.md

@@ -2,7 +2,6 @@
 name: ask-tim
 description: Ask which skill or flow fits your situation. A route through AOS's skills for work that travels idea to ship, plus a catalogue of the 185 available options for lookup. Use when unsure where to start, or when picking between overlapping choices.
 category: bdb-core
-disable-model-invocation: true
 ---
 
 <!-- The flow map below is derived from mattpocock/skills' ask-matt (MIT, see

package/skills/global_config/grill-me/SKILL.md

@@ -2,7 +2,6 @@
 name: grill-me
 description: A relentless interview to sharpen a plan or design. Use before committing to an approach, or on any 'grill me' trigger phrase.
 category: engineering-method
-disable-model-invocation: true
 ---
 
 <!-- Source: mattpocock/skills skills/productivity/grill-me — MIT, see THIRD_PARTY_NOTICES.md -->

package/skills/global_config/grill-with-docs/SKILL.md

@@ -2,7 +2,6 @@
 name: grill-with-docs
 description: A relentless interview to sharpen a plan or design, which also builds the project's domain model — glossary and ADRs — as it goes. Use in a working directory whenever an idea needs sharpening.
 category: engineering-method
-disable-model-invocation: true
 ---
 
 <!-- Source: mattpocock/skills skills/engineering/grill-with-docs — MIT, see THIRD_PARTY_NOTICES.md -->

package/skills/playbooks/pb-ci-fix/SKILL.md

@@ -19,7 +19,6 @@ outputs: [".github/workflows/*.yml", "production_artifacts/pb-ci-fix-<date>.md"]
 verify: "gh run list --commit <sha> --json conclusion -q '.[0].conclusion' == success"
 difficulty: intermediate
 est_time: 15-45 min
-disable-model-invocation: true
 ---
 
 # Fix red CI or set up GitHub Actions

package/skills/playbooks/pb-event-tracker/SKILL.md

@@ -19,7 +19,6 @@ outputs: ["brief.md", "tracker.csv", "summary.md", "vendor-requests-draft.md", "
 verify: "summary.md total recomputed from tracker.csv matches"
 difficulty: intermediate
 est_time: 20-40 min
-disable-model-invocation: true
 ---
 
 # Event tracker

package/skills/playbooks/pb-meeting-actions/SKILL.md

@@ -19,7 +19,6 @@ outputs: ["notes.md", "decisions.md", "actions.md", "followup-draft.md", "run-lo
 verify: "every decision and action in the files cites a transcript line"
 difficulty: beginner
 est_time: 10-20 min
-disable-model-invocation: true
 ---
 
 # Meeting notes and action list

package/skills/playbooks/pb-project-new/SKILL.md

@@ -19,7 +19,6 @@ outputs: [".aos/project.json", "AGENTS.md", ".openwiki/", "production_artifacts/
 verify: "gh repo view <owner>/<name> --json visibility -q .visibility == PRIVATE"
 difficulty: intermediate
 est_time: 20-40 min
-disable-model-invocation: true
 ---
 
 # New private AOS project

package/skills/playbooks/pb-week-plan/SKILL.md

@@ -19,7 +19,6 @@ outputs: ["inbox.md", "calendar.md", "week-plan.md", "run-log.md"]
 verify: "every line in week-plan.md points to a line in inbox.md"
 difficulty: beginner
 est_time: 10-20 min
-disable-model-invocation: true
 ---
 
 # Plan my week