@hybridlabor-api/aos 4.16.0 → 4.18.0

package/plugins/bdb-aos-codex/skills/graph/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: graph
+description: "Run the startcycle-graph pipeline: durable state, repair loop, quality gate, escalation. Generated from plugin-commands.json; invoke as $bdb-aos:graph."
+---
+
+Run the `startcycle-graph` skill; its contract defines the flow. Task: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/init/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: init
+description: "Set up the current project folder for AOS: slug, wiki, memory, Synapse map, AGENTS.md. Generated from plugin-commands.json; invoke as $bdb-aos:init."
+---
+
+Run the `aos-project-init` skill for the current project folder. This is project setup, not machine setup (that is `$bdb-aos:setup`). Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/loop/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: loop
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates. Generated from plugin-commands.json; invoke as $bdb-aos:loop."
+---
+
+Codex has no /loop. Use `/goal` with the filled `loop-templates` template as the goal, keeping its limits and stop condition. Codex /goal is unverified in AOS docs; confirm with `codex --help`. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: whatever the user wrote after the command name

package/plugins/bdb-aos-codex/skills/mastersession/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: mastersession
+description: "Supervise other Claude Code sessions on this machine: roster, status requests, GO board, idle notices. Generated from plugin-commands.json; invoke as $bdb-aos:mastersession."
+---
+
+Act as the master session with the `master-session` skill (ACP bridge: `bin/aos-acp.mjs`, see docs/master-session-acp.md). Keep the overview, relay the human's decisions, never decide for the human. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/memb/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: memb
+description: "Query or store long-term memory with memB. Generated from plugin-commands.json; invoke as $bdb-aos:memb."
+---
+
+Use `memb-skill` to search or remember and `memb-ingest` to import material. Never store secrets, tokens or credentials. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/orchestrator/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: orchestrator
+description: "Coordinate parallel coding agents across repositories through the AO daemon. Generated from plugin-commands.json; invoke as $bdb-aos:orchestrator."
+---
+
+Use the `ao-orchestrator` skill. It needs the AO daemon; check that it is running first and stop with a clear message if not. Do not confuse it with `agent-orchestrator`. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/plan/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: plan
+description: "Plan end to end: draft, render in plan-canvas or Plan Builder, annotate, await approval, then hand off. Generated from plugin-commands.json; invoke as $bdb-aos:plan."
+---
+
+Run the full planning pipeline: 1) draft the plan with `concise-planning`; 2) always offer the choice between plan-canvas and Plan Builder (`aos-plan-canvas open <dir> --mode bdb-plan-builder`) for rendering; 3) collect annotations and wait for the human's approval; 4) only after approval continue with `writing-plans` or `$bdb-aos:graph`. Topic: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/playbooks/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: playbooks
+description: "List all pb-* playbooks with duration, difficulty and requirements, and start one. Generated from plugin-commands.json; invoke as $bdb-aos:playbooks."
+---
+
+Run `node <bdb-aos skill dir>/scripts/list-playbooks.mjs` and show its output (name, est_time, difficulty, requires of every `pb-*` skill). If the human names a playbook in the arguments or picks one, start that `pb-*` skill; start nothing otherwise. Each playbook keeps its own go-gate points. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/setup/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: setup
+description: "Bring this machine to a complete, verified AOS installation (skills, MCP servers, gate hooks, memB, OpenWiki, Synapse). Generated from plugin-commands.json; invoke as $bdb-aos:setup."
+---
+
+Run the `aos-setup` skill for this machine. Report what is installed, what was repaired and what is still missing. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/shipping/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: shipping
+description: "Pre-ship framing and the technical release gate, with approvals under the go-gate rules. Generated from plugin-commands.json; invoke as $bdb-aos:shipping."
+---
+
+Use `bdb-shipping-skill` for the pre-flight and `godmode-shipping` for the gate. The playbook `pb-ship` can drive the whole flow. Push, merge and publish need the human's GO under the go-gate rules; never request one on the human's behalf. Arguments: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/startproject/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: startproject
+description: "Start a new composition: project init, brainstorm, then ask whether graph or startcycle follows. Generated from plugin-commands.json; invoke as $bdb-aos:startproject."
+---
+
+Sequence: 1) `aos-project-init`; 2) `bdbrainstorm`; 3) stop and ask the human whether `$bdb-aos:graph` (startcycle-graph) or `startcycle` follows. Do not start a pipeline on your own. Idea: whatever the user wrote after the skill name

package/plugins/bdb-aos-codex/skills/store/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: store
+description: "Browse and preview AOS skills, agents and playbooks in the local store UI. Generated from plugin-commands.json; invoke as $bdb-aos:store."
+---
+
+Start the `aos-store` interface. Preview freely, but install nothing until the human says yes for that specific item. Arguments: whatever the user wrote after the skill name

package/scripts/build-plugin-manifest.mjs

@@ -21,6 +21,19 @@
 // personaFile paths and regenerated by installer.js, so they cannot move). Both
 // facts mean the plugin needs a generated layout, which is what this script is.
 //
+// Slash commands (/bdb-aos:<name>) come from plugin-commands.json: one commands/<name>.md
+// per entry plus a "commands" array in both manifests. OpenCode gets flat hyphen names
+// (.opencode/commands/bdb-aos-<name>.md, /bdb-aos-<name>) because a colon is invalid in
+// Windows file names; bodies.opencode is optional and falls back to the claude body with
+// /bdb-aos:<cmd> rewritten. AOS_PLUGIN_COMMANDS overrides the source path (tests only).
+//
+// Codex has no verified commands/ handling, so its entry points are generated wrapper
+// SKILLS (plugins/bdb-aos-codex/skills/<cmd>/SKILL.md, invoked as $bdb-aos:<cmd>) in a real
+// directory, because `codex plugin add` drops symlinks from the install copy. The plugin's
+// .codex-plugin/plugin.json and .agents/plugins/marketplace.json point there.
+// agy reads a plugin.json at the plugin root (/bdb-aos:<cmd>); bodies.codex / bodies.agy are
+// optional, agy overrides land in agy-commands/ and are only wired when present.
+//
 // Usage: node scripts/build-plugin-manifest.mjs [--check]
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
@@ -81,6 +94,58 @@ if (!CHECK) {
   }
 }
 
+const commandsSrc = process.env.AOS_PLUGIN_COMMANDS ?? join(ROOT, 'plugin-commands.json');
+const commandDefs = JSON.parse(readFileSync(commandsSrc, 'utf8')).commands ?? {};
+const skillNames = new Set(skillDirs.map((dir) => dir.split(/[\\/]/).pop()));
+const commandErrors = [];
+for (const [name, def] of Object.entries(commandDefs)) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(name)) commandErrors.push(`${name}: invalid command name`);
+  if (skillNames.has(name)) commandErrors.push(`${name}: collides with a skill of the same name`);
+  if (!def.description?.trim()) commandErrors.push(`${name}: empty description`);
+  if (!def.bodies?.claude?.trim()) commandErrors.push(`${name}: no body for claude`);
+  for (const harness of ['opencode', 'codex', 'agy']) {
+    if (def.bodies?.[harness] !== undefined && !def.bodies[harness].trim()) commandErrors.push(`${name}: empty body for ${harness}`);
+  }
+  for (const ref of def.skills ?? []) {
+    const found = ref.endsWith('*')
+      ? [...skillNames].some((n) => n.startsWith(ref.slice(0, -1)))
+      : skillNames.has(ref);
+    if (!found && def.pending === undefined) commandErrors.push(`${name}: unknown skill ${ref}`);
+  }
+}
+if (commandErrors.length > 0) {
+  console.error(`plugin-commands.json invalid:\n  ${commandErrors.join('\n  ')}`);
+  process.exit(1);
+}
+const commandNames = Object.keys(commandDefs).sort();
+const commandFiles = Object.fromEntries(commandNames.map((name) => [
+  `${name}.md`,
+  `---\ndescription: ${JSON.stringify(commandDefs[name].description)}\n---\n\n${commandDefs[name].bodies.claude.trim()}\n`,
+]));
+const commands = commandNames.map((name) => `./commands/${name}.md`);
+const opencodeBody = (def) =>
+  (def.bodies.opencode ?? def.bodies.claude.replace(/\/bdb-aos:([a-z][a-z0-9-]*)/g, '/bdb-aos-$1')).trim();
+const opencodeFiles = Object.fromEntries(commandNames.map((name) => [
+  `bdb-aos-${name}.md`,
+  `---\ndescription: ${JSON.stringify(commandDefs[name].description)}\n---\n\n${opencodeBody(commandDefs[name])}\n`,
+]));
+
+// Codex has no per-user argument placeholder, so $ARGUMENTS becomes prose.
+const codexBody = (def) =>
+  (def.bodies.codex ?? def.bodies.claude
+    .replace(/\/bdb-aos:([a-z][a-z0-9-]*)/g, '$$bdb-aos:$1')
+    .replace(/\$ARGUMENTS/g, 'whatever the user wrote after the skill name')).trim();
+const codexFiles = Object.fromEntries(commandNames.map((name) => [
+  `${name}/SKILL.md`,
+  `---\nname: ${name}\ndescription: ${JSON.stringify(`${commandDefs[name].description} Generated from plugin-commands.json; invoke as $bdb-aos:${name}.`)}\n---\n\n${codexBody(commandDefs[name])}\n`,
+]));
+const agyOverrides = commandNames.filter((name) => commandDefs[name].bodies.agy !== undefined);
+const agyFiles = Object.fromEntries(agyOverrides.map((name) => [
+  `${name}.md`,
+  `---\ndescription: ${JSON.stringify(commandDefs[name].description)}\n---\n\n${commandDefs[name].bodies.agy.trim()}\n`,
+]));
+const agyCommands = commandNames.map((name) => `./${agyOverrides.includes(name) ? 'agy-commands' : 'commands'}/${name}.md`);
+
 const manifest = {
   $schema: 'https://anthropic.com/claude-code/plugin.schema.json',
   name: 'bdb-aos',
@@ -94,9 +159,96 @@ const manifest = {
   license: 'Apache-2.0',
   keywords: ['skills', 'agent-os', 'cicd', 'multiagent', 'startcycle', 'bdb'],
   skills,
+  commands,
 };
 
 const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const codexManifest = {
+  name: manifest.name,
+  version: pkg.version,
+  description: 'Full BDB Agent OS suite for Codex: command entry points ($bdb-aos:setup, $bdb-aos:init, ...) generated from plugin-commands.json.',
+  author: manifest.author,
+  homepage: repoUrl,
+  repository: repoUrl,
+  license: manifest.license,
+  keywords: manifest.keywords,
+  skills: './skills/',
+  interface: {
+    displayName: 'BDB Agent OS',
+    shortDescription: 'AOS commands for setup, planning and pipelines',
+    longDescription: 'Entry-point skills for the BDB Agent OS suite: invoke $bdb-aos:<command> to run setup, project init, planning and the startcycle pipelines.',
+    developerName: 'Hybridlabor Global LLC',
+    category: 'Developer Tools',
+    capabilities: ['Interactive', 'Read', 'Write'],
+    websiteURL: repoUrl,
+    defaultPrompt: ['$bdb-aos:setup', '$bdb-aos:doctor'],
+  },
+};
+const CODEX_ROOT = 'plugins/bdb-aos-codex';
+const codexMarket = {
+  name: 'bdb-aos',
+  interface: { displayName: 'BDB Agent OS' },
+  plugins: [{
+    name: manifest.name,
+    source: { source: 'local', path: `./${CODEX_ROOT}` },
+    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+    category: 'Developer Tools',
+  }],
+};
+const { $schema: _schema, ...agyBase } = manifest;
+const agyManifest = { ...agyBase, commands: agyCommands };
+const generated = {
+  '.codex-plugin/plugin.json': json({ ...codexManifest, skills: `./${CODEX_ROOT}/skills/` }),
+  [`${CODEX_ROOT}/.codex-plugin/plugin.json`]: json(codexManifest),
+  '.agents/plugins/marketplace.json': json(codexMarket),
+  'plugin.json': json(agyManifest),
+  'plugins/bdb-aos/plugin.json': json(agyManifest),
+  ...Object.fromEntries(Object.entries(codexFiles).map(([f, c]) => [`${CODEX_ROOT}/skills/${f}`, c])),
+  ...Object.fromEntries(Object.entries(agyFiles).map(([f, c]) => [`agy-commands/${f}`, c])),
+};
+const ownedDirs = { [`${CODEX_ROOT}/skills`]: (e) => e.isDirectory(), 'agy-commands': (e) => e.isFile() };
+const genDrift = Object.entries(generated)
+  .filter(([file, want]) => !existsSync(join(ROOT, file)) || readFileSync(join(ROOT, file), 'utf8') !== want)
+  .map(([file]) => file);
+const filesUnder = (rel) => readdirSync(join(ROOT, rel), { withFileTypes: true })
+  .flatMap((e) => (e.isDirectory() ? filesUnder(`${rel}/${e.name}`) : [`${rel}/${e.name}`]));
+const genStale = Object.entries(ownedDirs).flatMap(([dir, owned]) =>
+  existsSync(join(ROOT, dir))
+    ? readdirSync(join(ROOT, dir), { withFileTypes: true }).filter(owned).flatMap((e) => {
+      const path = `${dir}/${e.name}`;
+      if (!Object.keys(generated).some((file) => file === path || file.startsWith(`${path}/`))) return [path];
+      return e.isDirectory() ? filesUnder(path).filter((f) => !(f in generated)) : [];
+    })
+    : []);
+const legacyCodexMarket = join(ROOT, '.codex-plugin', 'marketplace.json');
+
+// Release-gate validation: every generated manifest parses, versions track package.json,
+// Codex outputs never carry the field its validator rejects, referenced files exist.
+function validateGenerated() {
+  const problems = [];
+  for (const file of Object.keys(generated)) {
+    if (!file.endsWith('.json') || !existsSync(join(ROOT, file))) continue;
+    let doc;
+    try { doc = JSON.parse(readFileSync(join(ROOT, file), 'utf8')); } catch { problems.push(`${file}: does not parse`); continue; }
+    if (file.endsWith('plugin.json') && doc.version !== pkg.version) problems.push(`${file}: version ${doc.version} != package.json ${pkg.version}`);
+    const base = join(ROOT, dirname(file).replace(/\.codex-plugin$/, ''));
+    if (file.endsWith('plugin.json') && file !== '.agents/plugins/marketplace.json') {
+      for (const ref of [...(doc.commands ?? []), ...(Array.isArray(doc.skills) ? doc.skills : [])]) {
+        const target = join(base, ref, ref.endsWith('.md') ? '' : 'SKILL.md');
+        if (!existsSync(target)) problems.push(`${file}: missing ${ref}`);
+      }
+      if (typeof doc.skills === 'string' && !existsSync(join(base, doc.skills))) problems.push(`${file}: missing ${doc.skills}`);
+    }
+  }
+  for (const file of Object.keys(generated)) {
+    if (/^(plugins\/bdb-aos-codex\/|\.codex-plugin\/|\.agents\/plugins\/)/.test(file) &&
+      existsSync(join(ROOT, file)) && readFileSync(join(ROOT, file), 'utf8').includes('disable-model-invocation')) {
+      problems.push(`${file}: contains disable-model-invocation (rejected by Codex)`);
+    }
+  }
+  return problems;
+}
 const SUBDIR = join(ROOT, 'plugins', 'bdb-aos');
 // Both manifests come from the same data; the subfolder one resolves the same
 // ./skills/... paths through its symlinks.
@@ -105,7 +257,12 @@ const targets = [
   join(SUBDIR, '.claude-plugin', 'plugin.json'),
 ];
 const stale = targets.filter((t) => !existsSync(t) || readFileSync(t, 'utf8') !== serialized);
-const links = { skills: '../../skills', agents: '../../agents' };
+const links = {
+  skills: '../../skills',
+  agents: '../../agents',
+  commands: '../../commands',
+  ...(agyOverrides.length > 0 ? { 'agy-commands': '../../agy-commands' } : {}),
+};
 const badLinks = Object.entries(links).filter(([name, to]) => {
   const path = join(SUBDIR, name);
   return !existsSync(path) || !lstatSync(path).isSymbolicLink() || readlinkSync(path) !== to;
@@ -120,6 +277,19 @@ const entry = market.plugins?.find((plugin) => plugin.name === manifest.name);
 if (!entry) throw new Error(`marketplace.json has no entry named ${manifest.name}`);
 entry.version = pkg.version;
 const marketSerialized = `${JSON.stringify(market, null, 2)}\n`;
+const commandsDst = join(ROOT, 'commands');
+const commandDrift = Object.entries(commandFiles)
+  .filter(([file, want]) => !existsSync(join(commandsDst, file)) || readFileSync(join(commandsDst, file), 'utf8') !== want)
+  .map(([file]) => file);
+const staleCommandFiles = existsSync(commandsDst)
+  ? readdirSync(commandsDst).filter((file) => !(file in commandFiles))
+  : [];
+const ocDst = join(ROOT, '.opencode', 'commands');
+const ocOwned = (file) => /^bdb-aos-.+\.md$/.test(file);
+const ocDrift = Object.entries(opencodeFiles)
+  .filter(([file, want]) => !existsSync(join(ocDst, file)) || readFileSync(join(ocDst, file), 'utf8') !== want)
+  .map(([file]) => file);
+const ocStale = existsSync(ocDst) ? readdirSync(ocDst).filter((file) => ocOwned(file) && !(file in opencodeFiles)) : [];
 const marketCurrent = readFileSync(marketPath, 'utf8');
 
 if (CHECK) {
@@ -135,20 +305,49 @@ if (CHECK) {
     console.error('marketplace.json version is out of date — run: node scripts/build-plugin-manifest.mjs');
     process.exit(1);
   }
+  if (commandDrift.length > 0 || staleCommandFiles.length > 0) {
+    console.error(`commands/ is out of date (${[...commandDrift, ...staleCommandFiles].join(', ')}) — run: node scripts/build-plugin-manifest.mjs`);
+    process.exit(1);
+  }
+  if (ocDrift.length > 0 || ocStale.length > 0) {
+    console.error(`.opencode/commands/ is out of date (${[...ocDrift, ...ocStale].join(', ')}) — run: node scripts/build-plugin-manifest.mjs`);
+    process.exit(1);
+  }
+  if (genDrift.length > 0 || genStale.length > 0 || existsSync(legacyCodexMarket)) {
+    console.error(`Codex/agy manifests are out of date (${[...genDrift, ...genStale, ...(existsSync(legacyCodexMarket) ? ['.codex-plugin/marketplace.json (legacy)'] : [])].join(', ')}) — run: node scripts/build-plugin-manifest.mjs`);
+    process.exit(1);
+  }
+  const problems = validateGenerated();
+  if (problems.length > 0) {
+    console.error(`generated manifests invalid:\n  ${problems.join('\n  ')}`);
+    process.exit(1);
+  }
   if (drift.length > 0) {
     console.error(`agents/ is out of date (${drift.join(', ')}) — run: node scripts/build-plugin-manifest.mjs`);
     process.exit(1);
   }
-  console.log(`plugin manifests up to date: ${skills.length} skills, ${agentNames.length} agents`);
+  console.log(`plugin manifests up to date: ${skills.length} skills, ${agentNames.length} agents, ${commandNames.length} commands (+ ${commandNames.length} OpenCode)`);
 } else {
+  mkdirSync(commandsDst, { recursive: true });
+  for (const [file, content] of Object.entries(commandFiles)) writeFileSync(join(commandsDst, file), content);
+  for (const file of staleCommandFiles) rmSync(join(commandsDst, file));
+  mkdirSync(ocDst, { recursive: true });
+  for (const [file, content] of Object.entries(opencodeFiles)) writeFileSync(join(ocDst, file), content);
+  for (const file of ocStale) rmSync(join(ocDst, file));
   for (const t of targets) {
     mkdirSync(dirname(t), { recursive: true });
     writeFileSync(t, serialized);
   }
+  for (const [file, content] of Object.entries(generated)) {
+    mkdirSync(dirname(join(ROOT, file)), { recursive: true });
+    writeFileSync(join(ROOT, file), content);
+  }
+  for (const path of genStale) rmSync(join(ROOT, path), { recursive: true });
+  rmSync(legacyCodexMarket, { force: true });
   for (const [name, to] of badLinks) {
     rmSync(join(SUBDIR, name), { force: true });
     symlinkSync(to, join(SUBDIR, name));
   }
   writeFileSync(marketPath, marketSerialized);
-  console.log(`Wrote 2 plugin.json files with ${skills.length} skills and ${agentNames.length} agents`);
+  console.log(`Wrote 2 plugin.json files with ${skills.length} skills, ${agentNames.length} agents and ${commandNames.length} commands`);
 }

package/scripts/codex-gate-smoke.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Plan and runner for the Codex hook smoke test. Default: print the plan, run nothing.
+// `--run` calls Codex, which calls a paid API, so it also needs AOS_CODEX_SMOKE=1 and a login
+// inside the throwaway CODEX_HOME (printed in the plan). Everything about firing under ACP
+// is UNVERIFIED until this has been run; see docs/codex-gate-smoke.md.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const PROBE = `import { appendFileSync, readFileSync } from "node:fs";
+let input = {};
+try { input = JSON.parse(readFileSync(0, "utf8")); } catch {}
+const cmd = input?.tool_input?.command ?? "";
+appendFileSync(process.env.AOS_SMOKE_MARKER, JSON.stringify({ at: new Date().toISOString(), keys: Object.keys(input), cmd }) + "\\n");
+if (String(cmd).includes("SMOKE_DENY")) { process.stderr.write("smoke: denied by probe hook\\n"); process.exit(2); }
+`;
+
+export function buildConfig(probePath) {
+  return [
+    "[features]",
+    "hooks = true",
+    "",
+    "[[hooks.PreToolUse]]",
+    'matcher = "^(Bash|run_command)$"',
+    "[[hooks.PreToolUse.hooks]]",
+    'type = "command"',
+    `command = ${JSON.stringify(`node "${probePath}"`)}`,
+    "timeout = 10",
+    "",
+  ].join("\n");
+}
+
+export function steps({ dir = "<tmpdir>", bypassTrust = false } = {}) {
+  const env = `CODEX_HOME=${dir}/codex-home AOS_SMOKE_MARKER=${dir}/marker.jsonl`;
+  const trust = bypassTrust ? " --dangerously-bypass-hook-trust" : "";
+  return [
+    { id: "setup", text: `Throwaway CODEX_HOME ${dir}/codex-home with config.toml holding the [[hooks.PreToolUse]] stanza that runs ${dir}/probe-hook.mjs. Log in inside it (codex login, or OPENAI_API_KEY); never copy credentials from ~/.codex.` },
+    { id: "exec-fires", cmd: `${env} codex exec${trust} --skip-git-repo-check -C ${dir} "Run the shell command: echo smoke-ok"`, expect: "marker.jsonl gains a line with cmd containing 'echo smoke-ok'. If not, hooks do not fire under codex exec (or the hook was not trusted)." },
+    { id: "exec-denies", cmd: `${env} codex exec${trust} --skip-git-repo-check -C ${dir} "Run the shell command: echo SMOKE_DENY"`, expect: "marker line for SMOKE_DENY exists and the command did not run (the agent reports it was blocked)." },
+    { id: "acp-fires", cmd: `${env} node ${join(root, "bin", "aos-acp.mjs")} codex --name smoke --cwd ${dir} --allow-default allow --timeout 180 --prompt "Run the shell command: echo smoke-acp"`, expect: "marker.jsonl gains a line with 'echo smoke-acp'. UNVERIFIED: if only the aos-acp permission request fires and the hook does not, aos-acp stays the only gate for Codex." },
+    { id: "record", text: "Write the observed result of each step (and the Codex version) into docs/codex-gate-smoke.md, replacing UNVERIFIED with the date and the result. Hook input keys are in marker.jsonl ('keys')." },
+  ];
+}
+
+const invokedAs = (() => { try { return realpathSync(process.argv[1] || ""); } catch { return ""; } })();
+if (invokedAs === fileURLToPath(import.meta.url)) {
+  const run = process.argv.includes("--run");
+  const bypassTrust = process.argv.includes("--bypass-trust");
+  if (!run) {
+    console.log("Codex hook smoke plan (nothing is executed; add --run with AOS_CODEX_SMOKE=1 to run it)\n");
+    for (const s of steps({ bypassTrust })) console.log(`[${s.id}] ${s.cmd ?? s.text}${s.expect ? `\n    expect: ${s.expect}` : ""}`);
+    process.exit(0);
+  }
+  if (process.env.AOS_CODEX_SMOKE !== "1") { console.error("refusing to run: this calls a paid API. Set AOS_CODEX_SMOKE=1."); process.exit(2); }
+  const dir = mkdtempSync(join(tmpdir(), "aos-codex-smoke-"));
+  writeFileSync(join(dir, "probe-hook.mjs"), PROBE);
+  const home = join(dir, "codex-home");
+  mkdirSync(home);
+  writeFileSync(join(home, "config.toml"), buildConfig(join(dir, "probe-hook.mjs")));
+  const marker = join(dir, "marker.jsonl");
+  for (const s of steps({ dir, bypassTrust }).filter((x) => x.cmd)) {
+    const before = existsSync(marker) ? readFileSync(marker, "utf8").split("\n").length : 0;
+    const r = spawnSync("sh", ["-c", s.cmd], { stdio: "inherit", timeout: 240000 });
+    const after = existsSync(marker) ? readFileSync(marker, "utf8").split("\n").length : 0;
+    console.log(`[${s.id}] exit ${r.status}; hook fired: ${after > before ? "YES" : "NO"}; expect: ${s.expect}`);
+  }
+  console.log(`marker and config kept in ${dir} (remove it yourself when done)`);
+}

package/skills/basic/master-session/SKILL.md

@@ -20,6 +20,17 @@ One session is the **master**: it keeps the overview, asks workers for status, a
   - agy: no sanctioned ACP adapter (`antigravity-acp` breaches Google's Antigravity terms). Adopt agy sessions or delegate via the `mcsc` skill.
   - If AO is installed, `ao-orchestrator` may run the same workers; it adds nothing the token protocol needs.
 
+### Routing: which channel for which job
+
+| Job | Channel |
+|---|---|
+| One-shot task for another harness | `mcsc` (one level deep, `delegate_agy` is read-only) |
+| A worker that may need a GO | `aos-acp` |
+| A message to a running OpenCode session | `aos-bus` |
+| A durable fleet across repos | AO (optional; AOS must work without it) |
+
+Details and limits (`opencode run --auto` auto-approves tool calls, a GO is never inherited): `docs/delegation-routing.md`.
+
 ### `aos-acp` in one paragraph
 
 `bin/aos-acp.mjs` is a zero-dependency ACP client: it spawns the adapter (`npx -y @agentclientprotocol/codex-acp`, `opencode acp`, `npx -y @agentclientprotocol/claude-agent-acp`), runs `initialize` → `session/new` → `session/prompt`, streams the worker's text to stdout and logs every event to `~/.aos/acp/<name>.jsonl`. A `session/request_permission` for a guarded command (the go-gate list) is answered `allow_once` only with a valid GO token for `<name>`; with `--go-wait <sec>` the request is parked (log event `permission_pending`, show it as `GO needed`) until the token appears or the wait ends. Everything else follows `--allow-default deny|allow` (deny by default). `--model <id>` is sent as ACP `session/set_config_option` (`configId: "model"`, id is adapter-specific, e.g. `sonnet`, `provider/model`); `fable` ids are rejected (workers run opus, sonnet or haiku), default is the adapter default and is logged. ACP workers are not in `ListAgents`: the roster lists them from the logs.

package/skills/bdb-aos/scripts/list-playbooks.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const unquote = (s) => s.trim().replace(/^["']|["']$/g, '');
+
+function frontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const out = {};
+  let key = null;
+  for (const line of (m?.[1] ?? '').split(/\r?\n/)) {
+    const top = line.match(/^([A-Za-z_-]+):\s*(.*)$/);
+    if (top) {
+      key = top[1];
+      out[key] = /^(>-?|\|-?)$/.test(top[2]) ? '' : top[2];
+    } else if (key && line.trim()) out[key] = `${out[key]} ${line.trim()}`.trim();
+  }
+  return out;
+}
+
+const flowList = (value, name) => {
+  const m = new RegExp(`(?:^|[\\s{,])${name}:\\s*\\[([^\\]]*)\\]`).exec(value ?? '');
+  return m ? m[1].split(',').map(unquote).filter(Boolean) : [];
+};
+
+export function listPlaybooks(skillsRoot) {
+  const found = [];
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.name === 'SKILL.md' && /^pb-/.test(dirname(full).split(sep).pop())) {
+        const fm = frontmatter(readFileSync(full, 'utf8'));
+        const req = fm.requires ?? '';
+        found.push({
+          name: unquote(fm.name ?? ''),
+          description: unquote(fm.description ?? ''),
+          est_time: unquote(fm.est_time ?? ''),
+          difficulty: unquote(fm.difficulty ?? ''),
+          requires: {
+            skills: flowList(req, 'skills'), agents: flowList(req, 'agents'),
+            mcps: flowList(req, 'mcps'), store: flowList(req, 'store'),
+          },
+        });
+      }
+    }
+  };
+  if (existsSync(skillsRoot)) visit(skillsRoot);
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export const requiresLabel = (r) => [...r.skills, ...r.agents.map((a) => `agent:${a}`), ...r.mcps.map((m) => `mcp:${m}`), ...r.store.map((s) => `store:${s}`)].join(', ');
+
+function defaultRoot() {
+  const parts = dirname(fileURLToPath(import.meta.url)).split(sep);
+  const i = parts.lastIndexOf('skills');
+  return i < 0 ? resolve('skills') : parts.slice(0, i + 1).join(sep);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = process.argv.slice(2).find((a) => !a.startsWith('--')) ?? defaultRoot();
+  const list = listPlaybooks(root);
+  if (process.argv.includes('--json')) console.log(JSON.stringify(list, null, 2));
+  else {
+    for (const p of list) {
+      console.log(`${p.name}\t${p.est_time}\t${p.difficulty}\trequires: ${requiresLabel(p.requires) || 'nothing'}`);
+      console.log(`  ${p.description}`);
+    }
+    console.log(`\n${list.length} playbook(s).`);
+  }
+}

package/skills/global_config/agenttrail/SKILL.md

@@ -33,7 +33,9 @@ It prints the URL (default http://localhost:5330, next free port if taken). Open
 aos-trail --ensure [--cwd <dir>] [--plan <file>] [--session <id>] [--json]
 ```
 
-Starts the map detached if none runs for this repo (matched via `/whoami` `repoPath` on 127.0.0.1:5330-5344), opens it at most once per session (state in `$TMPDIR/aos-trail-ensure/`), and always exits 0. Plan: `--plan`, else `production_artifacts/00_execution_plan.md`, else the single `production_artifacts/*/00_execution_plan.md`; it needs a `{#id}` marker. No open under `CI`, SSH, or headless Linux; with `AO_BROWSER_CAPABILITY` it runs `ao preview <url>`. `--json` prints `{url,started,opened,reason,plan,hint}`. Test overrides: `AOS_TRAIL_OPENER` (opener command), `AOS_TRAIL_PORTS=lo-hi` (probe range).
+Starts the map detached if none runs for this repo (matched via `/whoami` `repoPath` on 127.0.0.1:5330-5344). `repoPath` is the repo's main checkout, so every git worktree of a repo finds the same map; the map shows each worktree as its own lane (branch and folder) and files hook events by their `cwd`. `/whoami` also lists `worktrees`, opens it at most once per session (state in `$TMPDIR/aos-trail-ensure/`), and always exits 0. Plan: `--plan`, else `production_artifacts/00_execution_plan.md`, else the single `production_artifacts/*/00_execution_plan.md`; it needs a `{#id}` marker. No open under `CI`, SSH, or headless Linux; with `AO_BROWSER_CAPABILITY` it runs `ao preview <url>`. `--json` prints `{url,started,opened,reason,plan,hint}`. Test overrides: `AOS_TRAIL_OPENER` (opener command), `AOS_TRAIL_PORTS=lo-hi` (probe range).
+
+Lanes: main first, then at most 11 worktrees; the slots go to the most recently active ones (a lane with events in the last 10 min keeps its slot), and events from any further worktree of the repo are filed in one `other worktrees` lane, never in main. `/whoami` carries `protocol: 2`. `--ensure` replaces a daemon on this repo (or one of its worktrees) that lacks it: the new map starts first, then the old one is asked to quit via `POST /shutdown` (JSON body naming its own `repoPath`); a daemon that cannot (older ones have no such API) keeps running and `hint` says which port to stop. Two concurrent `--ensure` runs share a lock file in `$TMPDIR/aos-trail-ensure/`. `/setup` on a map with several lanes needs `{"lane": "<key>"}` and writes into that checkout.
 
 ## Plan convention